Context Navigation

← Previous Changeset
Next Changeset →

Changeset 80189ac2 in rtems

Timestamp:

09/29/98 21:51:52 (24 years ago)

Author:

Wade A Smith <warm38@…>

Branches:

4.10, 4.11, 4.8, 4.9, 5, master

Children:

6e62b72e

Parents:

f1ccfde

Message:

Made cosmetic changes, and document routines in the file.

File:

: 1 edited

doc/new_chapters/io.t (modified) (24 diffs)

Legend:

: Unmodified
: Added
: Removed

doc/new_chapters/io.t

-                      rf1ccfde
+                      r80189ac2
 @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
 …
 @section Background
+There is currently no text in this section.
 @section Operations
+There is currently no text in this section.
 @section Directives
 …
 @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
 …
 original descriptor and shares any locks.
+@subheading NOTES: None
+@subheading NOTES:
+NONE
 @page
 …
 #include <unistd.h>
+int dup2(int fildes,
+         int fildes2
+int dup2(
+  int fildes,
+  int fildes2
 );
 @end example
 …
 @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
 …
 @code{lseek} on one of the descriptors, the position is also changed for the other.
+@subheading NOTES: None
+@subheading NOTES:
+NONE
 @page
 …
 @item EBADF
 Invalid file descriptor
 @item EINTR
 Function was interrupted by a signal.
 …
 #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:
+int read(
+  int           fildes,
+  void         *buf,
+  unsigned int  nbyte
+);
+@end example
+@end ifset
+@ifset is-Ada
+@end ifset
+@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
 …
 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.
+@subheading NOTES: None
+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.
+@item The O_NONBLOCK flag is ignored if data is available.
+@end itemize
+@subheading NOTES:
+NONE
 @page
 …
 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.
 …
 be greater than @code{nbytes}.
+@subheading NOTES: None
+@subheading NOTES:
+NONE
 @page
 …
 #include <unistd.h>
+int fcntl(int fildes,
+          int    cmd
+int fcntl(
+  int   fildes,
+  int   cmd
 );
 @end example
 …
 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
 …
 @subheading DESCRIPTION:
+@subheading NOTES:
+@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
 …
 @ifset is-C
 @example
+#include <sys/types.h>
+#include <unistd.h>
 int lseek(
   int   fildes,
 …
 repositions the file pointer fildes as follows:
+  If @code{whence} is SEEK_SET, the offset is set to @code{offset} bytes.
+  If @code{whence} is SEEK_CUR, the offset is set to its current location
+  plus offset bytes.
+  If @cdoe{whence} is SEEK_END, the offset is set to the size of the
+  file plus @cdoe{offset} bytes.
+The @cdoe{lseek} function allows the file offset to be set beyond the end
+@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.
+@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
 …
 ciated with such a device is undefined.
+@subheading NOTES: None
+@page
+@subsection fsynch -
+@subheading CALLING SEQUENCE:
+@ifset is-C
+@example
+int fsynch(
+@subheading NOTES:
+NONE
+@page
+@subsection fsync -
+@subheading CALLING SEQUENCE:
+@ifset is-C
+@example
+int fsync(
 );
 @end example
 …
 @page
 @subsection fdatasynch -
 @subheading CALLING SEQUENCE:
 @ifset is-C
 @example
 int fdatasynch(
+@subsection fdatasync -
+@subheading CALLING SEQUENCE:
+@ifset is-C
+@example
+int fdatasync(
 );
 @end example
 …
 @item ENODEV
+@code{filesystemtype} not configured in the kernel.
+@item ENOTBLK
+@code{specialfile} is not a block device (if a device was required).
+@item EBUSY
+@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
+attempted, while @code{specialfile} was not already mounted on @code{dir}.
+Or, an umount was attempted, while @code{dir} was not a mount point.
+@item EFAULT
+One of the pointer arguments points outside the user address space.
+@item ENOMEM
+The kernel could not allocate a free page to copy filenames or data into.
+@item ENAMETOOLONG
+A pathname was longer than MAXPATHLEN.
+@item ENOTDIR
+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 @code{specialfile} is located on a filesystem mounted with
+the MS_NODEV option.
+@item ENXIO
+The major number of the block device @code{specialfile} is out of
+range.
+@item EMFILE
+(In case no block device is required:) Table of dummy devices is full.
+@end table
+@subheading DESCRIPTION:
+@code{Mount} attaches the filesystem specified by @code{specialfile}
+(which is often a device name) to the directory specified by @code{dir}.
+Only the super-user may mount filesystems.
+The @code{filesystemtype} argument may take one of the values listed in
+/proc/filesystems (link "minix", "ext2", "msdos", "proc", "nfs",
+"iso9660" etc.).
+The @code{rwflag} argument has the magic number 0xCOED in the top 16 bits,
+and various mount flags in the low order 16 bits.  If the magic number is
+absent, then the last two arguments are not used.
+The @code{data} argument is interpreted by the different file systems.
+@subheading NOTES:
+NONE
+@page
+@subsection umount - Umount file systems
+@subheading CALLING SEQUENCE:
+@ifset is-C
+@example
+#include <sys/mount.h>
+#include <linux/fs.h>
+int umount(
+  const char *specialfile
+);
+@end example
+@end ifset
+@ifset is-Ada
+@end ifset
+@subheading STATUS CODES:
+@table @b
+@item EPERM
+The user is not the super-user.
+@item ENODEV
 @code{Filesystemtype} not configured in the kernel.
 …
 @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.
 …
 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 EMFILE
 (In case no block device is required:) Table of dummy devices is full.
-@end table
-@subheading DESCRIPTION:
-@code{Mount} attaches the filesystem specified by @code{specialfile}
-(which is often a device name) to the directory specified by @code{dir}.
-Only the super-user may mount filesystems.
-The @code{filesystemtype} argument may take one of the values listed in
-/proc/filesystems (link "minix", "ext2", "msdos", "proc", "nfs",
-"iso9660" etc.).
-The @code{rwflag} argument has the magic number 0xCOED in the top 16 bits,
-and various mount flags in the low order 16 bits.  If the magic number is
-absent, then the last two arguments are not used.
-The @code{data} argument is interpreted by the different file systems.
-@subheading NOTES: None
-@page
-@subsection umount - Umount file systems
-@subheading CALLING SEQUENCE:
-@ifset is-C
-@example
-#include <sys/mount.h>
-#include <linux/fs.h>
-int umount(
-  const char *specialfile
-);
-@end example
-@end ifset
-@ifset is-Ada
-@end ifset
-@subheading STATUS CODES:
-@table @b
-@item EPERM
-The user is not the super-user.
-@item ENODEV
-@code{Filesystemtype} not configured in the kernel.
-@item ENOTBLK
-@code{Specialfile} is not a block device (if a device was required).
-@item EBUSY
-@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
-attempted, while @code{specialfile} was not already mounted on @code{dir}.
-Or, an umount was attempted, while @code{dir} was not a mount point.
-@item EFAULT
-One of the pointer arguments points outside the user address space.
-@item ENOMEM
-The kernel could not allocate a free page to copy filenames or data into.
-@item ENAMETOOLONG
-A pathname was longer than MAXPATHLEN.
-@item ENOTDIR
-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
-the MS_NODEV option.
-@item ENXIO
-The major number of the block device @code{specialfile} is out of
-range.
-@item EMFILE
-(In case no block device is required:) Table of dummy devices is full.
 @end table
 …
 Only the super-user may umount filesystems.
+@subheading NOTES: None
+@subheading NOTES:
+NONE
 @page

Note: See TracChangeset for help on using the changeset viewer.

Context Navigation

Changeset 80189ac2 in rtems

Legend:

doc/new_chapters/io.t

Download in other formats: