summaryrefslogtreecommitdiffstats
path: root/doc/new_chapters
diff options
context:
space:
mode:
authorWade A Smith <warm38@juno.com>1998-09-29 21:51:52 +0000
committerWade A Smith <warm38@juno.com>1998-09-29 21:51:52 +0000
commit80189ac2594b4d3591de955b624a9fe698bdb20b (patch)
tree9560ca16f2b4e5d94c2c9dd746e21d18c44ce5d7 /doc/new_chapters
parentf1ccfde6287c9381190dca37d7ef4ad4e6b02fab (diff)
downloadrtems-80189ac2594b4d3591de955b624a9fe698bdb20b.tar.bz2
Made cosmetic changes, and document routines in the file.
Diffstat (limited to 'doc/new_chapters')
-rw-r--r--doc/new_chapters/io.t250
1 files changed, 202 insertions, 48 deletions
diff --git a/doc/new_chapters/io.t b/doc/new_chapters/io.t
index e941f6489c..0345206593 100644
--- a/doc/new_chapters/io.t
+++ b/doc/new_chapters/io.t
@@ -23,8 +23,8 @@ The directives provided by the input and output primitives manager are:
@item @code{write} - Writes to a file
@item @code{fcntl} - Manipulates an open file descriptor
@item @code{lseek} - Reposition read/write file offset
-@item @code{fsynch} - XXX
-@item @code{fdatasynch} - XXX
+@item @code{fsync} - XXX
+@item @code{fdatasync} - XXX
@item @code{mount} - Mount a file system
@item @code{umount} - Unmount file systems
@item @code{aio_read} - YYY
@@ -39,8 +39,12 @@ The directives provided by the input and output primitives manager are:
@section Background
+There is currently no text in this section.
+
@section Operations
+There is currently no text in this section.
+
@section Directives
This section details the input and output primitives manager's directives.
@@ -100,8 +104,10 @@ int dup(int fildes
@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.
@@ -113,7 +119,9 @@ 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
+@subheading NOTES:
+
+NONE
@page
@subsection dup2 - Duplicates an open file descriptor
@@ -124,8 +132,9 @@ original descriptor and shares any locks.
@example
#include <unistd.h>
-int dup2(int fildes,
- int fildes2
+int dup2(
+ int fildes,
+ int fildes2
);
@end example
@end ifset
@@ -138,8 +147,10 @@ int dup2(int fildes,
@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.
@@ -153,7 +164,9 @@ 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
+@subheading NOTES:
+
+NONE
@page
@subsection close - Closes a file.
@@ -177,6 +190,7 @@ int close(int fildes
@table @b
@item EBADF
Invalid file descriptor
+
@item EINTR
Function was interrupted by a signal.
@end table
@@ -202,9 +216,10 @@ may or may not be closed.
@example
#include <unistd.h>
-int read(int f ildes,
- void *buf,
- unsigned int nbyte
+int read(
+ int fildes,
+ void *buf,
+ unsigned int nbyte
);
@end example
@end ifset
@@ -214,13 +229,19 @@ int read(int f ildes,
@subheading STATUS CODES:
+On error, this routine returns -1 and sets @code{errno} to one of
+the following:
+
@table @b
@item EAGAIN
The
+
@item EBADF
Invalid file descriptor
+
@item EINTR
Function was interrupted by a signal.
+
@item EIO
Input or output error
@@ -233,27 +254,52 @@ 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.
+
+@itemize @bullet
+
+@item The number of bytes left in the file is less than @code{nbyte}.
+
+@item The @code{read()} request was interrupted by a signal.
+
+@item The file is a pipe or FIFO or special file with less than @code{nbytes}
+immediately available for reading.
+
+@end itemize
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.
+
+
+@itemize @bullet
+
+@item If no process has the pipe open for writing, zero is returned to
+indicate end-of-file.
+
+@item If some process has the pipe open for writing and O_NONBLOCK is set,
+-1 is returned and @code{errno} is set to EAGAIN.
+
+@item 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.
+
+@end itemize
+
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.
+is available.
+
+@itemize @bullet
+
+@item If O_NONBLOCK is set, -1 is returned and @code{errno} is set to EAGAIN.
+
+@item If O_NONBLOCK is clear, @code{read()} waits for some data to become
+available.
-@subheading NOTES: None
+@item The O_NONBLOCK flag is ignored if data is available.
+
+@end itemize
+
+@subheading NOTES:
+
+NONE
@page
@subsection write - Writes to a file
@@ -280,16 +326,22 @@ int write(int fildes,
@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.
@@ -308,7 +360,9 @@ 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
+@subheading NOTES:
+
+NONE
@page
@subsection fcntl - Manipulates an open file descriptor
@@ -321,8 +375,9 @@ be greater than @code{nbytes}.
#include <fcntl.h>
#include <unistd.h>
-int fcntl(int fildes,
- int cmd
+int fcntl(
+ int fildes,
+ int cmd
);
@end example
@end ifset
@@ -336,19 +391,26 @@ int fcntl(int fildes,
@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
@@ -356,8 +418,84 @@ No locks available
@subheading DESCRIPTION:
+@code{fcntl()} performs one of various miscellaneous operations on
+@code{fd}. The operation in question is determined by @code{cmd}:
+
+@table @b
+
+@item F_DUPFD
+Makes @code{arg} be a copy of @code{fd}, closing @code{fd} first if necessary.
+
+The same functionality can be more easily achieved by using @code{dup2()}.
+
+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.
+
+The two descriptors do not share the close-on-exec flag, however. The
+close-on-exec flag of the copy is off, meaning that it will be closed on
+exec.
+
+On success, the new descriptor is returned.
+
+@item F_GETFD
+Read the close-on-exec flag. If the low-order bit is 0, the file will
+remain open across exec, otherwise it will be closed.
+
+@item F_SETFD
+Set the close-on-exec flag to the value specified by @code{arg} (only the least
+significant bit is used).
+
+@item F_GETFL
+Read the descriptor's flags (all flags (as set by open()) are returned).
+
+@item F_SETFL
+Set the descriptor's flags to the value specified by @code{arg}. Only
+@code{O_APPEND} and @code{O_NONBLOCK} may be set.
+
+The flags are shared between copies (made with @code{dup()} etc.) of the same
+file descriptor.
+
+The flags and their semantics are described in @code{open()}.
+
+@item F_GETLK, F_SETLK and F_SETLKW
+Manage discretionary file locks. The third argument @code{arg} is a pointer to a
+struct flock (that may be overwritten by this call).
+
+@item F_GETLK
+Return the flock structure that prevents us from obtaining the lock, or set the
+@code{l_type} field of the lock to @code{F_UNLCK} if there is no obstruction.
+
+@item F_SETLK
+The lock is set (when @code{l_type} is @code{F_RDLCK} or @code{F_WRLCK}) or
+cleared (when it is @code{F_UNLCK}. If lock is held by someone else, this
+call returns -1 and sets @code{errno} to EACCES or EAGAIN.
+
+@item F_SETLKW
+Like @code{F_SETLK}, but instead of returning an error we wait for the lock to
+be released.
+
+@item F_GETOWN
+Get the process ID (or process group) of the owner of a socket.
+
+Process groups are returned as negative values.
+
+@item F_SETOWN
+Set the process or process group that owns a socket.
+
+For these commands, ownership means receiving @code{SIGIO} or @code{SIGURG}
+signals.
+
+Process groups are specified using negative values.
+
+@end table
+
@subheading NOTES:
+The errors returned by @code{dup2} are different from those returned by
+@code{F_DUPFD}.
+
@page
@subsection lseek - Reposition read/write file offset
@@ -365,6 +503,9 @@ No locks available
@ifset is-C
@example
+#include <sys/types.h>
+#include <unistd.h>
+
int lseek(
int fildes,
off_t offset,
@@ -397,15 +538,22 @@ The @code{lseek} function repositions the offset of the file descriptor
The argument @code{fildes} must be an open file descriptor. @code{Lseek}
repositions the file pointer fildes as follows:
- If @code{whence} is SEEK_SET, the offset is set to @code{offset} bytes.
+@itemize @bullet
+
+@item
+If @code{whence} is SEEK_SET, the offset is set to @code{offset} bytes.
+
+@item
+If @code{whence} is SEEK_CUR, the offset is set to its current location
+plus offset bytes.
- If @code{whence} is SEEK_CUR, the offset is set to its current location
- plus offset bytes.
+@item
+If @code{whence} is SEEK_END, the offset is set to the size of the
+file plus @code{offset} bytes.
- If @cdoe{whence} is SEEK_END, the offset is set to the size of the
- file plus @cdoe{offset} bytes.
+@end itemize
-The @cdoe{lseek} function allows the file offset to be set beyond the end
+The @code{lseek} function allows the file offset to be set beyond the end
of the existing end-of-file of the file. If data is later written at this
point, subsequent reads of the data in the gap return bytes of zeros
(until data is actually written into the gap).
@@ -413,16 +561,18 @@ point, subsequent reads of the data in the gap return bytes of zeros
Some devices are incapable of seeking. The value of the pointer asso-
ciated with such a device is undefined.
-@subheading NOTES: None
+@subheading NOTES:
+
+NONE
@page
-@subsection fsynch -
+@subsection fsync -
@subheading CALLING SEQUENCE:
@ifset is-C
@example
-int fsynch(
+int fsync(
);
@end example
@end ifset
@@ -443,13 +593,13 @@ The
@subheading NOTES:
@page
-@subsection fdatasynch -
+@subsection fdatasync -
@subheading CALLING SEQUENCE:
@ifset is-C
@example
-int fdatasynch(
+int fdatasync(
);
@end example
@end ifset
@@ -499,20 +649,20 @@ int mount(
The user is not the super-user.
@item ENODEV
-@code{Filesystemtype} not configured in the kernel.
+@code{filesystemtype} not configured in the kernel.
@item ENOTBLK
-@code{Specialfile} is not a block device (if a device was required).
+@code{specialfile} is not a block device (if a device was required).
@item EBUSY
-@code{Specialfile} is already mounted. Or, it cannot be remounted
+@code{specialfile} is already mounted. Or, it cannot be remounted
read-only, because it still holds files open for writing. Or, it
cannot be mounted on @code{dir} because @code{dir} is still busy
(it is the working directory of some task, the mount point of another
device, has open files, etc.).
@item EINVAL
-@code{Specialfile had an invalid superblock. Or, a remount was
+@code{specialfile} had an invalid superblock. Or, a remount was
attempted, while @code{specialfile} was not already mounted on @code{dir}.
Or, an umount was attempted, while @code{dir} was not a mount point.
@@ -531,7 +681,7 @@ A pathname was empty or had a nonexistent component.
@item EACCES
A component of a path was not searchable. Or, mounting a read-only
filesystem was attempted without giving the MS_RDONLY flag. Or, the
-block device Specialfile is located on a filesystem mounted with
+block device @code{specialfile} is located on a filesystem mounted with
the MS_NODEV option.
@item ENXIO
@@ -560,7 +710,9 @@ absent, then the last two arguments are not used.
The @code{data} argument is interpreted by the different file systems.
-@subheading NOTES: None
+@subheading NOTES:
+
+NONE
@page
@subsection umount - Umount file systems
@@ -601,7 +753,7 @@ cannot be mounted on @code{dir} because @code{dir} is still busy
device, has open files, etc.).
@item EINVAL
-@code{Specialfile had an invalid superblock. Or, a remount was
+@code{specialfile} had an invalid superblock. Or, a remount was
attempted, while @code{specialfile} was not already mounted on @code{dir}.
Or, an umount was attempted, while @code{dir} was not a mount point.
@@ -620,7 +772,7 @@ A pathname was empty or had a nonexistent component.
@item EACCES
A component of a path was not searchable. Or, mounting a read-only
filesystem was attempted without giving the MS_RDONLY flag. Or, the
-block device Specialfile is located on a filesystem mounted with
+block device @code{specialfile} is located on a filesystem mounted with
the MS_NODEV option.
@item ENXIO
@@ -639,7 +791,9 @@ by @code{specialfile} or @code{dir}.
Only the super-user may umount filesystems.
-@subheading NOTES: None
+@subheading NOTES:
+
+NONE
@page
@subsection aio_read -