Message-Id: <3.0.1.32.19971124145829.007c17e0@yacker.xiotech.com> Date: Mon, 24 Nov 1997 14:58:29 -0600 To: djgpp-workers AT delorie DOT com From: Randy Maas Subject: proposed changes to fsext documentation Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=====================_880426709==_" Precedence: bulk --=====================_880426709==_ Content-Type: text/plain; charset="us-ascii" Attached are some proposed documentation differences. Mostly this is to let the programmer know that the calls will passed to file system extensions. Randy randym AT acm DOT org --=====================_880426709==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="dup2-t.dif" *** src/libc/posix/unistd/dup2.txh~1 Mon Jul 10 01:40:46 1995 --- src/libc/posix/unistd/dup2.txh Mon Nov 24 13:39:04 1997 *************** *** 12,16 This call causes @var{new_handle} to refer to the same file and file pointer as @var{existing_handle}. If @var{new_handle} is an open file, ! it is closed. @subheading Return Value --- 12,17 ----- This call causes @var{new_handle} to refer to the same file and file pointer as @var{existing_handle}. If @var{new_handle} is an open file, ! it is closed. This works for both MSDOS files and @xref{file system ! extension} files. @subheading Return Value --=====================_880426709==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="fse_o-t.dif" *** src/libc/fsext/fse_open.txh~1 Thu Sep 19 22:37:20 1996 --- src/libc/fsext/fse_open.txh Mon Nov 24 13:36:52 1997 *************** *** 45,47 This function is part of the @ref{File System Extensions}. It is used internally to libc.a to allow extensions to get an opportunity to ! override the @code{_open} and @code{_creat} functions. --- 45,53 ----- This function is part of the @ref{File System Extensions}. It is used internally to libc.a to allow extensions to get an opportunity to ! override the @code{_open}, @code{_creat}, @code{_copy}, @code{_link}, ! and @code{_unlink} functions. ! ! @subheading Return Value ! ! Returns true (1) if an extension handled the request, false (0) ! otherwise. @var{errno} is not set if no extension handled the request. --=====================_880426709==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="fsext-t.dif" *** src/libc/fsext/fsext.txh~1 Sun Aug 31 16:39:52 1997 --- src/libc/fsext/fsext.txh Mon Nov 24 13:29:22 1997 *************** *** 15,19 @example ! int function(__FSEXT_Fnumber func_number, int *rv, va_list args); @end example --- 15,19 ----- @example ! int function(__FSEXT_Fnumber func_number, int *rv, va_list args, void* state); @end example *************** *** 24,28 @item __FSEXT_nop ! A no-op. This is currently unused by the library functions. @item __FSEXT_open --- 24,30 ----- @item __FSEXT_nop ! A no-op. This is currently unused by the library functions, except ! the function @code{_FSEXT_nop} (@pxref(_FSEXT_nop}). It may be used to ! provide execution time to the file system extension. @item __FSEXT_open *************** *** 73,76 A close handler. Called when the ``file'' should be closed. @end table --- 75,113 ----- A close handler. Called when the ``file'' should be closed. + @item __FSEXT_fcntl + + A file fcntl handler. + + @item __FSEXT_ioctl + + A file ioctl handler. + + @item __FSEXT_lseek + + A file lseek handler (@pxref{lseek}). + + @item __FSEXT_link + + A file link handler (@pxref{link}). This is most relevant to + file system extensions that emulate a directory structure. + + @item __FSEXT_unlink + + A file unlink handler (@pxref{unlink}). This is most relevant to + file system extensions that emulate a directory structure. + + @item __FSEXT_copy + + A file copy handler (@pxref{_copy}. This is called when you would + like to copy a file from one location to another (possibly local) + location. This is also called on your behalf if link() fails. This + is most relevant to file system extensions that emulate a directory + structure. + + @item __FSEXT_dup2 + + A file dup2 handler (@pxref{dup2}). This is called when two different + file descriptors are used to refer to the same open file. + @end table *************** *** 219,222 @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 --- 256,261 ----- @end example + @subheading Description + 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 *************** *** 238,239 @} @end example --- 277,356 ----- @} @end example + + @c ---------------------------------------------------------------------- + @node __FSEXT_set_handler, file system + @subheading Syntax + + @example + #include + + int __FSEXT_set_handler(__FSEXT_Function* func, void* state) + @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. Unlike @code{__FSEXT_set_function}, the + @var{state} is an additional pointer to the handlers' specific data for the + file descriptor. + + @subheading Return Value + + Zero in case of success, non-zero in case of failure (like if @var{_fd} + is negative). + + + @c ---------------------------------------------------------------------- + @node __FSEXT_get_handler, file system + @subheading Syntax + + @example + #include + + int __FSEXT_get_handler(int _fd, __FSEXT_Function** func, void** state) + @end example + + @subheading Description + + 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 Return Value + 1 if the file descriptor has a handler associated with it, 0 otherwise. + + @subheading Example + @example + _read(int fd, void *buf, int len) + @{ + void* state; + __FSEXT_Function *func; + + if (__FSEXT_get_handler(fd, &func, &state) && func) + @{ + int rv; + if (func(__FSEXT_read, &rv, &fd, state)) return rv; + @} + /@* rest of read() *@/ + @} + @end example + + @c ---------------------------------------------------------------------- + @node __FSEXT_close_all, file system + @subheading Syntax + + @example + #inlucde + + void __FSEXT_close_all (void) + @end example + + @subheading Description + @code{__FSEXT_close_all} closes all of the currently open handles. + This should be called during a programs exit phase, after libc has + @code{fclose}'d all of the files it has opened. + + --=====================_880426709==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="link-t.dif" *** src/libc/posix/unistd/link.txh~1 Mon Jul 10 01:40:48 1995 --- src/libc/posix/unistd/link.txh Mon Nov 24 13:41:48 1997 *************** *** 12,16 Because of limitations of MS-DOS, this function doesn't really link two files together. However, it simulates a real @code{link} by copying the ! file at @var{exists} to @var{new}. @subheading Return Value --- 12,18 ----- Because of limitations of MS-DOS, this function doesn't really link two files together. However, it simulates a real @code{link} by copying the ! file at @var{exists} to @var{new}. This can be over-ridden by a ! @xref{file system extension} that emulates the ``link'' operation. ! (This extension must be added via @xref{__FSEXT_add_open_handler}). @subheading Return Value --=====================_880426709==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="lseek-t.dif" *** src/libc/posix/unistd/lseek.txh~1 Mon Jul 10 01:40:48 1995 --- src/libc/posix/unistd/lseek.txh Mon Nov 24 13:43:44 1997 *************** *** 29,32 @end table @subheading Return Value --- 29,35 ----- @end table + + If @var{fd} refers to an open file system extension, the extension handler + will be called to emulate the seek. @subheading Return Value --=====================_880426709==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="remove-t.dif" *** src/libc/ansi/stdio/remove.txh~1 Mon Jul 10 01:39:48 1995 --- src/libc/ansi/stdio/remove.txh Mon Nov 24 13:46:06 1997 *************** *** 12,16 This function removes the named @var{file} from the file system. Unless you have an un-erase program, the file and its contents are gone for ! good. @subheading Return Value --- 12,16 ----- This function removes the named @var{file} from the file system. Unless you have an un-erase program, the file and its contents are gone for ! good. This may be emulated by a @xref{file system extension}. @subheading Return Value --=====================_880426709==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="unlink-t.dif" *** src/libc/posix/unistd/unlink.txh~1 Mon Jul 10 01:40:50 1995 --- src/libc/posix/unistd/unlink.txh Mon Nov 24 13:34:26 1997 *************** *** 10,14 @subheading Description ! This function removes a file from the file system. @subheading Return Value --- 10,16 ----- @subheading Description ! This function removes a file from the file system. This first calls all of ! the file system open handlers to remove the file ! (@pxref{__FSEXT_call_open_handlers}). @subheading Return Value --=====================_880426709==_ Content-Type: text/plain; charset="us-ascii" --=====================_880426709==_--