Mail Archives: djgpp-workers/1997/11/24/15:56:21
--=====================_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 <io.h>
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==_--
- Raw text -