From e21f7d8d4877e4440be2ddaeb4cffc7daea1a97a Mon Sep 17 00:00:00 2001 From: Wade A Smith Date: Sun, 27 Sep 1998 16:00:18 +0000 Subject: Documented the following routines: dup, dup2, close, read, write, and fcntl.f --- doc/new_chapters/io.t | 217 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 168 insertions(+), 49 deletions(-) diff --git a/doc/new_chapters/io.t b/doc/new_chapters/io.t index 00592cbcfb..8b268afb91 100644 --- a/doc/new_chapters/io.t +++ b/doc/new_chapters/io.t @@ -10,30 +10,29 @@ @section Introduction -The -input and output primitives manager is ... +The input and output primitives manager is ... The directives provided by the input and output primitives manager are: @itemize @bullet -@item @code{pipe} - -@item @code{dup} - -@item @code{dup2} - -@item @code{close} - -@item @code{read} - -@item @code{write} - -@item @code{fcntl} - -@item @code{lseek} - -@item @code{fsynch} - -@item @code{fdatasynch} - -@item @code{aio_read} - -@item @code{aio_write} - -@item @code{lio_listio} - -@item @code{aio_error} - -@item @code{aio_return} - -@item @code{aio_cancel} - -@item @code{aio_suspend} - -@item @code{aio_fsync} - +@item @code{pipe} - YYY +@item @code{dup} - Duplicates an open file descriptor +@item @code{dup2} - Duplicates an open file descriptor +@item @code{close} - Closes a file +@item @code{read} - Reads from a file +@item @code{write} - Writes to a file +@item @code{fcntl} - Manipulates an open file descriptor +@item @code{lseek} - XXX +@item @code{fsynch} - XXX +@item @code{fdatasynch} - XXX +@item @code{aio_read} - YYY +@item @code{aio_write} - YYY +@item @code{lio_listio} - YYY +@item @code{aio_error} - YYY +@item @code{aio_return} - YYY +@item @code{aio_cancel} - YYY +@item @code{aio_suspend} - YYY +@item @code{aio_fsync} - YYY @end itemize @section Background @@ -75,13 +74,15 @@ The @subheading NOTES: @page -@subsection dup - +@subsection dup - Duplicates an open file descriptor @subheading CALLING SEQUENCE: @ifset is-C @example -int dup( +#include + +int dup(int fildes ); @end example @end ifset @@ -92,23 +93,34 @@ int dup( @subheading STATUS CODES: @table @b -@item E -The - +@item EBADF +Invalid file descriptor. +@item EINTR +Function was interrupted by a signal. +@item EMFILE +The process already has the maximum number of file descriptors open +and tried to open a new one. @end table @subheading DESCRIPTION: -@subheading NOTES: +The @code{dup} function returns the lowest numbered available file +descriptor. This new desciptor refers to the same open file as the +original descriptor and shares any locks. + +@subheading NOTES: None @page -@subsection dup2 - +@subsection dup2 - Duplicates an open file descriptor @subheading CALLING SEQUENCE: @ifset is-C @example -int dup2( +#include + +int dup2(int fildes, + int fildes2 ); @end example @end ifset @@ -119,23 +131,35 @@ int dup2( @subheading STATUS CODES: @table @b -@item E -The - +@item EBADF +Invalid file descriptor. +@item EINTR +Function was interrupted by a signal. +@item EMFILE +The process already has the maximum number of file descriptors open +and tried to open a new one. @end table @subheading DESCRIPTION: -@subheading NOTES: +@code{Dup2} creates a copy of the file descriptor @code{oldfd}. + +The old and new descriptors may be used interchangeably. They share locks, file +position pointers and flags; for example, if the file position is modified by using +@code{lseek} on one of the descriptors, the position is also changed for the other. + +@subheading NOTES: None @page -@subsection close - +@subsection close - Closes a file. @subheading CALLING SEQUENCE: @ifset is-C @example -int close( +#include + +int close(int fildes ); @end example @end ifset @@ -146,23 +170,36 @@ int close( @subheading STATUS CODES: @table @b -@item E -The - +@item EBADF +Invalid file descriptor +@item EINTR +Function was interrupted by a signal. @end table @subheading DESCRIPTION: +The @code{close()} function deallocates the file descriptor named by +@code{fildes} and makes it available for reuse. All outstanding +record locks owned by this process for the file are unlocked. + @subheading NOTES: +A signal can interrupt the @code{close()} function. In that case, +@code{close()} returns -1 with @code{errno} set to EINTR. The file +may or may not be closed. + @page -@subsection read - +@subsection read - Reads from a file. @subheading CALLING SEQUENCE: @ifset is-C @example -int read( +#include + +int read(int f ildes, + void *buf, + unsigned int nbyte ); @end example @end ifset @@ -173,23 +210,58 @@ int read( @subheading STATUS CODES: @table @b -@item E +@item EAGAIN The +@item EBADF +Invalid file descriptor +@item EINTR +Function was interrupted by a signal. +@item EIO +Input or output error @end table @subheading DESCRIPTION: -@subheading NOTES: +The @code{read()} function reads @code{nbyte} bytes from the file +associated with @code{fildes} into the buffer pointed to by @code{buf}. + +The @code{read()} function returns the number of bytes actually read +and placed in the buffer. This will be less than @code{nbyte} if: + - The number of bytes left in the file is less than @code{nbyte} + - The @code{read()} request was interrupted by a signal + - The file is a pipe or FIFO or special file with less than @code{nbytes} + immediately available for reading. + +When attempting to read from any empty pipe or FIFO: + - If no process has the pipe open for writing, zero is returned to + indicate end-of-file. + - If some process has the pipe open for writing and O_NONBLOCK is set, + -1 is returned and @code{errno} is set to EAGAIN. + - If some process has the pipe open for writing and O_NONBLOCK is clear, + @code{read()} waits for some data to be written or the pipe to be closed. + +When attempting to read from a file other than a pipe or FIFO and no data +is available + - If O_NONBLOCK is set, -1 is returned and @code{errno} is set to EAGAIN. + - If O_NONBLOCK is clear, @code{read()} waits for some data to become + available. + - The O_NONBLOCK flag is ignored if data is available. + +@subheading NOTES: None @page -@subsection write - +@subsection write - Writes to a file @subheading CALLING SEQUENCE: @ifset is-C @example -int write( +#include + +int write(int fildes, + const void *buf, + unsigned int nbytes ); @end example @end ifset @@ -200,23 +272,52 @@ int write( @subheading STATUS CODES: @table @b -@item E +@item EAGAIN +The O_NONBLOCK flag is set for a file descriptor and the process +would be delayed in the I/O operation. +@item EBADF +Invalid file descriptor +@item EFBIG The +@item EINTR +The function was interrupted by a signal. +@item EIO +Input or output error. +@item ENOSPC +No space left on disk. +@item EPIPE +Attempt to write to a pope or FIFO with no reader. @end table @subheading DESCRIPTION: -@subheading NOTES: +The @code{write()} function writes @code{nbyte} from the array pointed +to by @code{buf} into the file associated with @code{fildes}. + +If @code{nybte} is zero and the file is a regular file, the @code{write()} +function returns zero and has no other effect. If @code{nbyte} is zero +and the file is a special file, te results are not portable. + +The @code{write()} function returns the number of bytes written. This +number will be less than @code{nbytes} if there is an error. It will never +be greater than @code{nbytes}. + +@subheading NOTES: None @page -@subsection fcntl - +@subsection fcntl - Manipulates an open file descriptor @subheading CALLING SEQUENCE: @ifset is-C @example -int fcntl( +#include +#include +#include + +int fcntl(int fildes, + int cmd ); @end example @end ifset @@ -227,8 +328,24 @@ int fcntl( @subheading STATUS CODES: @table @b -@item E -The +@item EACCESS +Search permission is denied for a direcotry in a file's path +prefix. +@item EAGAIN +The O_NONBLOCK flag is set for a file descriptor and the process +would be delayed in the I/O operation. +@item EBADF +Invalid file descriptor +@item EDEADLK +An @code{fcntl} with function F_SETLKW would cause a deadlock. +@item EINTR +The functioin was interrupted by a signal. +@item EINVAL +Invalid argument +@item EMFILE +Too many file descriptor or in use by the process. +@item ENOLCK +No locks available @end table @@ -533,3 +650,5 @@ The @subheading NOTES: +This routine is not currently supported by RTEMS but could be +in a future version. -- cgit v1.2.3