diff options
author | ru <ru@FreeBSD.org> | 2004-07-02 23:52:20 +0000 |
---|---|---|
committer | ru <ru@FreeBSD.org> | 2004-07-02 23:52:20 +0000 |
commit | 01548ace1533487f9c0488f55112c9d8641f8184 (patch) | |
tree | 23294a96f715e1e5bc35c1029ec151c90ee95b96 /lib/libc | |
parent | 47f5e31e2bb626743fa9e912918201fe505b1419 (diff) | |
download | FreeBSD-src-01548ace1533487f9c0488f55112c9d8641f8184.zip FreeBSD-src-01548ace1533487f9c0488f55112c9d8641f8184.tar.gz |
Mechanically kill hard sentence breaks.
Diffstat (limited to 'lib/libc')
143 files changed, 851 insertions, 439 deletions
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 |