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

Made cosmetic changes, and document routines in the file.

Browse Source
This commit is contained in:
Wade A Smith
1998-09-29 21:51:52 +00:00
parent f1ccfde628
commit 80189ac259
1 changed files with 202 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

250
doc/new_chapters/io.t
View File

@@ -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.
@subheading NOTES: None
@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.
@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
If @code{whence} is SEEK_CUR, the offset is set to its current location
plus offset bytes.
@item
If @code{whence} is SEEK_SET, the offset is set to @code{offset} bytes.
If @cdoe{whence} is SEEK_END, the offset is set to the size of the
file plus @cdoe{offset} bytes.
@item
If @code{whence} is SEEK_CUR, the offset is set to its current location
plus offset bytes.
The @cdoe{lseek} function allows the file offset to be set beyond the end
@item
If @code{whence} is SEEK_END, the offset is set to the size of the
file plus @code{offset} bytes.
@end itemize
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 -