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. This is called just before the library is about to issue the DOS OpenFile call on behalf of your program.

__FSEXT_creat

A create handler. Called when a file needs to be created. Note that the handler should both create the "file" and open it.

__FSEXT_read

A read handler. Called when data should be read from a "file".

__FSEXT_write

A write handler. Called to write data to a "file". On "text" files it receives the ORIGINAL (unconverted) buffer.

__FSEXT_read

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. Called when the "file" should be closed.

__FSEXT_fcntl

A file fcntl handler.

__FSEXT_ioctl

A file ioctl handler.

__FSEXT_lseek

A file lseek handler (see section lseek).

__FSEXT_link

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

__FSEXT_unlink

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

__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_fstat

A file fstat handler (see section fstat). The extension should fill in various status information about the emulated 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.

Go to the first, previous, next, last section, table of contents.