File System Extensions

Description

The File System Extensions are a part of the lowest level of I/O operations in the C runtime library of DJGPP. These extensions are provided to allow for cases where Unix uses a file descriptor to access such items as serial ports, memory, and the network, but DOS does not. It allows a set of functions (called an extension) to gain control when one of these low-level functions is called on a file descriptor set up by the extension.

Each extension must provide one or two handler functions. All handler functions take the same arguments:

int function(__FSEXT_Fnumber func_number, int *rv, va_list args);

The func_number identifies which function is to be emulated. The file <sys/fsext.h> defines the function numbers as follows:

__FSEXT_nop

A no-op. This is currently unused by the library functions.

__FSEXT_open

An open handler (see section _open). This is called just before the library is about to issue the DOS OpenFile call on behalf of your program.

If _open was called from the library function open, then the file name passed to the handler will have either all its symlink components resolved or will refer to a symlink file (i.e.: all directory symlinks will be resolved), depending on whether the O_NOLINK was passed to open (see section open).

Do not use this extension to emulate symlinks. Use __FSEXT_readlink handler instead.

__FSEXT_creat

A create handler (see section _creat, and see section _creatnew). Called when a file needs to be created. Note that the handler should both create the "file" and open it.

If _creat or _creatnew were called from the library functions open or creat, then the file name passed to the handler will have all its symlink components resolved.

__FSEXT_read

A read handler (see section _read). Called when data should be read from a "file".

__FSEXT_write

A write handler (see section write, and see section _write). Called to write data to a "file". On "text" files it receives the original (unconverted) buffer.

__FSEXT_ready

A ready handler. It is called by select library function (see section select) when it needs to know whether a handle used to reference the "file" is ready for reading or writing, or has an error condition set. The handler should return an OR'ed bit mask of the following bits (defined on <sys/fsext.h>):

__FSEXT_ready_read

The "file" is ready for reading.

__FSEXT_ready_write

The "file" is ready for writing.

__FSEXT_ready_error

The "file" has an error condition set.

__FSEXT_close

A close handler (see section _close). Called when the "file" should be closed.

__FSEXT_fcntl

A file fcntl handler (see section fcntl).

__FSEXT_ioctl

A file ioctl handler (see section ioctl (General description)).

__FSEXT_lseek

A file lseek handler (see section lseek). Here for backwards compatibility. Use __FSEXT_llseek instead. If you have a __FSEXT_llseek handler you don't need a __FSEXT_lseek handler as lseek calls llseek internally.

__FSEXT_llseek

A file llseek handler (see section llseek).

__FSEXT_link

A file link handler (see section link). This is most relevant to file system extensions that emulate a directory structure.

The source and destination file names are passed to the handler unchanged.

__FSEXT_unlink

A file unlink handler (see section remove, and see section unlink). This is most relevant to file system extensions that emulate a directory structure.

The file name passed to the handler will have all its directory symlinks resolved, so it may refer to a symlink file.

__FSEXT_dup

A file dup handler (see section dup). This is called when a new descriptor is needed to refer to an existing descriptor.

__FSEXT_dup2

A file dup2 handler (see section dup2). This is called when two different file descriptors are used to refer to the same open file.

__FSEXT_stat

A file lstat handler (see section lstat). This extension should provide information about stated file. If you provide this hook, function stat will be hooked too, as stat always calls lstat.

If the handler is called as a result of a stat call, then the file name passed to the handler will have all its symlinks resolved, so it will refer to a "regular" file. If the handler is called as result of a lstat call and not a stat call, then the file name passed to the handler will have all its directory symlinks resolved, so it may refer to a symlink file.

__FSEXT_fstat

A file fstat handler (see section fstat). The extension should fill in various status information about the emulated file.

__FSEXT_readlink

A file readlink handler (see section readlink). This extension should be used to provide support for symlinks in some other than DJGPP format.

The file name passed to the handler will have all its directory symlinks resolved, so it may refer to a symlink file.

__FSEXT_symlink

A file symlink handler (see section symlink). This extension should create symlinks in other than DJGPP symlink file format.

The source and destination file names are passed to the handler unchanged.

__FSEXT_chmod

A file chmod handler (see section chmod). This is called when the permissions are to be changed for a file.

The file name passed to the handler will have all its symlinks resolved.

__FSEXT_chown

A file chown handler (see section chown). This is called when the ownership is to be changed for a file.

The file name passed to the handler will have all its symlinks resolved.

__FSEXT_fchmod

A file fchmod handler (see section fchmod). This is called when the permissions are to be changed for an open file.

__FSEXT_fchown

A file fchown handler (see section fchown). This is called when the ownership is to be changed for an open file.

rv points to a temporary return value pointer. If the function is emulated by the handler, the return value should be stored here, and the handler should return a nonzero value. If the handler returns zero, it is assumed to have not emulated the call, and the regular DOS I/O function will happen. The args represent the arguments passed to the original function; these point to the actual arguments on the stack, so the emulation may choose to modify them and return zero to the regular function, which will then act on the modified arguments.

A normal extension would provide these parts:

• Some function to create a connection to the extension. This may be a custom function (such as socket for networking) or an extension to open (such as /dev/ttyS0 to access the serial port).

• Initialization code that adds the open handler, if any.

• Overrides for the basic I/O functions, such as read and write. This is a single function in the extension that uses the function number parameter to select an extension function.

• The core functionality of the extension, if any.

Please note that the special Unix filenames `/dev/null' and `/dev/tty' are already mapped to the appropriate DOS names `NUL' and `CON', respectively, so you don't need to write extensions for these.

Please note that the special Unix filenames `/dev/zero' and `/dev/full' can be made available by calling the functions __install_dev_zero (see section __install_dev_zero) and __install_dev_full (see section __install_dev_full) respectively, so you don't need to write extensions for these. These are implemented using File System Extensions.

Programs using the DJGPP debug support functions in `libdbg.a' may have problems using File System Extensions, because the debug support functions use a File System Extension to track the opening and closing of files. Only the __FSEXT_open and __FSEXT_creat calls will be passed to other File System Extensions by `libdbg.a'. In other words, only fairly trivial File System Extensions can be used in programs at the same time as the debug support functions.