RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

Documented the following routines: dup, dup2, close, read, write, and fcntl.f

Browse Source
This commit is contained in:
Wade A Smith
1998-09-27 16:00:18 +00:00
parent 389c3e904f
commit e21f7d8d48
1 changed files with 232 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

345
doc/new_chapters/io.t
View File

@@ -10,30 +10,29 @@
@section Introduction @section Introduction
The The input and output primitives manager is ...
input and output primitives manager is ...
The directives provided by the input and output primitives manager are: The directives provided by the input and output primitives manager are:
@itemize @bullet @itemize @bullet
@item @code{pipe} - @item @code{pipe} - YYY
@item @code{dup} - @item @code{dup} - Duplicates an open file descriptor
@item @code{dup2} - @item @code{dup2} - Duplicates an open file descriptor
@item @code{close} - @item @code{close} - Closes a file
@item @code{read} - @item @code{read} - Reads from a file
@item @code{write} - @item @code{write} - Writes to a file
@item @code{fcntl} - @item @code{fcntl} - Manipulates an open file descriptor
@item @code{lseek} - @item @code{lseek} - XXX
@item @code{fsynch} - @item @code{fsynch} - XXX
@item @code{fdatasynch} - @item @code{fdatasynch} - XXX
@item @code{aio_read} - @item @code{aio_read} - YYY
@item @code{aio_write} - @item @code{aio_write} - YYY
@item @code{lio_listio} - @item @code{lio_listio} - YYY
@item @code{aio_error} - @item @code{aio_error} - YYY
@item @code{aio_return} - @item @code{aio_return} - YYY
@item @code{aio_cancel} - @item @code{aio_cancel} - YYY
@item @code{aio_suspend} - @item @code{aio_suspend} - YYY
@item @code{aio_fsync} - @item @code{aio_fsync} - YYY
@end itemize @end itemize
@section Background @section Background
@@ -75,13 +74,15 @@ The
@subheading NOTES: @subheading NOTES:
@page @page
@subsection dup - @subsection dup - Duplicates an open file descriptor
@subheading CALLING SEQUENCE: @subheading CALLING SEQUENCE:
@ifset is-C @ifset is-C
@example @example
int dup( #include <unistd.h>
int dup(int fildes
); );
@end example @end example
@end ifset @end ifset
@@ -92,23 +93,175 @@ int dup(
@subheading STATUS CODES: @subheading STATUS CODES:
@table @b @table @b
@item E @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:
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 - Duplicates an open file descriptor
@subheading CALLING SEQUENCE:
@ifset is-C
@example
#include <unistd.h>
int dup2(int fildes,
int fildes2
);
@end example
@end ifset
@ifset is-Ada
@end ifset
@subheading STATUS CODES:
@table @b
@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:
@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 - Closes a file.
@subheading CALLING SEQUENCE:
@ifset is-C
@example
#include <unistd.h>
int close(int fildes
);
@end example
@end ifset
@ifset is-Ada
@end ifset
@subheading STATUS CODES:
@table @b
@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 - Reads from a file.
@subheading CALLING SEQUENCE:
@ifset is-C
@example
#include <unistd.h>
int read(int f ildes,
void *buf,
unsigned int nbyte
);
@end example
@end ifset
@ifset is-Ada
@end ifset
@subheading STATUS CODES:
@table @b
@item EAGAIN
The The
@item EBADF
Invalid file descriptor
@item EINTR
Function was interrupted by a signal.
@item EIO
Input or output error
@end table @end table
@subheading DESCRIPTION: @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 @page
@subsection dup2 - @subsection write - Writes to a file
@subheading CALLING SEQUENCE: @subheading CALLING SEQUENCE:
@ifset is-C @ifset is-C
@example @example
int dup2( #include <unistd.h>
int write(int fildes,
const void *buf,
unsigned int nbytes
); );
@end example @end example
@end ifset @end ifset
@@ -119,23 +272,52 @@ int dup2(
@subheading STATUS CODES: @subheading STATUS CODES:
@table @b @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 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 @end table
@subheading DESCRIPTION: @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 @page
@subsection close - @subsection fcntl - Manipulates an open file descriptor
@subheading CALLING SEQUENCE: @subheading CALLING SEQUENCE:
@ifset is-C @ifset is-C
@example @example
int close( #include <sys/types.h>
#include <fcntl.h>
#include <unistd.h>
int fcntl(int fildes,
int cmd
); );
@end example @end example
@end ifset @end ifset
@@ -146,89 +328,24 @@ int close(
@subheading STATUS CODES: @subheading STATUS CODES:
@table @b @table @b
@item E @item EACCESS
The Search permission is denied for a direcotry in a file's path
prefix.
@end table @item EAGAIN
The O_NONBLOCK flag is set for a file descriptor and the process
@subheading DESCRIPTION: would be delayed in the I/O operation.
@item EBADF
@subheading NOTES: Invalid file descriptor
@item EDEADLK
@page An @code{fcntl} with function F_SETLKW would cause a deadlock.
@subsection read - @item EINTR
The functioin was interrupted by a signal.
@subheading CALLING SEQUENCE: @item EINVAL
Invalid argument
@ifset is-C @item EMFILE
@example Too many file descriptor or in use by the process.
int read( @item ENOLCK
); No locks available
@end example
@end ifset
@ifset is-Ada
@end ifset
@subheading STATUS CODES:
@table @b
@item E
The
@end table
@subheading DESCRIPTION:
@subheading NOTES:
@page
@subsection write -
@subheading CALLING SEQUENCE:
@ifset is-C
@example
int write(
);
@end example
@end ifset
@ifset is-Ada
@end ifset
@subheading STATUS CODES:
@table @b
@item E
The
@end table
@subheading DESCRIPTION:
@subheading NOTES:
@page
@subsection fcntl -
@subheading CALLING SEQUENCE:
@ifset is-C
@example
int fcntl(
);
@end example
@end ifset
@ifset is-Ada
@end ifset
@subheading STATUS CODES:
@table @b
@item E
The
@end table @end table
@@ -533,3 +650,5 @@ The
@subheading NOTES: @subheading NOTES:
This routine is not currently supported by RTEMS but could be
in a future version.