[src/trunk]: src/share/man/man9 New sentence, new line; grammar fixes; use mo...

[wiz <wiz%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/11f31d039cf8
branches:  trunk
changeset: 538438:11f31d039cf8
user:      wiz <wiz%NetBSD.org@localhost>
date:      Sun Oct 20 11:04:52 2002 +0000

description:
New sentence, new line; grammar fixes; use more markup.

diffstat:

 share/man/man9/cred.9       |   36 +++++++-----
 share/man/man9/dofileread.9 |   24 ++++----
 share/man/man9/file.9       |  123 +++++++++++++++++++++++--------------------
 share/man/man9/filedesc.9   |   74 ++++++++++++++-----------
 4 files changed, 139 insertions(+), 118 deletions(-)

diffs (truncated from 536 to 300 lines):

diff -r 840a9a5f3ef2 -r 11f31d039cf8 share/man/man9/cred.9
--- a/share/man/man9/cred.9     Sun Oct 20 10:50:01 2002 +0000
+++ b/share/man/man9/cred.9     Sun Oct 20 11:04:52 2002 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: cred.9,v 1.2 2002/10/20 10:46:57 wiz Exp $
+.\"     $NetBSD: cred.9,v 1.3 2002/10/20 11:04:52 wiz Exp $
 .\"
 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -39,12 +39,12 @@
 .Os
 .Sh NAME
 .Nm cred ,
+.Nm crcopy ,
+.Nm crcvt
+.Nm crdup ,
 .Nm crfree ,
+.Nm crget ,
 .Nm crhold ,
-.Nm crcopy ,
-.Nm crdup ,
-.Nm crget ,
-.Nm crcvt
 .Nd operations on user credentials
 .Sh SYNOPSIS
 .Fd #include \*[Lt]sys/ucred.h\*[Gt]
@@ -62,8 +62,9 @@
 .Fn crhold "struct ucred *cr"
 .Sh DESCRIPTION
 A process must have the appropriate user credentials for the kernel to
-perform an operation on its behalf.  The user credentials are stored
-along with the process in the following structure:
+perform an operation on its behalf.
+The user credentials are stored along with the process in the following
+structure:
 .Pp
 .Bd -literal
 struct ucred {
@@ -89,8 +90,8 @@
 system calls.
 .Pp
 References to user credentials are maintained from many different data
-structures, including processes, file descriptors and vnodes.  The
-ucred member
+structures, including processes, file descriptors and vnodes.
+The ucred member
 .Em cr_ref
 reflects the number of references to the credentials.
 .Sh FUNCTIONS
@@ -101,10 +102,11 @@
 Allocate a new credentials structure and copy the contents from
 credentials
 .Fa cr
-to the new one.  The old credentials
+to the new one.
+The old credentials
 .Fa cr
-is freed.  The reference count on the returned credentials is
-guaranteed to be one.
+are freed.
+The reference count on the returned credentials is guaranteed to be one.
 .It Fn crcvt "cr" "ucr"
 Convert from userland credentials
 .Fa ucr
@@ -114,10 +116,11 @@
 Allocate a new credentials structure and copy the contents from
 credentials
 .Fa cr
-to the new one.  The old credentials
+to the new one.
+The old credentials
 .Fa cr
-remains unchanged.  The reference count on the returned credentials is
-guaranteed to be one.
+remain unchanged.
+The reference count on the returned credentials is guaranteed to be one.
 .It Fn crfree "cr"
 Decrement the reference count on credentials
 .Fa cr .
@@ -135,4 +138,5 @@
 .Xr MALLOC 9
 and sometimes using the
 .Xr pool 9
-facility.  This cannot be right.
+facility.
+This cannot be right.
diff -r 840a9a5f3ef2 -r 11f31d039cf8 share/man/man9/dofileread.9
--- a/share/man/man9/dofileread.9       Sun Oct 20 10:50:01 2002 +0000
+++ b/share/man/man9/dofileread.9       Sun Oct 20 11:04:52 2002 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: dofileread.9,v 1.2 2002/10/20 10:46:57 wiz Exp $
+.\"     $NetBSD: dofileread.9,v 1.3 2002/10/20 11:04:52 wiz Exp $
 .\"
 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -39,8 +39,8 @@
 .Os
 .Sh NAME
 .Nm dofileread ,
+.Nm dofilereadv ,
 .Nm dofilewrite ,
-.Nm dofilereadv ,
 .Nm dofilewritev ,
 .Nd high-level file operations
 .Sh SYNOPSIS
@@ -61,19 +61,19 @@
 "const struct iovec *iovp" "int iovcnt" "off_t *offset" "int flags" \
 "register_t *retval"
 .Sh DESCRIPTION
-The function implement the underlying functionality of the
+The functions implement the underlying functionality of the
 .Xr read 2 ,
 .Xr write 2 ,
 .Xr readv 2 ,
 and
 .Xr writev 2
-system calls.  They are also used throughout the kernel as high-level
-access routines for file I/O.
+system calls.
+They are also used throughout the kernel as high-level access routines
+for file I/O.
 .Pp
 The
 .Fn dofileread
-function
-attempts to read
+function attempts to read
 .Fa nbytes
 of data from the object referenced by file entry
 .Fa fp
@@ -81,8 +81,7 @@
 .Fa buf .
 The
 .Fn dofilewrite
-function
-attempts to write
+function attempts to write
 .Fa nbytes
 of data to the object referenced by file entry
 .Fa fp
@@ -93,7 +92,7 @@
 .Fn dofilereadv
 and
 .Fn dofilewritev
-functions perform the same operations, but scatters the data with the
+functions perform the same operations, but scatter the data with the
 .Fa iovcnt
 buffers specified by the members of the
 .Fa iov
@@ -119,13 +118,14 @@
 is returned in
 .Fa *retval .
 .Sh RETURN VALUES
-Upon successful complete zero is returned, otherwise and appropriate
+Upon successful completion zero is returned, otherwise an appropriate
 error is returned.
 .Sh CODE REFERENCES
 This section describes places within the
 .Nx
 source tree where actual code implementing or utilising these file
-operations can be found.  All pathnames are relative to
+operations can be found.
+All pathnames are relative to
 .Pa /usr/src .
 .Pp
 The framework for these file operations is implemented within the file
diff -r 840a9a5f3ef2 -r 11f31d039cf8 share/man/man9/file.9
--- a/share/man/man9/file.9     Sun Oct 20 10:50:01 2002 +0000
+++ b/share/man/man9/file.9     Sun Oct 20 11:04:52 2002 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: file.9,v 1.2 2002/10/20 10:46:58 wiz Exp $
+.\"     $NetBSD: file.9,v 1.3 2002/10/20 11:04:52 wiz Exp $
 .\"
 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -62,10 +62,11 @@
 .Fn FILE_SET_MATURE "struct file *fp"
 .Sh DESCRIPTION
 The file descriptor table of a process references a file entry for
-each file used by the kernel.  See
+each file used by the kernel.
+See
 .Xr filedesc 9
-for details of the file descriptor table.  Each file entry is given
-by:
+for details of the file descriptor table.
+Each file entry is given by:
 .Pp
 .Bd -literal
 struct file {
@@ -98,95 +99,102 @@
 .Ed
 .Pp
 .Nx
-treats file entries in an object-oriented fashion after they are
-created.  Each entry specifies the object type,
+treats file entries in an object-oriented fashion after they are created.
+Each entry specifies the object type,
 .Em f_type ,
-which can have the values DTYPE_VNODE, DTYPE_SOCKET, DTYPE_PIPE and
-DTYPE_MISC.  The file entry also has a pointer
-to a data structure,
+which can have the values
+.Dv DTYPE_VNODE ,
+.Dv DTYPE_SOCKET ,
+.Dv DTYPE_PIPE
+and
+.Dv DTYPE_MISC .
+The file entry also has a pointer to a data structure,
 .Em f_data ,
-that contains information specific to the instance of the underlying
-object.  The data structure is opaque to the routines that manipulate
-the file entry.  Each entry also contains an array of function
-pointers,
+that contains information specific to the instance of the underlying object.
+The data structure is opaque to the routines that manipulate the file entry.
+Each entry also contains an array of function pointers,
 .Em f_ops ,
 that translate the generic operations on a file descriptor into the
-specific action associated with its type.  A reference to the data
-structure is passed as the first parameter to a function that
-implements a file operation.  The operations that must be implemented
-for each descriptor type are read, write, ioctl, fcntl, poll, stat and
-close.  All state associated with an instance of an object must be
-stored in that instance's data structure; the underlying objects are
-not permitted to manipulate the file entry themselves.
+specific action associated with its type.
+A reference to the data structure is passed as the first parameter to a
+function that implements a file operation.
+The operations that must be implemented for each descriptor type are
+read, write, ioctl, fcntl, poll, stat, and close.
+All state associated with an instance of an object must be stored in
+that instance's data structure; the underlying objects are not permitted
+to manipulate the file entry themselves.
 .Pp
 For data files, the file entry points to a
 .Xr vnode 9
-structure.  Pipes and sockets do not have data blocks allocated on the
-disk and are handled by the special-device filesystem that calls
-appropriate drivers to handle I/O for them.  For pipes, the file entry
-points to system block that is used during data transfer.  For
-sockets, the file entry points to a system block that is used in doing
-interprocess communications.
+structure.
+Pipes and sockets do not have data blocks allocated on the disk and
+are handled by the special-device filesystem that calls appropriate
+drivers to handle I/O for them.
+For pipes, the file entry points to a system block that is used during
+data transfer.
+For sockets, the file entry points to a system block that is used in
+doing interprocess communications.
 .Pp
 The descriptor table of a process (and thus access to the objects to
 which the descriptors refer) is inherited from its parent, so several
-different processes may reference the same file entry.  Thus, each
-file entry has a reference count,
+different processes may reference the same file entry.
+Thus, each file entry has a reference count,
 .Em f_count .
-Each time a new reference is created, the reference count is
-incremented.  When a descriptor is closed, the reference count is
-decremented.  When the reference count drops to zero, the file emtry
-is freed.
+Each time a new reference is created, the reference count is incremented.
+When a descriptor is closed, the reference count is decremented.
+When the reference count drops to zero, the file entry is freed.
 .Pp
 Some file descriptor semantics can be altered through the
 .Ar flags
 argument to the
 .Xr open 2
-system call.  These flags are recorded in
+system call.
+These flags are recorded in
 .Em f_flags
-member of the file entry.  For example, the flags record whether the
-descriptor is open for reading, writing, or both reading and writing.
+member of the file entry.
+For example, the flags record whether the descriptor is open for
+reading, writing, or both reading and writing.
 The following flags and their corresponding
 .Xr open 2
 flags are:
 .Pp
 .Bl -tag -offset indent -width FNONBLOCK -compact
 .It FAPPEND
-O_APPEND
+.Dv O_APPEND
 .It FASYNC
-O_ASYNC
+.Dv O_ASYNC
 .It O_FSYNC
-O_SYNC
+.Dv O_SYNC
 .It FNDELAY
-O_NONBLOCK
+.Dv O_NONBLOCK
 .It O_NDELAY
-O_NONBLOCK
+.Dv O_NONBLOCK