PC Extra Super CD 1998 January/PCPLUS131.iso/DJGPP/V2/DJLSR201.ZIP/src/libc/fsext/fsext.txh

Text File | 1996-09-19 | 6.5 KB | 239 lines

@node File System Extensions, file system

@subheading 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 @i{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:

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

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

@table @code
@item __FSEXT_nop

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

@item __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.

@item __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.

@item __FSEXT_read

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

@item __FSEXT_write

A write handler.  Called to write data to a ``file''.

@item __FSEXT_read

A ready handler.  It is called by @code{select} library function
(@pxref{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 @code{<sys/fsext.h>}):

@table @code

@item __FSEXT_ready_read

The ``file'' is ready for reading.

@item __FSEXT_ready_write

The ``file'' is ready for writing.

@item __FSEXT_ready_error

The ``file'' has an error condition set.

@end table

@item __FSEXT_close

A close handler.  Called when the ``file'' should be closed.

@end table


@var{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 @var{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:

@itemize @bullet

@item

Some function to create a connection to the extension.  This may be a
custom function (such as @code{socket} for networking) or an extension
to open (such as for @code{/dev/null} emulation).

@item

Initialization code that adds the open handler, if any.

@item

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

@item

The core functionality of the extension, if any.

@end itemize

@c ----------------------------------------------------------------------
@node __FSEXT_alloc_fd, file system
@subheading Syntax

@example
#include <sys/fsext.h>

int __FSEXT_alloc_fd(__FSEXT_Function *_function);
@end example

@subheading Description

This function is part of the @ref{File System Extensions}.  It is used
by extensions that fully emulate the I/O functions, and thus don't
have a corresponding DOS file handle.  This function opens DOS's
@samp{NUL} device, so as to allocate a handle that DOS won't then reuse.
It also assigns the handler function for that descriptor.

The module is responsible for calling @code{_close} on the descriptor
after setting the handler function to zero in the extended close
handler.

@subheading Example

@example

int socket()
@{
  int fd = __FSEXT_alloc_fd(socket_handler);
  init_socket(fd);
  return fd;
@}
@end example


@c ----------------------------------------------------------------------
@node __FSEXT_set_function, file system
@subheading Syntax

@example
#include <sys/fsext.h>

int __FSEXT_set_function(int _fd, __FSEXT_Function *_function);
@end example

@subheading Description

This function is part of the @ref{File System Extensions}.  It is used
to set the handler function for those extensions that use DOS files
for I/O.  One situation where you might need this is when you must catch
output to the terminal and play some tricks with it, like colorize it or
redirect it to another device.

@subheading Return Value

Zero in case of success, non-zero in case of failure (like if @var{_fd}
is negative).

@subheading Example

@example

#include <sys/fsext.h>
#include <conio.h>

/* A simple example of a write handler which converts DOS I/O to the
   screen into direct writes to video RAM.  */
static int
my_screen_write (__FSEXT_Fnumber func, int *retval, va_list rest_args)
@{
  char *buf, *mybuf;
  size_t buflen;
  int fd = va_arg (rest_args, int);

  if (func != __FSEXT_write || !isatty (fd))
    return 0;  /* and the usual DOS call will be issued */

  buf = va_arg (rest_args, char *);
  buflen = va_arg (rest_args, size_t);
  mybuf = alloca (buflen + 1);
  memcpy (mybuf, buf, buflen);
  mybuf[buflen] = '\0';
  cputs (mybuf);
  *retval = buflen;
  return 1;  /* meaning that we handled the call */
@}

/* Install our handler.  The `attribute constructor' causes this
   function to be called by the startup code.  */
static void __attribute__((constructor))
install_screen_write_handler (void)
@{
  __FSEXT_set_function (fileno (stdout), my_screen_write);
@}

@end example


@c ----------------------------------------------------------------------
@node __FSEXT_get_function, file system
@subheading Syntax

@example
#include <sys/fsext.h>

__FSEXT_Function *__FSEXT_get_function(int _fd);
@end example

This function is part of the @ref{File System Extensions}.  It is used
internal to libc.a to redirect I/O requests to the appropriate
extensions.

@subheading Example

@example
_read(int fd, void *buf, int len)
@{
  __FSEXT_Function *func = __FSEXT_get_function(fd);
  if (func)
  @{
    int rv;
    if (func(__FSEXT_read, &rv, &fd))
      return rv;
  @}
  /* rest of read() */
@}
@end example