Message-Id: <3.0.1.32.19970923144930.006ad64c@yacker.xiotech.com> Date: Tue, 23 Sep 1997 14:49:30 -0500 To: djgpp-workers AT delorie DOT com From: Randy Maas Subject: Rev .c of proposed fsext changes (part 3) Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=====================_875062170==_" Precedence: bulk --=====================_875062170==_ Content-Type: text/plain; charset="us-ascii" These are the txh files that couldn't be diff'd. Randy Maas randym AT acm DOT org --=====================_875062170==_ 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. --=====================_875062170==_ 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 --=====================_875062170==_ 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. @end table --=====================_875062170==_ 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. --=====================_875062170==_ 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. --=====================_875062170==_ 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. --=====================_875062170==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="fsemu.txh" @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. The emulation of these functions is based on simpler functions usually provided by the File System Extensions. Currently the following functions are emulated: @table @code @item __FSEXT_create @code{creat} can be simulate easily by most @code{open} functions -- just open the file, but with settings to create (@code{O_CREAT}) if it does not exist, and truncate (@code{O_TRUNC}) if it does exist. (Note: this is a kludge.) @item __FSEXT_link For those systems that can't really do a link (such as MSDOS), 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. We call _copy instead of emulating it here in the hopes that a File System Extension will properly handle the copying. If not, it will be reflected back, and we will emulate it below in __FSEXT_copy. @item __FSEXT_copy This emulates a file copy, using binary read and writes. Some operating systems provide a copy function. Others, like DOS, do not. (Why would an OS want to provide "copy" functionality? Consider Novell's Netware. To copy a file one one network drive to another, this routine will have the data sequentially sent down the network and and then send the data right back. Acceptable for one file, but not for a large number of files. If the OS handled it, it could send a command to the Netware server and do the copy right there. This is clearly more efficient, so it is common for network operating systems -- and others -- to provide copy functions as part of their file system API.) @item __FSEXT_pread @code{pread} is simulated by @code{lseek}'ing to the appopriate place in the file, and read the data. Upon completion, it @code{lseek}'s back to its previous position. This will fail if the file does not support @code{lseek}. @item __FSEXT_pwrite @code{pread} is simulated by @code{lseek}'ing to the appopriate place in the file, and writing the data. Upon completion, it @code{lseek}'s back to its previous position. This will fail if the file does not support @code{lseek}. @end Parse the arguments Return the IO to its previous position. @txh @end table @subheading Notes Unfortunately there is no easy way to add functionality to the emulator. @subheading See Also @pxref{File System Extensions} --=====================_875062170==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="pread.txh" @node pread, io @subheading Syntax @example #include ssize_t pread (Handle, Buffer, Size, Ofs) int Handle; // The IO handle to read from char* Buffer; // The buffer to read data into size_t Size; // The size of the buffer off_t Ofs; // The offset within the IO handle to read from @end example @subheading Description This reads from the specified position within the IO channel. It does this in such a way that the current IO position is not affected. @subheading Cavaets Attempting to use @code{pread} on a IO channel that is incapable of seeking will result in an error. @subheading Returns On success, the number of bytes actually read. --=====================_875062170==_ Content-Type: text/plain; charset="us-ascii" Content-Disposition: attachment; filename="pwrite.txh" @node pwrite, io @subheading Syntax @example #include ssize_t pwrite(Handle, Buffer, Size, Ofs) int Handle; // The IO handle to write to const char* Buffer; // The buffer to write data into size_t Size; // The size of the buffer off_t Ofs; // The offset within the IO handle to write to @end example @subheading Description This writes to the specified position within the IO channel. It does this in such a way that the current IO position is not affected. @subheading Cavaets Attempting to use @code{pwrite} on a IO channel that is incapable of seeking will result in an error. @subheading Returns On success, the number of bytes actually read. --=====================_875062170==_ Content-Type: text/plain; charset="us-ascii" --=====================_875062170==_--