[src/trunk]: src/share/man/man9 Various fixes:

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

details:   https://anonhg.NetBSD.org/src/rev/9d12a38aea83
branches:  trunk
changeset: 584183:9d12a38aea83
user:      wiz <wiz%NetBSD.org@localhost>
date:      Sat Sep 10 21:42:32 2005 +0000

description:
Various fixes:
file-system -> file system
make (most) lines shorter than 80 chars
use more appropriate macros
fix a few typos
add two XXX for wrong sentences I'm not sure how to fix properly

diffstat:

 share/man/man9/tmpfs.9 |  510 ++++++++++++++++++++++++++----------------------
 1 files changed, 272 insertions(+), 238 deletions(-)

diffs (truncated from 927 to 300 lines):

diff -r d55eb1442d9a -r 9d12a38aea83 share/man/man9/tmpfs.9
--- a/share/man/man9/tmpfs.9    Sat Sep 10 21:38:40 2005 +0000
+++ b/share/man/man9/tmpfs.9    Sat Sep 10 21:42:32 2005 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: tmpfs.9,v 1.1 2005/09/10 19:20:48 jmmv Exp $
+.\"    $NetBSD: tmpfs.9,v 1.2 2005/09/10 21:42:32 wiz Exp $
 .\"
 .\" Copyright (c) 2005 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -39,16 +39,17 @@
 .Os
 .Sh NAME
 .Nm tmpfs
-.Nd efficient memory file-system
+.Nd efficient memory file system
 .\" =======================================================================
 .Sh DESCRIPTION
 .Nm
-is a file-system that uses
-.Nx Ns 's
-virtual memory sub-system (the well-known UVM) to store file data and
-metadata in an efficient way.
-This means that it does not follow the structure of an on-disk file-system
-because it simply does not need to.
+is a file system that uses
+.Nx Ap s
+virtual memory sub-system (the well-known UVM, see
+.Xr uvm 9 )
+to store file data and metadata in an efficient way.
+This means that it does not follow the structure of an on-disk
+file system because it simply does not need to.
 Instead, it uses memory-specific data structures and algorithms to
 automatically allocate and release resources.
 .Pp
@@ -58,7 +59,7 @@
 functions, as well as the rationale behind several design decisions that
 arose during its development.
 It is recommended that you have
-.Nm Ns 's
+.Nm Ap s
 source code available while you read this document.
 .\" -----------------------------------------------------------------------
 .Ss Mount point structure
@@ -69,31 +70,32 @@
 It has the following attributes:
 .Bl -tag
 .It Ft size_t Va tm_pages_max
-Maximum number of memory pages available for use by the file-system, set
+Maximum number of memory pages available for use by the file system, set
 during mount time.
-This variable must never be used directly as it may be bigger that the
+This variable must never be used directly as it may be bigger than the
 current amount of free memory; in the extreme case, it will hold the
-.Va SIZE_MAX
+.Dv SIZE_MAX
 value.
 Instead, use the
 .Fn TMPFS_PAGES_MAX
 macro, which is described below.
 .It Ft size_t Va tm_pages_used
-Number of pages in use by the file-system.
+Number of pages in use by the file system.
 Cannot be bigger than the value returned by
 .Fn TMPFS_PAGES_MAX
 in any case.
 .It Ft "struct tmpfs_node *" Va tm_root
-Pointer to the node representing the root directory of the file-system.
+Pointer to the node representing the root directory of the file system.
 .It Ft "struct netexport" Va tm_export
 Standard structure that describes NFS export information.
 .It Ft ino_t Va tm_nodes_max
-Maximum number of possible nodes for this file-system; set during mount time.
-We need a hard limit on the maximum number of nodes to avoid allocating
-too much of them because their objects cannot be released until the
-file-system is unmounted.
-Otherwise, we could run out of memory easily by creating lots of empty files
-and then simply removing them.
+Maximum number of possible nodes for this file system; set during
+mount time.
+We need a hard limit on the maximum number of nodes to avoid
+allocating too much of them because their objects cannot be released
+until the file system is unmounted.
+Otherwise, we could run out of memory easily by creating lots of
+empty files and then simply removing them.
 .It Ft ino_t Va tm_nodes_last
 Number of nodes currently allocated.
 This number only grows.
@@ -103,10 +105,10 @@
 Of course, the old, unused ones can be reused.
 .It Ft "struct tmpfs_node_list *" Va tm_nodes_used
 Pointer to a list of nodes that contains all the used nodes in this
-specific file-system.
+specific file system.
 .It Ft "struct tmpfs_node_list *" Va tm_nodes_avail
-Pointer to a list of nodes that contains all the available nodes in this
-specific file-system.
+Pointer to a list of nodes that contains all the available nodes
+in this specific file system.
 .It Ft "struct tmpfs_pool" Va tm_dirent_pool
 Pool of directory entries.
 See
@@ -130,99 +132,105 @@
 field.
 In order to access this attribute, the
 .Fn VFS_TO_TMPFS
-macro is provided, which, aside returning the value of the field, does several
-consistency checks (only if kernel assertions are enabled).
+macro is provided, which, aside returning the value of the field,
+does several consistency checks (only if kernel assertions are
+enabled).
 .Pp
-Whenever the file-system needs to obtain the maximum size allowed for a mount
-point, the macro
+Whenever the file system needs to obtain the maximum size allowed
+for a mount point, the macro
 .Fn TMPFS_PAGES_MAX
 is used instead of directly retrieving the value from
 .Va tm_pages_max .
 The reason is that the size of a
 .Nm
-file-system is dynamic: it lets the user store files as long as there is
-enough free memory (including physical memory and swap space).
-Therefore, the amount of memory to be used is either the limit imposed by the
-user during mount time or the amount of available memory, whichever is lower.
-To avoid consuming all the memory for a given mount point, the system will
-always reserve a minimum of
+file system is dynamic: it lets the user store files as long as
+there is enough free memory (including physical memory and swap
+space).
+Therefore, the amount of memory to be used is either the limit
+imposed by the user during mount time or the amount of available
+memory, whichever is lower.
+To avoid consuming all the memory for a given mount point, the
+system will always reserve a minimum of
 .Va TMPFS_PAGES_RESERVED
 pages, which is also taken into account by this macro.
 .Pp
 For convenience, the
 .Fn TMPFS_PAGES_AVAIL
-macro returns the available space for the given file-system.
+macro returns the available space for the given file system.
 That is, the value returned by
 .Fn TMPFS_PAGES_MAX
 minus
 .Va tm_pages_used .
 .\" -----------------------------------------------------------------------
 .Ss Internal nodes
-As any other file-system,
+As any other file system,
 .Nm
 needs a structure,
 .Ft struct tmpfs_node ,
-to represent files of any type, no matter if they are in use by the system
-(there is an vnode representing them) or not.
-They are released whenever the corresponding file is created and removed
-when the file is explicitly removed.
+to represent files of any type, no matter if they are in use by
+the system (there is an vnode representing them) or not.
+They are released whenever the corresponding file is created and
+removed when the file is explicitly removed.
 Also, given the volatile nature of
 .Nm ,
 the nodes are also released as part of the unmount process.
-to describe existing files (of any type) within the file-system.
+.\" XXX: missing half sentence?
+to describe existing files (of any type) within the file system.
 .Pp
-This structure is splitted in two parts: one holds attributes common to all
-file types and the other holds data that is only applicable to a particular
-type.
-The code must be careful to only access those attributes that are actually
-allowed by the node's type.
+This structure is split in two parts: one holds attributes common
+to all file types and the other holds data that is only applicable
+to a particular type.
+The code must be careful to only access those attributes that are
+actually allowed by the node's type.
 .Pp
 The common attributes are described below:
 .Bl -tag
 .It Ft LIST_ENTRY(tmpfs_node) Va tn_entries
 Doubly-linked list entry which links all existing nodes for a single
-file-system.
+file system.
 This is provided to ease the removal of all nodes during the unmount
 operation.
 .It Ft "enum vtype" Va tn_type
 The node's type.
 Any of
-.Sq VBLK ,
-.Sq VCHR ,
-.Sq VDIR ,
-.Sq VFIFO ,
-.Sq VLNK ,
-.Sq VREG
+.Dv VBLK ,
+.Dv VCHR ,
+.Dv VDIR ,
+.Dv VFIFO ,
+.Dv VLNK ,
+.Dv VREG ,
 and
-.Sq VSOCK
+.Dv VSOCK
 is allowed.
-The usage of vnode types instead of a custom enumeration is to make things
-simpler and faster, as we do not need to convert between two types.
+The usage of vnode types instead of a custom enumeration is to make
+things simpler and faster, as we do not need to convert between
+two types.
 .It Ft ino_t Va tn_id
 Node identifier.
 .It Ft int Va tn_status
 The node's internal status.
-This is used by several file-system operations to do modifications to the
-node in a delayed fashion.
+This is used by several file system operations to do modifications
+to the node in a delayed fashion.
 .Pp
 Its value is a bitwise OR of the following values:
 .Bl -tag -width TMPFS_NODE_ACCESSED
-.It TMPFS_NODE_ACCESSED
+.It Dv TMPFS_NODE_ACCESSED
 The file contents have been accessed.
 .Fn tmpfs_update
 will update its atime when run.
-.It TMPFS_NODE_CHANGED
+.It Dv TMPFS_NODE_CHANGED
 The node has been changed.
 .Fn tmpfs_update
 will update its ctime when run.
-.It TMPFS_NODE_MODIFIED
+.It Dv TMPFS_NODE_MODIFIED
 The file contents have been modified.
 .Fn tmpfs_update
 will update its mtime when run.
 .El
 .It Ft off_t Va tn_size
 The node size.
-It does not necessarily match the real amount of memory consumed by it.
+It does not necessarily match the real amount of memory consumed
+by it.
 .It Ft uid_t Va tn_uid
 User identifier of the file's owner.
 .It Ft gid_t Va tn_gid
@@ -247,7 +255,9 @@
 Increased each time a node is reused.
 .It Ft struct vnode * Va tn_vnode
 Pointer to the vnode that represents this file.
-May be NULL when the node is unused (that is, no vnode has been allocated for
+May be
+.Dv NULL
+when the node is unused (that is, no vnode has been allocated for
 it or it has been reclaimed).
 .It Ft struct tmpfs_node * Va tn_lookup_dirent
 Pointer to the node returned by
@@ -258,7 +268,9 @@
 .Pa \&.
 or
 .Pa .. ,
-it holds a null pointer.
+it holds a
+.Dv NULL
+pointer.
 Used to simplify the
 .Fn tmpfs_remove
 and
@@ -273,20 +285,21 @@
 Nodes are organized in two different lists.
 The
 .Em used list
-contains all nodes that are currently used by the file-system; i.e., they
-refer to existing files.
+contains all nodes that are currently used by the file system;
+i.e., they refer to existing files.
 The
 .Em available list
-contains all nodes that are currently available for use by new files.
-Nodes must be kept in this list (instead of deleting them) because we need
-to keep track of their generation number
+contains all nodes that are currently available for use by new
+files.
+Nodes must be kept in this list (instead of deleting them) because
+we need to keep track of their generation number
 .Va ( tn_gen
 field).
-Note that nodes are lazily allocated: if the available list is empty and
-we have enough space to create more nodes, they will be created and inserted
-in the used list.
-Once these are released, they will go into the available list, remaining
-alive until the file-system is unmounted.
+Note that nodes are lazily allocated: if the available list is
+empty and we have enough space to create more nodes, they will be
+created and inserted in the used list.
+Once these are released, they will go into the available list,
+remaining alive until the file system is unmounted.
 .Pp
 In order to manipulate nodes, regardless of their type, the following
 functions and macros are provided:
@@ -306,39 +319,41 @@