diff options
217 files changed, 1440 insertions, 758 deletions
diff --git a/lib/libalias/libalias.3 b/lib/libalias/libalias.3 index 7a582db..bb77e30 100644 --- a/lib/libalias/libalias.3 +++ b/lib/libalias/libalias.3 @@ -196,7 +196,7 @@ mode bit is set. This bit should be set when the packet aliasing host originates network traffic as well as forwards it. When the packet aliasing host is waiting for a connection from an unknown -host address or unknown port number (e.g. an FTP data connection), this +host address or unknown port number (e.g.\& an FTP data connection), this mode bit specifies that a socket be allocated as a place holder to prevent port conflicts. Once a connection is established, usually within a minute or so, the socket @@ -237,7 +237,7 @@ possible to use a hole for another connection. A hole is removed when the connection that uses it dies. To cater to unexpected death of a program using .Nm -(e.g. kill -9), +(e.g.\& kill -9), changing the state of the flag will clear the entire firewall range allocated for holes. This will also happen on the initial call to @@ -560,7 +560,7 @@ For links created with .Fn LibAliasRedirectAddr , the .Fa port -argument is ignored and could have any value, e.g. htons(~0). +argument is ignored and could have any value, e.g.\& htons(~0). .Pp This function returns 0 on success, \-1 otherwise. .Ed @@ -571,15 +571,15 @@ This function returns 0 on success, \-1 otherwise. This function marks the specified static redirect rule entered by .Fn LibAliasRedirectPort as dynamic. -This can be used to e.g. dynamically redirect a single TCP connection, +This can be used to e.g.\& dynamically redirect a single TCP connection, after which the rule is removed. Only fully specified links can be made dynamic. (See the .Sx STATIC AND DYNAMIC LINKS and .Sx PARTIALLY SPECIFIED ALIASING LINKS -sections below for a definition of static vs. dynamic, -and partially vs. fully specified links.) +sections below for a definition of static vs.\& dynamic, +and partially vs.\& fully specified links.) .Pp This function returns 0 on success, \-1 otherwise. .Ed @@ -878,7 +878,7 @@ and .Fa maxpacketsize is provided for error checking purposes. This function can be used if an already-aliased packet needs to have its -original IP header restored for further processing (eg. logging). +original IP header restored for further processing (e.g.\& logging). .Ed .Sh BUGS PPTP aliasing does not work when more than one internal client diff --git a/lib/libarchive/archive_entry.3 b/lib/libarchive/archive_entry.3 index a0eba79..9629b2d 100644 --- a/lib/libarchive/archive_entry.3 +++ b/lib/libarchive/archive_entry.3 @@ -299,7 +299,8 @@ recognized. .Xr strtofflags 3 , which stops parsing at the first unrecognized name.) .Ss ACL Handling -XXX This needs serious help. XXX +XXX This needs serious help. +XXX .Pp An .Dq Access Control List diff --git a/lib/libarchive/archive_read.3 b/lib/libarchive/archive_read.3 index 15910c9..d1a6e58 100644 --- a/lib/libarchive/archive_read.3 +++ b/lib/libarchive/archive_read.3 @@ -269,7 +269,8 @@ and objects can be found in the overview manual page for .Xr libarchive 3 . .Sh EXAMPLE -The following illustrates basic usage of the library. In this example, +The following illustrates basic usage of the library. +In this example, the callback functions are simply wrappers around the standard .Xr open 2 , .Xr read 2 , diff --git a/lib/libarchive/archive_write.3 b/lib/libarchive/archive_write.3 index a4a135f..a6fd8da 100644 --- a/lib/libarchive/archive_write.3 +++ b/lib/libarchive/archive_write.3 @@ -225,7 +225,8 @@ overview. Compression support is built-in to libarchive, which uses zlib and bzlib to handle gzip and bzip2 compression, respectively. .Sh EXAMPLE -The following sketch illustrates basic usage of the library. In this example, +The following sketch illustrates basic usage of the library. +In this example, the callback functions are simply wrappers around the standard .Xr open 2 , .Xr write 2 , diff --git a/lib/libbluetooth/bluetooth.3 b/lib/libbluetooth/bluetooth.3 index 5980027..9c81f6c 100644 --- a/lib/libbluetooth/bluetooth.3 +++ b/lib/libbluetooth/bluetooth.3 @@ -101,7 +101,7 @@ should point to an address which is .Fa len bytes long, in binary form -(i.e. not an Bluetooth BD_ADDR in human readable +(i.e., not an Bluetooth BD_ADDR in human readable .Tn ASCII form). The diff --git a/lib/libbsnmp/modules/snmp_netgraph/snmp_netgraph.3 b/lib/libbsnmp/modules/snmp_netgraph/snmp_netgraph.3 index f470496..81cdd74 100644 --- a/lib/libbsnmp/modules/snmp_netgraph/snmp_netgraph.3 +++ b/lib/libbsnmp/modules/snmp_netgraph/snmp_netgraph.3 @@ -135,15 +135,18 @@ The .Nm snmp_netgraph module implements a number of tables and scalars that enable remote access to -the netgraph subsystem. It also exports a number of global variables and +the netgraph subsystem. +It also exports a number of global variables and functions, that allow other modules to easily use the netgraph system. .Pp If upon start up of the module the variable .Va begemotNgControlNodeName is not empty the module opens a netgraph socket and names that socket node. If the variable is empty, the socket is created, as soon as the variable is -written with a non-empty name. The socket can be closed by writing an empty -string to the variable. The socket itself and its name are available in +written with a non-empty name. +The socket can be closed by writing an empty +string to the variable. +The socket itself and its name are available in .Va snmp_node and .Va snmp_nodename . @@ -169,7 +172,8 @@ is the node specific command cookie, .It Fa opcode is the node specific code for the operation to performa, .It Fa arg -is a pointer to the message itself. This message must start with a +is a pointer to the message itself. +This message must start with a .Vt struct ng_mesg . .It Fa arglen is the overall length of the message (header plus arguments). @@ -178,8 +182,10 @@ The functions return the message id that can be used to match incoming responses or -1 if an error occurs. .Pp Another class of functions is used to send a control message and to wait for -a matching response. Note, that this operation blocks the daemon, so use it -only if you are sure that the response will happen. There is a maximum timeout +a matching response. +Note, that this operation blocks the daemon, so use it +only if you are sure that the response will happen. +There is a maximum timeout that is configurable in the MIB variable .Va begemotNgTimeout . Other messages arriving while the functions are waiting for the response are @@ -201,9 +207,11 @@ and waits for a matching response. .Pp All three functions take the same arguments as the .Fn ng_output* -functions. The functions return the reponse message in a buffer allocated by +functions. +The functions return the reponse message in a buffer allocated by .Xr malloc 3 -or NULL in case of an error. The maximum size of the response buffer can be +or NULL in case of an error. +The maximum size of the response buffer can be configured in the variable .Va begemotNgResBufSiz . .Pp @@ -212,16 +220,19 @@ A data message can be send with the function This function takes the name of the .Va snmp_node Ns 's hook through which to send the data, a pointer to the message buffer and -the size of the message. It returns -1 if an error happens. +the size of the message. +It returns -1 if an error happens. .Ss ASYNCHRONOUS CONTROL AND DATA MESSAGES A module can register functions to asynchronuosly receive control and data message. .Pp The function .Fn ng_register_cookie -registers a control message receive function. If a control message is +registers a control message receive function. +If a control message is received, that is not consumed by the dialog functions, the list of registerred -control message receive functions is scanned. If the cookie in the received +control message receive functions is scanned. +If the cookie in the received message is the same as the .Fa cookie argument to the @@ -238,7 +249,8 @@ is called with a pointer to the received message, the hook on which the message was received (or NULL if it was received not on a hook), the id of the sender's node and the .Fa uarg -argument of the registration call. The handler function should not modify +argument of the registration call. +The handler function should not modify the contents of the message, because more than one function may be registered to the same cookie and node id. .Pp @@ -253,12 +265,14 @@ A module can call .Fn ng_register_hook to register a callback for data messages on one of the .Va snmp_node Ns 's -hooks. If a data message is received on that hook, the callback function +hooks. +If a data message is received on that hook, the callback function .Fa func is called with the hook name, a pointer to the data message, the size of the message and the argument .Fa uarg -to the registration function. The message should be treated as read-only. +to the registration function. +The message should be treated as read-only. A data message registration can be undone by calling .Fn ng_unregister_hook with the return value of the registration call. @@ -291,7 +305,8 @@ and writes it to the buffer pointed to by .Fa name . This buffer should be at least .Li NG_NODESIZ -bytes long. The function returns the node id or 0 if the +bytes long. +The function returns the node id or 0 if the node is not found .Pp The function @@ -302,7 +317,8 @@ and writes it to the buffer pointed to by .Fa type . This buffer should be at least .Li NG_TYPESIZ -bytes long. The function returns the node id or 0 if the +bytes long. +The function returns the node id or 0 if the node is not found. .Pp The function @@ -315,8 +331,10 @@ to the buffer pointed to by .Fa peer_hook . The buffer should be at least .Li NG_HOOKSIZ -bytes long. The function returns 0 if the node and the hook is found, -1 -otherwise. The function skips intermediate tee nodes (see +bytes long. +The function returns 0 if the node and the hook is found, -1 +otherwise. +The function skips intermediate tee nodes (see .Xr ng_tee 4 ). .Pp The function @@ -348,7 +366,8 @@ of node .Fa id . If .Fa name -is not NULL the new node is named with this name. The function returns +is not NULL the new node is named with this name. +The function returns The node id of the new node or 0 if an error happens. .Pp The functions diff --git a/lib/libc/compat-43/gethostid.3 b/lib/libc/compat-43/gethostid.3 index 6a7c98b..8d58004 100644 --- a/lib/libc/compat-43/gethostid.3 +++ b/lib/libc/compat-43/gethostid.3 @@ -53,8 +53,10 @@ The function establishes a 32-bit identifier for the current processor that is intended to be unique among all -UNIX systems in existence. This is normally a DARPA Internet -address for the local machine. This call is allowed only to the +UNIX systems in existence. +This is normally a DARPA Internet +address for the local machine. +This call is allowed only to the super-user and is normally performed at boot time. .Pp The diff --git a/lib/libc/compat-43/sigvec.2 b/lib/libc/compat-43/sigvec.2 index 230e4b3..a3f95e2 100644 --- a/lib/libc/compat-43/sigvec.2 +++ b/lib/libc/compat-43/sigvec.2 @@ -60,7 +60,8 @@ This interface is made obsolete by The system defines a set of signals that may be delivered to a process. Signal delivery resembles the occurrence of a hardware interrupt: the signal is blocked from further occurrence, the current process -context is saved, and a new one is built. A process may specify a +context is saved, and a new one is built. +A process may specify a .Em handler to which a signal is delivered, or specify that a signal is to be .Em blocked @@ -69,7 +70,8 @@ or A process may also specify that a default action is to be taken by the system when a signal occurs. Normally, signal handlers execute on the current stack -of the process. This may be changed, on a per-handler basis, +of the process. +This may be changed, on a per-handler basis, so that signals are taken on a special .Em "signal stack" . .Pp @@ -82,8 +84,10 @@ but other signals may yet occur. A global .Em "signal mask" defines the set of signals currently blocked from delivery -to a process. The signal mask for a process is initialized -from that of its parent (normally 0). It +to a process. +The signal mask for a process is initialized +from that of its parent (normally 0). +It may be changed with a .Xr sigblock 2 or @@ -92,12 +96,15 @@ call, or when a signal is delivered to the process. .Pp When a signal condition arises for a process, the signal is added to a set of -signals pending for the process. If the signal is not currently +signals pending for the process. +If the signal is not currently .Em blocked -by the process then it is delivered to the process. When a signal +by the process then it is delivered to the process. +When a signal is delivered, the current state of the process is saved, a new signal mask is calculated (as described below), -and the signal handler is invoked. The call to the handler +and the signal handler is invoked. +The call to the handler is arranged so that if the signal handling routine returns normally the process will resume execution in the context from before the signal's delivery. @@ -119,7 +126,8 @@ in the signal mask associated with the handler to be invoked. The .Fn sigvec function -assigns a handler for a specific signal. If +assigns a handler for a specific signal. +If .Fa vec is non-zero, it specifies a handler routine and mask diff --git a/lib/libc/db/man/btree.3 b/lib/libc/db/man/btree.3 index 9c5fbfe..5712d18 100644 --- a/lib/libc/db/man/btree.3 +++ b/lib/libc/db/man/btree.3 @@ -87,7 +87,7 @@ The flag value is specified by any of the following values: .Bl -tag -width indent .It Dv R_DUP -Permit duplicate keys in the tree, i.e. permit insertion if the key to be +Permit duplicate keys in the tree, i.e., permit insertion if the key to be inserted already exists in the tree. The default behavior, as described in .Xr dbopen 3 , @@ -145,7 +145,7 @@ Not currently implemented. .It Va minkeypage The minimum number of keys which will be stored on any single page. This value is used to determine which keys will be stored on overflow -pages, i.e. if a key or data item is longer than the pagesize divided +pages, i.e., if a key or data item is longer than the pagesize divided by the minkeypage value, it will be stored on overflow pages instead of in the page itself. If diff --git a/lib/libc/db/man/dbopen.3 b/lib/libc/db/man/dbopen.3 index e68e3b5..e247563 100644 --- a/lib/libc/db/man/dbopen.3 +++ b/lib/libc/db/man/dbopen.3 @@ -335,7 +335,7 @@ or .Va sync routines. Modifications to the database during a sequential scan will be reflected -in the scan, i.e. records inserted behind the cursor will not be returned +in the scan, i.e., records inserted behind the cursor will not be returned while records inserted in front of the cursor will be returned. .Pp The diff --git a/lib/libc/db/man/recno.3 b/lib/libc/db/man/recno.3 index 9a786dd..726f74f 100644 --- a/lib/libc/db/man/recno.3 +++ b/lib/libc/db/man/recno.3 @@ -190,7 +190,7 @@ field of the key should be the size of that type. Because there can be no meta-data associated with the underlying .Nm access method files, any changes made to the default values -(e.g. fixed record length or byte separator value) must be explicitly +(e.g.\& fixed record length or byte separator value) must be explicitly specified each time the file is opened. .Pp In the interface specified by diff --git a/lib/libc/gen/basename.3 b/lib/libc/gen/basename.3 index 5da5e4f7..6f03b4a 100644 --- a/lib/libc/gen/basename.3 +++ b/lib/libc/gen/basename.3 @@ -100,4 +100,4 @@ function first appeared in and .Fx 4.2 . .Sh AUTHORS -Todd C. Miller <Todd.Miller@courtesan.com> +.An "Todd C. Miller" Aq Todd.Miller@courtesan.com diff --git a/lib/libc/gen/directory.3 b/lib/libc/gen/directory.3 index ce1ead7..5cd6667 100644 --- a/lib/libc/gen/directory.3 +++ b/lib/libc/gen/directory.3 @@ -78,7 +78,8 @@ with it and returns a pointer to be used to identify the .Em directory stream -in subsequent operations. The pointer +in subsequent operations. +The pointer .Dv NULL is returned if .Fa filename @@ -89,7 +90,8 @@ enough memory to hold the whole thing. The .Fn readdir function -returns a pointer to the next directory entry. It returns +returns a pointer to the next directory entry. +It returns .Dv NULL upon reaching the end of the directory or detecting an invalid .Fn seekdir @@ -102,7 +104,8 @@ provides the same functionality as .Fn readdir , but the caller must provide a directory .Fa entry -buffer to store the results in. If the read succeeds, +buffer to store the results in. +If the read succeeds, .Fa result is pointed at the .Fa entry ; @@ -126,7 +129,8 @@ are good only for the lifetime of the .Dv DIR pointer, .Fa dirp , -from which they are derived. If the directory is closed and then +from which they are derived. +If the directory is closed and then reopened, prior values returned by .Fn telldir will no longer be valid. diff --git a/lib/libc/gen/dirname.3 b/lib/libc/gen/dirname.3 index d66eeaaf..eac042d 100644 --- a/lib/libc/gen/dirname.3 +++ b/lib/libc/gen/dirname.3 @@ -107,4 +107,4 @@ function first appeared in and .Fx 4.2 . .Sh AUTHORS -Todd C. Miller <Todd.Miller@courtesan.com> +.An "Todd C. Miller" Aq Todd.Miller@courtesan.com diff --git a/lib/libc/gen/dladdr.3 b/lib/libc/gen/dladdr.3 index 84ea1b5..414fa49 100644 --- a/lib/libc/gen/dladdr.3 +++ b/lib/libc/gen/dladdr.3 @@ -93,7 +93,8 @@ The function first appeared in the Solaris operating system. .Sh BUGS This implementation is bug-compatible with the Solaris -implementation. In particular, the following bugs are present: +implementation. +In particular, the following bugs are present: .Bl -bullet .It If @@ -101,12 +102,15 @@ If lies in the main executable rather than in a shared library, the pathname returned in .Va dli_fname -may not be correct. The pathname is taken directly from +may not be correct. +The pathname is taken directly from .Va argv[0] -of the calling process. When executing a program specified by its +of the calling process. +When executing a program specified by its full pathname, most shells set .Va argv[0] -to the pathname. But this is not required of shells or guaranteed +to the pathname. +But this is not required of shells or guaranteed by the operating system. .It If @@ -115,10 +119,12 @@ is of the form .Va &func , where .Va func -is a global function, its value may be an unpleasant surprise. In +is a global function, its value may be an unpleasant surprise. +In dynamically linked programs, the address of a global function is considered to point to its program linkage table entry, rather than to -the entry point of the function itself. This causes most global +the entry point of the function itself. +This causes most global functions to appear to be defined within the main executable, rather than in the shared libraries where the actual code resides. .It diff --git a/lib/libc/gen/dllockinit.3 b/lib/libc/gen/dllockinit.3 index 6af2cf7..98d1074 100644 --- a/lib/libc/gen/dllockinit.3 +++ b/lib/libc/gen/dllockinit.3 @@ -40,22 +40,26 @@ .Sh DESCRIPTION .Bf Sy Due to enhancements in the dynamic linker, this interface is no longer -needed. It is deprecated and will be removed from future releases. +needed. +It is deprecated and will be removed from future releases. In current releases it still exists, but only as a stub which does nothing. .Ef .Pp Threads packages can call .Fn dllockinit at initialization time to register locking functions for the dynamic -linker to use. This enables the dynamic linker to prevent multiple +linker to use. +This enables the dynamic linker to prevent multiple threads from entering its critical sections simultaneously. .Pp The .Fa context -argument specifies an opaque context for creating locks. The +argument specifies an opaque context for creating locks. +The dynamic linker will pass it to the .Fa lock_create -function when creating the locks it needs. When the dynamic linker +function when creating the locks it needs. +When the dynamic linker is permanently finished using the locking functions (e.g., if the program makes a subsequent call to .Fn dllockinit @@ -65,7 +69,8 @@ to destroy the context. .Pp The .Fa lock_create -argument specifies a function for creating a read/write lock. It +argument specifies a function for creating a read/write lock. +It must return a pointer to the new lock. .Pp The @@ -73,18 +78,23 @@ The and .Fa wlock_acquire arguments specify functions which lock a lock for reading or -writing, respectively. The +writing, respectively. +The .Fa lock_release -argument specifies a function which unlocks a lock. Each of these +argument specifies a function which unlocks a lock. +Each of these functions is passed a pointer to the lock. .Pp The .Fa lock_destroy -argument specifies a function to destroy a lock. It may be +argument specifies a function to destroy a lock. +It may be .Dv NULL -if locks do not need to be destroyed. The +if locks do not need to be destroyed. +The .Fa context_destroy -argument specifies a function to destroy the context. It may be +argument specifies a function to destroy the context. +It may be .Dv NULL if the context does not need to be destroyed. .Pp @@ -96,9 +106,11 @@ a default locking mechanism which works by blocking the .Dv SIGPROF , and .Dv SIGALRM -signals. This is sufficient for many application level threads +signals. +This is sufficient for many application level threads packages, which typically use one of these signals to implement -preemption. An application which has registered its own locking +preemption. +An application which has registered its own locking methods with .Fn dllockinit can restore the default locking by calling diff --git a/lib/libc/gen/fmtcheck.3 b/lib/libc/gen/fmtcheck.3 index 1cb4883..3663558 100644 --- a/lib/libc/gen/fmtcheck.3 +++ b/lib/libc/gen/fmtcheck.3 @@ -64,7 +64,8 @@ is a valid format string. The .Xr printf 3 family of functions cannot verify the types of arguments that they are -passed at run-time. In some cases, like +passed at run-time. +In some cases, like .Xr catgets 3 , it is useful or necessary to use a user-supplied format string with no guarantee that the format string matches the specified arguments. @@ -76,10 +77,11 @@ was designed to be used in these cases, as in: printf(fmtcheck(user_format, standard_format), arg1, arg2); .Ed .Pp -In the check, field widths, fillers, precisions, etc. are ignored (unless +In the check, field widths, fillers, precisions, etc.\& are ignored (unless the field width or precision is an asterisk .Ql * -instead of a digit string). Also, any text other than the format specifiers +instead of a digit string). +Also, any text other than the format specifiers is completely ignored. .Sh RETURN VALUES If @@ -94,7 +96,8 @@ Otherwise, it will return .Fa fmt_default . .Sh SECURITY CONSIDERATIONS Note that the formats may be quite different as long as they accept the -same arguments. For example, +same arguments. +For example, .Qq Li "%p %o %30s %#llx %-10.*e %n" is compatible with .Qq Li "This number %lu %d%% and string %s has %qd numbers and %.*g floats (%n)" . diff --git a/lib/libc/gen/ftok.3 b/lib/libc/gen/ftok.3 index b43ce96..a1c7dde 100644 --- a/lib/libc/gen/ftok.3 +++ b/lib/libc/gen/ftok.3 @@ -53,7 +53,8 @@ of an existing file and a user-selectable The specified .Fa path must specify an existing file that is accessible to the calling process -or the call will fail. Also, note that links to files will return the +or the call will fail. +Also, note that links to files will return the same key, given the same .Fa id . .Sh RETURN VALUES diff --git a/lib/libc/gen/fts.3 b/lib/libc/gen/fts.3 index 3245ba8..3ef0220 100644 --- a/lib/libc/gen/fts.3 +++ b/lib/libc/gen/fts.3 @@ -202,7 +202,7 @@ A directory being visited in post-order. The contents of the .Vt FTSENT structure will be unchanged from when -it was returned in pre-order, i.e. with the +it was returned in pre-order, i.e., with the .Fa fts_info field set to .Dv FTS_D . @@ -306,7 +306,7 @@ It is initialized to A pointer to the .Vt FTSENT structure referencing the file in the hierarchy -immediately above the current file, i.e. the directory of which this +immediately above the current file, i.e., the directory of which this file is a member. A parent structure for the initial entry point is provided as well, however, only the @@ -601,7 +601,7 @@ has not yet been called for a hierarchy, .Fn fts_children will return a pointer to the files in the logical directory specified to .Fn fts_open , -i.e. the arguments specified to +i.e., the arguments specified to .Fn fts_open . Otherwise, if the .Vt FTSENT diff --git a/lib/libc/gen/getbootfile.3 b/lib/libc/gen/getbootfile.3 index 4ceaf66..03e4c12 100644 --- a/lib/libc/gen/getbootfile.3 +++ b/lib/libc/gen/getbootfile.3 @@ -54,7 +54,8 @@ A read/write interface to this information is available via the MIB variable .Dq Li kern.bootfile . .Sh RETURN VALUES -If the call succeeds a string giving the pathname is returned. If it +If the call succeeds a string giving the pathname is returned. +If it fails, a null pointer is returned and an error code is placed in the global location .Va errno . diff --git a/lib/libc/gen/getcap.3 b/lib/libc/gen/getcap.3 index 57072b4..6ab7721 100644 --- a/lib/libc/gen/getcap.3 +++ b/lib/libc/gen/getcap.3 @@ -135,9 +135,11 @@ is the current entry is removed from the database. A call to .Fn cgetset -must precede the database traversal. It must be called before the +must precede the database traversal. +It must be called before the .Fn cgetent -call. If a sequential access is being performed (see below), it must be called +call. +If a sequential access is being performed (see below), it must be called before the first sequential access call .Fn ( cgetfirst or @@ -166,16 +168,19 @@ with type .Fa type . A .Fa type -is specified using any single character. If a colon (`:') is used, an +is specified using any single character. +If a colon (`:') is used, an untyped capability will be searched for (see below for explanation of -types). A pointer to the value of +types). +A pointer to the value of .Fa cap in .Fa buf is returned on success, .Dv NULL if the requested capability couldn't be -found. The end of the capability value is signaled by a `:' or +found. +The end of the capability value is signaled by a `:' or .Tn ASCII .Dv NUL (see below for capability database syntax). @@ -240,7 +245,8 @@ record returned by the previous .Fn cgetfirst or .Fn cgetnext -call. If there is no such previous call, the first record in the database is +call. +If there is no such previous call, the first record in the database is returned. Each record is returned in a .Xr malloc 3 Ns \&'d @@ -263,27 +269,35 @@ Upon completion of database (0 return) the database is closed. The .Fn cgetclose function closes the sequential access and frees any memory and file descriptors -being used. Note that it does not erase the buffer pushed by a call to +being used. +Note that it does not erase the buffer pushed by a call to .Fn cgetset . .Sh CAPABILITY DATABASE SYNTAX Capability databases are normally .Tn ASCII and may be edited with standard -text editors. Blank lines and lines beginning with a `#' are comments -and are ignored. Lines ending with a `\|\e' indicate that the next line +text editors. +Blank lines and lines beginning with a `#' are comments +and are ignored. +Lines ending with a `\|\e' indicate that the next line is a continuation of the current line; the `\|\e' and following newline -are ignored. Long lines are usually continued onto several physical +are ignored. +Long lines are usually continued onto several physical lines by ending each line except the last with a `\|\e'. .Pp Capability databases consist of a series of records, one per logical -line. Each record contains a variable number of `:'-separated fields -(capabilities). Empty fields consisting entirely of white space +line. +Each record contains a variable number of `:'-separated fields +(capabilities). +Empty fields consisting entirely of white space characters (spaces and tabs) are ignored. .Pp The first capability of each record specifies its names, separated by `|' -characters. These names are used to reference records in the database. +characters. +These names are used to reference records in the database. By convention, the last name is usually a comment and is not intended as -a lookup tag. For example, the +a lookup tag. +For example, the .Em vt100 record from the .Xr termcap 5 @@ -308,16 +322,21 @@ has value does not exist .El .Pp -Names consist of one or more characters. Names may contain any character +Names consist of one or more characters. +Names may contain any character except `:', but it's usually best to restrict them to the printable -characters and avoid use of graphics like `#', `=', `%', `@', etc. Types +characters and avoid use of graphics like `#', `=', `%', `@', etc.\& Types are single characters used to separate capability names from their -associated typed values. Types may be any character except a `:'. -Typically, graphics like `#', `=', `%', etc. are used. Values may be any +associated typed values. +Types may be any character except a `:'. +Typically, graphics like `#', `=', `%', etc.\& are used. +Values may be any number of characters and may contain any character except `:'. .Sh CAPABILITY DATABASE SEMANTICS -Capability records describe a set of (name, value) bindings. Names may -have multiple values bound to them. Different values for a name are +Capability records describe a set of (name, value) bindings. +Names may +have multiple values bound to them. +Different values for a name are distinguished by their .Fa types . The @@ -326,7 +345,8 @@ function will return a pointer to a value of a name given the capability name and the type of the value. .Pp The types `#' and `=' are conventionally used to denote numeric and -string typed values, but no restriction on those types is enforced. The +string typed values, but no restriction on those types is enforced. +The functions .Fn cgetnum and @@ -351,7 +371,8 @@ capabilities may interpolate records which also contain .Ic tc capabilities and more than one .Ic tc -capability may be used in a record. A +capability may be used in a record. +A .Ic tc expansion scope (i.e., where the argument is searched for) contains the file in which the @@ -359,7 +380,8 @@ file in which the is declared and all subsequent files in the file array. .Pp When a database is searched for a capability record, the first matching -record in the search is returned. When a record is scanned for a +record in the search is returned. +When a record is scanned for a capability, the first matching capability is returned; the capability .Ic :nameT@: will hide any following definition of a value of type @@ -386,7 +408,8 @@ example\||\|an example of binding multiple values to names:\e .Ed .Pp The capability foo has two values bound to it (bar of type `%' and blah of -type `^') and any other value bindings are hidden. The capability abc +type `^') and any other value bindings are hidden. +The capability abc also has two values bound but only a value of type `$' is prevented from being defined in the capability record more. .Pp @@ -408,7 +431,8 @@ who-cares@ prevents the definition of any who-cares definitions in old from being seen, glork#200 is inherited from old, and blah and anything defined by the record extensions is added to those definitions in old. Note that the position of the fript=bar and who-cares@ definitions before -tc=old is important here. If they were after, the definitions in old +tc=old is important here. +If they were after, the definitions in old would take precedence. .Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS Two types are predefined by @@ -453,7 +477,8 @@ Otherwise, if the number starts with a it is interpreted as an octal number. Otherwise the number is interpreted as a decimal number. .Pp -String capability values may contain any character. Non-printable +String capability values may contain any character. +Non-printable .Dv ASCII codes, new lines, and colons may be conveniently represented by the use of escape sequences: @@ -472,7 +497,8 @@ of escape sequences: .El .Pp A `\|\e' may be followed by up to three octal digits directly specifies -the numeric code for a character. The use of +the numeric code for a character. +The use of .Tn ASCII .Dv NUL Ns s , while easily diff --git a/lib/libc/gen/getdiskbyname.3 b/lib/libc/gen/getdiskbyname.3 index 068bb87..0dffef9 100644 --- a/lib/libc/gen/getdiskbyname.3 +++ b/lib/libc/gen/getdiskbyname.3 @@ -52,7 +52,8 @@ takes a disk name (e.g.\& .Ql rm03 ) and returns a prototype disk label describing its geometry information and the standard -disk partition tables. All information is obtained from +disk partition tables. +All information is obtained from the .Xr disktab 5 file. diff --git a/lib/libc/gen/getdomainname.3 b/lib/libc/gen/getdomainname.3 index e063590..ed1f0ff 100644 --- a/lib/libc/gen/getdomainname.3 +++ b/lib/libc/gen/getdomainname.3 @@ -59,7 +59,8 @@ The argument specifies the size of the .Fa name -array. The returned name is null-terminated unless insufficient +array. +The returned name is null-terminated unless insufficient space is provided. .Pp The diff --git a/lib/libc/gen/getgrent.3 b/lib/libc/gen/getgrent.3 index 838e107..b8628b2 100644 --- a/lib/libc/gen/getgrent.3 +++ b/lib/libc/gen/getgrent.3 @@ -96,7 +96,8 @@ search the group database for the given group name pointed to by .Fa name or the group id pointed to by .Fa gid , -respectively, returning the first one encountered. Identical group +respectively, returning the first one encountered. +Identical group names or group gids may result in undefined behavior. .Pp The @@ -139,12 +140,15 @@ These functions will open the group file for reading, if necessary. The .Fn setgroupent function -opens the file, or rewinds it if it is already open. If +opens the file, or rewinds it if it is already open. +If .Fa stayopen is non-zero, file descriptors are left open, significantly speeding -functions subsequent calls. This functionality is unnecessary for +functions subsequent calls. +This functionality is unnecessary for .Fn getgrent -as it doesn't close its file descriptors by default. It should also +as it doesn't close its file descriptors by default. +It should also be noted that it is dangerous for long-running programs to use this functionality as the group file may be updated. .Pp diff --git a/lib/libc/gen/getobjformat.3 b/lib/libc/gen/getobjformat.3 index f3c1573..8705f01 100644 --- a/lib/libc/gen/getobjformat.3 +++ b/lib/libc/gen/getobjformat.3 @@ -43,7 +43,8 @@ function queries several sources to determine the preferred object file format, and copies its name into a buffer provided by the caller. .Pp -The object file format is determined as follows. If +The object file format is determined as follows. +If .Va argv is .No non- Ns Ev NULL @@ -70,9 +71,11 @@ Otherwise, a built-in system default object file format is returned. points to a user-supplied buffer into which the name of the object file format is copied. .Va bufsize -gives the size of the buffer in bytes. The string placed in +gives the size of the buffer in bytes. +The string placed in .Va buf -is always null-terminated. It is an error if the buffer is too +is always null-terminated. +It is an error if the buffer is too small to hold the null-terminated name. .Pp .Va argv @@ -104,7 +107,8 @@ null terminator. If the supplied buffer is too small to hold the object file format and its null terminator, .Fn getobjformat -returns -1. In that case, the contents of the buffer and argument +returns -1. +In that case, the contents of the buffer and argument vector supplied by the caller are indeterminate. .Sh ENVIRONMENT .Bl -tag -width OBJFORMAT @@ -118,7 +122,8 @@ is set, it overrides the default object file format. .Sh FILES .Bl -tag -width /etc/objformat -compact .It Pa /etc/objformat -If present, specifies the object file format to use. Syntax is +If present, specifies the object file format to use. +Syntax is .Ql OBJFORMAT=xxx . .El .Sh SEE ALSO diff --git a/lib/libc/gen/lockf.3 b/lib/libc/gen/lockf.3 index 63cf669..cb3b8ef 100644 --- a/lib/libc/gen/lockf.3 +++ b/lib/libc/gen/lockf.3 @@ -102,7 +102,8 @@ unlocked. The section to be locked or unlocked starts at the current offset in the file and extends forward for a positive size or backward for a negative size (the preceding bytes up to but not including the -current offset). However, it is not permitted to lock a section that +current offset). +However, it is not permitted to lock a section that starts or extends before the beginning of the file. If .Fa size @@ -142,7 +143,8 @@ controlled by the process. Locked sections will be unlocked starting at the current file offset through .Fa size -bytes or to the end of file if size is 0. When all of a locked section +bytes or to the end of file if size is 0. +When all of a locked section is not released (that is, when the beginning or end of the area to be unlocked falls within a locked section), the remaining portions of that section are still locked by the process. @@ -160,13 +162,15 @@ the requested section is the maximum value for an object of type off_t, when the process has an existing lock in which size is 0 and which includes the last byte of the requested section, will be treated as a request to unlock from the start of the requested section with a -size equal to 0. Otherwise an +size equal to 0. +Otherwise an .Dv F_ULOCK request will attempt to unlock only the requested section. .Pp A potential for deadlock occurs if a process controlling a locked region is put to sleep by attempting to lock the locked region of -another process. This implementation detects that sleeping until a +another process. +This implementation detects that sleeping until a locked region is unlocked would cause a deadlock and fails with an .Er EDEADLK error. diff --git a/lib/libc/gen/msgrcv.3 b/lib/libc/gen/msgrcv.3 index d6401b6..8c280ae 100644 --- a/lib/libc/gen/msgrcv.3 +++ b/lib/libc/gen/msgrcv.3 @@ -72,19 +72,22 @@ has one of the following meanings: The .Fa msgtyp argument -is greater than 0. The first message of type +is greater than 0. +The first message of type .Fa msgtyp will be received. .It The .Fa msgtyp argument -is equal to 0. The first message on the queue will be received. +is equal to 0. +The first message on the queue will be received. .It The .Fa msgtyp argument -is less than 0. The first message of the lowest message type that is +is less than 0. +The first message of the lowest message type that is less than or equal to the absolute value of .Fa msgtyp will be received. @@ -133,7 +136,8 @@ The message queue is removed, in which case -1 will be returned, and set to .Er EINVAL . .It -A signal is received and caught. -1 is returned, and +A signal is received and caught. +-1 is returned, and .Va errno set to .Er EINTR . diff --git a/lib/libc/gen/rand48.3 b/lib/libc/gen/rand48.3 index 3a263c8..1bd315e 100644 --- a/lib/libc/gen/rand48.3 +++ b/lib/libc/gen/rand48.3 @@ -81,7 +81,8 @@ and .Fn nrand48 functions return values of type long in the range -[0, 2**31-1]. The high-order (31) bits of +[0, 2**31-1]. +The high-order (31) bits of r(n+1) are loaded into the lower bits of the returned value, with the topmost (sign) bit set to zero. .Pp @@ -91,7 +92,8 @@ and .Fn jrand48 functions return values of type long in the range -[-2**31, 2**31-1]. The high-order (32) bits of +[-2**31, 2**31-1]. +The high-order (32) bits of r(n+1) are loaded into the returned value. .Pp The @@ -100,7 +102,8 @@ The and .Fn mrand48 functions -use an internal buffer to store r(n). For these functions +use an internal buffer to store r(n). +For these functions the initial value of r(0) = 0x1234abcd330e = 20017429951246. .Pp On the other hand, diff --git a/lib/libc/gen/setjmp.3 b/lib/libc/gen/setjmp.3 index fb9753a..d59fb89 100644 --- a/lib/libc/gen/setjmp.3 +++ b/lib/libc/gen/setjmp.3 @@ -90,7 +90,7 @@ call had just returned the value specified by .Fa val , instead of 0. .Pp -Pairs of calls may be intermixed, i.e. both +Pairs of calls may be intermixed, i.e., both .Fn sigsetjmp and .Fn siglongjmp @@ -99,7 +99,7 @@ and and .Fn longjmp combinations may be used in the same program, however, individual -calls may not, e.g. the +calls may not, e.g.\& the .Fa env argument to .Fn setjmp diff --git a/lib/libc/gen/setproctitle.3 b/lib/libc/gen/setproctitle.3 index a508441..fe9f19a 100644 --- a/lib/libc/gen/setproctitle.3 +++ b/lib/libc/gen/setproctitle.3 @@ -68,10 +68,12 @@ setproctitle("talking to %s", inet_ntoa(addr)); The .Fn setproctitle function -is implicitly non-standard. Other methods of causing the +is implicitly non-standard. +Other methods of causing the .Xr ps 1 command line to change, including copying over the argv[0] string are -also implicitly non-portable. It is preferable to use an operating system +also implicitly non-portable. +It is preferable to use an operating system supplied .Fn setproctitle if present. @@ -79,7 +81,8 @@ if present. Unfortunately, it is possible that there are other calling conventions to other versions of .Fn setproctitle , -although none have been found by the author as yet. This is believed to be +although none have been found by the author as yet. +This is believed to be the predominant convention. .Pp It is thought that the implementation is compatible with other systems, diff --git a/lib/libc/gen/shm_open.3 b/lib/libc/gen/shm_open.3 index 0619133..ac4c110 100644 --- a/lib/libc/gen/shm_open.3 +++ b/lib/libc/gen/shm_open.3 @@ -150,7 +150,8 @@ functions can fail with any error defined for .Fn open and .Fn unlink , -respectively. In addition, the following errors are defined for +respectively. +In addition, the following errors are defined for .Fn shm_open : .Bl -tag -width Er .It Bq Er EINVAL diff --git a/lib/libc/gen/signal.3 b/lib/libc/gen/signal.3 index b329691..681483d 100644 --- a/lib/libc/gen/signal.3 +++ b/lib/libc/gen/signal.3 @@ -63,7 +63,8 @@ facility. .Pp Signals allow the manipulation of a process from outside its domain as well as allowing the process to manipulate itself or -copies of itself (children). There are two general types of signals: +copies of itself (children). +There are two general types of signals: those that cause termination of a process and those that do not. Signals which cause termination of a program might result from an irrecoverable error or might be the result of a user at a terminal diff --git a/lib/libc/gen/sleep.3 b/lib/libc/gen/sleep.3 index dd0a322..4c204dc 100644 --- a/lib/libc/gen/sleep.3 +++ b/lib/libc/gen/sleep.3 @@ -66,7 +66,8 @@ and there is no special handling for SIGALRM. If the .Fn sleep function returns because the requested time has elapsed, the value -returned will be zero. If the +returned will be zero. +If the .Fn sleep function returns due to the delivery of a signal, the value returned will be the unslept amount (the requested time minus the time actually diff --git a/lib/libc/gen/sysctl.3 b/lib/libc/gen/sysctl.3 index 7fa187b..24d078a 100644 --- a/lib/libc/gen/sysctl.3 +++ b/lib/libc/gen/sysctl.3 @@ -83,7 +83,8 @@ length array of integers. The .Fn sysctlbyname function accepts an ASCII representation of the name and internally -looks up the integer name vector. Apart from that, it behaves the same +looks up the integer name vector. +Apart from that, it behaves the same as the standard .Fn sysctl function. @@ -454,7 +455,7 @@ The third and fourth level names are as follows: .El .Pp If the third level name is KERN_PROC_ARGS then the command line argument -array is returned in a flattened form, i.e. zero-terminated arguments +array is returned in a flattened form, i.e., zero-terminated arguments follow each other. The total size of array is returned. It is also possible for a process to set its own process title this way. @@ -752,12 +753,14 @@ The returned data consists of a 0 if the statistics-based page management algorithm is in use or 1 if the near-LRU algorithm is in use. .It Li VM_SWAPPING_ENABLED -1 if process swapping is enabled or 0 if disabled. This variable is +1 if process swapping is enabled or 0 if disabled. +This variable is permanently set to 0 if the kernel was built with swapping disabled. .It Li VM_V_CACHE_MAX Maximum desired size of the cache queue. .It Li VM_V_CACHE_MIN -Minimum desired size of the cache queue. If the cache queue size +Minimum desired size of the cache queue. +If the cache queue size falls very far below this value, the pageout daemon is awakened. .It Li VM_V_FREE_MIN Minimum amount of memory (cache memory plus free memory) @@ -771,7 +774,8 @@ The total amount of free memory (including cache memory) that the pageout daemon tries to maintain. .It Li VM_V_INACTIVE_TARGET The desired number of inactive pages that the pageout daemon should -achieve when it runs. Inactive pages can be quickly inserted into +achieve when it runs. +Inactive pages can be quickly inserted into process address space when needed. .It Li VM_V_PAGEOUT_FREE_MIN If the amount of free and cache memory falls below this value, the diff --git a/lib/libc/gen/tzset.3 b/lib/libc/gen/tzset.3 index e93fa69..42bcdbe 100644 --- a/lib/libc/gen/tzset.3 +++ b/lib/libc/gen/tzset.3 @@ -131,12 +131,14 @@ Three or more bytes that are the designation for the standard .Pq Em std or summer .Pq Em dst -time zone. Only +time zone. +Only .Em std is required; if .Em dst is missing, then summer time does not apply in this locale. -Upper and lowercase letters are explicitly allowed. Any characters +Upper and lowercase letters are explicitly allowed. +Any characters except a leading colon .Pq Ql \&: , digits, comma @@ -151,7 +153,8 @@ and are allowed. .It Em offset Indicates the value one must add to the local time to arrive at -Coordinated Universal Time. The +Coordinated Universal Time. +The .Em offset has the form: .Bd -ragged -offset indent @@ -167,26 +170,33 @@ The minutes .Pq Em mm and seconds .Pq Em ss -are optional. The hour +are optional. +The hour .Pq Em hh -is required and may be a single digit. The +is required and may be a single digit. +The .Em offset following .Em std -is required. If no +is required. +If no .Em offset follows .Em dst , -summer time is assumed to be one hour ahead of standard time. One or +summer time is assumed to be one hour ahead of standard time. +One or more digits may be used; the value is always interpreted as a decimal -number. The hour must be between zero and 24, and the minutes (and -seconds) \(em if present \(em between zero and 59. If preceded by a +number. +The hour must be between zero and 24, and the minutes (and +seconds) \(em if present \(em between zero and 59. +If preceded by a .Pq Ql \- the time zone shall be east of the Prime Meridian; otherwise it shall be west (which may be indicated by an optional preceding .Pq Ql + ) . .It Em rule -Indicates when to change to and back from summer time. The +Indicates when to change to and back from summer time. +The .Em rule has the form: .Bd -ragged -offset indent @@ -198,7 +208,8 @@ where the first describes when the change from standard to summer time occurs and the second .Em date -describes when the change back happens. Each +describes when the change back happens. +Each .Em time field describes when, in current local time, the change to the other time is made. @@ -214,7 +225,8 @@ The Julian day .Em n \*(Le 365). Leap days are not counted; that is, in all years \(em including leap -years \(em February 28 is day 59 and March 1 is day 60. It is +years \(em February 28 is day 59 and March 1 is day 60. +It is impossible to explicitly refer to the occasional February 29. .It Em n The zero-based Julian day @@ -246,10 +258,12 @@ the last day in month .Em m .Dc -which may occur in either the fourth or the fifth week). Week 1 is the +which may occur in either the fourth or the fifth week). +Week 1 is the first week in which the .Em d Ns 'th -day occurs. Day zero is Sunday. +day occurs. +Day zero is Sunday. .Pp The .Em time @@ -259,7 +273,8 @@ except that no leading sign .Pq Ql \- or .Pq Ql + -is allowed. The default, if +is allowed. +The default, if .Em time is not given, is .Sy 02:00:00 . diff --git a/lib/libc/gen/ualarm.3 b/lib/libc/gen/ualarm.3 index 639570e..7783a30 100644 --- a/lib/libc/gen/ualarm.3 +++ b/lib/libc/gen/ualarm.3 @@ -67,7 +67,7 @@ argument is non-zero, the signal will be sent to the process every .Fa interval -microseconds after the timer expires (e.g. after +microseconds after the timer expires (e.g.\& after .Fa microseconds number of microseconds have passed). .Pp diff --git a/lib/libc/gen/unvis.3 b/lib/libc/gen/unvis.3 index 59cd85e..b2cdbaa 100644 --- a/lib/libc/gen/unvis.3 +++ b/lib/libc/gen/unvis.3 @@ -60,7 +60,8 @@ are used to decode a visual representation of characters, as produced by the .Xr vis 3 function, back into -the original form. Unvis is called with successive characters in +the original form. +Unvis is called with successive characters in .Fa c until a valid sequence is recognized, at which time the decoded character is @@ -83,7 +84,8 @@ decoding any escape sequences along the way, and returns the number of characters placed into .Fa dst , or \-1 if an -invalid escape sequence was detected. The size of +invalid escape sequence was detected. +The size of .Fa dst should be equal to the size of @@ -106,20 +108,24 @@ The .Fn unvis function implements a state machine that can be used to decode an arbitrary -stream of bytes. All state associated with the bytes being decoded +stream of bytes. +All state associated with the bytes being decoded is stored outside the .Fn unvis function (that is, a pointer to the state is passed in), so -calls decoding different streams can be freely intermixed. To +calls decoding different streams can be freely intermixed. +To start decoding a stream of bytes, first initialize an integer -to zero. Call +to zero. +Call .Fn unvis with each successive byte, along with a pointer to this integer, and a pointer to a destination character. The .Fn unvis function -has several return codes that must be handled properly. They are: +has several return codes that must be handled properly. +They are: .Bl -tag -width UNVIS_VALIDPUSH .It Li \&0 (zero) Another character is necessary; nothing has been recognized yet. @@ -131,11 +137,13 @@ A valid character has been recognized and is available at the location pointed to by cp; however, the character currently passed in should be passed in again. .It Dv UNVIS_NOCHAR -A valid sequence was detected, but no character was produced. This +A valid sequence was detected, but no character was produced. +This return code is necessary to indicate a logical break between characters. .It Dv UNVIS_SYNBAD An invalid escape sequence was detected, or the decoder is in an -unknown state. The decoder is placed into the starting state. +unknown state. +The decoder is placed into the starting state. .El .Pp When all bytes in the stream have been processed, call diff --git a/lib/libc/gen/vis.3 b/lib/libc/gen/vis.3 index 3d094eb..8985abd 100644 --- a/lib/libc/gen/vis.3 +++ b/lib/libc/gen/vis.3 @@ -58,9 +58,11 @@ a string which represents the character .Fa c . If .Fa c -needs no encoding, it is copied in unaltered. The string is +needs no encoding, it is copied in unaltered. +The string is null terminated, and a pointer to the end of the string is -returned. The maximum length of any encoding is four +returned. +The maximum length of any encoding is four characters (not including the trailing .Dv NUL ) ; thus, when @@ -160,9 +162,11 @@ Synonym for \&| .Dv VIS_NL . .It Dv VIS_SAFE -Only encode "unsafe" characters. Unsafe means control +Only encode "unsafe" characters. +Unsafe means control characters which may cause common terminals to perform -unexpected functions. Currently this form allows space, +unexpected functions. +Currently this form allows space, tab, newline, backspace, bell, and return - in addition to all graphic characters - unencoded. .El @@ -259,7 +263,8 @@ where .Ar d represents a hexadecimal digit. .It Dv VIS_OCTAL -Use a three digit octal sequence. The form is +Use a three digit octal sequence. +The form is .Ql \eddd where .Ar d diff --git a/lib/libc/i386/sys/i386_get_ioperm.2 b/lib/libc/i386/sys/i386_get_ioperm.2 index 19ef481..4d3bbf1 100644 --- a/lib/libc/i386/sys/i386_get_ioperm.2 +++ b/lib/libc/i386/sys/i386_get_ioperm.2 @@ -45,7 +45,8 @@ The system call will return the permission for the process' I/O port space in the .Fa *enable -argument. The port range starts at +argument. +The port range starts at .Fa start and the number of contiguous entries will be returned in .Fa *length . diff --git a/lib/libc/i386/sys/i386_set_watch.3 b/lib/libc/i386/sys/i386_set_watch.3 index dfe60d8..15b8497 100644 --- a/lib/libc/i386/sys/i386_set_watch.3 +++ b/lib/libc/i386/sys/i386_set_watch.3 @@ -54,11 +54,14 @@ The .Fn i386_set_watch function will set up the specified debug registers as indicated by the -arguments. The +arguments. +The .Fa watchnum -argument specifies which watch register is used, 0, 1, 2, 3, or -1. If +argument specifies which watch register is used, 0, 1, 2, 3, or -1. +If .Fa watchnum -is -1, a free watch register is found and used. If there are no free +is -1, a free watch register is found and used. +If there are no free watch registers, an error code of -1 is returned. The .Fa watchaddr @@ -78,7 +81,8 @@ DBREG_DR7_RDWR Break when the watch area is read from or written .Ed .Pp Note that these functions do not actually set or clear breakpoints; -they manipulate the indicated debug register set. You must use +they manipulate the indicated debug register set. +You must use .Xr ptrace 2 to retrieve and install the debug register values for a process. .Sh RETURN VALUES @@ -96,7 +100,8 @@ will return the .Fa watchnum argument, or the watchnum actually used in the case that .Fa watchnum -is -1 on success. On error, +is -1 on success. +On error, .Fn i386_set_watch will return -1 indicating that the watchpoint could not be set up because either no more watchpoints are available, or diff --git a/lib/libc/locale/rune.3 b/lib/libc/locale/rune.3 index d3c8b3e..debb26e 100644 --- a/lib/libc/locale/rune.3 +++ b/lib/libc/locale/rune.3 @@ -191,7 +191,8 @@ function operates the same as .Fn sgetrune with the exception that it attempts to read enough bytes from .Fa stream -to decode a single rune. It returns either +to decode a single rune. +It returns either .Dv EOF on end of file, .Dv _INVALID_RUNE diff --git a/lib/libc/locale/setlocale.3 b/lib/libc/locale/setlocale.3 index 7e4ff85..278e18d 100644 --- a/lib/libc/locale/setlocale.3 +++ b/lib/libc/locale/setlocale.3 @@ -81,7 +81,8 @@ and functions. This controls recognition of upper and lower case, alphabetic or non-alphabetic characters, -and so on. The real work is done by the +and so on. +The real work is done by the .Fn setrunelocale function. .It Dv LC_MESSAGES diff --git a/lib/libc/locale/utf2.5 b/lib/libc/locale/utf2.5 index a5a1865..e41cad8 100644 --- a/lib/libc/locale/utf2.5 +++ b/lib/libc/locale/utf2.5 @@ -61,9 +61,11 @@ Unicode Standard. .Pp .Nm UTF2 representation is backwards compatible with ASCII, so 0x00-0x7f refer to the -ASCII character set. The multibyte encodings of wide characters between +ASCII character set. +The multibyte encodings of wide characters between 0x0080 and 0xffff -consist entirely of bytes whose high order bit is set. The actual +consist entirely of bytes whose high order bit is set. +The actual encoding is represented by the following table: .Bd -literal [0x0000 - 0x007f] [00000000.0bbbbbbb] -> 0bbbbbbb diff --git a/lib/libc/net/addr2ascii.3 b/lib/libc/net/addr2ascii.3 index fc9373d..b24c44e 100644 --- a/lib/libc/net/addr2ascii.3 +++ b/lib/libc/net/addr2ascii.3 @@ -52,7 +52,8 @@ The routines and .Fn ascii2addr are used to convert network addresses between binary form and a -printable form appropriate to the address family. Both functions take +printable form appropriate to the address family. +Both functions take an .Fa af argument, specifying the address family to be used in the conversion @@ -67,14 +68,17 @@ The .Fn addr2ascii function is used to convert binary, network-format addresses into printable -form. In addition to +form. +In addition to .Fa af , -there are three other arguments. The +there are three other arguments. +The .Fa addrp argument is a pointer to the network address to be converted. The .Fa len -argument is the length of the address. The +argument is the length of the address. +The .Fa buf argument is an optional pointer to a caller-allocated buffer to hold the result; if a null pointer is passed, @@ -94,7 +98,8 @@ and The .Fa ascii argument is a pointer to the string which is to be converted into -binary. The +binary. +The .Fa result argument is a pointer to an appropriate network address structure for the specified family. @@ -192,7 +197,8 @@ was improperly formatted for address family .Xr inet 4 .Sh HISTORY An interface close to this one was originally suggested by Craig -Partridge. This particular interface originally appeared in the +Partridge. +This particular interface originally appeared in the .Tn INRIA .Tn IPv6 implementation. @@ -201,8 +207,10 @@ Code and documentation by .An Garrett A. Wollman , MIT Laboratory for Computer Science. .Sh BUGS -The original implementations supported IPv6. This support should -eventually be resurrected. The +The original implementations supported IPv6. +This support should +eventually be resurrected. +The .Tn NRL implementation also included support for the .Dv AF_ISO @@ -210,13 +218,16 @@ and .Dv AF_NS address families. .Pp -The genericity of this interface is somewhat questionable. A truly +The genericity of this interface is somewhat questionable. +A truly generic interface would provide a means for determining the length of the buffer to be used so that it could be dynamically allocated, and would always require a .Dq Li "struct sockaddr" -to hold the binary address. Unfortunately, this is incompatible with existing -practice. This limitation means that a routine for printing network +to hold the binary address. +Unfortunately, this is incompatible with existing +practice. +This limitation means that a routine for printing network addresses from arbitrary address families must still have internal knowledge of the maximum buffer length needed and the appropriate part of the address to use as the binary address. diff --git a/lib/libc/net/byteorder.3 b/lib/libc/net/byteorder.3 index 21c105f..e10613d 100644 --- a/lib/libc/net/byteorder.3 +++ b/lib/libc/net/byteorder.3 @@ -85,4 +85,5 @@ functions appeared in On the .Tn VAX bytes are handled backwards from most everyone else in -the world. This is not expected to be fixed in the near future. +the world. +This is not expected to be fixed in the near future. diff --git a/lib/libc/net/gethostbyname.3 b/lib/libc/net/gethostbyname.3 index a4486bc..8fb1e96 100644 --- a/lib/libc/net/gethostbyname.3 +++ b/lib/libc/net/gethostbyname.3 @@ -107,7 +107,7 @@ should point to an address which is .Fa len bytes long, in binary form -(i.e. not an IP address in human readable +(i.e., not an IP address in human readable .Tn ASCII form). The diff --git a/lib/libc/net/getifaddrs.3 b/lib/libc/net/getifaddrs.3 index 3d7ea42..8387723 100644 --- a/lib/libc/net/getifaddrs.3 +++ b/lib/libc/net/getifaddrs.3 @@ -110,7 +110,8 @@ if one exists, otherwise it is NULL. .Pp The .Li ifa_data -field references address family specific data. For +field references address family specific data. +For .Dv AF_LINK addresses it contains a pointer to the .Fa struct if_data diff --git a/lib/libc/net/getipnodebyname.3 b/lib/libc/net/getipnodebyname.3 index c5e65a3..d0b1839 100644 --- a/lib/libc/net/getipnodebyname.3 +++ b/lib/libc/net/getipnodebyname.3 @@ -217,15 +217,19 @@ flag then the caller wants all addresses: IPv6 and IPv4-mapped IPv6. A query is first made for .Li AAAA records and if successful, the -IPv6 addresses are returned. Another query is then made for +IPv6 addresses are returned. +Another query is then made for .Li A records and any found are returned as IPv4-mapped IPv6 addresses. .Li h_length -will be 16. Only if both queries fail does the function +will be 16. +Only if both queries fail does the function return a .Dv NULL -pointer. This flag is ignored unless af equals -AF_INET6. If both +pointer. +This flag is ignored unless af equals +AF_INET6. +If both .Dv AI_ALL and .Dv AI_V4MAPPED diff --git a/lib/libc/net/getnetent.3 b/lib/libc/net/getnetent.3 index f05df36..b6cd944 100644 --- a/lib/libc/net/getnetent.3 +++ b/lib/libc/net/getnetent.3 @@ -72,7 +72,8 @@ broken-out fields of a line in the network data base .Pa /etc/networks , or entries supplied by the .Xr yp 8 -system. The order of the lookups is controlled by the +system. +The order of the lookups is controlled by the `networks' entry in .Xr nsswitch.conf 5 . .Pp @@ -94,7 +95,8 @@ A zero terminated list of alternate names for the network. .It Fa n_addrtype The type of the network number returned; currently only AF_INET. .It Fa n_net -The network number. Network numbers are returned in machine byte +The network number. +Network numbers are returned in machine byte order. .El .Pp @@ -106,7 +108,8 @@ reads the next line of the file, opening the file if necessary. The .Fn setnetent function -opens and rewinds the file. If the +opens and rewinds the file. +If the .Fa stayopen flag is non-zero, the net data base will not be closed after each call to diff --git a/lib/libc/net/getprotoent.3 b/lib/libc/net/getprotoent.3 index 8f48481..7811c78 100644 --- a/lib/libc/net/getprotoent.3 +++ b/lib/libc/net/getprotoent.3 @@ -95,7 +95,8 @@ reads the next line of the file, opening the file if necessary. The .Fn setprotoent function -opens and rewinds the file. If the +opens and rewinds the file. +If the .Fa stayopen flag is non-zero, the net data base will not be closed after each call to diff --git a/lib/libc/net/getservent.3 b/lib/libc/net/getservent.3 index 19cdfdf..26399b5 100644 --- a/lib/libc/net/getservent.3 +++ b/lib/libc/net/getservent.3 @@ -99,7 +99,8 @@ reads the next line of the file, opening the file if necessary. The .Fn setservent function -opens and rewinds the file. If the +opens and rewinds the file. +If the .Fa stayopen flag is non-zero, the net data base will not be closed after each call to diff --git a/lib/libc/net/inet.3 b/lib/libc/net/inet.3 index 39b60be..21d0d71 100644 --- a/lib/libc/net/inet.3 +++ b/lib/libc/net/inet.3 @@ -144,11 +144,13 @@ takes an Internet address and returns an .Tn ASCII string representing the address in .Ql .\& -notation. The routine +notation. +The routine .Fn inet_makeaddr takes an Internet network number and a local network address and constructs an Internet address -from it. The routines +from it. +The routines .Fn inet_netof and .Fn inet_lnaof @@ -174,7 +176,8 @@ a .Pp When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, -to the four bytes of an Internet address. Note +to the four bytes of an Internet address. +Note that when an Internet address is viewed as a 32-bit integer quantity on the .Tn VAX @@ -220,7 +223,8 @@ and .Fn inet_ntoa functions are semi-deprecated in favor of the .Xr addr2ascii 3 -family. However, since those functions are not yet widely implemented, +family. +However, since those functions are not yet widely implemented, portable programs cannot rely on their presence and will continue to use the .Xr inet 3 diff --git a/lib/libc/net/inet6_opt_init.3 b/lib/libc/net/inet6_opt_init.3 index 8f68380..4102414 100644 --- a/lib/libc/net/inet6_opt_init.3 +++ b/lib/libc/net/inet6_opt_init.3 @@ -66,7 +66,7 @@ complicated. The advanced API therefore defines a set of functions to help applications. These functions assume the -formatting rules specified in Appendix B in RFC2460 i.e. that the +formatting rules specified in Appendix B in RFC2460 i.e., that the largest field is placed last in the option. The function prototypes for these functions are all in the @@ -76,7 +76,7 @@ header. .Ss inet6_opt_init .Fn inet6_opt_init returns the number of bytes needed for the empty -extension header i.e. without any options. +extension header i.e., without any options. If .Li extbuf is not NULL it also initializes the extension header to have the correct length @@ -115,7 +115,7 @@ is the 8-bit option type. .Li len is the length of the option data .Po -i.e. excluding the option type and option length fields. +i.e., excluding the option type and option length fields. .Pc .Pp Once diff --git a/lib/libc/net/inet6_rthdr_space.3 b/lib/libc/net/inet6_rthdr_space.3 index 055a290..9c3e5be 100644 --- a/lib/libc/net/inet6_rthdr_space.3 +++ b/lib/libc/net/inet6_rthdr_space.3 @@ -72,7 +72,8 @@ .Sh DESCRIPTION RFC2292 IPv6 advanced API defines eight functions that the application calls to build and examine a Routing -header. Four functions build a Routing header: +header. +Four functions build a Routing header: .Bl -hang .It Fn inet6_rthdr_space return #bytes required for ancillary data @@ -108,7 +109,8 @@ containing the specified number of .Fa segments (addresses). For an IPv6 Type 0 Routing header, the number -of segments must be between 1 and 23, inclusive. The return value +of segments must be between 1 and 23, inclusive. +The return value includes the size of the cmsghdr structure that precedes the Routing header, and any required padding. .Pp diff --git a/lib/libc/net/resolver.3 b/lib/libc/net/resolver.3 index 235898c..49257bf 100644 --- a/lib/libc/net/resolver.3 +++ b/lib/libc/net/resolver.3 @@ -191,7 +191,8 @@ This option is enabled by default. .It Dv RES_NOALIASES This option turns off the user level aliasing feature controlled by the .Dq Ev HOSTALIASES -environment variable. Network daemons should set this option. +environment variable. +Network daemons should set this option. .It Dv RES_USE_INET6 Enables support for IPv6-only applications. This causes IPv4 addresses to be returned as an IPv4 mapped address. @@ -227,7 +228,8 @@ it can be overridden by the environment variable This environment variable may contain several blank-separated tokens if you wish to override the .Em "search list" -on a per-process basis. This is similar to the +on a per-process basis. +This is similar to the .Ic search command in the configuration file. Another environment variable @@ -238,7 +240,8 @@ set by changing fields in the .Va _res structure or are inherited from the configuration file's .Ic options -command. The syntax of the +command. +The syntax of the .Dq Ev RES_OPTIONS environment variable is explained in .Xr resolver 5 . diff --git a/lib/libc/posix1e/acl_delete.3 b/lib/libc/posix1e/acl_delete.3 index 8121d2e..818b1af 100644 --- a/lib/libc/posix1e/acl_delete.3 +++ b/lib/libc/posix1e/acl_delete.3 @@ -124,9 +124,11 @@ The file system is read-only. .Xr acl_set 3 , .Xr posix1e 3 .Sh STANDARDS -POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion of the draft continues on the cross-platform POSIX.1e implementation -mailing list. To join this list, see the +mailing list. +To join this list, see the .Fx POSIX.1e implementation page for more information. diff --git a/lib/libc/posix1e/acl_delete_entry.3 b/lib/libc/posix1e/acl_delete_entry.3 index 86fe7b2..a931db0 100644 --- a/lib/libc/posix1e/acl_delete_entry.3 +++ b/lib/libc/posix1e/acl_delete_entry.3 @@ -56,7 +56,8 @@ function fails if: .It Bq Er EINVAL Argument .Fa acl -does not point to a valid ACL. Argument +does not point to a valid ACL. +Argument .Fa entry_d is not a valid descriptor for an ACL entry in .Fa acl . diff --git a/lib/libc/posix1e/acl_delete_perm.3 b/lib/libc/posix1e/acl_delete_perm.3 index a3343aa0..0740d61 100644 --- a/lib/libc/posix1e/acl_delete_perm.3 +++ b/lib/libc/posix1e/acl_delete_perm.3 @@ -54,7 +54,8 @@ function fails if: .It Bq Er EINVAL Argument .Fa permset_d -is not a valid descriptor for a permission set. Argument +is not a valid descriptor for a permission set. +Argument .Fa perm does not contain a valid .Vt acl_perm_t diff --git a/lib/libc/posix1e/acl_dup.3 b/lib/libc/posix1e/acl_dup.3 index fa4a4f3..ae4ff4f 100644 --- a/lib/libc/posix1e/acl_dup.3 +++ b/lib/libc/posix1e/acl_dup.3 @@ -46,7 +46,8 @@ The function returns a pointer to a copy of the ACL pointed to by the argument .Va acl . .Pp -This function may cause memory to be allocated. The caller should free any +This function may cause memory to be allocated. +The caller should free any releasable memory, when the new ACL is no longer required, by calling .Xr acl_free 3 with the @@ -62,7 +63,8 @@ support for POSIX.1e interfaces and features is still under development at this time. .Sh RETURN VALUES Upon successful completion, this function shall return a pointer to the -duplicate ACL. Otherwise, a value of +duplicate ACL. +Otherwise, a value of .Va (acl_t)NULL shall be returned, and .Va errno @@ -92,9 +94,11 @@ system-imposed memory management constraints. .Xr acl_get 3 , .Xr posix1e 3 .Sh STANDARDS -POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion of the draft continues on the cross-platform POSIX.1e implementation -mailing list. To join this list, see the +mailing list. +To join this list, see the .Fx POSIX.1e implementation page for more information. diff --git a/lib/libc/posix1e/acl_free.3 b/lib/libc/posix1e/acl_free.3 index bc06c99..d64c72a 100644 --- a/lib/libc/posix1e/acl_free.3 +++ b/lib/libc/posix1e/acl_free.3 @@ -73,9 +73,11 @@ argument is invalid. .Xr acl_init 3 , .Xr posix1e 3 .Sh STANDARDS -POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion of the draft continues on the cross-platform POSIX.1e implementation -mailing list. To join this list, see the +mailing list. +To join this list, see the .Fx POSIX.1e implementation page for more information. diff --git a/lib/libc/posix1e/acl_from_text.3 b/lib/libc/posix1e/acl_from_text.3 index f717d7b..8b10784 100644 --- a/lib/libc/posix1e/acl_from_text.3 +++ b/lib/libc/posix1e/acl_from_text.3 @@ -48,7 +48,8 @@ function converts the text form of an ACL referred to by into the internal working structure for ACLs, appropriate for applying to files or manipulating. .Pp -This function may cause memory to be allocated. The caller should free any +This function may cause memory to be allocated. +The caller should free any releasable memory, when the new ACL is no longer required, by calling .Xr acl_free 3 with the @@ -60,7 +61,8 @@ support for POSIX.1e interfaces and features is still under development at this time. .Sh RETURN VALUES Upon successful completion, the function shall return a pointer to the -internal representation of the ACL in working storage. Otherwise, a value +internal representation of the ACL in working storage. +Otherwise, a value of .Va (acl_t)NULL shall be returned, and @@ -90,9 +92,11 @@ hardware or system-imposed memory management constraints. .Xr acl_to_text 3 , .Xr posix1e 3 .Sh STANDARDS -POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion of the draft continues on the cross-platform POSIX.1e implementation -mailing list. To join this list, see the +mailing list. +To join this list, see the .Fx POSIX.1e implementation page for more information. @@ -112,7 +116,8 @@ rely on the .Xr getpwent 3 library calls to manage username and uid mapping, as well as the .Xr getgrent 3 -library calls to manage groupname and gid mapping. These calls are not +library calls to manage groupname and gid mapping. +These calls are not thread safe, and so transitively, neither are .Fn acl_from_text and diff --git a/lib/libc/posix1e/acl_get.3 b/lib/libc/posix1e/acl_get.3 index 25ead88..fa915df 100644 --- a/lib/libc/posix1e/acl_get.3 +++ b/lib/libc/posix1e/acl_get.3 @@ -78,7 +78,8 @@ is a non-portable variation on which does not follow a symlink if the target of the call is a symlink. .Pp -These functions may cause memory to be allocated. The caller should free +These functions may cause memory to be allocated. +The caller should free any releasable memory, when the new ACL is no longer required, by calling .Xr acl_free 3 with the @@ -96,7 +97,8 @@ support for POSIX.1e interfaces and features is still under development at this time. .Sh RETURN VALUES Upon successful completion, the function shall return a pointer to the ACL -that was retrieved. Otherwise, a value of +that was retrieved. +Otherwise, a value of .Va (acl_t)NULL shall be returned, and .Va errno @@ -138,9 +140,11 @@ The file system does not support ACL retrieval. .Xr acl_set 3 , .Xr posix1e 3 .Sh STANDARDS -POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion of the draft continues on the cross-platform POSIX.1e implementation -mailing list. To join this list, see the +mailing list. +To join this list, see the .Fx POSIX.1e implementation page for more information. diff --git a/lib/libc/posix1e/acl_get_entry.3 b/lib/libc/posix1e/acl_get_entry.3 index 528fd34..0627ecb 100644 --- a/lib/libc/posix1e/acl_get_entry.3 +++ b/lib/libc/posix1e/acl_get_entry.3 @@ -82,7 +82,8 @@ If the function successfully obtains an ACL entry, a value of 1 is returned. If the ACL has no ACL entries, the .Fn acl_get_entry -returns a value of 0. If the value of +returns a value of 0. +If the value of .Fa entry_id is .Dv ACL_NEXT_ENTRY @@ -93,7 +94,8 @@ a value of 0 will be returned until a successful call with .Fa entry_id of .Dv ACL_FIRST_ENTRY -is made. Otherwise, a value of -1 will be returned and +is made. +Otherwise, a value of -1 will be returned and the global variable .Va errno will be set to indicate the error. @@ -105,7 +107,8 @@ fails if: .It Bq Er EINVAL Argument .Fa acl -does not point to a valid ACL. Argument +does not point to a valid ACL. +Argument .Fa entry_id is neither .Dv ACL_FIRST_ENTRY diff --git a/lib/libc/posix1e/acl_get_qualifier.3 b/lib/libc/posix1e/acl_get_qualifier.3 index cdfe882..867809e 100644 --- a/lib/libc/posix1e/acl_get_qualifier.3 +++ b/lib/libc/posix1e/acl_get_qualifier.3 @@ -78,7 +78,8 @@ will return a value of .Vt ( void * ) Ns Dv NULL and the function will fail. .Pp -This function may cause memory to be allocated. The caller should +This function may cause memory to be allocated. +The caller should free any releasable memory, when the new qualifier is no longer required, by calling .Fn acl_free @@ -102,7 +103,8 @@ fails if: .It Bq Er EINVAL Argument .Fa entry_d -does not point to a valid descriptor for an ACL entry. The +does not point to a valid descriptor for an ACL entry. +The value of the tag type in the ACL entry referenced by argument .Fa entry_d is not diff --git a/lib/libc/posix1e/acl_init.3 b/lib/libc/posix1e/acl_init.3 index 8a98643..dba8923 100644 --- a/lib/libc/posix1e/acl_init.3 +++ b/lib/libc/posix1e/acl_init.3 @@ -46,13 +46,16 @@ The function allocates and initializes the working storage for an ACL of at least .Va count -ACL entries. A pointer to the working storage is returned. The working +ACL entries. +A pointer to the working storage is returned. +The working storage allocated to contain the ACL is freed by a call to .Xr acl_free 3 . When the area is first allocated, it shall contain an ACL that contains no ACL entries. .Pp -This function may cause memory to be allocated. The caller should free any +This function may cause memory to be allocated. +The caller should free any releasable memory, when the new ACL is no longer required, by calling .Xr acl_free 3 with the @@ -64,7 +67,8 @@ support for POSIX.1e interfaces and features is still under development at this time. .Sh RETURN VALUES Upon successful completion, this function shall return a pointer to the -working storage. Otherwise, a value of +working storage. +Otherwise, a value of .Va (acl_t)NULL shall be returned, and .Va errno @@ -91,9 +95,11 @@ system-imposed memory management constraints. .Xr acl_free 3 , .Xr posix1e 3 .Sh STANDARDS -POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion of the draft continues on the cross-platform POSIX.1e implementation -mailing list. To join this list, see the +mailing list. +To join this list, see the .Fx POSIX.1e implementation page for more information. diff --git a/lib/libc/posix1e/acl_set.3 b/lib/libc/posix1e/acl_set.3 index db1be7d..a2d50b8 100644 --- a/lib/libc/posix1e/acl_set.3 +++ b/lib/libc/posix1e/acl_set.3 @@ -126,9 +126,11 @@ read-only. .Xr acl_valid 3 , .Xr posix1e 3 .Sh STANDARDS -POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion of the draft continues on the cross-platform POSIX.1e implementation -mailing list. To join this list, see the +mailing list. +To join this list, see the .Fx POSIX.1e implementation page for more information. diff --git a/lib/libc/posix1e/acl_set_qualifier.3 b/lib/libc/posix1e/acl_set_qualifier.3 index 04dc2a2..3442a82 100644 --- a/lib/libc/posix1e/acl_set_qualifier.3 +++ b/lib/libc/posix1e/acl_set_qualifier.3 @@ -56,7 +56,8 @@ function fails if: .It Bq Er EINVAL Argument .Fa entry_d -is not a valid descriptor for an ACL entry. The tag type of the +is not a valid descriptor for an ACL entry. +The tag type of the ACL entry .Fa entry_d is not diff --git a/lib/libc/posix1e/acl_set_tag_type.3 b/lib/libc/posix1e/acl_set_tag_type.3 index 460e925..3830be7 100644 --- a/lib/libc/posix1e/acl_set_tag_type.3 +++ b/lib/libc/posix1e/acl_set_tag_type.3 @@ -56,7 +56,8 @@ function fails if: .It Bq Er EINVAL Argument .Fa entry_d -is not a valid descriptor for an ACL entry. Argument +is not a valid descriptor for an ACL entry. +Argument .Fa tag_type is not a valid ACL tag type. .El diff --git a/lib/libc/posix1e/acl_to_text.3 b/lib/libc/posix1e/acl_to_text.3 index 1283a68c..833a6d2 100644 --- a/lib/libc/posix1e/acl_to_text.3 +++ b/lib/libc/posix1e/acl_to_text.3 @@ -45,7 +45,8 @@ The .Fn acl_to_text function translates the ACL pointed to by argument .Va acl -into a NULL terminated character string. If the pointer +into a NULL terminated character string. +If the pointer .Va len_p is not NULL, then the function shall return the length of the string (not including the NULL terminator) in the location pointed to by @@ -55,7 +56,8 @@ The format of the text string returned by shall be the POSIX.1e long ACL form. .Pp This function allocates any memory necessary to contain the string and -returns a pointer to the string. The caller should free any releasable +returns a pointer to the string. +The caller should free any releasable memory, when the new string is no longer required, by calling .Xr acl_free 3 with the @@ -67,7 +69,8 @@ support for POSIX.1e interfaces and features is still under development at this time. .Sh RETURN VALUES Upon successful completion, the function shall return a pointer to the -long text form of an ACL. Otherwise, a value of +long text form of an ACL. +Otherwise, a value of .Va (char*)NULL shall be returned and .Va errno @@ -100,9 +103,11 @@ by the hardware or software-imposed memory management constraints. .Xr acl_from_text 3 , .Xr posix1e 3 .Sh STANDARDS -POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion of the draft continues on the cross-platform POSIX.1e implementation -mailing list. To join this list, see the +mailing list. +To join this list, see the .Fx POSIX.1e implementation page for more information. @@ -122,7 +127,8 @@ rely on the .Xr getpwent 3 library calls to manage username and uid mapping, as well as the .Xr getgrent 3 -library calls to manage groupname and gid mapping. These calls are not +library calls to manage groupname and gid mapping. +These calls are not thread safe, and so transitively, neither are .Fn acl_from_text and diff --git a/lib/libc/posix1e/acl_valid.3 b/lib/libc/posix1e/acl_valid.3 index 3d47da5..e525db6 100644 --- a/lib/libc/posix1e/acl_valid.3 +++ b/lib/libc/posix1e/acl_valid.3 @@ -52,10 +52,12 @@ .Sh DESCRIPTION These functions check that the ACL referred to by the argument .Va acl -is valid. The POSIX.1e routine, +is valid. +The POSIX.1e routine, .Fn acl_valid , checks this validity only with POSIX.1e ACL semantics, and irrespective -of the context in which the ACL is to be used. The non-portable forms, +of the context in which the ACL is to be used. +The non-portable forms, .Fn acl_valid_fd_np , .Fn acl_valid_file_np , and @@ -140,9 +142,11 @@ The file system does not support ACL retrieval. .Xr acl_set 3 , .Xr posix1e 3 .Sh STANDARDS -POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion +POSIX.1e is described in IEEE POSIX.1e draft 17. +Discussion of the draft continues on the cross-platform POSIX.1e implementation -mailing list. To join this list, see the +mailing list. +To join this list, see the .Fx POSIX.1e implementation page for more information. diff --git a/lib/libc/regex/re_format.7 b/lib/libc/regex/re_format.7 index 58e05e0..d4555a0 100644 --- a/lib/libc/regex/re_format.7 +++ b/lib/libc/regex/re_format.7 @@ -232,7 +232,7 @@ sequence of characters of that collating element. The sequence is a single element of the bracket expression's list. A bracket expression containing a multi-character collating element can thus match more than one character, -e.g. if the collating sequence includes a +e.g.\& if the collating sequence includes a .Ql ch collating element, then the RE diff --git a/lib/libc/regex/regex.3 b/lib/libc/regex/regex.3 index 68edd7f..a267dcc 100644 --- a/lib/libc/regex/regex.3 +++ b/lib/libc/regex/regex.3 @@ -564,7 +564,7 @@ or .Ql |\& cannot appear first or last in a (sub)expression or after another .Ql |\& , -i.e. an operand of +i.e., an operand of .Ql |\& cannot be an empty subexpression. An empty parenthesized subexpression, @@ -651,7 +651,7 @@ empty (sub)expression .It Dv REG_ASSERT can't happen - you found a bug .It Dv REG_INVARG -invalid argument, e.g. negative-length string +invalid argument, e.g.\& negative-length string .El .Sh HISTORY Originally written by diff --git a/lib/libc/rpc/getrpcent.3 b/lib/libc/rpc/getrpcent.3 index 862a89f..4d209b5 100644 --- a/lib/libc/rpc/getrpcent.3 +++ b/lib/libc/rpc/getrpcent.3 @@ -64,7 +64,8 @@ reads the next line of the file, opening the file if necessary. The .Fn setrpcent function -opens and rewinds the file. If the +opens and rewinds the file. +If the .Fa stayopen flag is non-zero, the net data base will not be closed after each call to diff --git a/lib/libc/rpc/getrpcport.3 b/lib/libc/rpc/getrpcport.3 index 13985b4..6e1f199 100644 --- a/lib/libc/rpc/getrpcport.3 +++ b/lib/libc/rpc/getrpcport.3 @@ -26,7 +26,8 @@ and using protocol .Fa proto . It returns 0 if it cannot contact the portmapper, or if .Fa prognum -is not registered. If +is not registered. +If .Fa prognum is registered but not with version .Fa versnum , diff --git a/lib/libc/rpc/rpc_secure.3 b/lib/libc/rpc/rpc_secure.3 index 559cb6b..07c6314 100644 --- a/lib/libc/rpc/rpc_secure.3 +++ b/lib/libc/rpc/rpc_secure.3 @@ -39,9 +39,11 @@ .Sh DESCRIPTION These routines are part of the .Tn RPC -library. They implement +library. +They implement .Tn DES -Authentication. See +Authentication. +See .Xr rpc 3 for further details about .Tn RPC . @@ -81,14 +83,16 @@ derived from the utility routine but could also represent a user name using .Fn user2netname . The second field is window on the validity of -the client credential, given in seconds. A small +the client credential, given in seconds. +A small window is more secure than a large one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third argument .Fa addr -is optional. If it is +is optional. +If it is .Dv NULL , then the authentication system will assume that the local clock is always in sync with the server's @@ -104,7 +108,8 @@ address of the server itself. The final argument .Fa ckey -is also optional. If it is +is also optional. +If it is .Dv NULL , then the authentication system will generate a random @@ -184,7 +189,8 @@ takes a server netname and a .Tn DES key, and decrypts the key by using the public key of the server and the secret key -associated with the effective uid of the calling process. It +associated with the effective uid of the calling process. +It is the inverse of .Fn key_encryptsession . .Pp @@ -195,7 +201,8 @@ is a keyserver interface routine. It takes a server netname and a des key, and encrypts it using the public key of the server and the secret key -associated with the effective uid of the calling process. It +associated with the effective uid of the calling process. +It is the inverse of .Fn key_decryptsession . .Pp @@ -230,7 +237,8 @@ Returns .Dv TRUE if it succeeds and .Dv FALSE -if it fails. Inverse of +if it fails. +Inverse of .Fn host2netname . .Pp The diff --git a/lib/libc/stdio/stdio.3 b/lib/libc/stdio/stdio.3 index d54ee33..ab5d1fd 100644 --- a/lib/libc/stdio/stdio.3 +++ b/lib/libc/stdio/stdio.3 @@ -92,15 +92,19 @@ object is indeterminate (garbage) after a file is closed. .Pp A file may be subsequently reopened, by the same or another program execution, and its contents reclaimed or modified (if it can be repositioned -at the start). If the main function returns to its original caller, or +at the start). +If the main function returns to its original caller, or the .Xr exit 3 function is called, all open files are closed (hence all output -streams are flushed) before program termination. Other methods +streams are flushed) before program termination. +Other methods of program termination may not close files properly and hence -buffered output may be lost. In particular, +buffered output may be lost. +In particular, .Xr _exit 2 -does not flush stdio files. Neither does an exit due to a signal. +does not flush stdio files. +Neither does an exit due to a signal. Buffers are flushed by .Xr abort 3 as required by POSIX, although previous implementations did not. diff --git a/lib/libc/stdlib/getenv.3 b/lib/libc/stdlib/getenv.3 index 269fecb..11922a7 100644 --- a/lib/libc/stdlib/getenv.3 +++ b/lib/libc/stdlib/getenv.3 @@ -144,13 +144,15 @@ assigning a differently sized .Fa value to the same .Fa name -will result in a memory leak. The +will result in a memory leak. +The .Fx semantics for these functions (namely, that the contents of .Fa value are copied and that old values remain accessible indefinitely) make this -bug unavoidable. Future versions may eliminate one or both of these +bug unavoidable. +Future versions may eliminate one or both of these semantic guarantees in order to fix the bug. .Sh HISTORY The functions diff --git a/lib/libc/stdlib/qsort.3 b/lib/libc/stdlib/qsort.3 index 6dfffd6..07777db 100644 --- a/lib/libc/stdlib/qsort.3 +++ b/lib/libc/stdlib/qsort.3 @@ -149,11 +149,13 @@ The .Fn qsort and .Fn qsort_r -functions are an implementation of C.A.R. Hoare's +functions are an implementation of C.A.R. +Hoare's .Dq quicksort algorithm, -a variant of partition-exchange sorting; in particular, see D.E. Knuth's -Algorithm Q. +a variant of partition-exchange sorting; in particular, see +.An D.E. Knuth Ns 's +.%T "Algorithm Q" . .Sy Quicksort takes O N lg N average time. This implementation uses median selection to avoid its @@ -161,10 +163,13 @@ O N**2 worst-case behavior. .Pp The .Fn heapsort -function is an implementation of J.W.J. William's +function is an implementation of +.An "J.W.J. William" Ns 's .Dq heapsort algorithm, -a variant of selection sorting; in particular, see D.E. Knuth's Algorithm H. +a variant of selection sorting; in particular, see +.An "D.E. Knuth" Ns 's +.%T "Algorithm H" . .Sy Heapsort takes O N lg N worst-case time. Its diff --git a/lib/libc/stdlib/radixsort.3 b/lib/libc/stdlib/radixsort.3 index 9558259..da4ed16 100644 --- a/lib/libc/stdlib/radixsort.3 +++ b/lib/libc/stdlib/radixsort.3 @@ -105,7 +105,10 @@ The function is not stable, but uses no additional memory. .Pp These functions are variants of most-significant-byte radix sorting; in -particular, see D.E. Knuth's Algorithm R and section 5.2.5, exercise 10. +particular, see +.An "D.E. Knuth" Ns 's +.%T "Algorithm R" +and section 5.2.5, exercise 10. They take linear time relative to the number of bytes in the strings. .Sh RETURN VALUES .Rv -std radixsort diff --git a/lib/libc/stdlib/random.3 b/lib/libc/stdlib/random.3 index 66ccd55..a1dbf8a 100644 --- a/lib/libc/stdlib/random.3 +++ b/lib/libc/stdlib/random.3 @@ -81,9 +81,11 @@ functions. The difference is that .Xr rand 3 produces a much less random sequence \(em in fact, the low dozen bits -generated by rand go through a cyclic pattern. All the bits generated by +generated by rand go through a cyclic pattern. +All the bits generated by .Fn random -are usable. For example, +are usable. +For example, .Sq Li random()&01 will produce a random binary value. @@ -115,13 +117,15 @@ a fixed seed. The .Fn initstate routine allows a state array, passed in as an argument, to be initialized -for future use. The size of the state array (in bytes) is used by +for future use. +The size of the state array (in bytes) is used by .Fn initstate to decide how sophisticated a random number generator it should use \(em the more state, the better the random numbers will be. (Current "optimal" values for the amount of state information are 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to -the nearest known amount. Using less than 8 bytes will cause an error.) +the nearest known amount. +Using less than 8 bytes will cause an error.) The seed for the initialization (which specifies a starting point for the random number sequence, and provides for restarting at the same point) is also an argument. diff --git a/lib/libc/stdlib/tsearch.3 b/lib/libc/stdlib/tsearch.3 index 0c7f1bd..ea0a9da 100644 --- a/lib/libc/stdlib/tsearch.3 +++ b/lib/libc/stdlib/tsearch.3 @@ -51,7 +51,8 @@ The and .Fn twalk functions manage binary search trees based on algorithms T and D -from Knuth (6.2.2). The comparison function passed in by +from Knuth (6.2.2). +The comparison function passed in by the user has the same style of return values as .Xr strcmp 3 . .Pp @@ -72,7 +73,8 @@ is identical to .Fn tfind except that if no match is found, .Fa key -is inserted into the tree and a pointer to it is returned. If +is inserted into the tree and a pointer to it is returned. +If .Fa rootp points to a NULL value a new binary search tree is created. .Pp diff --git a/lib/libc/stdtime/ctime.3 b/lib/libc/stdtime/ctime.3 index 68aa10b..7b98304 100644 --- a/lib/libc/stdtime/ctime.3 +++ b/lib/libc/stdtime/ctime.3 @@ -354,7 +354,8 @@ function will modify the same object. The C Standard provides no mechanism for a program to modify its current local timezone setting, and the .Tn POSIX Ns No \&-standard -method is not reentrant. (However, thread-safe implementations are provided +method is not reentrant. +(However, thread-safe implementations are provided in the .Tn POSIX threaded environment.) diff --git a/lib/libc/stdtime/strftime.3 b/lib/libc/stdtime/strftime.3 index a251faf..e6c3807 100644 --- a/lib/libc/stdtime/strftime.3 +++ b/lib/libc/stdtime/strftime.3 @@ -184,7 +184,8 @@ is replaced by the weekday (Monday as the first day of the week) as a decimal number (1-7). .It Cm \&%V is replaced by the week number of the year (Monday as the first day of -the week) as a decimal number (01-53). If the week containing January +the week) as a decimal number (01-53). +If the week containing January 1 has four or more days in the new year, then it is week 1; otherwise it is the last week of the previous year, and the next week is week 1. .It Cm %v diff --git a/lib/libc/stdtime/strptime.3 b/lib/libc/stdtime/strptime.3 index 1d7eb7f..5f93b34 100644 --- a/lib/libc/stdtime/strptime.3 +++ b/lib/libc/stdtime/strptime.3 @@ -161,7 +161,8 @@ The format specifier only accepts time zone abbreviations of the local time zone, or the value "GMT". This limitation is because of ambiguity due to of the over loading of time -zone abbreviations. One such example is +zone abbreviations. +One such example is .Fa EST which is both Eastern Standard Time and Eastern Australia Summer Time. .Pp diff --git a/lib/libc/string/strlcpy.3 b/lib/libc/string/strlcpy.3 index 3cc5ae4..f674fe2 100644 --- a/lib/libc/string/strlcpy.3 +++ b/lib/libc/string/strlcpy.3 @@ -47,7 +47,8 @@ The .Fn strlcpy and .Fn strlcat -functions copy and concatenate strings respectively. They are designed +functions copy and concatenate strings respectively. +They are designed to be safer, more consistent, and less error prone replacements for .Xr strncpy 3 and @@ -108,7 +109,8 @@ The and .Fn strlcat functions return the total length of the string they tried to -create. For +create. +For .Fn strlcpy that means the length of .Fa src . diff --git a/lib/libc/string/strsep.3 b/lib/libc/string/strsep.3 index 77c7b84..7a2b0f8 100644 --- a/lib/libc/string/strsep.3 +++ b/lib/libc/string/strsep.3 @@ -115,7 +115,7 @@ While the .Fn strtok function should be preferred for portability reasons (it conforms to .St -isoC ) -it is unable to handle empty fields, i.e. detect fields delimited by +it is unable to handle empty fields, i.e., detect fields delimited by two adjacent delimiter characters, or to be used for more than a single string at a time. The diff --git a/lib/libc/sys/accept.2 b/lib/libc/sys/accept.2 index 387c7fc..5b844c6 100644 --- a/lib/libc/sys/accept.2 +++ b/lib/libc/sys/accept.2 @@ -76,7 +76,8 @@ connections are present on the queue, returns an error as described below. The accepted socket may not be used -to accept more connections. The original socket +to accept more connections. +The original socket .Fa s remains open. .Pp @@ -130,7 +131,8 @@ For some applications, performance may be enhanced by using an .Xr accept_filter 9 to pre-process incoming connections. .Sh RETURN VALUES -The call returns \-1 on error. If it succeeds, it returns a non-negative +The call returns \-1 on error. +If it succeeds, it returns a non-negative integer that is a descriptor for the accepted socket. .Sh ERRORS The diff --git a/lib/libc/sys/aio_error.2 b/lib/libc/sys/aio_error.2 index 02b0caa..91bb097 100644 --- a/lib/libc/sys/aio_error.2 +++ b/lib/libc/sys/aio_error.2 @@ -45,9 +45,11 @@ associated with the structure pointed to by .Sh RETURN VALUES If the asynchronous I/O request has completed successfully, .Fn aio_error -returns 0. If the request has not yet completed, +returns 0. +If the request has not yet completed, .Er EINPROGRESS -is returned. If the request has completed unsuccessfully the error +is returned. +If the request has completed unsuccessfully the error status is returned as described in .Xr read 2 , .Xr write 2 , diff --git a/lib/libc/sys/aio_read.2 b/lib/libc/sys/aio_read.2 index 0358b23..047661b 100644 --- a/lib/libc/sys/aio_read.2 +++ b/lib/libc/sys/aio_read.2 @@ -85,7 +85,8 @@ The Asynchronous I/O Control Block structure pointed to by and the buffer that the .Fa iocb->aio_buf member of that structure references must remain valid until the -operation has completed. For this reason, use of auto (stack) variables +operation has completed. +For this reason, use of auto (stack) variables for these objects is discouraged. .Pp The asynchronous I/O control buffer @@ -122,7 +123,8 @@ system call is not supported. .Pp The following conditions may be synchronously detected when the .Fn aio_read -system call is made, or asynchronously, at any time thereafter. If they +system call is made, or asynchronously, at any time thereafter. +If they are detected at call time, .Fn aio_read returns -1 and sets diff --git a/lib/libc/sys/aio_suspend.2 b/lib/libc/sys/aio_suspend.2 index ec5e5db..06d278a 100644 --- a/lib/libc/sys/aio_suspend.2 +++ b/lib/libc/sys/aio_suspend.2 @@ -50,7 +50,8 @@ The argument is an array of .Fa niocb -pointers to asynchronous I/O requests. Array members containing +pointers to asynchronous I/O requests. +Array members containing NULL will be silently ignored. .Pp If @@ -58,7 +59,8 @@ If is a non-nil pointer, it specifies a maximum interval to suspend. If .Fa timeout -is a nil pointer, the suspend blocks indefinitely. To effect a +is a nil pointer, the suspend blocks indefinitely. +To effect a poll, the .Fa timeout should point to a zero-value timespec structure. @@ -66,7 +68,8 @@ should point to a zero-value timespec structure. If one or more of the specified asynchronous I/O requests have completed, .Fn aio_suspend -returns 0. Otherwise it returns -1 and sets +returns 0. +Otherwise it returns -1 and sets .Va errno to indicate the error, as enumerated below. .Sh ERRORS diff --git a/lib/libc/sys/aio_write.2 b/lib/libc/sys/aio_write.2 index e417f82..5fe8d98 100644 --- a/lib/libc/sys/aio_write.2 +++ b/lib/libc/sys/aio_write.2 @@ -47,7 +47,8 @@ to the descriptor .Fa iocb->aio_fildes . The call returns immediately after the write request has been enqueued to the descriptor; the write may or may not have completed at the time -the call returns. If the request could not be enqueued, generally due +the call returns. +If the request could not be enqueued, generally due to invalid arguments, the call returns without having enqueued the request. .Pp @@ -57,7 +58,8 @@ is set for .Fa iocb->aio_fildes , .Fn aio_write operations append to the file in the same order as the calls were -made. If +made. +If .Dv O_APPEND is not set for the file descriptor, the write operation will occur at the absolute position from the beginning of the file plus @@ -89,7 +91,8 @@ The Asynchronous I/O Control Block structure pointed to by and the buffer that the .Fa iocb->aio_buf member of that structure references must remain valid until the -operation has completed. For this reason, use of auto (stack) variables +operation has completed. +For this reason, use of auto (stack) variables for these objects is discouraged. .Pp The asynchronous I/O control buffer @@ -124,7 +127,8 @@ system call is not supported. .Pp The following conditions may be synchronously detected when the .Fn aio_write -system call is made, or asynchronously, at any time thereafter. If they +system call is made, or asynchronously, at any time thereafter. +If they are detected at call time, .Fn aio_write returns -1 and sets diff --git a/lib/libc/sys/chmod.2 b/lib/libc/sys/chmod.2 index 66b4d56..7da7092 100644 --- a/lib/libc/sys/chmod.2 +++ b/lib/libc/sys/chmod.2 @@ -132,7 +132,8 @@ then the owner of any new files and sub-directories created within this directory are set to be the same as the owner of that directory. If this function is enabled, new directories will inherit -the bit from their parents. Execute bits are removed from +the bit from their parents. +Execute bits are removed from the file, and it will not be given to root. This behavior does not change the requirements for the user to be allowed to write the file, but only the eventual diff --git a/lib/libc/sys/chroot.2 b/lib/libc/sys/chroot.2 index b2c3b4e..7142e0d 100644 --- a/lib/libc/sys/chroot.2 +++ b/lib/libc/sys/chroot.2 @@ -97,7 +97,8 @@ Any other value for .Ql kern.chroot_allow_open_directories will bypass the check for open directories .Pp -Upon successful completion, a value of 0 is returned. Otherwise, +Upon successful completion, a value of 0 is returned. +Otherwise, a value of -1 is returned and .Va errno is set to indicate an error. diff --git a/lib/libc/sys/clock_gettime.2 b/lib/libc/sys/clock_gettime.2 index f519094..a608870 100644 --- a/lib/libc/sys/clock_gettime.2 +++ b/lib/libc/sys/clock_gettime.2 @@ -95,7 +95,8 @@ system call even when the system is secure. .Pp The resolution (granularity) of a clock is returned by the .Fn clock_getres -system call. This value is placed in a (non-NULL) +system call. +This value is placed in a (non-NULL) .Fa *tp . .Sh RETURN VALUES .Rv -std diff --git a/lib/libc/sys/close.2 b/lib/libc/sys/close.2 index 26b4fbd..04dbe3d 100644 --- a/lib/libc/sys/close.2 +++ b/lib/libc/sys/close.2 @@ -83,7 +83,8 @@ all descriptors for the new child process reference the same objects as they did in the parent before the fork. If a new process is then to be run using .Xr execve 2 , -the process would normally inherit these descriptors. Most +the process would normally inherit these descriptors. +Most of the descriptors can be rearranged with .Xr dup2 2 or deleted with diff --git a/lib/libc/sys/dup.2 b/lib/libc/sys/dup.2 index f4da9f5..ef903f9 100644 --- a/lib/libc/sys/dup.2 +++ b/lib/libc/sys/dup.2 @@ -59,7 +59,8 @@ the calling process The argument .Fa oldd is a small non-negative integer index in -the per-process descriptor table. The value must be less +the per-process descriptor table. +The value must be less than the size of the table, which is returned by .Xr getdtablesize 2 . The new descriptor returned by the call @@ -96,7 +97,8 @@ In .Fn dup2 , the value of the new descriptor .Fa newd -is specified. If this descriptor is already in use and +is specified. +If this descriptor is already in use and .Fa oldd \*(Ne .Fa newd , diff --git a/lib/libc/sys/execve.2 b/lib/libc/sys/execve.2 index 9b0f22c..427f9ab 100644 --- a/lib/libc/sys/execve.2 +++ b/lib/libc/sys/execve.2 @@ -58,7 +58,8 @@ This file is either an executable object file, or a file of data for an interpreter. An executable object file consists of an identifying header, followed by pages of data representing the initial program (text) -and initialized data pages. Additional pages may be specified +and initialized data pages. +Additional pages may be specified by the header to be initialized with zero data; see .Xr elf 5 and @@ -87,7 +88,8 @@ and the name of the originally file becomes the second argument; otherwise, the name of the originally .Sy execve Ap d -file becomes the first argument. The original arguments are shifted over to +file becomes the first argument. +The original arguments are shifted over to become the subsequent arguments. The zeroth argument is set to the specified .Em interpreter . @@ -97,7 +99,8 @@ The argument is a pointer to a null-terminated array of character pointers to null-terminated character strings. These strings construct the argument list to be made available to the new -process. At least one argument must be present in +process. +At least one argument must be present in the array; by custom, the first element should be the name of the executed program (for example, the last component of .Fa path ) . @@ -159,7 +162,8 @@ These values may be used in changing the effective IDs later (see .Pp The set-ID bits are not honored if the respective file system has the .Cm nosuid -option enabled or if the new process file is an interpreter file. Syscall +option enabled or if the new process file is an interpreter file. +Syscall tracing is disabled if effective IDs are changed. .Pp The new process also inherits the following attributes from diff --git a/lib/libc/sys/fcntl.2 b/lib/libc/sys/fcntl.2 index 92b7440..804b4ab 100644 --- a/lib/libc/sys/fcntl.2 +++ b/lib/libc/sys/fcntl.2 @@ -52,7 +52,8 @@ The argument .Fa fd is a descriptor to be operated on by .Fa cmd -as described below. Depending on the value of +as described below. +Depending on the value of .Fa cmd , .Fn fcntl can take an additional third argument @@ -157,8 +158,10 @@ corresponds to the flag of .Xr open 2 . .It Dv O_DIRECT -Minimize or eliminate the cache effects of reading and writing. The system -will attempt to avoid caching the data you read or write. If it cannot +Minimize or eliminate the cache effects of reading and writing. +The system +will attempt to avoid caching the data you read or write. +If it cannot avoid caching the data, it will minimize the impact the data has on the cache. Use of this flag can drastically reduce performance if not used with care. .It Dv O_ASYNC diff --git a/lib/libc/sys/flock.2 b/lib/libc/sys/flock.2 index 1d095bd..acb9741 100644 --- a/lib/libc/sys/flock.2 +++ b/lib/libc/sys/flock.2 @@ -93,7 +93,8 @@ after other processes have gained and released the lock). .Pp Requesting a lock on an object that is already locked normally causes the caller to be blocked until the lock may be -acquired. If +acquired. +If .Dv LOCK_NB is included in .Fa operation , @@ -102,13 +103,15 @@ the error .Er EWOULDBLOCK will be returned. .Sh NOTES -Locks are on files, not file descriptors. That is, file descriptors +Locks are on files, not file descriptors. +That is, file descriptors duplicated through .Xr dup 2 or .Xr fork 2 do not result in multiple instances of a lock, but rather multiple -references to a single lock. If a process holding a lock on a file +references to a single lock. +If a process holding a lock on a file forks and the child explicitly unlocks the file, the parent will lose its lock. .Pp diff --git a/lib/libc/sys/fork.2 b/lib/libc/sys/fork.2 index a1adafd..5dd6413 100644 --- a/lib/libc/sys/fork.2 +++ b/lib/libc/sys/fork.2 @@ -84,7 +84,8 @@ Upon successful completion, .Fn fork returns a value of 0 to the child process and returns the process ID of the child -process to the parent process. Otherwise, a value of -1 is returned +process to the parent process. +Otherwise, a value of -1 is returned to the parent process, no child process is created, and the global variable .Va errno diff --git a/lib/libc/sys/getdtablesize.2 b/lib/libc/sys/getdtablesize.2 index cda45fa..b53571e 100644 --- a/lib/libc/sys/getdtablesize.2 +++ b/lib/libc/sys/getdtablesize.2 @@ -46,7 +46,8 @@ .Fn getdtablesize void .Sh DESCRIPTION Each process has a fixed size descriptor table, -which is guaranteed to have at least 20 slots. The entries in +which is guaranteed to have at least 20 slots. +The entries in the descriptor table are numbered with small integers starting at 0. The .Fn getdtablesize diff --git a/lib/libc/sys/getitimer.2 b/lib/libc/sys/getitimer.2 index 9949983..babcd3b 100644 --- a/lib/libc/sys/getitimer.2 +++ b/lib/libc/sys/getitimer.2 @@ -102,7 +102,8 @@ system clock are rounded up to this resolution .Pp The .Dv ITIMER_REAL -timer decrements in real time. A +timer decrements in real time. +A .Dv SIGALRM signal is delivered when this timer expires. @@ -110,7 +111,8 @@ delivered when this timer expires. The .Dv ITIMER_VIRTUAL timer decrements in process virtual time. -It runs only when the process is executing. A +It runs only when the process is executing. +A .Dv SIGVTALRM signal is delivered when it expires. @@ -118,7 +120,8 @@ is delivered when it expires. The .Dv ITIMER_PROF timer decrements both in process virtual time and -when the system is running on behalf of the process. It is designed +when the system is running on behalf of the process. +It is designed to be used by interpreters in statistically profiling the execution of interpreted programs. Each time the @@ -126,7 +129,8 @@ Each time the timer expires, the .Dv SIGPROF signal is -delivered. Because this signal may interrupt in-progress +delivered. +Because this signal may interrupt in-progress system calls, programs using this timer must be prepared to restart interrupted system calls. .Pp diff --git a/lib/libc/sys/getlogin.2 b/lib/libc/sys/getlogin.2 index c7d03c7..9a254f3 100644 --- a/lib/libc/sys/getlogin.2 +++ b/lib/libc/sys/getlogin.2 @@ -76,7 +76,8 @@ except the caller must provide the buffer with length .Fa len bytes -to hold the result. The buffer should be at least +to hold the result. +The buffer should be at least .Dv MAXLOGNAME bytes in length. .Pp @@ -103,7 +104,8 @@ Making a .Fn setsid system call is the .Em ONLY -way to do this. The +way to do this. +The .Xr daemon 3 function calls .Fn setsid diff --git a/lib/libc/sys/getpriority.2 b/lib/libc/sys/getpriority.2 index 0b580dc..6e7ab2a 100644 --- a/lib/libc/sys/getpriority.2 +++ b/lib/libc/sys/getpriority.2 @@ -84,16 +84,19 @@ denotes the current process, process group, or user. The .Fa prio argument -is a value in the range -20 to 20. The default priority is 0; +is a value in the range -20 to 20. +The default priority is 0; lower priorities cause more favorable scheduling. .Pp The .Fn getpriority system call returns the highest priority (lowest numerical value) -enjoyed by any of the specified processes. The +enjoyed by any of the specified processes. +The .Fn setpriority system call sets the priorities of all of the specified processes -to the specified value. Only the super-user may lower priorities. +to the specified value. +Only the super-user may lower priorities. .Sh RETURN VALUES Since .Fn getpriority diff --git a/lib/libc/sys/getrlimit.2 b/lib/libc/sys/getrlimit.2 index 159989a..1e67083 100644 --- a/lib/libc/sys/getrlimit.2 +++ b/lib/libc/sys/getrlimit.2 @@ -103,11 +103,13 @@ this defines how far a program's stack segment may be extended. Stack extension is performed automatically by the system. .El .Pp -A resource limit is specified as a soft limit and a hard limit. When a +A resource limit is specified as a soft limit and a hard limit. +When a soft limit is exceeded a process may receive a signal (for example, if the cpu time or file size is exceeded), but it will be allowed to continue execution until it reaches the hard limit (or modifies -its resource limit). The +its resource limit). +The .Vt rlimit structure is used to specify the hard and soft limits on a resource, .Bd -literal -offset indent @@ -117,7 +119,8 @@ struct rlimit { }; .Ed .Pp -Only the super-user may raise the maximum limits. Other users +Only the super-user may raise the maximum limits. +Other users may only alter .Fa rlim_cur within the range from 0 to @@ -152,7 +155,8 @@ A file I/O operation that would create a file larger that the process' soft limit will cause the write to fail and a signal .Dv SIGXFSZ to be -generated; this normally terminates the process, but may be caught. When +generated; this normally terminates the process, but may be caught. +When the soft cpu time limit is exceeded, a signal .Dv SIGXCPU is sent to the diff --git a/lib/libc/sys/getrusage.2 b/lib/libc/sys/getrusage.2 index 6a529c1..9bafce3 100644 --- a/lib/libc/sys/getrusage.2 +++ b/lib/libc/sys/getrusage.2 @@ -99,7 +99,8 @@ an .Dq integral value indicating the amount of memory used by the text segment -that was also shared among other processes. This value is expressed +that was also shared among other processes. +This value is expressed in units of kilobytes * ticks-of-execution. Ticks are statistics clock ticks. The statistics clock has a frequency of diff --git a/lib/libc/sys/getsockname.2 b/lib/libc/sys/getsockname.2 index 68c5bdb..0c285ad 100644 --- a/lib/libc/sys/getsockname.2 +++ b/lib/libc/sys/getsockname.2 @@ -51,7 +51,8 @@ The system call returns the current .Fa name -for the specified socket. The +for the specified socket. +The .Fa namelen argument should be initialized to indicate the amount of space pointed to by diff --git a/lib/libc/sys/getsockopt.2 b/lib/libc/sys/getsockopt.2 index b30eba9..ccc71e3 100644 --- a/lib/libc/sys/getsockopt.2 +++ b/lib/libc/sys/getsockopt.2 @@ -56,7 +56,8 @@ and system calls manipulate the .Em options -associated with a socket. Options may exist at multiple +associated with a socket. +Options may exist at multiple protocol levels; they are always present at the uppermost .Dq socket level. @@ -69,7 +70,8 @@ is specified as .Dv SOL_SOCKET . To manipulate options at any other level the protocol number of the appropriate protocol -controlling the option is supplied. For example, +controlling the option is supplied. +For example, to indicate that an option is to be interpreted by the .Tn TCP protocol, @@ -89,14 +91,16 @@ are used to access option values for For .Fn getsockopt they identify a buffer in which the value for the -requested option(s) are to be returned. For +requested option(s) are to be returned. +For .Fn getsockopt , .Fa optlen is a value-result argument, initially containing the size of the buffer pointed to by .Fa optval , and modified on return to indicate the actual size of -the value returned. If no option value is +the value returned. +If no option value is to be supplied or returned, .Fa optval may be NULL. @@ -179,14 +183,16 @@ This option permits multiple instances of a program to each receive UDP/IP multicast or broadcast datagrams destined for the bound port. .Dv SO_KEEPALIVE enables the -periodic transmission of messages on a connected socket. Should the +periodic transmission of messages on a connected socket. +Should the connected party fail to respond to these messages, the connection is considered broken and processes using the socket are notified via a .Dv SIGPIPE signal when attempting to send data. .Dv SO_DONTROUTE indicates that outgoing messages should -bypass the standard routing facilities. Instead, messages are directed +bypass the standard routing facilities. +Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. .Pp diff --git a/lib/libc/sys/gettimeofday.2 b/lib/libc/sys/gettimeofday.2 index 3812e54..f104253 100644 --- a/lib/libc/sys/gettimeofday.2 +++ b/lib/libc/sys/gettimeofday.2 @@ -58,8 +58,10 @@ zone is obtained with the .Fn gettimeofday system call, and set with the .Fn settimeofday -system call. The time is expressed in seconds and microseconds -since midnight (0 hour), January 1, 1970. The resolution of the system +system call. +The time is expressed in seconds and microseconds +since midnight (0 hour), January 1, 1970. +The resolution of the system clock is hardware dependent, and the time may be updated continuously or in .Dq ticks . diff --git a/lib/libc/sys/intro.2 b/lib/libc/sys/intro.2 index 6be0ac0..b16c3ea 100644 --- a/lib/libc/sys/intro.2 +++ b/lib/libc/sys/intro.2 @@ -322,7 +322,8 @@ The host you were connected to crashed and rebooted. .It Er 53 ECONNABORTED Em "Software caused connection abort" . A connection abort was caused internal to your host machine. .It Er 54 ECONNRESET Em "Connection reset by peer" . -A connection was forcibly closed by a peer. This normally +A connection was forcibly closed by a peer. +This normally results from a loss of the connection on the remote socket due to a timeout or a reboot. .It Er 55 ENOBUFS Em "\&No buffer space available" . @@ -353,11 +354,13 @@ A or .Xr send 2 request failed because the connected party did not -properly respond after a period of time. (The timeout +properly respond after a period of time. +(The timeout period is dependent on the communication protocol.) .It Er 61 ECONNREFUSED Em "Connection refused" . No connection could be made because the target machine actively -refused it. This usually results from trying to connect +refused it. +This usually results from trying to connect to a service that is inactive on the foreign host. .It Er 62 ELOOP Em "Too many levels of symbolic links" . A path name lookup involved more than 32 @@ -462,7 +465,8 @@ at run-time. .Bl -tag -width Ds .It Process ID . Each active process in the system is uniquely identified by a non-negative -integer called a process ID. The range of this ID is from 0 to 99999. +integer called a process ID. +The range of this ID is from 0 to 99999. .It Parent process ID A new process is created by a currently active process; (see .Xr fork 2 ) . @@ -472,8 +476,10 @@ the parent process ID of each child is set to the ID of a system process, .Xr init 8 . .It Process Group Each active process is a member of a process group that is identified by -a non-negative integer called the process group ID. This is the process -ID of the group leader. This grouping permits the signaling of related +a non-negative integer called the process group ID. +This is the process +ID of the group leader. +This grouping permits the signaling of related processes (see .Xr termios 4 ) and the job control mechanisms of @@ -527,7 +533,8 @@ termed the real user ID. .Pp Each user is also a member of one or more groups. One of these groups is distinguished from others and -used in implementing accounting facilities. The positive +used in implementing accounting facilities. +The positive integer corresponding to this distinguished group is termed the real group ID. .Pp @@ -544,7 +551,8 @@ group IDs, and it is unspecified whether the effective group ID is a member of the list.) .Pp The effective user ID and effective group ID are initially the -process's real user ID and real group ID respectively. Either +process's real user ID and real group ID respectively. +Either may be modified through execution of a set-user-ID or set-group-ID file (possibly by one its ancestors) (see .Xr execve 2 ) . @@ -553,7 +561,8 @@ list) is duplicated, so that the execution of a set-group-ID program does not result in the loss of the original (real) group ID. .Pp The group access list is a set of group IDs -used only in determining resource accessibility. Access checks +used only in determining resource accessibility. +Access checks are performed as described below in ``File Access Permissions''. .It "Saved Set User ID and Saved Set Group ID" When a process executes a new file, the effective user ID is set @@ -625,12 +634,14 @@ If a path name begins with a slash, the path search begins at the .Em root directory. Otherwise, the search begins from the current working directory. -A slash by itself names the root directory. An empty +A slash by itself names the root directory. +An empty pathname refers to the current directory. .It Directory A directory is a special type of file that contains entries that are references to other files. -Directory entries are called links. By convention, a directory +Directory entries are called links. +By convention, a directory contains at least two links, .Ql .\& and @@ -639,32 +650,38 @@ referred to as .Em dot and .Em dot-dot -respectively. Dot refers to the directory itself and +respectively. +Dot refers to the directory itself and dot-dot refers to its parent directory. .It "Root Directory and Current Working Directory" Each process has associated with it a concept of a root directory and a current working directory for the purpose of resolving path -name searches. A process's root directory need not be the root +name searches. +A process's root directory need not be the root directory of the root file system. .It File Access Permissions Every file in the file system has a set of access permissions. These permissions are used in determining whether a process may perform a requested operation on the file (such as opening -a file for writing). Access permissions are established at the -time a file is created. They may be changed at some later time +a file for writing). +Access permissions are established at the +time a file is created. +They may be changed at some later time through the .Xr chmod 2 call. .Pp File access is broken down according to whether a file may be: read, -written, or executed. Directory files use the execute +written, or executed. +Directory files use the execute permission to control if the directory may be searched. .Pp File access permissions are interpreted by the system as they apply to three different classes of users: the owner of the file, those users in the file's group, anyone else. Every file has an independent set of access permissions for -each of these classes. When an access check is made, the system +each of these classes. +When an access check is made, the system decides if permission should be granted by checking the access information applicable to the caller. .Pp @@ -707,9 +724,12 @@ for more information about the types available and their properties. .Pp Each instance of the system supports some number of sets of -communications protocols. Each protocol set supports addresses -of a certain format. An Address Family is the set of addresses -for a specific group of protocols. Each socket has an address +communications protocols. +Each protocol set supports addresses +of a certain format. +An Address Family is the set of addresses +for a specific group of protocols. +Each socket has an address chosen from the address family in which the socket was created. .El .Sh SEE ALSO diff --git a/lib/libc/sys/ioctl.2 b/lib/libc/sys/ioctl.2 index b6de37e..e5a902f 100644 --- a/lib/libc/sys/ioctl.2 +++ b/lib/libc/sys/ioctl.2 @@ -50,7 +50,7 @@ The .Fn ioctl system call manipulates the underlying device parameters of special files. In particular, many operating -characteristics of character special files (e.g. terminals) +characteristics of character special files (e.g.\& terminals) may be controlled with .Fn ioctl requests. diff --git a/lib/libc/sys/issetugid.2 b/lib/libc/sys/issetugid.2 index 5b0e6e7..a9b234b 100644 --- a/lib/libc/sys/issetugid.2 +++ b/lib/libc/sys/issetugid.2 @@ -75,7 +75,8 @@ system call (or other library code that calls fork, such as It is assumed that a program that clears all privileges as it prepares to execute another will also reset the environment, hence the .Dq tainted -status will not be passed on. This is important for programs such as +status will not be passed on. +This is important for programs such as .Xr su 1 which begin setuid but need to be able to create an untainted process. .Sh ERRORS diff --git a/lib/libc/sys/kldnext.2 b/lib/libc/sys/kldnext.2 index 4cf443c..9588647c 100644 --- a/lib/libc/sys/kldnext.2 +++ b/lib/libc/sys/kldnext.2 @@ -51,7 +51,8 @@ is the last file loaded. The .Fn kldnext system call -returns the fileid of the next kld file (see DESCRIPTION) or 0. If an error +returns the fileid of the next kld file (see DESCRIPTION) or 0. +If an error occurs, .Va errno is set to indicate the error. diff --git a/lib/libc/sys/kldstat.2 b/lib/libc/sys/kldstat.2 index 5f91520..946417a 100644 --- a/lib/libc/sys/kldstat.2 +++ b/lib/libc/sys/kldstat.2 @@ -92,7 +92,8 @@ The file was not found (probably not loaded). .It Bq Er EINVAL The version specified in the .Fa version -field of stat is not the proper version. You would need to rebuild world, the +field of stat is not the proper version. +You would need to rebuild world, the kernel, or your application, if this error occurs, given that you did properly fill in the .Fa version diff --git a/lib/libc/sys/kqueue.2 b/lib/libc/sys/kqueue.2 index 4baaf69..5e84e8a 100644 --- a/lib/libc/sys/kqueue.2 +++ b/lib/libc/sys/kqueue.2 @@ -124,15 +124,18 @@ specified unlike If .Fa timeout is a non-NULL pointer, it specifies a maximum interval to wait -for an event, which will be interpreted as a struct timespec. If +for an event, which will be interpreted as a struct timespec. +If .Fa timeout is a NULL pointer, .Fn kevent -waits indefinitely. To effect a poll, the +waits indefinitely. +To effect a poll, the .Fa timeout argument should be non-NULL, pointing to a zero-valued .Va timespec -structure. The same array may be used for the +structure. +The same array may be used for the .Fa changelist and .Fa eventlist . @@ -165,7 +168,8 @@ Value used to identify this event. The exact interpretation is determined by the attached filter, but often is a file descriptor. .It filter -Identifies the kernel filter used to process this event. The pre-defined +Identifies the kernel filter used to process this event. +The pre-defined system filters are described below. .It flags Actions to perform on the event. @@ -182,9 +186,11 @@ The field can contain the following values: .Bl -tag -width XXXEV_ONESHOT .It EV_ADD -Adds the event to the kqueue. Re-adding an existing event +Adds the event to the kqueue. +Re-adding an existing event will modify the parameters of the original event, and not result -in a duplicate entry. Adding an event automatically enables it, +in a duplicate entry. +Adding an event automatically enables it, unless overridden by the EV_DISABLE flag. .It EV_ENABLE Permit @@ -193,19 +199,23 @@ to return the event if it is triggered. .It EV_DISABLE Disable the event so .Fn kevent -will not return it. The filter itself is not disabled. +will not return it. +The filter itself is not disabled. .It EV_DELETE -Removes the event from the kqueue. Events which are attached to +Removes the event from the kqueue. +Events which are attached to file descriptors are automatically deleted on the last close of the descriptor. .It EV_ONESHOT Causes the event to return only the first occurrence of the filter -being triggered. After the user retrieves the event from the kqueue, +being triggered. +After the user retrieves the event from the kqueue, it is deleted. .It EV_CLEAR After the event is retrieved by the user, its state is reset. This is useful for filters which report state transitions -instead of the current state. Note that some filters may automatically +instead of the current state. +Note that some filters may automatically set this flag internally. .It EV_EOF Filters may set this flag to indicate filter-specific EOF condition. @@ -283,7 +293,8 @@ contains the number of bytes available. .El .It EVFILT_WRITE Takes a descriptor as the identifier, and returns whenever -it is possible to write to the descriptor. For sockets, pipes +it is possible to write to the descriptor. +For sockets, pipes and fifos, .Va data will contain the amount of space remaining in the write buffer. @@ -319,7 +330,8 @@ Alternatively, a kevent structure may be initialized, with containing the descriptor of the kqueue, and the address of the kevent structure placed in the .Va aio_lio_opcode -field of the AIO request. However, this approach will not work on +field of the AIO request. +However, this approach will not work on architectures with 64-bit pointers, and should be considered deprecated. .It EVFILT_VNODE Takes a file descriptor as the identifier and the events to watch for in @@ -371,7 +383,8 @@ or similar call. .It NOTE_TRACK Follow a process across .Fn fork -calls. The parent process will return with NOTE_TRACK set in the +calls. +The parent process will return with NOTE_TRACK set in the .Va fflags field, while the child process will return with NOTE_CHILD set in .Va fflags @@ -392,9 +405,11 @@ This coexists with the .Fn signal and .Fn sigaction -facilities, and has a lower precedence. The filter will record +facilities, and has a lower precedence. +The filter will record all attempts to deliver a signal to a process, even if the signal has -been marked as SIG_IGN. Event notification happens after normal +been marked as SIG_IGN. +Event notification happens after normal signal delivery processing. .Va data returns the number of times the signal has occurred since the last call to diff --git a/lib/libc/sys/link.2 b/lib/libc/sys/link.2 index 9c064b4..f39768a 100644 --- a/lib/libc/sys/link.2 +++ b/lib/libc/sys/link.2 @@ -170,5 +170,6 @@ function appeared in The .Fn link system call traditionally allows the super-user to link directories which -corrupts the file system coherency. This implementation no longer permits +corrupts the file system coherency. +This implementation no longer permits it. diff --git a/lib/libc/sys/lseek.2 b/lib/libc/sys/lseek.2 index 30cf1e0..13bcf21 100644 --- a/lib/libc/sys/lseek.2 +++ b/lib/libc/sys/lseek.2 @@ -101,7 +101,8 @@ 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). .Pp -Some devices are incapable of seeking. The value of the pointer +Some devices are incapable of seeking. +The value of the pointer associated with such a device is undefined. .Sh RETURN VALUES Upon successful completion, diff --git a/lib/libc/sys/madvise.2 b/lib/libc/sys/madvise.2 index 25cb5c7..ea7e8ef 100644 --- a/lib/libc/sys/madvise.2 +++ b/lib/libc/sys/madvise.2 @@ -70,23 +70,28 @@ pages immediately preceding a given page when it is faulted in. .It Dv MADV_WILLNEED Causes pages that are in a given virtual address range to temporarily have higher priority, and if they are in -memory, decrease the likelihood of them being freed. Additionally, +memory, decrease the likelihood of them being freed. +Additionally, the pages that are already in memory will be immediately mapped into the process, thereby eliminating unnecessary overhead of going through -the entire process of faulting the pages in. This WILL NOT fault +the entire process of faulting the pages in. +This WILL NOT fault pages in from backing store, but quickly map the pages already in memory into the calling process. .It Dv MADV_DONTNEED Allows the VM system to decrease the in-memory priority -of pages in the specified range. Additionally future references to +of pages in the specified range. +Additionally future references to this address range will incur a page fault. .It Dv MADV_FREE Gives the VM system the freedom to free pages, and tells the system that information in the specified page range -is no longer important. This is an efficient way of allowing +is no longer important. +This is an efficient way of allowing .Xr malloc 3 to free pages anywhere in the address space, while keeping the address space -valid. The next time that the page is referenced, the page might be demand +valid. +The next time that the page is referenced, the page might be demand zeroed, or might contain the data that was there before the .Dv MADV_FREE call. @@ -95,9 +100,11 @@ page the information back in from backing store until the page is modified again. .It Dv MADV_NOSYNC Request that the system not flush the data associated with this map to -physical backing store unless it needs to. Typically this prevents the +physical backing store unless it needs to. +Typically this prevents the file system update daemon from gratuitously writing pages dirtied -by the VM system to physical disk. Note that VM/file system coherency is +by the VM system to physical disk. +Note that VM/file system coherency is always maintained, this feature simply ensures that the mapped data is only flush when it needs to be, usually by the system pager. .Pp @@ -106,14 +113,17 @@ memory area to communicate between processes (IPC) and do not particularly need the data being stored in that area to be physically written to disk. With this feature you get the equivalent performance with mmap that you would expect to get with SysV shared memory calls, but in a more controllable -and less restrictive manner. However, note that this feature is not portable +and less restrictive manner. +However, note that this feature is not portable across UNIX platforms (though some may do the right thing by default). For more information see the MAP_NOSYNC section of .Xr mmap 2 .It Dv MADV_AUTOSYNC Undoes the effects of MADV_NOSYNC for any future pages dirtied within the -address range. The effect on pages already dirtied is indeterminate - they -may or may not be reverted. You can guarantee reversion by using the +address range. +The effect on pages already dirtied is indeterminate - they +may or may not be reverted. +You can guarantee reversion by using the .Xr msync 2 or .Xr fsync 2 diff --git a/lib/libc/sys/mmap.2 b/lib/libc/sys/mmap.2 index 8d6cfd7..798396e 100644 --- a/lib/libc/sys/mmap.2 +++ b/lib/libc/sys/mmap.2 @@ -181,7 +181,7 @@ it. You can test file fragmentation by observing the KB/t (kilobytes per transfer) results from an .Dq Li iostat 1 -while reading a large file sequentially, e.g. using +while reading a large file sequentially, e.g.\& using .Dq Li dd if=filename of=/dev/null bs=32k . .Pp The diff --git a/lib/libc/sys/modnext.2 b/lib/libc/sys/modnext.2 index b512b7b..3a6f69b 100644 --- a/lib/libc/sys/modnext.2 +++ b/lib/libc/sys/modnext.2 @@ -65,7 +65,8 @@ The system call returns the modid of the next module (see .Sx DESCRIPTION ) -or 0. If an error +or 0. +If an error occurs, .Va errno is set to indicate the error. diff --git a/lib/libc/sys/modstat.2 b/lib/libc/sys/modstat.2 index 21673f5..9356232 100644 --- a/lib/libc/sys/modstat.2 +++ b/lib/libc/sys/modstat.2 @@ -95,7 +95,8 @@ The module was not found (probably not loaded). .It Bq Er EINVAL The version specified in the .Fa version -field of stat is not the proper version. You would need to rebuild world, the +field of stat is not the proper version. +You would need to rebuild world, the kernel, or your application, if this error occurs, given that you did properly fill in the .Fa version diff --git a/lib/libc/sys/nanosleep.2 b/lib/libc/sys/nanosleep.2 index 2d03ee5..f086305 100644 --- a/lib/libc/sys/nanosleep.2 +++ b/lib/libc/sys/nanosleep.2 @@ -51,7 +51,8 @@ The .Fn nanosleep system call -causes the process to sleep for the specified time. An unmasked signal will +causes the process to sleep for the specified time. +An unmasked signal will cause it to terminate the sleep early, regardless of the .Dv SA_RESTART value on the interrupting signal. diff --git a/lib/libc/sys/open.2 b/lib/libc/sys/open.2 index 8048ee5..14d8722 100644 --- a/lib/libc/sys/open.2 +++ b/lib/libc/sys/open.2 @@ -247,7 +247,7 @@ or is specified but the underlying file system does not support locking. .It Bq Er EOPNOTSUPP The named file is a special file mounted through a file system that -does not support access to it (e.g. NFS). +does not support access to it (e.g.\& NFS). .It Bq Er EWOULDBLOCK .Dv O_NONBLOCK and one of diff --git a/lib/libc/sys/poll.2 b/lib/libc/sys/poll.2 index 3456350..28c426e 100644 --- a/lib/libc/sys/poll.2 +++ b/lib/libc/sys/poll.2 @@ -50,7 +50,8 @@ The .Fa fds argument is a pointer to an array of pollfd structures as defined in .In poll.h -(shown below). The +(shown below). +The .Fa nfds argument determines the size of the .Fa fds @@ -68,13 +69,16 @@ The fields of are as follows: .Bl -tag -width XXXrevents .It fd -File descriptor to poll. If fd is equal to -1 then +File descriptor to poll. +If fd is equal to -1 then .Fa revents is cleared (set to zero), and that pollfd is not checked. .It events -Events to poll for. (See below.) +Events to poll for. +(See below.) .It revents -Events which may occur. (See below.) +Events which may occur. +(See below.) .El .Pp The event bitmasks in @@ -97,15 +101,18 @@ Normal data may be written without blocking. .It POLLWRBAND Data with a non-zero priority may be written without blocking. .It POLLERR -An exceptional condition has occurred on the device or socket. This +An exceptional condition has occurred on the device or socket. +This flag is always checked, even if not present in the .Fa events bitmask. .It POLLHUP -The device or socket has been disconnected. This flag is always +The device or socket has been disconnected. +This flag is always checked, even if not present in the .Fa events -bitmask. Note that +bitmask. +Note that POLLHUP and POLLOUT @@ -113,7 +120,8 @@ should never be present in the .Fa revents bitmask at the same time. .It POLLNVAL -The file descriptor is not open. This flag is always checked, even +The file descriptor is not open. +This flag is always checked, even if not present in the .Fa events bitmask. @@ -122,9 +130,11 @@ bitmask. If .Fa timeout is neither zero nor INFTIM (-1), it specifies a maximum interval to -wait for any file descriptor to become ready, in milliseconds. If +wait for any file descriptor to become ready, in milliseconds. +If .Fa timeout -is INFTIM (-1), the poll blocks indefinitely. If +is INFTIM (-1), the poll blocks indefinitely. +If .Fa timeout is zero, then .Fn poll @@ -134,7 +144,8 @@ The .Fn poll system call returns the number of descriptors that are ready for I/O, or -1 if an -error occurred. If the time limit expires, +error occurred. +If the time limit expires, .Fn poll returns 0. If @@ -148,15 +159,18 @@ array will be unmodified. This implementation differs from the historical one in that a given file descriptor may not cause .Fn poll -to return with an error. In cases where this would have happened in -the historical implementation (e.g. trying to poll a +to return with an error. +In cases where this would have happened in +the historical implementation (e.g.\& trying to poll a .Xr revoke 2 Ns ed descriptor), this implementation instead copies the .Fa events bitmask to the .Fa revents -bitmask. Attempting to perform I/O on this descriptor will then -return an error. This behaviour is believed to be more useful. +bitmask. +Attempting to perform I/O on this descriptor will then +return an error. +This behaviour is believed to be more useful. .Sh ERRORS An error return from .Fn poll @@ -187,7 +201,8 @@ The distinction between some of the fields in the .Fa events and .Fa revents -bitmasks is really not useful without STREAMS. The fields are +bitmasks is really not useful without STREAMS. +The fields are defined for compatibility with existing software. .Sh HISTORY The diff --git a/lib/libc/sys/read.2 b/lib/libc/sys/read.2 index 8e38652..1e98f3a 100644 --- a/lib/libc/sys/read.2 +++ b/lib/libc/sys/read.2 @@ -112,7 +112,8 @@ Upon return from the pointer is incremented by the number of bytes actually read. .Pp Objects that are not capable of seeking always read from the current -position. The value of the pointer associated with such an +position. +The value of the pointer associated with such an object is undefined. .Pp Upon successful completion, @@ -166,7 +167,7 @@ and no data were ready to be read. .It Bq Er EISDIR The file descriptor is associated with a directory residing on a file system that does not allow regular read operations on -directories (e.g. NFS). +directories (e.g.\& NFS). .It Bq Er EOPNOTSUPP The file descriptor is associated with a file system and file type that do not allow regular read operations on it. diff --git a/lib/libc/sys/rename.2 b/lib/libc/sys/rename.2 index 6a9be42..0080f40 100644 --- a/lib/libc/sys/rename.2 +++ b/lib/libc/sys/rename.2 @@ -168,7 +168,8 @@ The link named by .Fa to and the file named by .Fa from -are on different logical devices (file systems). Note that this error +are on different logical devices (file systems). +Note that this error code will not be returned if the implementation permits cross-device links. .It Bq Er ENOSPC diff --git a/lib/libc/sys/rfork.2 b/lib/libc/sys/rfork.2 index 7f160ec..d6c69dc 100644 --- a/lib/libc/sys/rfork.2 +++ b/lib/libc/sys/rfork.2 @@ -59,7 +59,8 @@ If set, the kernel will force sharing of the entire address space, typically by sharing the hardware page table directly. The child will thus inherit and share all the segments the parent process owns, -whether they are normally shareable or not. The stack segment is +whether they are normally shareable or not. +The stack segment is not split (both the parent and child return on the same stack) and thus .Fn rfork with the RFMEM flag may not generally be called directly from high level @@ -67,7 +68,8 @@ languages including C. May be set only with .Dv RFPROC . A helper function is provided to assist with this problem and will cause -the new process to run on the provided stack. See +the new process to run on the provided stack. +See .Xr rfork_thread 3 for information. .It Dv RFSIGSHARE @@ -75,7 +77,8 @@ If set, the kernel will force sharing the sigacts structure between the child and the parent. .It Dv RFLINUXTHPN If set, the kernel will return SIGUSR1 instead of SIGCHILD upon thread -exit for the child. This is intended to mimic certain Linux clone behaviour. +exit for the child. +This is intended to mimic certain Linux clone behaviour. .El .Pp File descriptors in a shared file descriptor table are kept @@ -110,7 +113,8 @@ Upon successful completion, .Fn rfork returns a value of 0 to the child process and returns the process ID of the child -process to the parent process. Otherwise, a value of -1 is returned +process to the parent process. +Otherwise, a value of -1 is returned to the parent process, no child process is created, and the global variable .Va errno @@ -166,7 +170,8 @@ does not yet implement a native .Fn clone library call, and the current pthreads implementation does not use .Fn rfork -with RFMEM. A native port of the linux threads library, +with RFMEM. +A native port of the linux threads library, .Pa /usr/ports/devel/linuxthreads , contains a working .Fn clone diff --git a/lib/libc/sys/sched_get_priority_max.2 b/lib/libc/sys/sched_get_priority_max.2 index 9f8104a..88d1d6d 100644 --- a/lib/libc/sys/sched_get_priority_max.2 +++ b/lib/libc/sys/sched_get_priority_max.2 @@ -82,7 +82,8 @@ If successful, the and .Fn sched_get_priority_min system calls shall return the appropriate maximum or minimum values, -respectively. If unsuccessful, they shall return a value of -1 and set +respectively. +If unsuccessful, they shall return a value of -1 and set .Fa errno to indicate the error. .Pp diff --git a/lib/libc/sys/sched_setparam.2 b/lib/libc/sys/sched_setparam.2 index bfd9115..dfc2ac0 100644 --- a/lib/libc/sys/sched_setparam.2 +++ b/lib/libc/sys/sched_setparam.2 @@ -85,12 +85,14 @@ argument is set higher than that of the lowest priority running process and if the specified process is ready to run, the process specified by the .Fa pid -argument will preempt a lowest priority running process. Similarly, if +argument will preempt a lowest priority running process. +Similarly, if the process calling .Fn sched_setparam sets its own priority lower than that of one or more other nonempty process lists, then the process that is the head of the highest priority -list will also preempt the calling process. Thus, in either case, the +list will also preempt the calling process. +Thus, in either case, the originating process might not receive notification of the completion of the requested priority change until the higher priority process has executed. @@ -128,7 +130,8 @@ as a read-style operation. If .Fa pid is zero, the scheduling parameters for the calling process will be -returned. In this implementation, the +returned. +In this implementation, the .Fa sched_getparam system call will fail if .Fa pid diff --git a/lib/libc/sys/sched_setscheduler.2 b/lib/libc/sys/sched_setscheduler.2 index 15a1ab7..21b34e0 100644 --- a/lib/libc/sys/sched_setscheduler.2 +++ b/lib/libc/sys/sched_setscheduler.2 @@ -123,7 +123,8 @@ as a read-style operation. If .Fa pid is zero, the scheduling parameters for the calling process will be -returned. In this implementation, the +returned. +In this implementation, the .Fa sched_getscheduler system call will fail if .Fa pid diff --git a/lib/libc/sys/sched_yield.2 b/lib/libc/sys/sched_yield.2 index c8a60a0..9db8942 100644 --- a/lib/libc/sys/sched_yield.2 +++ b/lib/libc/sys/sched_yield.2 @@ -39,7 +39,8 @@ The .Fn sched_yield system call forces the running process to relinquish the processor until it -again becomes the head of its process list. It takes no arguments. +again becomes the head of its process list. +It takes no arguments. .Sh RETURN VALUES .Rv -std sched_yield .Sh ERRORS diff --git a/lib/libc/sys/select.2 b/lib/libc/sys/select.2 index 823eeaa..bacd76e 100644 --- a/lib/libc/sys/select.2 +++ b/lib/libc/sys/select.2 @@ -109,7 +109,8 @@ to the maximum number of descriptors supported by the system. If .Fa timeout is a non-nil pointer, it specifies the maximum interval to wait for the -selection to complete. System activity can lengthen the interval by +selection to complete. +System activity can lengthen the interval by an indeterminate amount. .Pp If @@ -158,7 +159,8 @@ points to an invalid address. A signal was delivered before the time limit expired and before any of the selected events occurred. .It Bq Er EINVAL -The specified time limit is invalid. One of its components is +The specified time limit is invalid. +One of its components is negative or too large. .It Bq Er EINVAL The @@ -195,7 +197,8 @@ If .Fa nfds is greater than the number of open files, .Fn select -is not guaranteed to examine the unused file descriptors. For historical +is not guaranteed to examine the unused file descriptors. +For historical reasons, .Fn select will always examine the first 256 descriptors. diff --git a/lib/libc/sys/semctl.2 b/lib/libc/sys/semctl.2 index b69b8fb..0971949 100644 --- a/lib/libc/sys/semctl.2 +++ b/lib/libc/sys/semctl.2 @@ -95,7 +95,8 @@ or .Fa sem_perm.cuid , or it must have superuser privileges. .It IPC_RMID -Immediately removes the semaphore set from the system. The calling +Immediately removes the semaphore set from the system. +The calling process's effective uid must equal the semaphore set's .Fa sem_perm.uid or diff --git a/lib/libc/sys/semget.2 b/lib/libc/sys/semget.2 index f493281..18c083b 100644 --- a/lib/libc/sys/semget.2 +++ b/lib/libc/sys/semget.2 @@ -53,13 +53,15 @@ set of semaphores. .\" The key is analogous to a filename: it provides a handle that names an -IPC object. There are three ways to specify a key: +IPC object. +There are three ways to specify a key: .Bl -bullet .It IPC_PRIVATE may be specified, in which case a new IPC object will be created. .It -An integer constant may be specified. If no IPC object corresponding +An integer constant may be specified. +If no IPC object corresponding to .Fa key is specified and the IPC_CREAT bit is set in diff --git a/lib/libc/sys/send.2 b/lib/libc/sys/send.2 index 38c8f80..f5fae6f 100644 --- a/lib/libc/sys/send.2 +++ b/lib/libc/sys/send.2 @@ -183,7 +183,8 @@ but may be caused by transient congestion. The remote host was unreachable. .It Bq Er ECONNREFUSED The socket received an ICMP destination unreachable message -from the last message sent. This typically means that the +from the last message sent. +This typically means that the receiver is not listening on the remote port. .It Bq Er EHOSTDOWN The remote host was down. @@ -214,7 +215,8 @@ domain socket then .Fn close it before it has actually been sent, the result being that the receiver -gets a closed file descriptor. It is left to the application to +gets a closed file descriptor. +It is left to the application to implement an acknowledgment mechanism to prevent this from happening. .Sh SEE ALSO .Xr fcntl 2 , diff --git a/lib/libc/sys/shm_open.2 b/lib/libc/sys/shm_open.2 index 0619133..ac4c110 100644 --- a/lib/libc/sys/shm_open.2 +++ b/lib/libc/sys/shm_open.2 @@ -150,7 +150,8 @@ functions can fail with any error defined for .Fn open and .Fn unlink , -respectively. In addition, the following errors are defined for +respectively. +In addition, the following errors are defined for .Fn shm_open : .Bl -tag -width Er .It Bq Er EINVAL diff --git a/lib/libc/sys/shmat.2 b/lib/libc/sys/shmat.2 index b992d41..8fe340c 100644 --- a/lib/libc/sys/shmat.2 +++ b/lib/libc/sys/shmat.2 @@ -49,7 +49,8 @@ The system call attaches the shared memory segment identified by .Fa shmid -to the calling process's address space. The address where the segment +to the calling process's address space. +The address where the segment is attached is determined as follows: .\" .\" These are cribbed almost exactly from Stevens, _Advanced Programming in diff --git a/lib/libc/sys/shmctl.2 b/lib/libc/sys/shmctl.2 index ea7eaa7..d73c516 100644 --- a/lib/libc/sys/shmctl.2 +++ b/lib/libc/sys/shmctl.2 @@ -71,10 +71,12 @@ or .Fa shm_perm.cuid , or it must have superuser privileges. .It Dv IPC_RMID -Removes the segment from the system. The removal will not take +Removes the segment from the system. +The removal will not take effect until all processes having attached the segment have exited; however, once the IPC_RMID operation has taken place, no further -processes will be allowed to attach the segment. For the operation +processes will be allowed to attach the segment. +For the operation to succeed, the calling process's effective uid must match .Fa shm_perm.uid or diff --git a/lib/libc/sys/shmget.2 b/lib/libc/sys/shmget.2 index 5d8bc5a..e7fd6d1 100644 --- a/lib/libc/sys/shmget.2 +++ b/lib/libc/sys/shmget.2 @@ -54,13 +54,15 @@ memory segment. .\" The key is analogous to a filename: it provides a handle that names an -IPC object. There are three ways to specify a key: +IPC object. +There are three ways to specify a key: .Bl -bullet .It IPC_PRIVATE may be specified, in which case a new IPC object will be created. .It -An integer constant may be specified. If no IPC object corresponding +An integer constant may be specified. +If no IPC object corresponding to .Fa key is specified and the IPC_CREAT bit is set in @@ -100,7 +102,8 @@ Write access for other. .Pp When creating a new shared memory segment, .Fa size -indicates the desired size of the new segment in bytes. The size +indicates the desired size of the new segment in bytes. +The size of the segment may be rounded up to a multiple convenient to the kernel (i.e., the page size). .Sh RETURN VALUES diff --git a/lib/libc/sys/sigaction.2 b/lib/libc/sys/sigaction.2 index 69f60e4..cd4eb89 100644 --- a/lib/libc/sys/sigaction.2 +++ b/lib/libc/sys/sigaction.2 @@ -559,7 +559,7 @@ cause of the signal, usually one of the .Dv SI_... values from .In sys/signal.h -or codes specific to a signal, i.e. one of the +or codes specific to a signal, i.e., one of the .Dv FPE_... values for .Dv SIGFPE . diff --git a/lib/libc/sys/socket.2 b/lib/libc/sys/socket.2 index dab67b2..dadd683 100644 --- a/lib/libc/sys/socket.2 +++ b/lib/libc/sys/socket.2 @@ -81,7 +81,8 @@ PF_NETGRAPH Netgraph sockets .Pp The socket has the indicated .Fa type , -which specifies the semantics of communication. Currently +which specifies the semantics of communication. +Currently defined types are: .Pp .Bd -literal -offset indent -compact @@ -123,9 +124,11 @@ The argument specifies a particular protocol to be used with the socket. Normally only a single protocol exists to support a particular -socket type within a given protocol family. However, it is possible +socket type within a given protocol family. +However, it is possible that many protocols may exist, in which case a particular protocol -must be specified in this manner. The protocol number to use is +must be specified in this manner. +The protocol number to use is particular to the .Dq "communication domain" in which communication @@ -135,10 +138,12 @@ is to take place; see Sockets of type .Dv SOCK_STREAM are full-duplex byte streams, similar -to pipes. A stream socket must be in a +to pipes. +A stream socket must be in a .Em connected state before any data may be sent or received -on it. A connection to another socket is created with a +on it. +A connection to another socket is created with a .Xr connect 2 system call. Once connected, data may be transferred using @@ -168,7 +173,8 @@ and received as described in The communications protocols used to implement a .Dv SOCK_STREAM insure that data -is not lost or duplicated. If a piece of data for which the +is not lost or duplicated. +If a piece of data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, then the connection is considered broken and calls @@ -184,7 +190,7 @@ by forcing transmissions roughly every minute in the absence of other activity. An error is then indicated if no response can be elicited on an otherwise -idle connection for an extended period (e.g. 5 minutes). +idle connection for an extended period (e.g.\& 5 minutes). A .Dv SIGPIPE signal is raised if a process sends @@ -195,7 +201,8 @@ which do not handle the signal, to exit. sockets employ the same system calls as .Dv SOCK_STREAM -sockets. The only difference +sockets. +The only difference is that .Xr read 2 calls will return only the amount of data requested, @@ -207,7 +214,8 @@ and sockets allow sending of datagrams to correspondents named in .Xr send 2 -calls. Datagrams are generally received with +calls. +Datagrams are generally received with .Xr recvfrom 2 , which returns the next datagram with its return address. .Pp diff --git a/lib/libc/sys/swapon.2 b/lib/libc/sys/swapon.2 index 6aaf4f2..29e9da5 100644 --- a/lib/libc/sys/swapon.2 +++ b/lib/libc/sys/swapon.2 @@ -53,9 +53,11 @@ system call makes the block device .Fa special available to the system for -allocation for paging and swapping. The names of potentially +allocation for paging and swapping. +The names of potentially available devices are known to the system and defined at system -configuration time. The size of the swap area on +configuration time. +The size of the swap area on .Fa special is calculated at the time the device is first made available for swapping. diff --git a/lib/libc/sys/sysarch.2 b/lib/libc/sys/sysarch.2 index 0b3e8ae..9d8f050 100644 --- a/lib/libc/sys/sysarch.2 +++ b/lib/libc/sys/sysarch.2 @@ -69,7 +69,8 @@ functions can be found in the header file The .Fn sysarch system call should never be called directly by -user programs. Instead, they should access +user programs. +Instead, they should access its functions using the architecture-dependent library. .Sh RETURN VALUES diff --git a/lib/libc/sys/truncate.2 b/lib/libc/sys/truncate.2 index 29892ac..5966f5f 100644 --- a/lib/libc/sys/truncate.2 +++ b/lib/libc/sys/truncate.2 @@ -57,7 +57,8 @@ or referenced by .Fa fd to be truncated or extended to .Fa length -bytes in size. If the file +bytes in size. +If the file was larger than this size, the extra data is lost. If the file was smaller than this size, diff --git a/lib/libc/sys/umask.2 b/lib/libc/sys/umask.2 index 9226071..00ff4e7 100644 --- a/lib/libc/sys/umask.2 +++ b/lib/libc/sys/umask.2 @@ -49,7 +49,8 @@ The .Fn umask routine sets the process's file mode creation mask to .Fa numask -and returns the previous value of the mask. The 9 low-order +and returns the previous value of the mask. +The 9 low-order access permission bits of .Fa numask diff --git a/lib/libc/sys/unlink.2 b/lib/libc/sys/unlink.2 index 6050b39..3326134 100644 --- a/lib/libc/sys/unlink.2 +++ b/lib/libc/sys/unlink.2 @@ -118,5 +118,6 @@ function appeared in The .Fn unlink system call traditionally allows the super-user to unlink directories which -can damage the file system integrity. This implementation no longer permits +can damage the file system integrity. +This implementation no longer permits it. diff --git a/lib/libc/sys/vfork.2 b/lib/libc/sys/vfork.2 index cf57134..b299923 100644 --- a/lib/libc/sys/vfork.2 +++ b/lib/libc/sys/vfork.2 @@ -50,7 +50,8 @@ The system call can be used to create new processes without fully copying the address space of the old process, which is horrendously inefficient in a paged -environment. It is useful when the purpose of +environment. +It is useful when the purpose of .Xr fork 2 would have been to create a new system context for an .Xr execve 2 . diff --git a/lib/libc/sys/wait.2 b/lib/libc/sys/wait.2 index 4f6df2d..35a2818 100644 --- a/lib/libc/sys/wait.2 +++ b/lib/libc/sys/wait.2 @@ -102,7 +102,8 @@ equals the absolute value of .Pp The .Fa status -argument is defined below. The +argument is defined below. +The .Fa options argument contains the bitwise OR of any of the following options. The @@ -237,7 +238,8 @@ If .Fn wait returns due to a stopped or terminated child process, the process ID of the child -is returned to the calling process. Otherwise, a value of -1 +is returned to the calling process. +Otherwise, a value of -1 is returned and .Va errno is set to indicate the error. diff --git a/lib/libc/sys/write.2 b/lib/libc/sys/write.2 index 2064769..4687e3b 100644 --- a/lib/libc/sys/write.2 +++ b/lib/libc/sys/write.2 @@ -112,7 +112,8 @@ Upon return from the pointer is incremented by the number of bytes which were written. .Pp Objects that are not capable of seeking always write from the current -position. The value of the pointer associated with such an object +position. +The value of the pointer associated with such an object is undefined. .Pp If the real user is not the super-user, then @@ -134,7 +135,8 @@ the return value must be noted, and the remainder of the operation should be retried when possible. .Sh RETURN VALUES Upon successful completion the number of bytes which were written -is returned. Otherwise a -1 is returned and the global variable +is returned. +Otherwise a -1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS diff --git a/lib/libcalendar/calendar.3 b/lib/libcalendar/calendar.3 index 4c4c4ec..469f1c9 100644 --- a/lib/libcalendar/calendar.3 +++ b/lib/libcalendar/calendar.3 @@ -62,7 +62,7 @@ .Fn weekday "int nd" .Sh DESCRIPTION These functions provide calendar arithmetic for a large range of years, -starting at March 1st, year zero (i. e. 1 B.C.) and ending way beyond +starting at March 1st, year zero (i.e., 1 B.C.) and ending way beyond year 100000. .Pp Programs should be linked with @@ -103,7 +103,8 @@ of a date and the "number of days" representation, which is better suited for calculations. The days are numbered from March 1st year 1 B.C., starting with zero, so the number of a day gives the number of days since March 1st, -year 1 B.C. The conversions work for nonnegative day numbers only. +year 1 B.C. +The conversions work for nonnegative day numbers only. .Pp The .Fn gdate @@ -151,7 +152,8 @@ Most catholic countries adopted the new calendar by the end of the 16th century, whereas others stayed with the Julian Calendar until the 20th century. The United Kingdom and -their colonies switched on September 2, 1752. They already had to +their colonies switched on September 2, 1752. +They already had to delete 11 days. .Pp The function @@ -168,7 +170,7 @@ This function is defined for Gregorian Calendar only. .Pp The function .Fn weekday -returns the weekday (Mo = 0 .. Su = 6) of the day numbered +returns the weekday (Mo = 0 ..\& Su = 6) of the day numbered .Fa nd . .Pp The structure diff --git a/lib/libcam/cam.3 b/lib/libcam/cam.3 index 439fe78..abfd7c2 100644 --- a/lib/libcam/cam.3 +++ b/lib/libcam/cam.3 @@ -121,8 +121,10 @@ .Fc .Sh DESCRIPTION The CAM library consists of a number of functions designed to aid in -programming with the CAM subsystem. This man page covers the basic set of -library functions. More functions are documented in the man pages listed +programming with the CAM subsystem. +This man page covers the basic set of +library functions. +More functions are documented in the man pages listed below. .Pp Many of the CAM library functions use the @@ -181,29 +183,35 @@ takes as arguments a string describing the device it is to open, and suitable for passing to .Xr open 2 . The "path" passed in may actually be most any type of string that contains -a device name and unit number to be opened. The string will be parsed by +a device name and unit number to be opened. +The string will be parsed by .Fn cam_get_device -into a device name and unit number. Once the device name and unit number +into a device name and unit number. +Once the device name and unit number are determined, a lookup is performed to determine the passthrough device that corresponds to the given device. .Fn cam_open_device is rather simple to use, but it isn't really suitable for general use -because its behavior isn't necessarily deterministic. Programmers writing +because its behavior isn't necessarily deterministic. +Programmers writing new applications should make the extra effort to use one of the other open routines documented below. .Pp .Fn cam_open_spec_device opens the .Xr pass 4 -device that corresponds to the device name and unit number passed in. The +device that corresponds to the device name and unit number passed in. +The .Ar flags should be flags suitable for passing to .Xr open 2 . The .Ar device -argument is optional. The user may supply pre-allocated space for the +argument is optional. +The user may supply pre-allocated space for the .Va cam_device -structure. If the +structure. +If the .Ar device argument is .Va NULL , @@ -219,11 +227,14 @@ is similar to except that it takes a .Tn SCSI bus, target and logical unit instead of a device name and unit number as -arguments. The +arguments. +The .Va path_id argument is the CAM equivalent of a .Tn SCSI -bus number. It represents the logical bus number in the system. The +bus number. +It represents the logical bus number in the system. +The .Ar flags should be flags suitable for passing to .Xr open 2 . @@ -238,10 +249,12 @@ takes as an argument the .Fa path of a .Xr pass 4 -device to open. No translation or lookup is performed, so the path passed +device to open. +No translation or lookup is performed, so the path passed in must be that of a CAM .Xr pass 4 -device. The +device. +The .Fa flags should be flags suitable for passing to .Xr open 2 . @@ -258,15 +271,18 @@ structure. frees the .Va cam_device structure allocated by one of the above open() calls, and closes the file -descriptor to the passthrough device. This routine should not be called if +descriptor to the passthrough device. +This routine should not be called if the user allocated space for the .Va cam_device -structure. Instead, the user should call +structure. +Instead, the user should call .Fn cam_close_spec_device . .Pp .Fn cam_close_spec_device merely closes the file descriptor opened in one of the open() routines -described above. This function should be called when the +described above. +This function should be called when the .Va cam_device structure was allocated by the caller, rather than the CAM library. .Pp @@ -297,7 +313,8 @@ takes as arguments a structure, and a string with length .Fa len . It creates a colon-terminated printing prefix string similar to the ones -used by the kernel. e.g.: "(cd0:ahc1:0:4:0): ". +used by the kernel. +e.g.: "(cd0:ahc1:0:4:0): ". .Fn cam_path_string will place at most .Fa len Ns \-1 @@ -370,7 +387,8 @@ returns a value of -1 if an error occured, and is set to indicate the error. .Pp .Fn cam_path_string -returns a filled printing prefix string as a convenience. This is the same +returns a filled printing prefix string as a convenience. +This is the same .Fa str that is passed into .Fn cam_path_string . @@ -403,11 +421,13 @@ The CAM library first appeared in .Fn cam_open_device doesn't check to see if the .Fa path -passed in is a symlink to something. It also doesn't check to see if the +passed in is a symlink to something. +It also doesn't check to see if the .Fa path passed in is an actual .Xr pass 4 -device. The former would be rather easy to implement, but the latter would +device. +The former would be rather easy to implement, but the latter would require a definitive way to identify a device node as a .Xr pass 4 device. diff --git a/lib/libcam/cam_cdbparse.3 b/lib/libcam/cam_cdbparse.3 index e31a0fb..7d7d4de 100644 --- a/lib/libcam/cam_cdbparse.3 +++ b/lib/libcam/cam_cdbparse.3 @@ -170,7 +170,8 @@ layer. These functions may be used in new applications, but users may find it easier to use the various SCSI CCB building functions included with the .Xr cam 3 -library. (e.g.\& +library. +(e.g.\& .Fn cam_fill_csio , .Fn scsi_start_stop , and @@ -194,10 +195,12 @@ argument. .Fa data_ptr is the data buffer used during the .Tn SCSI -data phase. If no data is to be +data phase. +If no data is to be transferred for the .Tn SCSI -command in question, this should be set to NULL. If there is data to +command in question, this should be set to NULL. +If there is data to transfer for the command, this buffer must be at least .Fa dxfer_len long. @@ -252,17 +255,20 @@ typedef enum { } ccb_flags; .Ed .Pp -Multiple flags should be ORed together. Any of the CCB flags may be used, +Multiple flags should be ORed together. +Any of the CCB flags may be used, although it is worth noting several important ones here: .Pp .Bl -tag -width CAM_PASS_ERR_RECOVER .It Dv CAM_DIR_IN -This indicates that the operation in question is a read operation. i.e., +This indicates that the operation in question is a read operation. +i.e., data is being read from the .Tn SCSI device to the user-supplied buffer. .It Dv CAM_DIR_OUT -This indicates that the operation is a write operation. i.e. data is being +This indicates that the operation is a write operation. +i.e., data is being written from the user-supplied buffer to the device. .It Dv CAM_DIR_NONE This indicates that there is no data to be transferred for this command. @@ -271,7 +277,8 @@ This flag disables device queue freezing as an error recovery mechanism. .It Dv CAM_PASS_ERR_RECOVER This flag tells the .Xr pass 4 -driver to enable error recovery. The default is to not perform error +driver to enable error recovery. +The default is to not perform error recovery, which means that the retry count won't be honored without this flag, among other things. .It Dv CAM_DATA_PHYS @@ -282,7 +289,8 @@ is a physical address, not a virtual address. .Pp The .Fa retry_count -tells the kernel how many times to retry the command in question. The +tells the kernel how many times to retry the command in question. +The retry count is ignored unless the .Xr pass 4 driver is told to enable error recovery via the @@ -291,22 +299,26 @@ flag. .Pp The .Fa timeout -tells the kernel how long to wait for the given command to complete. If +tells the kernel how long to wait for the given command to complete. +If the timeout expires and the command hasn't completed, the CCB will be returned from the kernel with an appropriate error status. .Pp .Fa cmd_spec is a CDB format specifier used to build up the SCSI CDB. -This text string is made up of a list of field specifiers. Field +This text string is made up of a list of field specifiers. +Field specifiers specify the value for each CDB field (including indicating that the value be taken from the next argument in the variable argument list), the width -of the field in bits or bytes, and an optional name. White space is +of the field in bits or bytes, and an optional name. +White space is ignored, and the pound sign ('#') introduces a comment that ends at the end of the current line. .Pp The optional name is the first part of a field specifier and -is in curly braces. The text in curly braces in this example are +is in curly braces. +The text in curly braces in this example are the names: .Dl "{PS} v:b1 {Reserved} 0:b1 {Page Code} v:b6 # Mode select page" .Pp @@ -378,7 +390,8 @@ function takes two arguments: .It Fa gethook is passed into the .Fn arg_get -function at each invocation. This enables the +function at each invocation. +This enables the .Fn arg_get function to keep some state in between calls without using global or static variables. @@ -447,7 +460,8 @@ is a void pointer to the value being passed into the function. .It Fa count is the size of the value being passed into the .Fn arg_put -function. The argument format determines the unit of measure. +function. +The argument format determines the unit of measure. .It Fa name This is a text description of the field, if one was provided in the .Fa fmt . @@ -506,7 +520,8 @@ The CAM versions of these functions are based upon similar functions implemented for the old .Fx .Tn SCSI -layer. The encoding/decoding functions in the old +layer. +The encoding/decoding functions in the old .Tn SCSI code were written by Peter Dufault. .Pp @@ -516,7 +531,8 @@ SCSI command in user space. The old .Va scsireq data structure was almost identical to the SGI /dev/scsi data -structure. If anyone knows the name of the authors it should +structure. +If anyone knows the name of the authors it should go here; Peter Dufault first read about it in a 1989 Sun Expert magazine. .Pp The new CCB data structures are derived from the CAM-2 and CAM-3 @@ -533,16 +549,20 @@ library and the related kernel ioctl. If anyone needs that for compatibility contact dufault@hda.com. .Sh AUTHORS Kenneth Merry implemented the CAM versions of these encoding and decoding -functions. This current work is based upon earlier work by Peter Dufault. +functions. +This current work is based upon earlier work by Peter Dufault. .Sh BUGS There should probably be a function that encodes both the CDB and the data buffer portions of a .Tn SCSI -CCB. I discovered this while implementing the arbitrary command execution +CCB. +I discovered this while implementing the arbitrary command execution code in .Xr camcontrol 8 , but I haven't yet had time to implement such a function. .Pp -Some of the CCB flag descriptions really don't belong here. Rather they -belong in a generic CCB man page. Since that man page hasn't yet been +Some of the CCB flag descriptions really don't belong here. +Rather they +belong in a generic CCB man page. +Since that man page hasn't yet been written, the shorter descriptions here will have to suffice. diff --git a/lib/libcompat/4.3/rexec.3 b/lib/libcompat/4.3/rexec.3 index 4f25ca8..5faf8ea 100644 --- a/lib/libcompat/4.3/rexec.3 +++ b/lib/libcompat/4.3/rexec.3 @@ -101,7 +101,8 @@ output from the command (unit 2) on this channel, and will also accept bytes on this channel as being .Ux signal numbers, to be -forwarded to the process group of the command. The diagnostic +forwarded to the process group of the command. +The diagnostic information returned does not include remote authorization failure, as the secondary connection is set up after authorization has been verified. diff --git a/lib/libcompat/4.4/cuserid.3 b/lib/libcompat/4.4/cuserid.3 index 4b823b2..72811d5 100644 --- a/lib/libcompat/4.4/cuserid.3 +++ b/lib/libcompat/4.4/cuserid.3 @@ -54,10 +54,12 @@ function is made obsolete by The function .Fn cuserid gets the user name associated with the effective UID of the current -process. If the argument +process. +If the argument .Fa s is non-NULL, the name is copied to the buffer it points to, -and that address is being returned. This buffer must provide space +and that address is being returned. +This buffer must provide space for at least .Em L_cuserid characters. diff --git a/lib/libcompat/regexp/regexp.3 b/lib/libcompat/regexp/regexp.3 index d4db21a..f6dad10 100644 --- a/lib/libcompat/regexp/regexp.3 +++ b/lib/libcompat/regexp/regexp.3 @@ -228,7 +228,7 @@ If two characters in the sequence are separated by `\-', this is shorthand for the full list of .Tn ASCII characters between them -(e.g. `[0-9]' matches any decimal digit). +(e.g.\& `[0-9]' matches any decimal digit). To include a literal `]' in the sequence, make it the first character (following a possible `^'). To include a literal `\-', make it the first or last character. diff --git a/lib/libcrypt/crypt.3 b/lib/libcrypt/crypt.3 index 85cee0d..1f97dae 100644 --- a/lib/libcrypt/crypt.3 +++ b/lib/libcrypt/crypt.3 @@ -51,7 +51,8 @@ The .Fn crypt function performs password hashing with additional code added to -deter key search attempts. Different algorithms can be used to +deter key search attempts. +Different algorithms can be used to in the hash. .\" .\" NOTICE: @@ -100,7 +101,8 @@ If neither of the above is true, it assumes the Traditional Format, using the entire string as the salt (or the first portion). .El .Pp -All routines are designed to be time-consuming. A brief test on a +All routines are designed to be time-consuming. +A brief test on a .Tn Pentium 166/MMX shows the .Tn DES @@ -139,7 +141,7 @@ The introduces disorder in the .Tn DES algorithm in one of 16777216 or 4096 possible ways -(ie. with 24 or 12 bits: if bit +(i.e., with 24 or 12 bits: if bit .Em i of the .Ar salt @@ -166,13 +168,18 @@ followed by the encoded 64-bit encryption. .Pp If the salt begins with the string .Fa $digit$ -then the Modular Crypt Format is used. The +then the Modular Crypt Format is used. +The .Fa digit -represents which algorithm is used in encryption. Following the token is -the actual salt to use in the encryption. The length of the salt is limited +represents which algorithm is used in encryption. +Following the token is +the actual salt to use in the encryption. +The length of the salt is limited to 8 characters--because the length of the returned output is also limited -(_PASSWORD_LEN). The salt must be terminated with the end of the string -(NULL) or a dollar sign. Any characters after the dollar sign are ignored. +(_PASSWORD_LEN). +The salt must be terminated with the end of the string +(NULL) or a dollar sign. +Any characters after the dollar sign are ignored. .Pp Currently supported algorithms are: .Pp @@ -185,7 +192,8 @@ Blowfish NT-Hash .El .Pp -Other crypt formats may be easily added. An example salt would be: +Other crypt formats may be easily added. +An example salt would be: .Bl -tag -offset indent .It Cm "$4$thesalt$rest" .El @@ -206,7 +214,8 @@ This is currently DES if it is available, or MD5 if not. .Pp -How the salt is used will depend upon the algorithm for the hash. For +How the salt is used will depend upon the algorithm for the hash. +For best results, specify at least two characters of salt. .Pp The @@ -259,7 +268,8 @@ The .Fn crypt function returns a pointer to static data, and subsequent calls to .Fn crypt -will modify the same data. Likewise, +will modify the same data. +Likewise, .Fn crypt_set_format modifies static data. .Pp diff --git a/lib/libdevstat/devstat.3 b/lib/libdevstat/devstat.3 index bbd860c..fc6c769 100644 --- a/lib/libdevstat/devstat.3 +++ b/lib/libdevstat/devstat.3 @@ -241,7 +241,7 @@ selects devices to display based upon a number of criteria: .Bl -tag -width flag .It specified devices Specified devices are the first selection priority. -These are generally devices specified by name by the user e.g. da0, da1, cd0. +These are generally devices specified by name by the user e.g.\& da0, da1, cd0. .It match patterns These are pattern matching expressions generated by .Fn devstat_buildmatch @@ -491,7 +491,7 @@ The total number of blocks transferred between the acquisition of and .Va current . This number is in terms of the blocksize reported by the device. -If no blocksize has been reported (i.e. the block size is 0), a default +If no blocksize has been reported (i.e., the block size is 0), a default blocksize of 512 bytes will be used in the calculation. .It DSM_TOTAL_BLOCKS_READ .It DSM_TOTAL_BLOCKS_WRITE @@ -503,7 +503,7 @@ The total number of blocks of the specified type between the acquisition of and .Va current . This number is in terms of the blocksize reported by the device. -If no blocksize has been reported (i.e. the block size is 0), a default +If no blocksize has been reported (i.e., the block size is 0), a default blocksize of 512 bytes will be used in the calculation. .It DSM_KB_PER_TRANSFER type: long double * @@ -566,7 +566,7 @@ The average number of blocks transferred per second between the acquisition of and .Va current . This number is in terms of the blocksize reported by the device. -If no blocksize has been reported (i.e. the block size is 0), a default +If no blocksize has been reported (i.e., the block size is 0), a default blocksize of 512 bytes will be used in the calculation. .It DSM_BLOCKS_PER_SECOND_READ .It DSM_BLOCKS_PER_SECOND_WRITE @@ -579,7 +579,7 @@ between the acquisition of and .Va current . This number is in terms of the blocksize reported by the device. -If no blocksize has been reported (i.e. the block size is 0), a default +If no blocksize has been reported (i.e., the block size is 0), a default blocksize of 512 bytes will be used in the calculation. .It DSM_MS_PER_TRANSACTION type: long double * diff --git a/lib/libdisk/libdisk.3 b/lib/libdisk/libdisk.3 index 341bb4f..1f4cef0 100644 --- a/lib/libdisk/libdisk.3 +++ b/lib/libdisk/libdisk.3 @@ -201,7 +201,8 @@ The and .Ql private_clone fields are for data private to the application, and the management -thereof. If the functions are not provided, no storage management is +thereof. +If the functions are not provided, no storage management is done, cloning will just copy the pointer and freeing will just forget it. .Pp @@ -247,16 +248,19 @@ to warnings about broken design rules in this disklayout. .Fn Disk_Names returns .Ql char** -with all disk's names (wd0, wd1 ...). You must free each pointer, as +with all disk's names (wd0, wd1 ...). +You must free each pointer, as well as the array by hand. .Pp .Fn Set_Boot_Mgr -sets this boot-manager for use on this disk. Gets written when +sets this boot-manager for use on this disk. +Gets written when .Fn Write_Disk is called. .Pp .Fn Set_Boot_Blocks -sets the boot-blocks for use on this disk. Gets written when +sets the boot-blocks for use on this disk. +Gets written when .Fn Write_Disk is called. .Pp @@ -295,7 +299,8 @@ is aligned on a track according to the BIOS geometry. .Pp .Fn Create_Chunk_DWIM creates a partition inside the given parent of the given size, and -returns a pointer to it. The first unused chunk big enough is used. +returns a pointer to it. +The first unused chunk big enough is used. .Pp .Fn MakeDev makes the device nodes for this chunk. diff --git a/lib/libfetch/fetch.3 b/lib/libfetch/fetch.3 index 118d754..da965a8 100644 --- a/lib/libfetch/fetch.3 +++ b/lib/libfetch/fetch.3 @@ -442,7 +442,7 @@ Invalid URL .El .Pp The accompanying error message includes a protocol-specific error code -and message, e.g. "File is not available (404 Not Found)" +and message, e.g.\& "File is not available (404 Not Found)" .Sh ENVIRONMENT .Bl -tag -width ".Ev FETCH_BIND_ADDRESS" .It Ev FETCH_BIND_ADDRESS diff --git a/lib/libftpio/ftpio.3 b/lib/libftpio/ftpio.3 index 5f3fd01..3d2b577 100644 --- a/lib/libftpio/ftpio.3 +++ b/lib/libftpio/ftpio.3 @@ -93,7 +93,8 @@ function attempts to log in using the supplied .Fa ftp_port defaults to the standard ftp port of 21) and .Fa verbose -fields. If it is successful, a +fields. +If it is successful, a standard stream descriptor is returned which should be passed to subsequent FTP operations. On failure, NULL is returned and @@ -104,7 +105,8 @@ The .Fn ftpChdir function attempts to issue a server CD command to the directory named in .Fa dir . -On success, zero is returned. On failure, the error code from the server. +On success, zero is returned. +On failure, the error code from the server. .Pp The .Fn ftpErrno @@ -121,14 +123,16 @@ function attempts to retrieve the file named by the argument (which is assumed to be relative to the FTP server's current directory, see .Fn ftpChdir ) -and returns a new FILE* pointer for the file or NULL on failure. If +and returns a new FILE* pointer for the file or NULL on failure. +If .Fa seekto is non-NULL, the contents of the integer it points to will be used as a restart point for the file, that is to say that the stream returned will point .Fa *seekto bytes into the file gotten (this is handy for restarting failed -transfers efficiently). If the seek operation fails, the value +transfers efficiently). +If the seek operation fails, the value of .Fa *seekto will be zero'd. @@ -137,13 +141,15 @@ The .Fn ftpGetModtime function returns the last modification time of the file named by the .Fa file -argument. If the file could not be opened or stat'd, 0 is returned. +argument. +If the file could not be opened or stat'd, 0 is returned. .Pp The .Fn ftpGetSize function returns the size in bytes of the file named by the .Fa file -argument. If the file could not be opened or stat'd, -1 is returned. +argument. +If the file could not be opened or stat'd, -1 is returned. .Pp The .Fn ftpPut @@ -195,7 +201,8 @@ and operations except that no server .Fa stream is ever returned - the connection to the server closes when -the file has been completely read. Use the lower-level routines +the file has been completely read. +Use the lower-level routines if multiple gets are required as it will be far more efficient. .Pp The @@ -208,7 +215,8 @@ and can be considered equivalent to the combined and .Fn ftpPut operations except that no server stream is ever returned - the connection -to the server closes when the file has been completely written. Use the +to the server closes when the file has been completely written. +Use the lower-level routines if multiple puts are required as it will be far more efficient. .Pp @@ -242,7 +250,8 @@ all my tests. .Sh HISTORY Started life as Poul-Henning Kamp's ftp driver for the system installation utility, later significantly mutated into a more general form as an -extension of stdio by Jordan Hubbard. Also incorporates some ideas and +extension of stdio by Jordan Hubbard. +Also incorporates some ideas and extensions from Jean-Marc Zucconi. .Sh AUTHORS .An Jordan Hubbard , diff --git a/lib/libipx/ipx.3 b/lib/libipx/ipx.3 index e349f6c..e232892 100644 --- a/lib/libipx/ipx.3 +++ b/lib/libipx/ipx.3 @@ -105,7 +105,8 @@ It is interpreted as octal if there is a leading and there are no super-octal digits. Otherwise, it is converted as a decimal number. .Sh RETURN VALUES -None. (See +None. +(See .Sx BUGS . ) .Sh SEE ALSO .\" .Xr ns 4 , diff --git a/lib/libkiconv/kiconv.3 b/lib/libkiconv/kiconv.3 index 3f1c7cb..093abfba 100644 --- a/lib/libkiconv/kiconv.3 +++ b/lib/libkiconv/kiconv.3 @@ -68,7 +68,8 @@ between .Ar fromcode charset and .Ar tocode -charset. You can specify +charset. +You can specify .Ar flag to determine if .Xr tolower 3 diff --git a/lib/libkvm/kvm.3 b/lib/libkvm/kvm.3 index e06fd2a..1d3c5eb 100644 --- a/lib/libkvm/kvm.3 +++ b/lib/libkvm/kvm.3 @@ -64,7 +64,8 @@ The .Fn kvm_open function is first called to obtain a descriptor for all subsequent calls. .Sh COMPATIBILITY -The kvm interface was first introduced in SunOS. A considerable +The kvm interface was first introduced in SunOS. +A considerable number of programs have been developed that use this interface, making backward compatibility highly desirable. In most respects, the Sun kvm interface is consistent and clean. @@ -77,11 +78,13 @@ and .Fn kvm_nlist ) has been incorporated into the .Bx -interface. Indeed, many kvm +interface. +Indeed, many kvm applications (i.e., debuggers and statistical monitors) use only this subset of the interface. .Pp -The process interface was not kept. This is not a portability +The process interface was not kept. +This is not a portability issue since any code that manipulates processes is inherently machine dependent. .Pp diff --git a/lib/libkvm/kvm_getfiles.3 b/lib/libkvm/kvm_getfiles.3 index c89a35c..d803c97 100644 --- a/lib/libkvm/kvm_getfiles.3 +++ b/lib/libkvm/kvm_getfiles.3 @@ -63,14 +63,16 @@ The and .Fa arg arguments constitute a predicate which limits the set of files -returned. No predicates are currently defined. +returned. +No predicates are currently defined. .Pp The number of files found is returned in the reference parameter .Fa cnt . The files are returned as a contiguous array of file structures, preceded by the address of the first file entry in the kernel. This memory is owned by kvm and is not guaranteed to be persistent across -subsequent kvm library calls. Data should be copied out if it needs to be +subsequent kvm library calls. +Data should be copied out if it needs to be saved. .Sh RETURN VALUES The diff --git a/lib/libkvm/kvm_getprocs.3 b/lib/libkvm/kvm_getprocs.3 index b2703a1..bacaed6 100644 --- a/lib/libkvm/kvm_getprocs.3 +++ b/lib/libkvm/kvm_getprocs.3 @@ -68,7 +68,8 @@ The and .Fa arg arguments constitute a predicate which limits the set of processes -returned. The value of +returned. +The value of .Fa op describes the filtering predicate as follows: .Pp @@ -116,7 +117,8 @@ command line arguments passed to process indicated by .Fa p . Most likely, these arguments correspond to the values passed to .Xr exec 3 -on process creation. This information is, however, +on process creation. +This information is, however, deliberately under control of the process itself. Note that the original command name can be found, unaltered, in the p_comm field of the process structure returned by @@ -125,7 +127,8 @@ in the p_comm field of the process structure returned by The .Fa nchr argument indicates the maximum number of characters, including null bytes, -to use in building the strings. If this amount is exceeded, the string +to use in building the strings. +If this amount is exceeded, the string causing the overflow is truncated and the partial result is returned. This is handy for programs like .Xr ps 1 @@ -139,7 +142,8 @@ is zero, no limit is imposed and all argument strings are returned in their entirety. .Pp The memory allocated to the argv pointers and string storage -is owned by the kvm library. Subsequent +is owned by the kvm library. +Subsequent .Fn kvm_getprocs and .Xr kvm_close 3 @@ -149,7 +153,8 @@ The .Fn kvm_getenvv function is similar to .Fn kvm_getargv -but returns the vector of environment strings. This data is +but returns the vector of environment strings. +This data is also alterable by the process. .Sh RETURN VALUES The diff --git a/lib/libkvm/kvm_getswapinfo.3 b/lib/libkvm/kvm_getswapinfo.3 index d28fc05..1927a9e 100644 --- a/lib/libkvm/kvm_getswapinfo.3 +++ b/lib/libkvm/kvm_getswapinfo.3 @@ -29,10 +29,12 @@ information for each swap device, for up to \- 1 devices. The number of devices, up to .Fa maxswap -\- 1, is returned. A grand +\- 1, is returned. +A grand total of all swap devices (including any devices that go beyond .Fa maxswap -\- 1) is returned in one additional array entry. This +\- 1) is returned in one additional array entry. +This entry is not counted in the return value. Thus, if you specify a .Fa maxswap @@ -40,7 +42,8 @@ value of 1, the function will typically return the value 0 and the single .Vt kvm_swap structure will be filled with -the grand total over all swap devices. The grand total is calculated +the grand total over all swap devices. +The grand total is calculated from all available swap devices whether or not you made room for them all in the array. The grand total is returned. @@ -51,7 +54,8 @@ If an error occurs, -1 is returned. .Pp Each swap partition and the grand total is summarized in the .Vt kvm_swap -structure. This structure contains the following fields: +structure. +This structure contains the following fields: .Pp .Bl -item -offset indent -compact .It @@ -84,6 +88,7 @@ If the load average was unobtainable, \-1 is returned; otherwise, the number of swap devices actually retrieved is returned. .Pp If the name of the swap device does not fit in the static char buffer -in the structure, it is truncated. The buffer is always zero terminated. +in the structure, it is truncated. +The buffer is always zero terminated. .Sh SEE ALSO .Xr kvm 3 diff --git a/lib/libkvm/kvm_nlist.3 b/lib/libkvm/kvm_nlist.3 index c49bd3a..c1dd8b7 100644 --- a/lib/libkvm/kvm_nlist.3 +++ b/lib/libkvm/kvm_nlist.3 @@ -60,12 +60,14 @@ an entry whose n_name field is (see .Xr nlist 3 ) . Each symbol is looked up using the n_name field, and if found, the -corresponding n_type and n_value fields are filled in. These fields are set +corresponding n_type and n_value fields are filled in. +These fields are set to 0 if the symbol is not found. .Pp The .Xr kldsym 2 -system call is used to locate the symbol. This is a less than perfect +system call is used to locate the symbol. +This is a less than perfect emulation of the nlist values but has the advantage of being aware of kernel modules and is reasonably fast. .Sh RETURN VALUES diff --git a/lib/libkvm/kvm_open.3 b/lib/libkvm/kvm_open.3 index 2e2794f..a289a7e 100644 --- a/lib/libkvm/kvm_open.3 +++ b/lib/libkvm/kvm_open.3 @@ -63,7 +63,8 @@ and return a descriptor used to access kernel virtual memory via the .Xr kvm 3 -library routines. Both active kernels and crash dumps are accessible +library routines. +Both active kernels and crash dumps are accessible through this interface. .Pp The @@ -121,9 +122,11 @@ other provides an improved error reporting framework. .Pp The .Fn kvm_open -function is the Sun kvm compatible open call. Here, the +function is the Sun kvm compatible open call. +Here, the .Fa errstr -argument indicates how errors should be handled. If it is +argument indicates how errors should be handled. +If it is .Dv NULL , no errors are reported and the application cannot know the specific nature of the failed kvm call. @@ -164,7 +167,8 @@ Thus, .Fn kvm_openfiles will place any error message in the .Fa errbuf -argument. This buffer should be _POSIX2_LINE_MAX characters large (from +argument. +This buffer should be _POSIX2_LINE_MAX characters large (from <limits.h>). .Sh RETURN VALUES The @@ -185,7 +189,8 @@ The .Fn kvm_close function returns 0 on success and -1 on failure. .Sh BUGS -There should not be two open calls. The ill-defined error semantics +There should not be two open calls. +The ill-defined error semantics of the Sun library and the desire to have a backward-compatible library for .Bx diff --git a/lib/libkvm/kvm_read.3 b/lib/libkvm/kvm_read.3 index 2e5a3fb..a2a2485 100644 --- a/lib/libkvm/kvm_read.3 +++ b/lib/libkvm/kvm_read.3 @@ -57,7 +57,8 @@ The and .Fn kvm_write functions are used to read and write kernel virtual memory (or a crash -dump file). See +dump file). +See .Fn kvm_open 3 or .Fn kvm_openfiles 3 diff --git a/lib/libnetgraph/netgraph.3 b/lib/libnetgraph/netgraph.3 index 108775e..0b832cc 100644 --- a/lib/libnetgraph/netgraph.3 +++ b/lib/libnetgraph/netgraph.3 @@ -390,7 +390,7 @@ ASCII control message array or fixed width string buffer overflow. .Sh HISTORY The .Nm netgraph -system was designed and first implemented at Whistle Communications, Inc. in +system was designed and first implemented at Whistle Communications, Inc.\& in a version of .Fx 2.2 customized for the Whistle InterJet. diff --git a/lib/libpam/modules/pam_chroot/pam_chroot.8 b/lib/libpam/modules/pam_chroot/pam_chroot.8 index e55c908..1bb4800 100644 --- a/lib/libpam/modules/pam_chroot/pam_chroot.8 +++ b/lib/libpam/modules/pam_chroot/pam_chroot.8 @@ -89,6 +89,6 @@ module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network -Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_echo/pam_echo.8 b/lib/libpam/modules/pam_echo/pam_echo.8 index 137bd55..b162b5b 100644 --- a/lib/libpam/modules/pam_echo/pam_echo.8 +++ b/lib/libpam/modules/pam_echo/pam_echo.8 @@ -88,6 +88,6 @@ module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network -Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_exec/pam_exec.8 b/lib/libpam/modules/pam_exec/pam_exec.8 index df752ee..c07ff26 100644 --- a/lib/libpam/modules/pam_exec/pam_exec.8 +++ b/lib/libpam/modules/pam_exec/pam_exec.8 @@ -61,6 +61,6 @@ module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network -Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_ftpusers/pam_ftpusers.8 b/lib/libpam/modules/pam_ftpusers/pam_ftpusers.8 index 0489d93..380e3b0 100644 --- a/lib/libpam/modules/pam_ftpusers/pam_ftpusers.8 +++ b/lib/libpam/modules/pam_ftpusers/pam_ftpusers.8 @@ -94,6 +94,6 @@ module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network -Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_group/pam_group.8 b/lib/libpam/modules/pam_group/pam_group.8 index ce7ef7a..832841b 100644 --- a/lib/libpam/modules/pam_group/pam_group.8 +++ b/lib/libpam/modules/pam_group/pam_group.8 @@ -78,6 +78,6 @@ module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network -Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_guest/pam_guest.8 b/lib/libpam/modules/pam_guest/pam_guest.8 index fd777f0..90fe3bd 100644 --- a/lib/libpam/modules/pam_guest/pam_guest.8 +++ b/lib/libpam/modules/pam_guest/pam_guest.8 @@ -93,6 +93,6 @@ module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network -Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_lastlog/pam_lastlog.8 b/lib/libpam/modules/pam_lastlog/pam_lastlog.8 index b54fe63..274de2f 100644 --- a/lib/libpam/modules/pam_lastlog/pam_lastlog.8 +++ b/lib/libpam/modules/pam_lastlog/pam_lastlog.8 @@ -101,6 +101,6 @@ The .Nm module and this manual page were developed for the FreeBSD Project by ThinkSec AS and NAI Labs, the Security Research Division of Network -Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_login_access/login.access.5 b/lib/libpam/modules/pam_login_access/login.access.5 index 2f83d4b..78be906 100644 --- a/lib/libpam/modules/pam_login_access/login.access.5 +++ b/lib/libpam/modules/pam_login_access/login.access.5 @@ -18,7 +18,8 @@ When someone logs in, the .Nm is scanned for the first entry that matches the (user, host) combination, or, in case of non-networked -logins, the first entry that matches the (user, tty) combination. The +logins, the first entry that matches the (user, tty) combination. +The permissions field of that table entry determines whether the login will be accepted or refused. .Pp @@ -30,11 +31,13 @@ character: The first field should be a "+" (access granted) or "-" (access denied) character. The second field should be a list of one or more login names, -group names, or ALL (always matches). The third field should be a list +group names, or ALL (always matches). +The third field should be a list of one or more tty names (for non-networked logins), host names, domain names (begin with "."), host addresses, internet network numbers (end with "."), ALL (always matches) or LOCAL (matches any string that does -not contain a "." character). If you run NIS you can use @netgroupname +not contain a "." character). +If you run NIS you can use @netgroupname in host or user patterns. .Pp The EXCEPT operator makes it possible to write very compact rules. diff --git a/lib/libpam/modules/pam_login_access/pam_login_access.8 b/lib/libpam/modules/pam_login_access/pam_login_access.8 index 9e808ae..6995227 100644 --- a/lib/libpam/modules/pam_login_access/pam_login_access.8 +++ b/lib/libpam/modules/pam_login_access/pam_login_access.8 @@ -84,6 +84,6 @@ module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network -Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_opieaccess/pam_opieaccess.8 b/lib/libpam/modules/pam_opieaccess/pam_opieaccess.8 index 862c6ec..07a66a4 100644 --- a/lib/libpam/modules/pam_opieaccess/pam_opieaccess.8 +++ b/lib/libpam/modules/pam_opieaccess/pam_opieaccess.8 @@ -135,6 +135,6 @@ module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network -Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_passwdqc/pam_passwdqc.8 b/lib/libpam/modules/pam_passwdqc/pam_passwdqc.8 index 926b93c..408f77d 100644 --- a/lib/libpam/modules/pam_passwdqc/pam_passwdqc.8 +++ b/lib/libpam/modules/pam_passwdqc/pam_passwdqc.8 @@ -263,6 +263,6 @@ for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network -Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_radius/pam_radius.8 b/lib/libpam/modules/pam_radius/pam_radius.8 index 27ec9f6..2ff5575 100644 --- a/lib/libpam/modules/pam_radius/pam_radius.8 +++ b/lib/libpam/modules/pam_radius/pam_radius.8 @@ -69,7 +69,8 @@ If no password has been entered then authentication fails. .It Cm try_first_pass causes .Nm -to use a previously entered password, if one is available. If no +to use a previously entered password, if one is available. +If no password has been entered, .Nm prompts for one as usual. @@ -92,7 +93,7 @@ The user will be authenticated with the supplied username and password, but his credentials to the system will be presented as the ones for .Ar username , -i.e., his login class, home directory, resource limits, etc. will be set to ones +i.e., his login class, home directory, resource limits, etc.\& will be set to ones defined for .Ar username . .Pp diff --git a/lib/libpam/modules/pam_rhosts/pam_rhosts.8 b/lib/libpam/modules/pam_rhosts/pam_rhosts.8 index dea0349..8adfcc6 100644 --- a/lib/libpam/modules/pam_rhosts/pam_rhosts.8 +++ b/lib/libpam/modules/pam_rhosts/pam_rhosts.8 @@ -90,6 +90,6 @@ module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network -Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_self/pam_self.8 b/lib/libpam/modules/pam_self/pam_self.8 index 2c0bab0..d021434 100644 --- a/lib/libpam/modules/pam_self/pam_self.8 +++ b/lib/libpam/modules/pam_self/pam_self.8 @@ -91,6 +91,6 @@ module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network -Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libpam/modules/pam_ssh/pam_ssh.8 b/lib/libpam/modules/pam_ssh/pam_ssh.8 index b6efc6e..468e99c 100644 --- a/lib/libpam/modules/pam_ssh/pam_ssh.8 +++ b/lib/libpam/modules/pam_ssh/pam_ssh.8 @@ -145,7 +145,7 @@ The current implementation was developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network -Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. This manual page was written by diff --git a/lib/libpam/modules/pam_tacplus/pam_tacplus.8 b/lib/libpam/modules/pam_tacplus/pam_tacplus.8 index 5ad7f07..03faf0c 100644 --- a/lib/libpam/modules/pam_tacplus/pam_tacplus.8 +++ b/lib/libpam/modules/pam_tacplus/pam_tacplus.8 @@ -91,7 +91,7 @@ The user will be authenticated with the supplied username and password, but his credentials to the system will be presented as the ones for .Ar username , -i.e., his login class, home directory, resource limits, etc. will be set to ones +i.e., his login class, home directory, resource limits, etc.\& will be set to ones defined for .Ar username . .Pp diff --git a/lib/libradius/radius.conf.5 b/lib/libradius/radius.conf.5 index d5ef42d..6fa5cd7 100644 --- a/lib/libradius/radius.conf.5 +++ b/lib/libradius/radius.conf.5 @@ -35,10 +35,12 @@ .Sh DESCRIPTION .Nm contains the information necessary to configure the RADIUS client -library. It is parsed by +library. +It is parsed by .Xr rad_config 3 . The file contains one or more lines of text, each describing a -single RADIUS server which will be used by the library. Leading +single RADIUS server which will be used by the library. +Leading white space is ignored, as are empty lines and lines containing only comments. .Pp @@ -57,13 +59,16 @@ Timeout Retries .El .Pp -The fields are separated by white space. The +The fields are separated by white space. +The .Ql # character at the beginning of a field begins a comment, which extends -to the end of the line. A field may be enclosed in double quotes, +to the end of the line. +A field may be enclosed in double quotes, in which case it may contain white space and/or begin with the .Ql # -character. Within a quoted string, the double quote character can +character. +Within a quoted string, the double quote character can be represented by .Ql \e\&" , and the backslash can be represented by @@ -75,9 +80,12 @@ The first field gives the service type, either .Ql auth for RADIUS authentication or .Ql acct -for RADIUS accounting. If a single server provides both services, two -lines are required in the file. Earlier versions of this file did -not include a service type. For backward compatibility, if the first +for RADIUS accounting. +If a single server provides both services, two +lines are required in the file. +Earlier versions of this file did +not include a service type. +For backward compatibility, if the first field is not .Ql auth or @@ -89,9 +97,11 @@ were fields two through five. .Pp The second field specifies the server host, either as a fully qualified domain name or as a -dotted-quad IP address. The host may optionally be followed by a +dotted-quad IP address. +The host may optionally be followed by a .Ql \&: -and a numeric port number, without intervening white space. If the +and a numeric port number, without intervening white space. +If the port specification is omitted, it defaults to the .Ql radius or @@ -107,21 +117,27 @@ If no such entry is present, the standard ports 1812 and 1813 are used. .Pp The third field contains the shared secret, which should be known -only to the client and server hosts. It is an arbitrary string of +only to the client and server hosts. +It is an arbitrary string of characters, though it must be enclosed in double quotes if it -contains white space. The shared secret may be +contains white space. +The shared secret may be any length, but the RADIUS protocol uses only the first 128 -characters. N.B., some popular RADIUS servers have bugs which +characters. +N.B., some popular RADIUS servers have bugs which prevent them from working properly with secrets longer than 16 characters. .Pp The fourth field contains a decimal integer specifying the timeout in -seconds for receiving a valid reply from the server. If this field +seconds for receiving a valid reply from the server. +If this field is omitted, it defaults to 3 seconds. .Pp The fifth field contains a decimal integer specifying the maximum number of attempts that will be made to authenticate with the server -before giving up. If omitted, it defaults to 3 attempts. Note, +before giving up. +If omitted, it defaults to 3 attempts. +Note, this is the total number of attempts and not the number of retries. .Pp Up to 10 RADIUS servers may be specified for each service type. diff --git a/lib/libsdp/sdp.3 b/lib/libsdp/sdp.3 index 24b0779..8954792 100644 --- a/lib/libsdp/sdp.3 +++ b/lib/libsdp/sdp.3 @@ -101,7 +101,8 @@ and macros are used to get byte, short, long, long long and 128-bit integer from the buffer pointed by .Vt cp -pointer. The pointer is automatically advanced. +pointer. +The pointer is automatically advanced. .Pp The .Fn SDP_PUT8 , @@ -113,7 +114,8 @@ and macros are used to put byte, short, long, long long and 128-bit integer into the buffer pointed by .Vt cp -pointer. The pointer is automatically advanced. +pointer. +The pointer is automatically advanced. .Pp .Fn sdp_open and @@ -192,7 +194,8 @@ parameter is the length of the Service Search pattern. The .Vt ap parameter is a Attribute ID Range List - an array of one or more SDP Attribute -ID Range. Each attribute ID Range is encoded as a 32-bit unsigned integer data +ID Range. +Each attribute ID Range is encoded as a 32-bit unsigned integer data element, where the high order 16 bits are interpreted as the beginning attribute ID of the range and the low order 16 bits are interpreted as the ending attribute ID of the range. @@ -241,7 +244,7 @@ The .Fn sdp_search function will fill each .Vt sdp_attr_t -structure with attribute and value, i.e. it will set +structure with attribute and value, i.e., it will set .Vt flags , .Vt attr and diff --git a/lib/libstand/libstand.3 b/lib/libstand/libstand.3 index 634cc9f..0e964f4 100644 --- a/lib/libstand/libstand.3 +++ b/lib/libstand/libstand.3 @@ -39,7 +39,8 @@ library provides a set of supporting functions for standalone applications, mimicking where possible the standard .Bx programming -environment. The following sections group these functions by kind. +environment. +The following sections group these functions by kind. Unless specifically described here, see the corresponding section 3 manpages for the given functions. .Sh STRING FUNCTIONS @@ -69,9 +70,11 @@ Free the allocated object at .Fn setheap "void *start" "void *limit" .Xc .Pp -Initialise the heap. This function must be called before calling +Initialise the heap. +This function must be called before calling .Fn alloc -for the first time. The region between +for the first time. +The region between .Fa start and .Fa limit @@ -84,14 +87,17 @@ in a panic. .Pp Provides the behaviour of .Fn sbrk 0 , -ie. returns the highest point that the heap has reached. This value can -be used during testing to determine the actual heap usage. The +i.e., returns the highest point that the heap has reached. +This value can +be used during testing to determine the actual heap usage. +The .Fa junk argument is ignored. .El .Sh ENVIRONMENT A set of functions are provided for manipulating a flat variable space similar -to the traditional shell-supported environment. Major enhancements are support +to the traditional shell-supported environment. +Major enhancements are support for set/unset hook functions. .Bl -hang -width 10n .It Xo @@ -133,18 +139,21 @@ and arguments may be specified. .Pp The set hook is invoked whenever an attempt -is made to set the variable, unless the EV_NOHOOK flag is set. Typically +is made to set the variable, unless the EV_NOHOOK flag is set. +Typically a set hook will validate the .Fa value argument, and then call .Fn env_setenv -again with EV_NOHOOK set to actually save the value. The predefined function +again with EV_NOHOOK set to actually save the value. +The predefined function .Fn env_noset may be specified to refuse all attempts to set a variable. .Pp The unset hook is invoked when an attempt is made to unset a variable. If it -returns zero, the variable will be unset. The predefined function +returns zero, the variable will be unset. +The predefined function .Fa env_nounset may be used to prevent a variable being unset. .El @@ -190,7 +199,8 @@ Defined as .Fn _setjmp and .Fn _longjmp -respectively as there is no signal state to manipulate. Requires +respectively as there is no signal state to manipulate. +Requires .In setjmp.h . .El .Sh CHARACTER I/O @@ -227,7 +237,8 @@ characters into .Fa buf . Line terminating characters are stripped, and the buffer is always .Dv NUL -terminated. Returns the number of characters in +terminated. +Returns the number of characters in .Fa buf if successful, or -1 if a read error occurs. .It Xo @@ -249,13 +260,16 @@ if successful, or -1 if a read error occurs. .Pp The *printf functions implement a subset of the standard .Fn printf -family functionality and some extensions. The following standard conversions -are supported: c,d,n,o,p,s,u,x. The following modifiers are supported: +family functionality and some extensions. +The following standard conversions +are supported: c,d,n,o,p,s,u,x. +The following modifiers are supported: +,-,#,*,0,field width,precision,l. .Pp The .Li b -conversion is provided to decode error registers. Its usage is: +conversion is provided to decode error registers. +Its usage is: .Pp .Bd -ragged -offset indent printf( @@ -265,8 +279,9 @@ regval, ); .Ed .Pp -where <base> is the output expressed as a control character, eg. \e10 gives -octal, \e20 gives hex. Each <arg> is a sequence of characters, the first of +where <base> is the output expressed as a control character, e.g.\& \e10 gives +octal, \e20 gives hex. +Each <arg> is a sequence of characters, the first of which gives the bit number to be inspected (origin 1) and the next characters (up to a character less than 32) give the text to be displayed if the bit is set. Thus @@ -287,7 +302,7 @@ reg=3<BITTWO,BITONE> .Pp The .Li D -conversion provides a hexdump facility, eg. +conversion provides a hexdump facility, e.g. .Pp .Bd -ragged -offset indent printf( @@ -356,7 +371,8 @@ ptr, Similar to the behaviour as specified in .Xr open 2 , except that file creation is not supported, so the mode parameter is not -required. The +required. +The .Fa flags argument may be one of O_RDONLY, O_WRONLY and O_RDWR (although no file systems currently support writing). @@ -402,7 +418,8 @@ and .Fn fstat functions only fill out the following fields in the .Fa sb -structure: st_mode,st_nlink,st_uid,st_gid,st_size. The +structure: st_mode,st_nlink,st_uid,st_gid,st_size. +The .Nm tftp file system cannot provide meaningful values for this call, and the .Nm cd9660 @@ -420,7 +437,8 @@ commands. .Xc .Pp Initialises the pager and tells it that the next line output will be the top of the -display. The environment variable LINES is consulted to determine the number of +display. +The environment variable LINES is consulted to determine the number of lines to be displayed before pausing. .It Xo .Ft void @@ -437,7 +455,8 @@ Sends the lines in the .Dv NUL Ns -terminated buffer at .Fa lines -to the pager. Newline characters are counted in order to determine the number +to the pager. +Newline characters are counted in order to determine the number of lines being output (wrapped lines are not accounted for). The .Fn pager_output @@ -469,7 +488,8 @@ The following resources are consumed by .Pp The stack must be established before .Nm -functions can be invoked. Stack requirements vary depending on the functions +functions can be invoked. +Stack requirements vary depending on the functions and file systems used by the consumer and the support layer functions detailed below. .Pp @@ -480,7 +500,8 @@ or by calling .Fn setheap . Heap usage will vary depending on the number of simultaneously open files, -as well as client behaviour. Automatic decompression will allocate more +as well as client behaviour. +Automatic decompression will allocate more than 64K of data per open file. .Pp Console access is performed via the @@ -542,13 +563,15 @@ returning in .Fa file a pointer to the remaining body of .Fa name -which does not refer to the device. The +which does not refer to the device. +The .Va f_dev field in .Fa of will be set to point to the .Vt devsw -structure for the opened device if successful. Device identifiers must +structure for the opened device if successful. +Device identifiers must always precede the path component, but may otherwise be arbitrarily formatted. Used by .Fn open @@ -566,7 +589,8 @@ should clean up any allocation made by devopen only. .Fn panic "const char *msg" "..." .Xc .Pp -Signal a fatal and unrecoverable error condition. The +Signal a fatal and unrecoverable error condition. +The .Fa msg ... arguments are as for .Fn printf . @@ -577,7 +601,8 @@ Internal file systems are enabled by the consumer exporting the array which should be initialised with pointers to .Vt struct fs_ops -structures. The following file system handlers are supplied by +structures. +The following file system handlers are supplied by .Nm , the consumer may supply other file systems of their own: .Bl -hang -width ".Va cd9660_fsops" @@ -600,10 +625,12 @@ When trying the gzipfs file system, appends .Li .gz to the end of the filename, and then tries to locate the file using the other -file systems. Placement of this file system in the +file systems. +Placement of this file system in the .Va file_system[] array determines whether gzipped files will be opened in preference to non-gzipped -files. It is only possible to seek a gzipped file forwards, and +files. +It is only possible to seek a gzipped file forwards, and .Fn stat and .Fn fstat diff --git a/lib/libtacplus/libtacplus.3 b/lib/libtacplus/libtacplus.3 index 9547607..94c9694 100644 --- a/lib/libtacplus/libtacplus.3 +++ b/lib/libtacplus/libtacplus.3 @@ -78,9 +78,11 @@ The .Nm library implements the client side of the TACACS+ network access -control protocol. TACACS+ allows clients to perform authentication, +control protocol. +TACACS+ allows clients to perform authentication, authorization, and accounting by means of network requests to remote -servers. This library currently supports only the authentication +servers. +This library currently supports only the authentication and authorization portion of the protocol. .Sh INITIALIZATION To use the library, an application must first call @@ -90,14 +92,16 @@ to obtain a which provides context for subsequent operations. Calls to .Fn tac_open -always succeed unless insufficient virtual memory is available. If +always succeed unless insufficient virtual memory is available. +If the necessary memory cannot be allocated, .Fn tac_open returns .Dv NULL . .Pp Before issuing any TACACS+ requests, the library must be made aware -of the servers it can contact. The easiest way to configure the +of the servers it can contact. +The easiest way to configure the library is to call .Fn tac_config . .Fn tac_config @@ -124,24 +128,28 @@ parameter specifies the server host, either as a fully qualified domain name or as a dotted-quad IP address in text form. The .Va port -parameter specifies the TCP port to contact on the server. If +parameter specifies the TCP port to contact on the server. +If .Va port is given as 0, the library uses port 49, the standard TACACS+ port. The shared secret for the server host is passed to the .Va secret -parameter. It may be any null-terminated string of bytes. +parameter. +It may be any null-terminated string of bytes. The timeout for receiving replies from the server is passed to the .Va timeout parameter, in units of seconds. The .Va flags parameter is a bit mask of flags to specify various characteristics of -the server. It may contain: +the server. +It may contain: .Pp .Bl -tag -width Fl .It Dv TAC_SRVR_SINGLE_CONNECT Causes the library to attempt to negotiate single connection mode -when communicating with the server. In single connection mode, the +when communicating with the server. +In single connection mode, the original TCP connection is held open for multiple TACACS+ sessions. Older servers do not support this mode, and some of them become confused if the client attempts to negotiate it. @@ -155,7 +163,8 @@ may be called multiple times, and it may be used together with .Fn tac_config . At most 10 servers may be specified. When multiple servers are given, they are tried in round-robin -fashion until a working, accessible server is found. Once the +fashion until a working, accessible server is found. +Once the library finds such a server, it continues to use it as long as it works. .Sh CREATING A TACACS+ AUTHENTICATION REQUEST @@ -167,7 +176,8 @@ The and .Va service arguments must be set to appropriate values as defined in the -TACACS+ protocol specification. The +TACACS+ protocol specification. +The .In taclib.h header file contains symbolic constants for these values. .Sh CREATING A TACACS+ AUTHORIZATION REQUEST @@ -179,7 +189,8 @@ The and .Va service arguments must be set to appropriate values as defined in the -TACACS+ protocol specification. The +TACACS+ protocol specification. +The .In taclib.h header file contains symbolic constants for these values. .Sh SETTING OPTIONAL PARAMETERS ON A REQUEST @@ -194,17 +205,21 @@ and .Fn tac_set_user . The library creates its own copies of any strings provided to these functions, so that it is not necessary for the caller to preserve -them. By default, each of these parameters is empty except for the +them. +By default, each of these parameters is empty except for the privilege level, which defaults to .Ql USER privilege. .Pp .Fn tac_set_av -only applies to the context of an authorization request. The format +only applies to the context of an authorization request. +The format for an attribute value pair is defined in the TACACS+ protocol -specification. The index specified can be any value between 0 and +specification. +The index specified can be any value between 0 and 255 inclusive and indicates the position in the list to place the -attribute value pair. Calling +attribute value pair. +Calling .Fn tac_set_av with same index twice effectively replaces the value at that position. Use @@ -215,10 +230,13 @@ After the TACACS+ authentication request has been constructed, it is sent by means of .Fn tac_send_authen . This function connects to a server if not already connected, sends -the request, and waits for a reply. On failure, +the request, and waits for a reply. +On failure, .Fn tac_send_authen -returns \-1. Otherwise, it returns the TACACS+ status code and flags, -packed into an integer value. The status can be extracted using the +returns \-1. +Otherwise, it returns the TACACS+ status code and flags, +packed into an integer value. +The status can be extracted using the macro .Fn TAC_AUTHEN_STATUS . Possible status codes, defined in @@ -249,15 +267,18 @@ macro .Fn TAC_AUTHEN_NOECHO . .Sh EXTRACTING INFORMATION FROM THE SERVER'S AUTHENTICATION RESPONSE An authentication response packet from the server may contain a -server message, a data string, or both. After a successful call to +server message, a data string, or both. +After a successful call to .Fn tac_send_authen , this information may be retrieved from the response by calling .Fn tac_get_msg and .Fn tac_get_data . These functions return dynamically-allocated copies of the -information from the packet. The caller is responsible for freeing -the copies when it no longer needs them. The data returned from +information from the packet. +The caller is responsible for freeing +the copies when it no longer needs them. +The data returned from these functions is guaranteed to be terminated by a null byte. .Pp In the case of @@ -266,7 +287,8 @@ the .Va len argument points to a location into which the library will store the actual length of the received data, not including the null -terminator. This argument may be given as +terminator. +This argument may be given as .Dv NULL if the caller is not interested in the length. .Sh SENDING AUTHENTICATION CONTINUE PACKETS @@ -278,7 +300,8 @@ returns a value containing one of the status codes or .Dv TAC_AUTHEN_STATUS_GETPASS , then the client must provide additional information to the server by -means of a TACACS+ CONTINUE packet. To do so, the application must +means of a TACACS+ CONTINUE packet. +To do so, the application must first set the packet's user message and/or data fields using .Fn tac_set_msg and @@ -305,11 +328,14 @@ After the TACACS+ authorization request has been constructed, it is sent by means of .Fn tac_send_author . This function connects to a server if not already connected, sends -the request, and waits for a reply. On failure, +the request, and waits for a reply. +On failure, .Fn tac_send_author -returns \-1. Otherwise, it returns the TACACS+ status code and +returns \-1. +Otherwise, it returns the TACACS+ status code and number of attribute value (AV) pairs received packed into an -integer value. The status can be extracted using the macro +integer value. +The status can be extracted using the macro .Fn TAC_AUTHOR_STATUS . Possible status codes, defined in .In taclib.h , @@ -331,12 +357,14 @@ The number of AV pairs received is obtained using .Sh EXTRACTING INFORMATION FROM THE SERVER'S AUTHORIZATION RESPONSE Like an authentication response packet, an authorization response packet from the -server may contain a server message, a data string, or both. Refer +server may contain a server message, a data string, or both. +Refer to EXTRACTING INFORMATION FROM THE SERVER'S AUTHENTICATION RESPONSE for instruction on extraction of those values. .Pp An authorization response packet from the server may also contain -attribute value (AV) pairs. To extract these, use +attribute value (AV) pairs. +To extract these, use .Fn tac_get_av or .Fn tac_get_av_value . @@ -352,15 +380,18 @@ Alternatively, can be used. .Fn tac_get_av_value takes the attribute name and returns the -corresponding value only, not the AV pair. These functions return +corresponding value only, not the AV pair. +These functions return dynamically-allocated copies of the information from the packet. The caller is responsible for freeing the copies when it no longer -needs them. The data returned from these functions is guaranteed +needs them. +The data returned from these functions is guaranteed to be terminated by a null byte. .Sh OBTAINING ERROR MESSAGES Those functions which accept a .Va struct tac_handle * -argument record an error message if they fail. The error message +argument record an error message if they fail. +The error message can be retrieved by calling .Fn tac_strerror . The message text is overwritten on each new error for the given @@ -371,7 +402,8 @@ subsequent library calls using the same handle. To free the resources used by the TACACS+ library, call .Fn tac_close . .Sh RETURN VALUES -The following functions return a non-negative value on success. If +The following functions return a non-negative value on success. +If they detect an error, they return \-1 and record an error message which can be retrieved using .Fn tac_strerror . @@ -407,7 +439,8 @@ which can be retrieved using .Pp The following functions return a .No non- Ns Dv NULL -pointer on success. If they are unable to allocate sufficient +pointer on success. +If they are unable to allocate sufficient virtual memory, they return .Dv NULL and record an error message which can be retrieved using @@ -426,7 +459,8 @@ and record an error message which can be retrieved using .Pp The following functions return a .No non- Ns Dv NULL -pointer on success. If they are unable to allocate sufficient +pointer on success. +If they are unable to allocate sufficient virtual memory, they return .Dv NULL , without recording an error message. diff --git a/lib/libtacplus/tacplus.conf.5 b/lib/libtacplus/tacplus.conf.5 index 6f7130f..e68982d 100644 --- a/lib/libtacplus/tacplus.conf.5 +++ b/lib/libtacplus/tacplus.conf.5 @@ -35,23 +35,29 @@ .Sh DESCRIPTION .Nm contains the information necessary to configure the TACACS+ client -library. It is parsed by +library. +It is parsed by .Fn tac_config (see .Xr libtacplus 3 ) . The file contains one or more lines of text, each describing a -single TACACS+ server which is to be used by the library. Leading +single TACACS+ server which is to be used by the library. +Leading white space is ignored, as are empty lines and lines containing only comments. .Pp -A TACACS+ server is described by two to four fields on a line. The -fields are separated by white space. The +A TACACS+ server is described by two to four fields on a line. +The +fields are separated by white space. +The .Ql # character at the beginning of a field begins a comment, which extends -to the end of the line. A field may be enclosed in double quotes, +to the end of the line. +A field may be enclosed in double quotes, in which case it may contain white space and/or begin with the .Ql # -character. Within a quoted string, the double quote character can +character. +Within a quoted string, the double quote character can be represented by .Ql \e\&" , and the backslash can be represented by @@ -60,32 +66,40 @@ No other escape sequences are supported. .Pp The first field specifies the server host, either as a fully qualified domain name or as a -dotted-quad IP address. The host may optionally be followed by a +dotted-quad IP address. +The host may optionally be followed by a .Ql \&: -and a numeric port number, without intervening white space. If the +and a numeric port number, without intervening white space. +If the port specification is omitted, it defaults to 49, the standard TACACS+ port. .Pp The second field contains the shared secret, which should be known -only to the client and server hosts. It is an arbitrary string +only to the client and server hosts. +It is an arbitrary string of characters, though it must be enclosed in double quotes if it -contains white space or is empty. An empty secret disables the +contains white space or is empty. +An empty secret disables the normal encryption mechanism, causing all data to cross the network in cleartext. .Pp The third field contains a decimal integer specifying the timeout -in seconds for communicating with the server. The timeout applies -separately to each connect, write, and read operation. If this field +in seconds for communicating with the server. +The timeout applies +separately to each connect, write, and read operation. +If this field is omitted, it defaults to 3 seconds. .Pp The optional fourth field may contain the string .Ql single-connection . If this option is included, the library will attempt to negotiate with the server to keep the TCP connection open for multiple -sessions. Some older TACACS+ servers become confused if this option +sessions. +Some older TACACS+ servers become confused if this option is specified. .Pp -Up to 10 TACACS+ servers may be specified. The servers are tried in +Up to 10 TACACS+ servers may be specified. +The servers are tried in order, until a valid response is received or the list is exhausted. .Pp The standard location for this file is diff --git a/lib/libugidfw/bsde_get_rule.3 b/lib/libugidfw/bsde_get_rule.3 index 6998753..a3b6691 100644 --- a/lib/libugidfw/bsde_get_rule.3 +++ b/lib/libugidfw/bsde_get_rule.3 @@ -153,6 +153,7 @@ This software was contributed to the .Fx Project by Network Associates Labs, the Security Research Division of Network Associates -Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Inc. +under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libugidfw/bsde_get_rule_count.3 b/lib/libugidfw/bsde_get_rule_count.3 index 3453311..bf441e1 100644 --- a/lib/libugidfw/bsde_get_rule_count.3 +++ b/lib/libugidfw/bsde_get_rule_count.3 @@ -87,6 +87,7 @@ This software was contributed to the .Fx Project by Network Associates Labs, the Security Research Division of Network Associates -Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Inc. +under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libugidfw/bsde_parse_rule.3 b/lib/libugidfw/bsde_parse_rule.3 index 5a11abc4..d510cab 100644 --- a/lib/libugidfw/bsde_parse_rule.3 +++ b/lib/libugidfw/bsde_parse_rule.3 @@ -99,6 +99,7 @@ This software was contributed to the .Fx Project by Network Associates Labs, the Security Research Division of Network Associates -Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Inc. +under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libugidfw/bsde_rule_to_string.3 b/lib/libugidfw/bsde_rule_to_string.3 index 89a14aa..4414406 100644 --- a/lib/libugidfw/bsde_rule_to_string.3 +++ b/lib/libugidfw/bsde_rule_to_string.3 @@ -76,6 +76,7 @@ This software was contributed to the .Fx Project by Network Associates Labs, the Security Research Division of Network Associates -Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Inc. +under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libugidfw/libugidfw.3 b/lib/libugidfw/libugidfw.3 index 9b04a3e..ea7ce89 100644 --- a/lib/libugidfw/libugidfw.3 +++ b/lib/libugidfw/libugidfw.3 @@ -117,6 +117,7 @@ This software was contributed to the .Fx Project by Network Associates Labs, the Security Research Division of Network Associates -Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +Inc. +under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. diff --git a/lib/libutil/auth.conf.5 b/lib/libutil/auth.conf.5 index c80d067..0d1c0b9 100644 --- a/lib/libutil/auth.conf.5 +++ b/lib/libutil/auth.conf.5 @@ -26,7 +26,8 @@ contains various attributes important to the authentication code, most notably .Xr kerberos 5 -for the time being. This documentation will be updated as the +for the time being. +This documentation will be updated as the .Pa /etc/auth.conf file, which is very new, evolves. .Sh SEE ALSO diff --git a/lib/libutil/login.3 b/lib/libutil/login.3 index de13139..d88f719 100644 --- a/lib/libutil/login.3 +++ b/lib/libutil/login.3 @@ -49,7 +49,8 @@ entry being passed into the appropriate slot of the file, and appends it to the .Xr wtmp 5 -file. The calling process must have permission to write to both files. +file. +The calling process must have permission to write to both files. .Sh RETURN VALUES None. .Sh SEE ALSO @@ -60,6 +61,7 @@ None. .Sh BUGS The interface provided by .Fn login -is rather crude. The caller must know about the details of a +is rather crude. +The caller must know about the details of a .Va struct utmp . Some better abstraction needs to be worked out. diff --git a/lib/libutil/login.conf.5 b/lib/libutil/login.conf.5 index c3b91cf..e5e0d68 100644 --- a/lib/libutil/login.conf.5 +++ b/lib/libutil/login.conf.5 @@ -105,7 +105,7 @@ home directories etc.) A numeric value, either decimal (default), hexadecimal (with leading 0x), or octal (with a leading 0). With a numeric type, only one numeric value is allowed. -Numeric types may also be specified in string format (ie. the capability +Numeric types may also be specified in string format (i.e., the capability tag being delimited from the value by '=' instead of '#'). Whichever method is used, then all records in the database must use the same method to allow values to be correctly overridden in interpolated diff --git a/lib/libutil/login_cap.3 b/lib/libutil/login_cap.3 index b3a2d66..07fda65 100644 --- a/lib/libutil/login_cap.3 +++ b/lib/libutil/login_cap.3 @@ -369,7 +369,7 @@ kilobytes, megabytes, gigabytes, and on systems that support the .Ar long long type, terabytes. The suffix used determines the units, and multiple values and -units may be used in combination (e.g. 1m500k = 1.5 megabytes). +units may be used in combination (e.g.\& 1m500k = 1.5 megabytes). A value with no suffix is interpreted as bytes, B as 512-byte blocks, K as kilobytes, M as megabytes, G as gigabytes and T as terabytes. diff --git a/lib/libutil/login_ok.3 b/lib/libutil/login_ok.3 index c005e5d..8a6f291 100644 --- a/lib/libutil/login_ok.3 +++ b/lib/libutil/login_ok.3 @@ -64,7 +64,7 @@ tty group (see .Xr ttys 5 ) is not in the list. Access to ttys may be allowed or restricted specifically by tty device -name, a device name which includes a wildcard (e.g. ttyD* or cuaD*), +name, a device name which includes a wildcard (e.g.\& ttyD* or cuaD*), or may name a ttygroup, when group=<name> tags have been assigned in .Pa /etc/ttys . Matching of ttys and ttygroups is case sensitive. @@ -90,7 +90,7 @@ The function is used for matching, and the matching on hostnames is case insensitive. Note that this function expects that the hostname is fully expanded -(i.e. the local domain name added if necessary) and the IP address +(i.e., the local domain name added if necessary) and the IP address is in its canonical form. No hostname or address lookups are attempted. .Pp diff --git a/lib/libutil/login_times.3 b/lib/libutil/login_times.3 index 9419c7f..e1f57ce 100644 --- a/lib/libutil/login_times.3 +++ b/lib/libutil/login_times.3 @@ -96,7 +96,7 @@ and one bit unused. A series .Em LTM_* macros may be used for testing bits individually and in combination. -If no bits are set in this field - ie. it contains the value +If no bits are set in this field - i.e., it contains the value .Em LTM_NONE - then the entire period is assumed invalid. This is used as a convention to mark the termination of an array @@ -142,7 +142,7 @@ function returns a filled in structure of type login_time_t containing the parsed time period. If a parsing error occurs, the lt_dow field is set to .Em LTM_NONE -(i.e. 0). +(i.e., 0). .Pp The .Fn in_ltm diff --git a/lib/libutil/login_tty.3 b/lib/libutil/login_tty.3 index b7111e7..6303d68 100644 --- a/lib/libutil/login_tty.3 +++ b/lib/libutil/login_tty.3 @@ -40,11 +40,13 @@ .Sh DESCRIPTION The function .Fn login_tty -prepares a terminal for a new login session. The file descriptor +prepares a terminal for a new login session. +The file descriptor .Ar fd passed to .Fn login_tty -must be opened for reading and writing on a terminal device. It will be +must be opened for reading and writing on a terminal device. +It will be made the controlling terminal for the calling process, after allocating a new session with .Xr setsid 2 . diff --git a/lib/libutil/logout.3 b/lib/libutil/logout.3 index 2fe2d4f..426fe08 100644 --- a/lib/libutil/logout.3 +++ b/lib/libutil/logout.3 @@ -45,7 +45,8 @@ searches the .Xr utmp 5 file for the slot described by .Ar line -(usually a tty name). If such a slot could be found, it will be updated +(usually a tty name). +If such a slot could be found, it will be updated with a record where the .Em name and diff --git a/lib/libutil/property.3 b/lib/libutil/property.3 index d9b5d12..e5acef3 100644 --- a/lib/libutil/property.3 +++ b/lib/libutil/property.3 @@ -67,7 +67,8 @@ The .Fn property_find function returns the associated value string for the property named .Fa name -if found, otherwise NULL. The value returned may be up to +if found, otherwise NULL. +The value returned may be up to .Dv PROPERTY_MAX_VALUE bytes in length. .Pp @@ -84,9 +85,11 @@ where is an alphanumeric string (and any punctuation not including the `=' character) and .Fa value -is an arbitary string of text terminated by a newline character. If newlines +is an arbitary string of text terminated by a newline character. +If newlines are desired, the entire value should be enclosed in { } (curly-bracket) -characters. Any line beginning with a # or ; character is assumed to +characters. +Any line beginning with a # or ; character is assumed to be a comment and will be ignored. .Sh SEE ALSO .Xr auth_getval 3 diff --git a/lib/libutil/pty.3 b/lib/libutil/pty.3 index 19cf9f7..35f0b82 100644 --- a/lib/libutil/pty.3 +++ b/lib/libutil/pty.3 @@ -62,7 +62,8 @@ If the argument is not .Dv NULL , .Fn openpty -copies the pathname of the slave pty to this area. The caller is +copies the pathname of the slave pty to this area. +The caller is responsible for allocating the required space in this array. .Pp If the arguments @@ -86,12 +87,16 @@ The .Fn forkpty function first calls .Fn openpty -to obtain the next available pseudo-terminal from the system. Upon success, -it forks off a new process. In the child process, it closes the descriptor +to obtain the next available pseudo-terminal from the system. +Upon success, +it forks off a new process. +In the child process, it closes the descriptor for the master side of the pty, and calls .Xr login_tty 3 -for the slave pty. In the parent process, it closes the descriptor for the -slave side of the pty. The arguments +for the slave pty. +In the parent process, it closes the descriptor for the +slave side of the pty. +The arguments .Fa amaster , .Fa name , .Fa termp , @@ -133,7 +138,8 @@ may set it to any value as described for .Xr group 5 .Sh BUGS The calling process must have an effective UID of super-user in order -to perform all the intended actions. No notification will occur if +to perform all the intended actions. +No notification will occur if .Fn openpty or .Fn forkpty diff --git a/lib/libutil/realhostname.3 b/lib/libutil/realhostname.3 index 37b166a..e5cdbf1 100644 --- a/lib/libutil/realhostname.3 +++ b/lib/libutil/realhostname.3 @@ -43,7 +43,8 @@ The function .Fn realhostname converts .Ar ip -to the corresponding host name. This is done by resolving +to the corresponding host name. +This is done by resolving .Ar ip to a host name and then ensuring that the host name resolves back to diff --git a/lib/libutil/realhostname_sa.3 b/lib/libutil/realhostname_sa.3 index 72340aa..773c4af 100644 --- a/lib/libutil/realhostname_sa.3 +++ b/lib/libutil/realhostname_sa.3 @@ -72,7 +72,8 @@ The function .Fn realhostname_sa converts .Ar addr -to the corresponding host name. This is done by resolving +to the corresponding host name. +This is done by resolving .Ar addr to a host name and then ensuring that the host name resolves back to diff --git a/lib/libutil/trimdomain.3 b/lib/libutil/trimdomain.3 index 66b8369..f01e884 100644 --- a/lib/libutil/trimdomain.3 +++ b/lib/libutil/trimdomain.3 @@ -44,10 +44,12 @@ removes the current domain name from the passed .Ar fullhost name by writing a .Dv NUL -character over the first period of the passed name. The current domain +character over the first period of the passed name. +The current domain name is determined by calling .Xr gethostname 3 -and removing everything up to the first period. The name is determined +and removing everything up to the first period. +The name is determined the first time this function is called and is cached for future use. .Pp The diff --git a/lib/libutil/uucplock.3 b/lib/libutil/uucplock.3 index a69af95..d901831 100644 --- a/lib/libutil/uucplock.3 +++ b/lib/libutil/uucplock.3 @@ -127,7 +127,8 @@ the reason for failure is returned. .Fn uu_lockerr uses the current value of .Va errno -to determine the exact error. Care should be made not to allow +to determine the exact error. +Care should be made not to allow .Va errno to be changed between calls to .Fn uu_lock @@ -138,7 +139,8 @@ and may return any of the following values: .Pp .Dv UU_LOCK_OK : -The transfer was successful. The specified process now holds the device +The transfer was successful. +The specified process now holds the device lock. .Pp .Dv UU_LOCK_OWNER_ERR : @@ -152,7 +154,8 @@ If .Fn uu_lock returns one of the error values above, the global value .Va errno -can be used to determine the cause. Refer to the respective manual pages +can be used to determine the cause. +Refer to the respective manual pages for further details. .Pp .Fn uu_unlock @@ -174,6 +177,7 @@ the stale lock. .Pp The calling process must have write permissions to the .Pa /var/spool/lock -directory. There is no mechanism in place to ensure that the +directory. +There is no mechanism in place to ensure that the permissions of this directory are the same as those of the serial devices that might be locked. diff --git a/lib/libvgl/vgl.3 b/lib/libvgl/vgl.3 index 93b5640..fb155f7e 100644 --- a/lib/libvgl/vgl.3 +++ b/lib/libvgl/vgl.3 @@ -136,7 +136,8 @@ .Sh DESCRIPTION .Nm Libvgl is a library that enables the programmer access to the graphics -modes supported by the console driver (syscons). The library takes care of +modes supported by the console driver (syscons). +The library takes care of programming the actual video hardware, and provides a number of simple functions to do various graphic operations. There is also support for a @@ -199,7 +200,8 @@ more than one raw scan code may be generated when a key is pressed. when you have finished using the keyboard, call this function. .Pp .Fn VGLKeyboardGetCh -read one byte from the keyboard. As the keyboard I/O is in the +read one byte from the keyboard. +As the keyboard I/O is in the .Dq raw input mode, the function will not block even if there is no input data, and returns 0. @@ -371,7 +373,8 @@ set the border color to color .Va color . .Pp .Fn VGLSetVScreenSize -change the virtual screen size of the display. Note that this +change the virtual screen size of the display. +Note that this function must be called when our vty is in the foreground. And .Va object @@ -380,7 +383,8 @@ must be Passing an in-memory bitmap to this function results in error. .Pp The desired virtual screen width may not be achievable because -of the video card hardware. In such case the video driver (and +of the video card hardware. +In such case the video driver (and underlaying video BIOS) may choose the next largest values. Always examine .Va object->VXsize diff --git a/lib/msun/man/atan2.3 b/lib/msun/man/atan2.3 index 174be74..f951812 100644 --- a/lib/msun/man/atan2.3 +++ b/lib/msun/man/atan2.3 @@ -145,7 +145,8 @@ is mapped to (r=0,theta=0) .if t \ (r=0,\(*h=0) -on a VAX. In general, conversions to polar coordinates +on a VAX. +In general, conversions to polar coordinates should be computed thus: .Bd -unfilled -offset indent .if n \{\ diff --git a/lib/msun/man/erf.3 b/lib/msun/man/erf.3 index 07cea0b..0ebb6a7 100644 --- a/lib/msun/man/erf.3 +++ b/lib/msun/man/erf.3 @@ -64,10 +64,12 @@ and the functions calculate the error function of x; where .Bd -ragged -offset indent .if n \{\ -erf(x) = 2/sqrt(pi)\(**\|integral from 0 to x of exp(\-t\(**t) dt. \} +erf(x) = 2/sqrt(pi)\(**\|integral from 0 to x of exp(\-t\(**t) dt. +\} .if t \{\ erf\|(x) := -(2/\(sr\(*p)\|\(is\d\s8\z0\s10\u\u\s8x\s10\d\|exp(\-t\u\s82\s10\d)\|dt. \} +(2/\(sr\(*p)\|\(is\d\s8\z0\s10\u\u\s8x\s10\d\|exp(\-t\u\s82\s10\d)\|dt. +\} .Ed .Pp The diff --git a/lib/msun/man/exp.3 b/lib/msun/man/exp.3 index f035f07..62e9e3e 100644 --- a/lib/msun/man/exp.3 +++ b/lib/msun/man/exp.3 @@ -261,7 +261,8 @@ operand on a .Tn VAX ) . Previous implementations of pow may have defined x**0 to be undefined in some or all of these -cases. Here are reasons for returning x**0 = 1 always: +cases. +Here are reasons for returning x**0 = 1 always: .Bl -enum -width indent .It Any program that already tests whether x is zero (or @@ -272,7 +273,7 @@ upon 0**0 to be invalid is dubious anyway since that expression's meaning and, if invalid, its consequences vary from one computer system to another. .It -Some Algebra texts (e.g. Sigler's) define x**0 = 1 for +Some Algebra texts (e.g.\& Sigler's) define x**0 = 1 for all x, including x = 0. This is compatible with the convention that accepts a[0] as the value of polynomial diff --git a/lib/msun/man/ieee.3 b/lib/msun/man/ieee.3 index 7b9f0ac..73a39f6 100644 --- a/lib/msun/man/ieee.3 +++ b/lib/msun/man/ieee.3 @@ -166,7 +166,8 @@ moreover if 1/2 then .Fa n -is even. Consequently +is even. +Consequently the remainder is computed exactly and .Sm off .Pf \\*(Ba Fa r No \\*(Ba diff --git a/sys/netinet/libalias/libalias.3 b/sys/netinet/libalias/libalias.3 index 7a582db..bb77e30 100644 --- a/sys/netinet/libalias/libalias.3 +++ b/sys/netinet/libalias/libalias.3 @@ -196,7 +196,7 @@ mode bit is set. This bit should be set when the packet aliasing host originates network traffic as well as forwards it. When the packet aliasing host is waiting for a connection from an unknown -host address or unknown port number (e.g. an FTP data connection), this +host address or unknown port number (e.g.\& an FTP data connection), this mode bit specifies that a socket be allocated as a place holder to prevent port conflicts. Once a connection is established, usually within a minute or so, the socket @@ -237,7 +237,7 @@ possible to use a hole for another connection. A hole is removed when the connection that uses it dies. To cater to unexpected death of a program using .Nm -(e.g. kill -9), +(e.g.\& kill -9), changing the state of the flag will clear the entire firewall range allocated for holes. This will also happen on the initial call to @@ -560,7 +560,7 @@ For links created with .Fn LibAliasRedirectAddr , the .Fa port -argument is ignored and could have any value, e.g. htons(~0). +argument is ignored and could have any value, e.g.\& htons(~0). .Pp This function returns 0 on success, \-1 otherwise. .Ed @@ -571,15 +571,15 @@ This function returns 0 on success, \-1 otherwise. This function marks the specified static redirect rule entered by .Fn LibAliasRedirectPort as dynamic. -This can be used to e.g. dynamically redirect a single TCP connection, +This can be used to e.g.\& dynamically redirect a single TCP connection, after which the rule is removed. Only fully specified links can be made dynamic. (See the .Sx STATIC AND DYNAMIC LINKS and .Sx PARTIALLY SPECIFIED ALIASING LINKS -sections below for a definition of static vs. dynamic, -and partially vs. fully specified links.) +sections below for a definition of static vs.\& dynamic, +and partially vs.\& fully specified links.) .Pp This function returns 0 on success, \-1 otherwise. .Ed @@ -878,7 +878,7 @@ and .Fa maxpacketsize is provided for error checking purposes. This function can be used if an already-aliased packet needs to have its -original IP header restored for further processing (eg. logging). +original IP header restored for further processing (e.g.\& logging). .Ed .Sh BUGS PPTP aliasing does not work when more than one internal client diff --git a/usr.sbin/bsnmpd/modules/snmp_netgraph/snmp_netgraph.3 b/usr.sbin/bsnmpd/modules/snmp_netgraph/snmp_netgraph.3 index f470496..81cdd74 100644 --- a/usr.sbin/bsnmpd/modules/snmp_netgraph/snmp_netgraph.3 +++ b/usr.sbin/bsnmpd/modules/snmp_netgraph/snmp_netgraph.3 @@ -135,15 +135,18 @@ The .Nm snmp_netgraph module implements a number of tables and scalars that enable remote access to -the netgraph subsystem. It also exports a number of global variables and +the netgraph subsystem. +It also exports a number of global variables and functions, that allow other modules to easily use the netgraph system. .Pp If upon start up of the module the variable .Va begemotNgControlNodeName is not empty the module opens a netgraph socket and names that socket node. If the variable is empty, the socket is created, as soon as the variable is -written with a non-empty name. The socket can be closed by writing an empty -string to the variable. The socket itself and its name are available in +written with a non-empty name. +The socket can be closed by writing an empty +string to the variable. +The socket itself and its name are available in .Va snmp_node and .Va snmp_nodename . @@ -169,7 +172,8 @@ is the node specific command cookie, .It Fa opcode is the node specific code for the operation to performa, .It Fa arg -is a pointer to the message itself. This message must start with a +is a pointer to the message itself. +This message must start with a .Vt struct ng_mesg . .It Fa arglen is the overall length of the message (header plus arguments). @@ -178,8 +182,10 @@ The functions return the message id that can be used to match incoming responses or -1 if an error occurs. .Pp Another class of functions is used to send a control message and to wait for -a matching response. Note, that this operation blocks the daemon, so use it -only if you are sure that the response will happen. There is a maximum timeout +a matching response. +Note, that this operation blocks the daemon, so use it +only if you are sure that the response will happen. +There is a maximum timeout that is configurable in the MIB variable .Va begemotNgTimeout . Other messages arriving while the functions are waiting for the response are @@ -201,9 +207,11 @@ and waits for a matching response. .Pp All three functions take the same arguments as the .Fn ng_output* -functions. The functions return the reponse message in a buffer allocated by +functions. +The functions return the reponse message in a buffer allocated by .Xr malloc 3 -or NULL in case of an error. The maximum size of the response buffer can be +or NULL in case of an error. +The maximum size of the response buffer can be configured in the variable .Va begemotNgResBufSiz . .Pp @@ -212,16 +220,19 @@ A data message can be send with the function This function takes the name of the .Va snmp_node Ns 's hook through which to send the data, a pointer to the message buffer and -the size of the message. It returns -1 if an error happens. +the size of the message. +It returns -1 if an error happens. .Ss ASYNCHRONOUS CONTROL AND DATA MESSAGES A module can register functions to asynchronuosly receive control and data message. .Pp The function .Fn ng_register_cookie -registers a control message receive function. If a control message is +registers a control message receive function. +If a control message is received, that is not consumed by the dialog functions, the list of registerred -control message receive functions is scanned. If the cookie in the received +control message receive functions is scanned. +If the cookie in the received message is the same as the .Fa cookie argument to the @@ -238,7 +249,8 @@ is called with a pointer to the received message, the hook on which the message was received (or NULL if it was received not on a hook), the id of the sender's node and the .Fa uarg -argument of the registration call. The handler function should not modify +argument of the registration call. +The handler function should not modify the contents of the message, because more than one function may be registered to the same cookie and node id. .Pp @@ -253,12 +265,14 @@ A module can call .Fn ng_register_hook to register a callback for data messages on one of the .Va snmp_node Ns 's -hooks. If a data message is received on that hook, the callback function +hooks. +If a data message is received on that hook, the callback function .Fa func is called with the hook name, a pointer to the data message, the size of the message and the argument .Fa uarg -to the registration function. The message should be treated as read-only. +to the registration function. +The message should be treated as read-only. A data message registration can be undone by calling .Fn ng_unregister_hook with the return value of the registration call. @@ -291,7 +305,8 @@ and writes it to the buffer pointed to by .Fa name . This buffer should be at least .Li NG_NODESIZ -bytes long. The function returns the node id or 0 if the +bytes long. +The function returns the node id or 0 if the node is not found .Pp The function @@ -302,7 +317,8 @@ and writes it to the buffer pointed to by .Fa type . This buffer should be at least .Li NG_TYPESIZ -bytes long. The function returns the node id or 0 if the +bytes long. +The function returns the node id or 0 if the node is not found. .Pp The function @@ -315,8 +331,10 @@ to the buffer pointed to by .Fa peer_hook . The buffer should be at least .Li NG_HOOKSIZ -bytes long. The function returns 0 if the node and the hook is found, -1 -otherwise. The function skips intermediate tee nodes (see +bytes long. +The function returns 0 if the node and the hook is found, -1 +otherwise. +The function skips intermediate tee nodes (see .Xr ng_tee 4 ). .Pp The function @@ -348,7 +366,8 @@ of node .Fa id . If .Fa name -is not NULL the new node is named with this name. The function returns +is not NULL the new node is named with this name. +The function returns The node id of the new node or 0 if an error happens. .Pp The functions |
