summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorWade A Smith <warm38@juno.com>1998-09-27 16:00:18 +0000
committerWade A Smith <warm38@juno.com>1998-09-27 16:00:18 +0000
commite21f7d8d4877e4440be2ddaeb4cffc7daea1a97a (patch)
tree9621d1289f95b788a33fc0b5ae0daea449bbba26
parentDocumented the following routines in this file: rewinddir, pathconf, (diff)
downloadrtems-e21f7d8d4877e4440be2ddaeb4cffc7daea1a97a.tar.bz2
Documented the following routines: dup, dup2, close, read, write, and fcntl.f
-rw-r--r--doc/new_chapters/io.t217
1 files 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 <unistd.h>
+
+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 <unistd.h>
+
+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 <unistd.h>
+
+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 <unistd.h>
+
+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 <unistd.h>
+
+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 <sys/types.h>
+#include <fcntl.h>
+#include <unistd.h>
+
+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.