Message-Id: <3.0.1.32.19971017084505.007d3700@yacker.xiotech.com> Date: Fri, 17 Oct 1997 08:45:05 -0500 To: djgpp-workers AT delorie DOT com From: Randy Maas Subject: some more io and fsext documentation Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=====================_877113905==_" Precedence: bulk --=====================_877113905==_ Content-Type: text/plain; charset="us-ascii" Attached is some new (proposed) documentation that can be added to the libc manual to describe (to a programmer) how the IO and File System functions are implemented. Randy Maas randym AT acm DOT org --=====================_877113905==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="ioimpl.txh" @c IO and FS Implementation documentation @c rcm 971017 @node IO Implementation, io @subheading Description This describes the how the I/O portion of libc is designed and works. Traditionally, UNIX-ish operating systems provide some basic calls for I/O: @code{open}, @code{close}, @code{read}, @code{write}, @code{dup2}, @code{lseek}, @code{ioctl}, @code{fcntl}, @code{pipe}. @c --- The thin subroutines ------------------------------------------------- In DJGPP's libc many of these subroutines are ``thin'' -- that is, they don't process anything directly, but call a lower-level subroutine to do the work. @code{close} calls @code{_close}, @code{dup2} calls @code{_dup2} and so on. The minor exceptions are @code{open}, @code{read} and @code{write}. These check to see if the file is a text file, and if any newline translation needs to be translated for DOS. Then they call @code{_open}, @code{_read}, or @code{_write} respectively. One major exception is @code{fcntl} which does not call a routine @code{_fcntl} at all. In general, the "thin" subroutines get translated by gcc as a jmp opcode. The parameters are left on the stack, as is, to be used by the lower-level subroutine. This adds very little size to the executable image, and does little (outside of a cache miss) to slow the processor down. The thin nature allows for programmers -- at their own risk -- to replace the @code{_open}, @code{_close}, etc. routines with their own and still be able to use many of the compiled library's functions. Of course, the recommended method to add functionality to @code{_open}, @code{_close}, etc. is through @xref{file system extensions}. @pxref{File System Implementation} @c --- IO to FS translation table ------------------------------------------- @subheading How I/O calls translate into File System calls @c table formating may need tinkering @multitable @columnfractions .15 .15 .60 @item IO Call @tab FS Call @tab Description @item @xref{open} @tab @xref{_open} @tab To open a named file for reading or writing @item @xref{close} @tab @xref{_close} @tab To close a previously opened file @item @xref{read} @tab @xref{_read} @tab To read data from a previously opened file @item @xref{write} @tab @xref{_write} @tab To write data to a previously opened file @item @xref{dup2} @tab @xref{_dup2} @tab Set a second file descriptor to refer to the same things as the first. @item @xref{lseek} @tab @xref{_lseek} @tab Moves the current position indicator for the file. @item @xref{ioctl} @tab @tab @item @xref{fcntl} @tab @tab This provides a standard set of file control mechanisms (manipulating the file descriptor, setting and releasing locks, etc.) @item @xref{pipe} @tab @xref{_pipe} @tab This creates a bi-directional communication channel. @end multitable @c --- Redirection to File System Extensions -------------------------------- @node File System Implementation, file system @subheading Description In DJGPP's libc many of the file system subroutines are ``thin'' -- that is, they don't process anything directly, but call a lower-level subroutine to do the work. These functions translate as follows: @c table may need some tinkering @multitable @columnfractions .15 .15 .60 @item FS Call @tab Becomes @tab Description @item @xref{link} @tab @xref{_link} @tab Allows for two differently named files to refer to the same data. @item @xref{unlink} @tab @xref{_unlink} @tab The named file will cease to exist. @item @xref{remove} @tab @xref{_unlink} @tab The named file will cease to exist. @end multitable In general, the "thin" subroutines get translated by gcc as a jmp opcode. The parameters are left on the stack, as is, to be used by the lower-level subroutine. This adds very little size to the executable image, and does little (outside of a cache miss) to slow the processor down. Other file system routines call the file system extension. These will be discussed shortly. @subheading Redirection to File System Extensions The low-level routines most often just call the file system extensions to implement the function. Often this is through a common procedure called @code{__FSEXT_Call}. For example, @code{_dup2} does this by: @example int _dup2(int fd, int new_fd) @{ va_list Args = &fd; /* Trick to get the arguments list */ ... __FSEXT_Call(__FSEXT_dup2, fd, Args); @} @end example As few of these provide functionality to emulate the operation, in the event that the extension does not. To prevent unneccessary code from being linked in, the emulator is added to the table of emulators -- but only the first time the particular functions is called. The missing code from above looks like: @example if (!inited) __FSEXT_Emu_add(_dup2_emu); inited = 1; @end example This way the @code{dup2} emulator will be linked into a program only if the programmer uses @code{dup2}. @subheading How File System calls translate into File System Extension calls @c table may need some tinkering @multitable @columnfractions .4 .45 .15 @item Procedure @tab FSEXT Operation @tab Emulated? @item _open @tab __FSEXT_open @tab No. @item _close @tab __FSEXT_close @tab No. @item _read @tab __FSEXT_read @tab No. @item _write @tab __FSEXT_write @tab No. @item ioctl @tab __FSEXT_ioctl @tab No. @item fcntl @tab __FSEXT_fcntl @tab No. @item _lseek @tab __FSEXT_lseek @tab No. @item _dup2 @tab __FSEXT_dup2 @tab Yes @item _link @tab __FSEXT_link @tab Yes @item _copy @tab __FSEXT_copy @tab Yes @item _unlink @tab __FSEXT_unlink @tab Yes @end multitable --=====================_877113905==_ Content-Type: text/plain; charset="us-ascii" --=====================_877113905==_--