Mail Archives: djgpp-workers/1997/10/15/17:44:08
--=====================_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 <io.h>
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==_--
- Raw text -