Message-Id: <3.0.1.32.19971015164156.0069d4d4@yacker.xiotech.com> Date: Wed, 15 Oct 1997 16:41:56 -0500 To: djgpp-workers AT delorie DOT com From: Randy Maas Subject: 971009: FileSysExt's Rev D. p3 Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=====================_876969716==_" Precedence: bulk --=====================_876969716==_ Content-Type: text/plain; charset="us-ascii" Attached are the new .txh files Randy Maas randym AT acm DOT org --=====================_876969716==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="_def_fs.txh" @node _def_fsext, file system @syntax @example int _def_fsext(__FSEXT_Fnumber Op, int* rv, va_list Args, void* State) @end example @subheading Description This is the lowest level file system extension. By default, @code{_def_fsext} calls MSDOS (@pxref{_DOS_FS_Entry}). By providing your own @code{_def_fsext} subroutine, the basic file system services can be changed. For instance, if you were trying to implement a win32 based system (and didn't want MSDOS in the way), you would want to provide a dummy @code{_def_fsext} routine that calls your win32 interface. --=====================_876969716==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="_DOS_fd.txh" @node _DOS_alloc_fd, dos @subheading Syntax @example int _DOS_alloc_fd() @end example @subheading Description 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. @subheading Return Value Returns the handle, or -1 on error --=====================_876969716==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="_DOS_fsext.txh" @node _DOS_FS_Entry, dos @subheading Syntax @example int _DOS_FS_Entry(Op, RV, Args, State) __FSEXT_Fnumber Op; // Operation to perform. int* RV; // Return value of the operation. va_list Args; // Arguments to the operation. void* State; // Ignored @end example @subheading Description This provides a common entry point for DOS file system functions. (see @ref{File System Extensions}). The FS_Ext functions are implemented as follows: @table @code @item __FSEXT_open This is a direct connection to the MS-DOS open function call, int 0x21, %ah = 0x3d. The file is set to binary mode. @item __FSEXT_creat This is a direct connection to the MS-DOS creat function call, int 0x21, %ah = 0x3c. The file is set to binary mode. @item __FSEXT_close This is a direct connection to the MS-DOS close function call, int 0x21, %ah = 0x3e. Returns zero if the file was closed, else nonzero. @item __FSEXT_seek This is a direct connection to the MS-DOS lseek function call, int 0x21, %ah = 0x42. Returns -1 on error, the position within the file otherwise. @item __FSEXT_write This is a direct connection to the MS-DOS write function call, int 0x21, %ah = 0x40. No conversion is done on the data; it is written as raw binary data. @item __FSEXT_read This is a direct connection to the MS-DOS read function call, int 0x21, %ah = 0x3f. No conversion is done on the data; it is read as raw binary data. @item __FSEXT_dup2 This calls the MSDOS forcedup function call, (int 0x21, %ah=0x46). @end table --=====================_876969716==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="_fs_call.txh" @node __FSEXT_Call, file system @subheading Syntax @example int __FSEXT_Call(__FSEXT_Fnumber Op, int Handle, va_list Args) //Op identifies which function is to be emulated. //Handle is the handle to entity to worked on. //Args represents the arguments passed to the original function @end example @subheading Description This procedure is meant to be called by functions require some form of emulation. It calls the File System Extension associated with the Handle. If the function is not emulated by this extension, it tries a generic function emulator to carry out the operation. @subheading Return Value If it is unable to find a handler that corresponds to the handle, or the handler did not carry out the operation, @code{_FS_Call} sets @var{errno} to EINVAL and returns -1. Otherwise it returns the value from the handler. --=====================_876969716==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="_io_api.txh" @node _nop, file system @subheading Syntax @example #include int _nop(int handle) @end example @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. --=====================_876969716==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="_ipc.txh" @node IPC Overview, io IPC works by setting up a transfer area that is shared between the two processes. It is up to @xref{_ipc_write_pipe} to set this area up and to close it down. @subheading The transfer area The pipe transfer area is 256 bytes long. This size is specifically choosen so that two transfer areas (eg, "in" and "out") can fit in a single disk block, and 16 of them can fit in a single memory page. Experience has shown that most file (and pipe'd data) are only a few kilobytes in length, and usually text. In frequently, a streem of non-deterministic length is passed through a pipe. For both of these a 128 byte buffer is sufficient in many multitasking environments. However, DPMI environments usally do no support efficient task switching, which would be beneficial to drain the queue's buffers in a timely fashion. Hence variable length buffering may be required. The transfer are has a special format: @table @asis @item Reserved 2 bytes @item Tail_Flag 1 byte @item Tail_Index 1 byte @item Head_Flag 1 byte @item Head_Index 1 byte @item Data Area 250 bytes @end table --=====================_876969716==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="_copy.txh" @node _copy, file system @subheading Syntax @example int _copy(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 handles the copy, they copy will be emulated by @code{__FSEXT_Emu}. This emulates a file copy, using binary read and writes. @subheading Return Value -1 on error. --=====================_876969716==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="_ipcpipe.txh" @node _ipc_pipe, io @example ssize_t _ipc_pipe(int Transfer_FD, int filedes[2], int mode) @end example @subheading Example @example Set the stdin to be from an ipc pipe. */ int fd = open("foo", O_RDWR), iofds[2]; _ipc_pipe(fd, iofds, O_RDWR); dup2(iofds[0], 0); @end example @subheading Description Opens dual pipe transfer areas at the current file position. @code{_ipc_pipe} is actually a @xref{file system extension} that only supports the nop, close, read, write, ready and lseek (to the right from the current position for read) file system operations. @var{Transfer_FD} can refer to a MSDOS file, or file system extension file. It must, however: @enumerate @item Comply with the current settings of @var{IPC_Use_lock}. @pxref{IPC_Use_lock}. @item Support @code{lseek}, @code{write}, and @code{read}. @end enumerate @subheading Cavaets This file system extension is expected to be very time expensive due to the potential for multiple OS calls during every read and write. Closing pipes does not restore the area of the IPC file for later IPC use. @subheading Return Value -1 on error, otherwise the size of the block used within the file for managing queues. --=====================_876969716==_ 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 emulate calling @xref{FSEXT_Emu). This just does 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. --=====================_876969716==_ 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. --=====================_876969716==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="_pipe.txh" @node _pipe, file system @subheading Syntax @example void _pipe(int filedes[2]) @end example @subheading Description This opens a bi-directional pipe. That is both filedes[0] and filedes[1] can be written to and read from. Whatever is written to filedes[0] can be read from filedes[1]. Whatever is written to filedes[1] can be read from filedes[0]. @subheading Cavaets This pipe mechanism will not work directly with conventional DOS programs --=====================_876969716==_ 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 copy a file. If no extension handles the copy, they copy will be emulated by @code{__FSEXT_Emu}. @subheading Return Value -1 on error. --=====================_876969716==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="fsemu.txh" @node __FSEXT_Emu_add, file system @subheading Syntax @example void __FSEXT_Emu_add(__FSEXT_Function* Func) @end example @subheading Description This is used to add an emulator that will be called when a file system extension does not implement a function. @pxref{__FSEXT_Emu} @subheading Cavaets Does not check if the emulator has been added multiple times. @node __FSEXT_Emu, file system @subheading Syntax @example int __FSEXT_Emu(__FSEXT_Fnumber Op, int* rv, va_list Args, void* State) @end example @subheading Description This provides some a simple entry point to emulating File System Extension functions not directly implemented by an extension. The emulation of these functions is based on simpler functions, added by @xref{__FSEXT_Emu_add}. Each emulator, from the most recently added to the least, is called until one successfully carries out the operation. @subheading Return Value 1 if the operation was emulated, 0 otherwise. --=====================_876969716==_ Content-Type: text/plain; charset="us-ascii" --=====================_876969716==_--