Made cosmetic changes, and document routines in the file.

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{fsync} - XXX
-@item @code{fdatasynch} - 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 dup2(
-         int fildes2
+  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,
+int read(
-         void         *buf,
+  int           fildes,
-         unsigned int  nbyte
+  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 
+@itemize @bullet
-  - The file is a pipe or FIFO or special file with less than @code{nbytes}
+
-    immediately available for reading.
+@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,
+@itemize @bullet
-    -1 is returned and @code{errno} is set to EAGAIN.
+
-  - If some process has the pipe open for writing and O_NONBLOCK is clear,
+@item If no process has the pipe open for writing, zero is returned to 
-    @code{read()} waits for some data to be written or the pipe to be closed.
+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
+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
+@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 fcntl(
-          int    cmd
+  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
+@item 
-  plus offset bytes.
+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
+@item 
-  file plus @cdoe{offset} bytes.
+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 -