emxrt - a Python extension module for EMX platform specific functionality
-------------------------------------------------------------------------

This module was inspired by the "msvcrt" module which provides support 
for functionality specific to the MSVC Runtime Library, available with 
the standard Win32 builds of Python.

The EMX runtime library also has APIs that provide access to some OS/2 
functionality, which is not accessible via the Posix API support.

The EMX functionality currently exposed by this module is:-
- changing file newline translation modes
  (setmode(), fsetmode());
- opening files with OS/2 specific file sharing modes
  (sopen(), fsopen());
- retrieving OS/2 specific information
  (execname(), filesys());
- extended attribute manipulation"
  (ea_get(), ea_getall(), ea_pu(), ea_putall, ea_remove()).

Usage
-----

execname()
	Get the full pathname of the executable file for the
	current process.  This duplicates os.executable(), but 
	using the EMX execname() rather than a generic 
	algorithm.

filesys(drive)
	return the file system type for the specified drive
	letter in DOS string format ('C:').

setmode(fd, mode)	
	Set the newline translation mode of file descriptor fd to mode.
	fd must be an integer. mode is either emxrt.O_TEXT or
	emxrt.O_BINARY. os.O_TEXT or os.O_BINARY can also be used.

fsetmode(file, mode)
	Set the newline translation mode of a python file object to mode.
	mode can be 't' (text) or 'b' (binary).

sopen(name, o_flags, sh_flags)
	Open a file descriptor for the named file.
	o_flags are the same as for os.open().
	sh_flags can be one of emxrt.SH_DENYRW, emxrt.SH_DENYRD,
	emxrt.SH_DENYWR, emxrt.SH_DENYNO.

fsopen(name, mode, sh_flags)
	Create a file object for the named file
	mode is the same as for open().
	sh_flags can be one of emxrt.SH_DENYRW, emxrt.SH_DENYRD,
	emxrt.SH_DENYWR, emxrt.SH_DENYNO.

ea_get(file, ea_name)
	Return a tuple (ea_data, ea_flags) for the specified OS/2
	extended attribute.
	file is a file object, file handle or file name string;
	file objects or handles must have open modes permitting 
	read access.
	ea_name is a string containing the name of the EA; case is
	ignored.
	The returned EA data is an arbitrary string value.
	A KeyError exception is returned when the EA doesn't exist.

ea_put(file, ea_name, ea_value [, ea_flags])
	Add an extended attribute to a file or directory, returns None.
	file is a file object, file handle or file name string;
	file objects or handles must have open modes permitting 
	write access.
	ea_name is a string containing the name of the EA; case is
	ignored.
	ea_value is the string to be set as the EA value.
	ea_flags is an integer containing flag bits for the EA (default 0)
		- bit 7 (0x80) = critical EA.

	EMX documentation cautions:
	"flags should be 0 unless you know exactly what you are doing"

ea_remove(file, ea_name)
	Remove an extended attribute from a file or directory, returns None.
	file is a file object, file handle or file name string;
	file objects or handles must have open modes permitting 
	write access.
	ea_name is a string containing the name of the EA; case is ignored.

ea_getall(file)
	Get all extended attributes associated with a file or directory,
	returns a dictionary with the EA names as keys and item values
	being tuples containing the EA values as strings and EA flags
	as integers.
	file is a file object, file handle or file name string;
	file objects or handles must have open modes permitting 
	read access.

ea_putall(file, EAs[, merge])
	Associate a collection of extended attributes with a file or
	directory.
	file is a file object, file handle or file name string;
	file objects or handles must have open modes permitting 
	write access.
	EAs is a dictionary containing the EA collection - keys as
	EA names, values as tuples of EA value strings and EA flag
	integers.
	A ValueError exception will be raised if a dictionary entry
	item value is not a string, integer tuple.
	merge is an integer flag indicating whether the EAs in the
	supplied dictionary replace all EAs already associated with
	the file, or are merged with the files existing EAs:
	  replace: 0 (default), merge: 1.
	See the description for ea_put() for comments about the EA
	flag values.

Installation
------------

Build and install with the command

  python setup.py install

This will install emxrt.pyd into the Lib/site-packages subdirectory 
of the PYTHONHOME directory.

A working EMX development environment is required for the build to
succeed.

There is also a rudimentary test script, test.py, which also serves 
as a crude example for using the module.

In the longer term, I plan to incorporate this module in to the OS/2+EMX 
port support in the Python distribution, where it will live in 
Lib/lib-dynload.

Legalities
----------

This software is released under the terms of the MIT licence.


Feedback
--------

Constructive feedback, positive or negative, about this module is 
welcome.



Andrew MacIntyre.
andymac@bullseye.apana.org.au or andymac@pcug.org.au
http://www.andymac.org/
July 20, 2008.
