Message-Id: <3.0.1.32.19971124145927.007bbd60@yacker.xiotech.com> Date: Mon, 24 Nov 1997 14:59:27 -0600 To: djgpp-workers AT delorie DOT com From: Randy Maas Subject: some proposed new fsext txh files Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=====================_880426767==_" Precedence: bulk --=====================_880426767==_ Content-Type: text/plain; charset="us-ascii" Attached is some proposed documentation for the "new" procedures, and an overview txh file. --=====================_880426767==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="_copy.txh" @node _copy, file system @subheading Syntax @example int _copy(const char* path1, const char* path2) @end example @subheading Description This attempts to have the named file copied from @var{path1} to @var{dest}. This functions calls @code{__FSEXT_call_open_handlers} to have an appropriate File System Extension copy a file. If no extension handles the copy, the file will be copied using binary read and writes. @subheading Return Value -1 on error. --=====================_880426767==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="_dup2.txh" @node _dup2, file system @subheading Syntax @example int _dup2(int fd, int new_fd) @end example @subheading Description This attempts to have the @var{new_fd} IO handle be the same as the @var{fd} IO handle. If @var{new_fd} is open, it will be closed. This functions calls the File System Extensions on behalf of your program, otherwise MSDOS's dup2 command is called. @code{_dup2} is emulated for file system extensions that otherwise do not support __FSEXT_dup2. This is done by making the new IO handle referred to the file system extension with the same state pointer. The new IO handle is close'd first. @subheading Return Value -1 on error, otherwise the new IO handle. --=====================_880426767==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="_fse_nop.txh" @node _FSEXT_nop, file system @subheading Syntax @example #include int _FSEXT_nop(int handle) @subheading Description This performs no operation on the IO device or file (referred to by handle). It's primary purpose is to allow the handler time to mantain internals of this entity. Usually this is connection maintenance in the networking world. @subheading Return Value 0 if everything is okay, or -1 on error. --=====================_880426767==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="_link.txh" @node _link, file system @subheading Syntax @example int _link(const char* src, const char* dest) @end example @subheading Description This attempts to have the named file copied from @var{src} to @var{dest}. This functions calls @code{__FSEXT_call_open_handlers} to have an appropriate File System Extension copy a file. If no extension or file system (such as MSDOS) handles the link, we just do a copy instead, which is as close as these systems get. Alternatively, we could always fail and return -1. I think this is slightly better. @subheading Return Value -1 on error. @end txh --=====================_880426767==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="_lseek.txh" @node _lseek, file system @subheading Syntax @example off_t _lseek(int handle, off_t offset, int whence) @end example @subheading Description This function seeks within the file associated with @var{handle}. If the handle is associated with a file system extension, that extension will be responsible for emulating the ``lseek'' functionality. Otherwise, MSDOS will be called. @subheading Return Value The number of bytes read, or -1 on error. --=====================_880426767==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="_unlink.txh" @node _unlink, file system @subheading Syntax @example int _unlink(const char* src) @end example @subheading Description This attempts to have the named file unlinked or removed from the file system. This functions calls @code{__FSEXT_call_open_handlers} to have an appropriate File System Extension remove the file. If no extension handles the removes the file, it will be remove DOS. @subheading Return Value -1 on error. --=====================_880426767==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="Ioimpl.txh" @c IO and FS Implementation documentation @c written 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 Passes control commands to an opened file @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_get_handler}. 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_Function * func = NULL; void *state = NULL; ... if (__FSEXT_get_handler(fd, &func, &state) && func) @{ int rv; if (func(__FSEXT_dup2, &rv, &fd, state)) return rv; ... @} @} @end example @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 Native DOS Command? @item _open @tab __FSEXT_open @tab Yes. @item _close @tab __FSEXT_close @tab Yes. @item _read @tab __FSEXT_read @tab Yes. @item _write @tab __FSEXT_write @tab Yes. @item ioctl @tab __FSEXT_ioctl @tab Yes. @item fcntl @tab __FSEXT_fcntl @tab No. @item _lseek @tab __FSEXT_lseek @tab Yes. @item _dup2 @tab __FSEXT_dup2 @tab Yes. @item _link @tab __FSEXT_link @tab No. @item _copy @tab __FSEXT_copy @tab No. @item _unlink @tab __FSEXT_unlink @tab Yes. @end multitable --=====================_880426767==_ Content-Type: text/plain; charset="us-ascii" --=====================_880426767==_--