Click above to get retro games delivered to your door ever month!

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".

`__FSEXT_read'
     A ready handler.  It is called by `select' library function (*note
     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.

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 for `/dev/null' emulation).

   *  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.