diff options
59 files changed, 537 insertions, 391 deletions
diff --git a/lib/libc/gen/basename.3 b/lib/libc/gen/basename.3 index 53e01067660..e5c74951f33 100644 --- a/lib/libc/gen/basename.3 +++ b/lib/libc/gen/basename.3 @@ -24,7 +24,7 @@ .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $OpenBSD: basename.3,v 1.11 1999/06/04 01:30:10 aaron Exp $ +.\" $OpenBSD: basename.3,v 1.12 2000/04/18 03:01:25 aaron Exp $ .\" .Dd August 17, 1997 .Dt BASENAME 3 @@ -44,13 +44,15 @@ returns the last component from the pathname pointed to by .Ar path , deleting any trailing .Sq \&/ -characters. If +characters. +If .Ar path consists entirely of .Sq \&/ characters, a pointer to the string .Qq \&/ -is returned. If +is returned. +If .Ar path is a null pointer or the empty string, a pointer to the string .Qq \&. diff --git a/lib/libc/gen/directory.3 b/lib/libc/gen/directory.3 index a0b7e01b6af..1256e853de7 100644 --- a/lib/libc/gen/directory.3 +++ b/lib/libc/gen/directory.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: directory.3,v 1.12 2000/04/15 02:15:22 aaron Exp $ +.\" $OpenBSD: directory.3,v 1.13 2000/04/18 03:01:25 aaron Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -56,7 +56,7 @@ .Ft long .Fn telldir "const DIR *dirp" .Ft void -.Fn seekdir "DIR *dirp" "long loc" +.Fn seekdir "DIR *dirp" "long loc" .Ft void .Fn rewinddir "DIR *dirp" .Ft int @@ -74,7 +74,8 @@ with it and returns a pointer to be used to identify the directory stream -in subsequent operations. A null pointer is returned if +in subsequent operations. +A null pointer is returned if .Fa filename cannot be accessed, or if .Xr malloc 3 @@ -133,7 +134,8 @@ operation on the named directory stream The new position reverts to the one associated with the directory stream when the .Fn telldir -operation was performed. Values returned by +operation was performed. +Values returned by .Fn telldir are good only for the lifetime of the .Dv DIR diff --git a/lib/libc/gen/dirname.3 b/lib/libc/gen/dirname.3 index 4f3d7754562..1857849f5ab 100644 --- a/lib/libc/gen/dirname.3 +++ b/lib/libc/gen/dirname.3 @@ -24,7 +24,7 @@ .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $OpenBSD: dirname.3,v 1.8 1999/07/17 09:32:30 downsj Exp $ +.\" $OpenBSD: dirname.3,v 1.9 2000/04/18 03:01:25 aaron Exp $ .\" .Dd August 17, 1997 .Dt DIRNAME 3 @@ -47,7 +47,8 @@ it returns a pointer to the parent directory of the pathname pointed to by Any trailing .Sq \&/ characters are not counted as part of the directory -name. If +name. +If .Ar path is a null pointer, the empty string, or contains no .Sq \&/ diff --git a/lib/libc/gen/exec.3 b/lib/libc/gen/exec.3 index 734da4d14af..bc5d7a48878 100644 --- a/lib/libc/gen/exec.3 +++ b/lib/libc/gen/exec.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: exec.3,v 1.9 1999/06/04 01:30:10 aaron Exp $ +.\" $OpenBSD: exec.3,v 1.10 2000/04/18 03:01:26 aaron Exp $ .\" .\" Copyright (c) 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -52,7 +52,7 @@ .Ft int .Fn execle "const char *path" "const char *arg" ... "char *const envp[]" .Ft int -.Fn exect "const char *path" "char *const argv[]" "char *const envp[]" +.Fn exect "const char *path" "char *const argv[]" "char *const envp[]" .Ft int .Fn execv "const char *path" "char *const argv[]" .Ft int @@ -80,7 +80,7 @@ and .Fn execle functions can be thought of as .Fa arg0 , -.Fa arg1 , +.Fa arg1 , \&..., .Fa argn . Together they describe a list of one or more pointers to diff --git a/lib/libc/gen/ftok.3 b/lib/libc/gen/ftok.3 index c6a747da494..b5f4dfbcc34 100644 --- a/lib/libc/gen/ftok.3 +++ b/lib/libc/gen/ftok.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ftok.3,v 1.9 1999/09/23 04:12:00 alex Exp $ +.\" $OpenBSD: ftok.3,v 1.10 2000/04/18 03:01:26 aaron Exp $ .\" .\" Copyright (c) 1994 SigmaSoft, Th. Lockert <tholo@sigmasoft.com> .\" All rights reserved. @@ -52,8 +52,8 @@ of an existing file and a user-selectable The specified .Fa path must refer to an existing file that is accessible to the calling process -or the call will fail. Also, note that links to files will return the -same key, given the same +or the call will fail. +Also, note that links to files will return the same key, given the same .Fa id . Only the 8 least significant bits of .Fa id diff --git a/lib/libc/gen/fts.3 b/lib/libc/gen/fts.3 index 61df9e1ab2f..7e0957e3bc1 100644 --- a/lib/libc/gen/fts.3 +++ b/lib/libc/gen/fts.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: fts.3,v 1.15 1999/10/03 19:22:22 millert Exp $ +.\" $OpenBSD: fts.3,v 1.16 2000/04/18 03:01:26 aaron Exp $ .\" .\" Copyright (c) 1989, 1991, 1993, 1994 .\" The Regents of the University of California. All rights reserved. @@ -141,7 +141,7 @@ With the exception of directories without errors all of these entries are terminal, that is, they will not be revisited, nor will any of their descendants be visited. -.Bl -tag -width FTS_DEFAULT +.Bl -tag -width FTS_DEFAULT .It Dv FTS_D A directory being visited in pre-order. .It Dv FTS_DC diff --git a/lib/libc/gen/getcap.3 b/lib/libc/gen/getcap.3 index 8bc3e98236b..2a40775d866 100644 --- a/lib/libc/gen/getcap.3 +++ b/lib/libc/gen/getcap.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getcap.3,v 1.18 2000/03/06 21:46:56 aaron Exp $ +.\" $OpenBSD: getcap.3,v 1.19 2000/04/18 03:01:26 aaron Exp $ .\" .\" Copyright (c) 1992, 1993 .\" The Regents of the University of California. All rights reserved. @@ -131,7 +131,8 @@ is .Dv NULL , the current entry is removed from the database. .Fn cgetset -must precede the database traversal. It must be called before +must precede the database traversal. +It must be called before .Fn cgetent . If a sequential access is being performed (see below), it must be called before the first sequential access call @@ -160,18 +161,21 @@ with type .Fa type . A .Fa type -is specified using any single character. If a colon +is specified using any single character. +If a colon .Pq Sq \&: 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 or .Dv NULL if the requested capability couldn't be -found. The end of the capability value is signaled by a +found. +The end of the capability value is signaled by a .Sq \&: or .Tn ASCII @@ -228,7 +232,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 Ns \&'d @@ -238,7 +243,7 @@ copy pointed to by expansion is done (see .Ic tc= comments below). -Upon completion of the database 0 is returned, 1 is returned upon successful +Upon completion of the database 0 is returned, 1 is returned upon successful return of record with possibly more remaining (we haven't reached the end of the database yet), 2 is returned if the record contains an unresolved .Ic tc @@ -250,36 +255,43 @@ Upon completion of database (0 return) the database is closed. .Pp .Fn cgetclose 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 . .Ss Capability database syntax Capability databases are normally .Tn ASCII and may be edited with standard -text editors. Blank lines and lines beginning with a +text editors. +Blank lines and lines beginning with a .Sq \&# are comments -and ignored. Lines ending with a +and ignored. +Lines ending with a .Sq \|\e indicate that the next line is a continuation of the current line; the .Sq \|\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 .Sq \|\e . .Pp Capability databases consist of a series of records, one per logical -line. Each record contains a variable number of -colon-separated fields -(capabilities). Empty fields consisting entirely of whitespace +line. +Each record contains a variable number of colon-separated fields +(capabilities). +Empty fields consisting entirely of whitespace characters (spaces and tabs) are ignored. .Pp The first capability of each record specifies its names, separated by .Sq \&| -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 .Dq vt100 record from the .Nm termcap @@ -304,8 +316,8 @@ has value does not exist .El .Pp -Names consist of one or more characters. Names may contain any character -except +Names consist of one or more characters. +Names may contain any character except .Sq \&: , but it's usually best to restrict them to the printable characters and avoid use of graphics like @@ -313,21 +325,22 @@ characters and avoid use of graphics like .Sq \&= , .Sq \&% , .Sq \&@ , -etc. Types -are single characters used to separate capability names from their -associated typed values. Types may be any character except a +etc. +Types are single characters used to separate capability names from their +associated typed values. +Types may be any character except a .Sq \&: . Typically, graphics like .Sq \&# , .Sq \&= , .Sq \&% , -etc. are used. Values may be any -number of characters and may contain any character except +etc. are used. +Values may be any number of characters and may contain any character except .Sq \&: . .Ss 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 -distinguished by their +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 . .Fn cgetcap will return a pointer to a value of a name given the capability name and @@ -338,8 +351,8 @@ The types and .Sq \&= are conventionally used to denote numeric and -string typed values, but no restriction on those types is enforced. The -functions +string typed values, but no restriction on those types is enforced. +The functions .Fn cgetnum and .Fn cgetstr @@ -365,7 +378,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 @@ -373,7 +387,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 @@ -429,7 +444,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: @@ -450,7 +466,8 @@ of escape sequences: A .Sq \|\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 NULs, while easily encoded, causes all sorts of problems and must be used with care since @@ -471,8 +488,8 @@ The capability foo has two values bound to it (bar of type and blah of type .Sq \&^ ) -and any other value bindings are hidden. The capability abc -also has two values bound but only a value of type +and any other value bindings are hidden. +The capability abc also has two values bound but only a value of type .Sq \&$ is prevented from being defined in the capability record more. @@ -495,8 +512,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 -would take precedence. +tc=old is important here. +If they were after, the definitions in old would take precedence. .Sh DIAGNOSTICS .Fn cgetent , .Fn cgetset , diff --git a/lib/libc/gen/getdiskbyname.3 b/lib/libc/gen/getdiskbyname.3 index 170af443249..48769d8a2fc 100644 --- a/lib/libc/gen/getdiskbyname.3 +++ b/lib/libc/gen/getdiskbyname.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getdiskbyname.3,v 1.5 1999/07/09 13:35:16 aaron Exp $ +.\" $OpenBSD: getdiskbyname.3,v 1.6 2000/04/18 03:01:26 aaron Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -48,9 +48,8 @@ function takes a disk name (e.g., .Qq rm03 ) and returns a prototype disk label -describing its geometry information and the standard -disk partition tables. All information is obtained from -the +describing its geometry information and the standard disk partition tables. +All information is obtained from the .Xr disktab 5 file. .Sh SEE ALSO diff --git a/lib/libc/gen/getdomainname.3 b/lib/libc/gen/getdomainname.3 index a295a9f2d94..fc19c150225 100644 --- a/lib/libc/gen/getdomainname.3 +++ b/lib/libc/gen/getdomainname.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getdomainname.3,v 1.16 2000/04/15 11:46:02 aaron Exp $ +.\" $OpenBSD: getdomainname.3,v 1.17 2000/04/18 03:01:26 aaron Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -55,7 +55,8 @@ The parameter .Fa namelen specifies the size of the .Fa name -array. If insufficient space is provided, the returned name is truncated. +array. +If insufficient space is provided, the returned name is truncated. The returned name is always null terminated. .Pp .Fn setdomainname @@ -66,8 +67,8 @@ which has length This call is restricted to the superuser and is normally used only when the system is bootstrapped. .Sh RETURN VALUES -If the call succeeds a value of 0 is returned. If the call -fails, a value of \-1 is returned and an error code is +If the call succeeds a value of 0 is returned. +If the call fails, a value of \-1 is returned and an error code is placed in the global variable .Va errno . .Sh ERRORS @@ -95,7 +96,8 @@ Domain names are limited to .Dv MAXHOSTNAMELEN (from .Ao Pa sys/param.h Ac ) -characters, currently 256. This includes the terminating NUL character. +characters, currently 256. +This includes the terminating NUL character. .Pp If the buffer passed to .Fn getdomainname diff --git a/lib/libc/gen/getgrent.3 b/lib/libc/gen/getgrent.3 index 77f31a4a1de..f7a237c106e 100644 --- a/lib/libc/gen/getgrent.3 +++ b/lib/libc/gen/getgrent.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getgrent.3,v 1.8 2000/03/23 22:14:03 d Exp $ +.\" $OpenBSD: getgrent.3,v 1.9 2000/04/18 03:01:26 aaron Exp $ .\" .\" Copyright (c) 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -94,8 +94,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 -names or group GIDs may result in undefined behavior. +respectively, returning the first one encountered. +Identical group names or group GIDs may result in undefined behavior. .Pp .Fn getgrent sequentially reads the group database and is intended for programs @@ -104,12 +104,15 @@ that wish to step through the complete list of groups. All three routines will open the group file for reading, if necessary. .Pp .Fn setgroupent -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 -subsequent function calls. This functionality is unnecessary for +subsequent function 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 @@ -208,9 +211,8 @@ The functions and .Fn setgrent leave their results in an internal static object and return -a pointer to that object. Subsequent calls to -the same function -will modify the same object. +a pointer to that object. +Subsequent calls to the same function will modify the same object. .Pp The functions .Fn getgrent , diff --git a/lib/libc/gen/gethostname.3 b/lib/libc/gen/gethostname.3 index d89aa0f7bd5..a10102b5943 100644 --- a/lib/libc/gen/gethostname.3 +++ b/lib/libc/gen/gethostname.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: gethostname.3,v 1.16 2000/04/15 11:46:02 aaron Exp $ +.\" $OpenBSD: gethostname.3,v 1.17 2000/04/18 03:01:26 aaron Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -54,7 +54,8 @@ The parameter .Fa namelen specifies the size of the .Fa name -array. If insufficient space is provided, the returned name is truncated. +array. +If insufficient space is provided, the returned name is truncated. The returned name is always null terminated. .Pp .Fn sethostname @@ -65,8 +66,8 @@ which has length This call is restricted to the superuser and is normally used only when the system is bootstrapped. .Sh RETURN VALUES -If the call succeeds a value of 0 is returned. If the call -fails, a value of \-1 is returned and an error code is +If the call succeeds a value of 0 is returned. +If the call fails, a value of \-1 is returned and an error code is placed in the global variable .Va errno . .Sh ERRORS @@ -94,7 +95,8 @@ Host names are limited to .Dv MAXHOSTNAMELEN (from .Ao Pa sys/param.h Ac ) -characters, currently 256. This includes the terminating NUL character. +characters, currently 256. +This includes the terminating NUL character. .Pp If the buffer passed to .Fn gethostname diff --git a/lib/libc/gen/getloadavg.3 b/lib/libc/gen/getloadavg.3 index 933eaaeb637..8a65e0e05c8 100644 --- a/lib/libc/gen/getloadavg.3 +++ b/lib/libc/gen/getloadavg.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getloadavg.3,v 1.7 1999/06/03 10:03:21 aaron Exp $ +.\" $OpenBSD: getloadavg.3,v 1.8 2000/04/18 03:01:26 aaron Exp $ .\" .\" Copyright (c) 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -53,8 +53,8 @@ samples are retrieved and assigned to successive elements of The system imposes a maximum of 3 samples, representing averages over the last 1, 5, and 15 minutes, respectively. .Sh RETURN VALUES -Upon successful completion, the number of samples retrieved is -returned. If an error occurs, \-1 is returned and the global variable +Upon successful completion, the number of samples retrieved is returned. +If an error occurs, \-1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS diff --git a/lib/libc/gen/getmntinfo.3 b/lib/libc/gen/getmntinfo.3 index 4467c1224de..10123bfebc3 100644 --- a/lib/libc/gen/getmntinfo.3 +++ b/lib/libc/gen/getmntinfo.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getmntinfo.3,v 1.7 1999/08/25 12:26:51 millert Exp $ +.\" $OpenBSD: getmntinfo.3,v 1.8 2000/04/18 03:01:26 aaron Exp $ .\" .\" Copyright (c) 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -97,8 +97,8 @@ function first appeared in The .Fn getmntinfo function writes the array of structures to an internal static object -and returns -a pointer to that object. Subsequent calls to +and returns a pointer to that object. +Subsequent calls to .Fn getmntinfo will modify the same object. .Pp diff --git a/lib/libc/gen/getpwent.3 b/lib/libc/gen/getpwent.3 index f736ae6b391..879c1a41739 100644 --- a/lib/libc/gen/getpwent.3 +++ b/lib/libc/gen/getpwent.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getpwent.3,v 1.10 2000/04/15 02:15:22 aaron Exp $ +.\" $OpenBSD: getpwent.3,v 1.11 2000/04/18 03:01:27 aaron Exp $ .\" .\" Copyright (c) 1988, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -52,7 +52,7 @@ .Ft struct passwd * .Fn getpwuid "uid_t uid" .Ft int -.Fn setpassent "int stayopen" +.Fn setpassent "int stayopen" .Ft void .Fn setpwent void .Ft void @@ -184,9 +184,8 @@ The functions and .Fn getpwuid leave their results in an internal static object and return -a pointer to that object. Subsequent calls to -any of these functions -will modify the same object. +a pointer to that object. +Subsequent calls to any of these functions will modify the same object. .Pp The routines .Fn getpwent , diff --git a/lib/libc/gen/getusershell.3 b/lib/libc/gen/getusershell.3 index a45d724cdc2..1d41eb1cc64 100644 --- a/lib/libc/gen/getusershell.3 +++ b/lib/libc/gen/getusershell.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getusershell.3,v 1.7 1999/07/09 13:35:17 aaron Exp $ +.\" $OpenBSD: getusershell.3,v 1.8 2000/04/18 03:01:27 aaron Exp $ .\" .\" Copyright (c) 1985, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -93,6 +93,7 @@ function appeared in The .Fn getusershell function leaves its result in an internal static object and returns -a pointer to that object. Subsequent calls to +a pointer to that object. +Subsequent calls to .Fn getusershell will modify the same object. diff --git a/lib/libc/gen/lockf.3 b/lib/libc/gen/lockf.3 index 2aa2d8b2bd8..e7b0c7bae28 100644 --- a/lib/libc/gen/lockf.3 +++ b/lib/libc/gen/lockf.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: lockf.3,v 1.8 1999/06/05 03:44:54 aaron Exp $ +.\" $OpenBSD: lockf.3,v 1.9 2000/04/18 03:01:27 aaron Exp $ .\" $NetBSD: lockf.3,v 1.1 1997/12/20 20:23:17 kleink Exp $ .\" .\" Copyright (c) 1997 The NetBSD Foundation, Inc. @@ -96,11 +96,12 @@ detects if a lock by another process is present on the specified section. .Pp The .Fa size -argument is the number of contiguous bytes to be locked or -unlocked. The section to be locked or unlocked starts at the current +argument is the number of contiguous bytes to be locked or 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 @@ -113,9 +114,11 @@ The sections locked with or .Dv F_TLOCK may, in whole or in part, contain or be contained by a previously -locked section for the same process. When this occurs, or if adjacent +locked section for the same process. +When this occurs, or if adjacent locked sections would occur, the sections are combined into a single -locked section. If the request would cause the number of locks to +locked section. +If the request would cause the number of locks to exceed a system-imposed limit, the request will fail. .Pp The @@ -135,15 +138,19 @@ file descriptor for the file. .Pp .Dv F_ULOCK requests release (wholly or in part) of one or more locked sections -controlled by the process. Locked sections will be unlocked starting +controlled by the process. +Locked sections will be unlocked starting at the current file offset through .Fa size -bytes or to the end of the file if size is 0. When all of a locked section +bytes or to the end of the 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. Releasing the center +that section are still locked by the process. +Releasing the center portion of a locked section will cause the remaining locked beginning -and end portions to become two separate locked sections. If the +and end portions to become two separate locked sections. +If the request would cause the number of locks in the system to exceed a system-imposed limit, the request will fail. .Pp @@ -155,13 +162,15 @@ the requested section is the maximum value for an object of type 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/psignal.3 b/lib/libc/gen/psignal.3 index 455965e3c4e..d247e95f285 100644 --- a/lib/libc/gen/psignal.3 +++ b/lib/libc/gen/psignal.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: psignal.3,v 1.7 1999/07/09 13:35:18 aaron Exp $ +.\" $OpenBSD: psignal.3,v 1.8 2000/04/18 03:01:27 aaron Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -68,11 +68,12 @@ is produced. .Pp The message strings can be accessed directly using the external array .Va sys_siglist , -indexed by recognized signal numbers. The external array +indexed by recognized signal numbers. +The external array .Va sys_signame is used similarly and contains short, upper-case abbreviations for signals -which are useful for recognizing signal names in user input. The defined -variable +which are useful for recognizing signal names in user input. +The defined variable .Dv NSIG contains a count of the strings in .Va sys_siglist diff --git a/lib/libc/gen/setjmp.3 b/lib/libc/gen/setjmp.3 index df0fc58d4f5..87e828a0a92 100644 --- a/lib/libc/gen/setjmp.3 +++ b/lib/libc/gen/setjmp.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: setjmp.3,v 1.9 1999/07/09 13:35:18 aaron Exp $ +.\" $OpenBSD: setjmp.3,v 1.10 2000/04/18 03:01:27 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -94,8 +94,8 @@ as well as .Fn setjmp and .Fn longjmp -combinations may be used in the same program. However, individual -calls may not \(em e.g., the +combinations may be used in the same program. +However, individual calls may not \(em e.g., the .Fa env argument to .Fn setjmp @@ -131,7 +131,8 @@ The function pairs save and restore the signal mask if the argument .Fa savemask -is non-zero. Otherwise, only the register set and the stack are saved. +is non-zero. +Otherwise, only the register set and the stack are saved. .Sh ERRORS If the contents of the .Fa env diff --git a/lib/libc/gen/signal.3 b/lib/libc/gen/signal.3 index 21f070bef6e..3566c7ed2ae 100644 --- a/lib/libc/gen/signal.3 +++ b/lib/libc/gen/signal.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: signal.3,v 1.12 1999/07/09 13:35:19 aaron Exp $ +.\" $OpenBSD: signal.3,v 1.13 2000/04/18 03:01:27 aaron Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -55,7 +55,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 @@ -150,7 +151,8 @@ To ignore the signal, should be .Dv SIG_IGN . This will cause subsequent instances of the signal to be ignored -and pending instances to be discarded. If +and pending instances to be discarded. +If .Dv SIG_IGN is not used, further occurrences of the signal are diff --git a/lib/libc/gen/sleep.3 b/lib/libc/gen/sleep.3 index b4aea47d790..bd51f899a72 100644 --- a/lib/libc/gen/sleep.3 +++ b/lib/libc/gen/sleep.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sleep.3,v 1.7 1999/08/31 16:52:34 aaron Exp $ +.\" $OpenBSD: sleep.3,v 1.8 2000/04/18 03:01:27 aaron Exp $ .\" .\" Copyright (c) 1986, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -48,8 +48,8 @@ function suspends execution of the calling process until either the number of seconds specified by .Fa seconds have elapsed or a signal is delivered to the calling process and its -action is to invoke a signal-catching function or to terminate the -process. The suspension time may be longer than requested due to the +action is to invoke a signal-catching function or to terminate the process. +The suspension time may be longer than requested due to the scheduling of other activity by the system. .Pp This function is implemented using @@ -67,7 +67,8 @@ interferes with interval timers anymore). 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 request time minus the time actually diff --git a/lib/libc/gen/sysctl.3 b/lib/libc/gen/sysctl.3 index b84fae29f33..528c1e2f8b9 100644 --- a/lib/libc/gen/sysctl.3 +++ b/lib/libc/gen/sysctl.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sysctl.3,v 1.41 2000/04/12 21:48:01 aaron Exp $ +.\" $OpenBSD: sysctl.3,v 1.42 2000/04/18 03:01:27 aaron Exp $ .\" .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. @@ -198,7 +198,7 @@ level is detailed below. The changeable column shows whether a process with appropriate privileges may change the value. .Bl -column "Second level nameXXXXXX" integerXXX -offset indent -.It Sy Second level name Type Changeable +.It Sy Second level name Type Changeable .It Dv HW_MACHINE No " string no" .It Dv HW_MODEL No " string no" .It Dv HW_NCPU No " integer no" @@ -720,8 +720,8 @@ in seconds.) .It Li tcp.sack Returns 1 if RFC2018 Selective Acknowledgements are enabled. .It Li tcp.mssdflt -The maximum segment size that is used as default for non local -connections. The default value is 512. +The maximum segment size that is used as default for non-local connections. +The default value is 512. .It Li udp.checksum Returns 1 when .Tn UDP @@ -1009,9 +1009,9 @@ Return the system wide virtual memory statistics. The returned data consists of a .Li struct vmtotal . .It Dv VM_SWAPENCRYPT -Set to 1 to enable swap encryption for all processes. A 0 -disables swap encryption. Pages still on swap receive a -grandfather clause. +Set to 1 to enable swap encryption for all processes. +A 0 disables swap encryption. +Pages still on swap receive a grandfather clause. .El .Sh RETURN VALUES If the call to diff --git a/lib/libc/gen/timezone.3 b/lib/libc/gen/timezone.3 index 8c6df4144a0..23c64eec6a1 100644 --- a/lib/libc/gen/timezone.3 +++ b/lib/libc/gen/timezone.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: timezone.3,v 1.9 2000/03/31 00:04:14 millert Exp $ +.\" $OpenBSD: timezone.3,v 1.10 2000/04/18 03:01:28 aaron Exp $ .\" .\" Copyright (c) 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -64,8 +64,8 @@ and .Fa dst is non-zero if Daylight Saving Time is in effect. .Pp -This function is not used to set the system's time zone. The -default system time zone may be set by running +This function is not used to set the system's time zone. +The default system time zone may be set by running .Li Dq zic -l timezone as the superuser. .Sh SEE ALSO diff --git a/lib/libc/gen/tolower.3 b/lib/libc/gen/tolower.3 index bf67f324e80..2a80e804bc7 100644 --- a/lib/libc/gen/tolower.3 +++ b/lib/libc/gen/tolower.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: tolower.3,v 1.8 1999/07/09 13:35:19 aaron Exp $ +.\" $OpenBSD: tolower.3,v 1.9 2000/04/18 03:01:28 aaron Exp $ .\" .\" Copyright (c) 1989, 1991 The Regents of the University of California. .\" All rights reserved. @@ -52,7 +52,8 @@ The .Fn tolower function converts an upper-case letter to the corresponding lower-case -letter. The +letter. +The .Fn _tolower function is identical to .Fn tolower diff --git a/lib/libc/gen/toupper.3 b/lib/libc/gen/toupper.3 index 8ce6d914384..c2abea2cd00 100644 --- a/lib/libc/gen/toupper.3 +++ b/lib/libc/gen/toupper.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: toupper.3,v 1.10 1999/07/09 13:35:19 aaron Exp $ +.\" $OpenBSD: toupper.3,v 1.11 2000/04/18 03:01:28 aaron Exp $ .\" .\" Copyright (c) 1989, 1991 The Regents of the University of California. .\" All rights reserved. @@ -52,7 +52,8 @@ The .Fn toupper function converts a lower-case letter to the corresponding -upper-case letter. The +upper-case letter. +The .Fn _toupper function is identical to .Fn toupper diff --git a/lib/libc/gen/ttyname.3 b/lib/libc/gen/ttyname.3 index 664662519ce..0dca816732b 100644 --- a/lib/libc/gen/ttyname.3 +++ b/lib/libc/gen/ttyname.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ttyname.3,v 1.10 2000/01/22 12:00:42 aaron Exp $ +.\" $OpenBSD: ttyname.3,v 1.11 2000/04/18 03:01:28 aaron Exp $ .\" .\" Copyright (c) 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -52,7 +52,8 @@ .Fn ttyslot "void" .Sh DESCRIPTION These functions operate on the system file descriptors for terminal -type devices. These descriptors are not related to the standard +type devices. +These descriptors are not related to the standard .Tn I/O .Dv FILE typedef, but refer to the special device files found in @@ -93,7 +94,8 @@ in the character array referenced by The array is .Fa namesize characters long and should have space for the name and the terminating -NUL character. The maximum length of the terminal name is +NUL character. +The maximum length of the terminal name is .Dv TTY_NAME_MAX . .Pp The @@ -174,6 +176,7 @@ function appeared in the POSIX Threads Extension (1003.1c-1995). The .Fn ttyname function leaves its result in an internal static object and returns -a pointer to that object. Subsequent calls to +a pointer to that object. +Subsequent calls to .Fn ttyname will modify the same object. diff --git a/lib/libc/gen/unvis.3 b/lib/libc/gen/unvis.3 index a10e539324f..663b6f8331f 100644 --- a/lib/libc/gen/unvis.3 +++ b/lib/libc/gen/unvis.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: unvis.3,v 1.10 1999/08/11 03:06:06 deraadt Exp $ +.\" $OpenBSD: unvis.3,v 1.11 2000/04/18 03:01:28 aaron Exp $ .\" .\" Copyright (c) 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -80,7 +80,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 @@ -91,20 +92,22 @@ 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 -is stored outside the +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 -start decoding a stream of bytes, first initialize an integer -to zero. Call +calls decoding different streams can be freely intermixed. +To start decoding a stream of bytes, first initialize an integer +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. @@ -118,11 +121,12 @@ pointed to by .Fa 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 -return code is necessary to indicate a logical break between characters. +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/utime.3 b/lib/libc/gen/utime.3 index 2615ddda57b..64144d2232e 100644 --- a/lib/libc/gen/utime.3 +++ b/lib/libc/gen/utime.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: utime.3,v 1.12 2000/04/15 11:46:02 aaron Exp $ +.\" $OpenBSD: utime.3,v 1.13 2000/04/18 03:01:28 aaron Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -80,7 +80,8 @@ The access time is set to the value of the member, and the modification time is set to the value of the .Fa modtime -member. The times are measured in +member. +The times are measured in seconds since 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time (UTC). The calling process must be the owner of the file or be the superuser. diff --git a/lib/libc/gen/vis.3 b/lib/libc/gen/vis.3 index 49d8e7ea422..da260c7b0fd 100644 --- a/lib/libc/gen/vis.3 +++ b/lib/libc/gen/vis.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: vis.3,v 1.9 1999/07/09 13:35:20 aaron Exp $ +.\" $OpenBSD: vis.3,v 1.10 2000/04/18 03:01:28 aaron Exp $ .\" .\" Copyright (c) 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -57,9 +57,10 @@ a string which represents the character .Fa c . If .Fa c -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 +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 characters (not including the trailing NUL); thus, when encoding a set of characters into a buffer, the size of the buffer should @@ -145,9 +146,10 @@ Synonym for .It Dv VIS_SAFE Only encode .Dq unsafe -characters. These are control -characters which may cause common terminals to perform -unexpected functions. Currently this form allows space, +characters. +These are control characters which may cause common terminals to perform +unexpected functions. +Currently this form allows space, tab, newline, backspace, bell, and return -- in addition to all graphic characters -- unencoded. .El @@ -235,7 +237,8 @@ If is an octal digit, the latter representation is used to avoid ambiguity. .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/hash/rmd160.3 b/lib/libc/hash/rmd160.3 index 03cd1f3d133..38ce2f64261 100644 --- a/lib/libc/hash/rmd160.3 +++ b/lib/libc/hash/rmd160.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: rmd160.3,v 1.11 1999/08/11 03:06:06 deraadt Exp $ +.\" $OpenBSD: rmd160.3,v 1.12 2000/04/18 03:01:29 aaron Exp $ .\" .\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com> .\" All rights reserved. @@ -59,8 +59,10 @@ .Fn RMD160Data "u_char *data" "u_int len" "char *buf" .Sh DESCRIPTION The RMD160 functions implement the 160-bit RIPE message digest hash algorithm -(RMD-160). RMD-160 is used to generate a condensed representation -of a message called a message digest. The algorithm takes a +(RMD-160). +RMD-160 is used to generate a condensed representation +of a message called a message digest. +The algorithm takes a message less than 2^64 bits as input and produces a 160-bit digest suitable for use as a digital signature. .Pp @@ -70,7 +72,8 @@ and .Xr md5 3 functions and at least as secure as the .Xr sha1 3 -function. All share a similar interface. +function. +All share a similar interface. .Pp The .Fn RMD160Init @@ -144,8 +147,8 @@ and functions the .Ar buf parameter should either be a string of at least 41 characters in -size or a NULL pointer. In the latter case, space will be dynamically -allocated via +size or a NULL pointer. +In the latter case, space will be dynamically allocated via .Xr malloc 3 and should be freed using .Xr free 3 diff --git a/lib/libc/hash/sha1.3 b/lib/libc/hash/sha1.3 index a115d785412..0ed67a75f97 100644 --- a/lib/libc/hash/sha1.3 +++ b/lib/libc/hash/sha1.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sha1.3,v 1.17 1999/10/06 14:55:29 espie Exp $ +.\" $OpenBSD: sha1.3,v 1.18 2000/04/18 03:01:29 aaron Exp $ .\" .\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com> .\" All rights reserved. @@ -58,8 +58,10 @@ .Fn SHA1Data "u_char *data" "u_int len" "char *buf" .Sh DESCRIPTION The SHA1 functions implement the NIST Secure Hash Algorithm (SHA-1), -FIPS PUB 180-1. SHA-1 is used to generate a condensed representation -of a message called a message digest. The algorithm takes a +FIPS PUB 180-1. +SHA-1 is used to generate a condensed representation +of a message called a message digest. +The algorithm takes a message less than 2^64 bits as input and produces a 160-bit digest suitable for use as a digital signature. .Pp @@ -141,8 +143,8 @@ and functions the .Ar buf parameter should either be a string of at least 41 characters in -size or a NULL pointer. In the latter case, space will be dynamically -allocated via +size or a NULL pointer. +In the latter case, space will be dynamically allocated via .Xr malloc 3 and should be freed using .Xr free 3 diff --git a/lib/libc/locale/setlocale.3 b/lib/libc/locale/setlocale.3 index dd5050947c4..6747026ac0e 100644 --- a/lib/libc/locale/setlocale.3 +++ b/lib/libc/locale/setlocale.3 @@ -82,8 +82,8 @@ Set a locale for the .Xr ctype 3 functions. This controls recognition of upper and lower case, -alphabetic or non-alphabetic characters, -and so on. The real work is done by the +alphabetic or non-alphabetic characters, and so on. +The real work is done by the .Fn setrunelocale function. .It Dv LC_MONETARY diff --git a/lib/libc/md/mdX.3 b/lib/libc/md/mdX.3 index 91c0465e45b..e91eb4fd977 100644 --- a/lib/libc/md/mdX.3 +++ b/lib/libc/md/mdX.3 @@ -6,7 +6,7 @@ .\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp .\" ---------------------------------------------------------------------------- .\" -.\" $OpenBSD: mdX.3,v 1.15 2000/03/28 17:35:09 millert Exp $ +.\" $OpenBSD: mdX.3,v 1.16 2000/04/18 03:01:30 aaron Exp $ .\" .Dd October 9, 1996 .Dt MDX 3 @@ -39,19 +39,24 @@ .Fn MDXData "unsigned char *data" "unsigned int len" "char *buf" .Sh DESCRIPTION The MDX functions calculate a 128-bit cryptographic checksum (digest) -for any number of input bytes. A cryptographic checksum is a one-way +for any number of input bytes. +A cryptographic checksum is a one-way hash-function, that is, you cannot find (except by exhaustive search) -the input corresponding to a particular output. This net result is -a ``fingerprint'' of the input-data, which doesn't disclose the actual -input. +the input corresponding to a particular output. +This net result is a +.Dq fingerprint +of the input-data, which doesn't disclose the actual input. .Pp MD2 is the slowest, MD4 is the fastest and MD5 is somewhere in the middle. MD2 can only be used for Privacy-Enhanced Mail. MD4 has been shown to have severe vulnerabilities; it should only be used where necessary for backward compatibility. MD5 has not yet (1999-02-11) been broken, but recent attacks have cast -some doubt on its security properties. The attacks on both MD4 and MD5 -are both in the nature of finding ``collisions'' \- that is, multiple +some doubt on its security properties. +The attacks on both MD4 and MD5 +are both in the nature of finding +.Dq collisions +\- that is, multiple inputs which hash to the same value; it is still unlikely for an attacker to be able to determine the exact original input given a hash value. .Pp @@ -60,7 +65,8 @@ The .Fn MDXUpdate , and .Fn MDXFinal -functions are the core functions. Allocate an MDX_CTX, initialize it with +functions are the core functions. +Allocate an MDX_CTX, initialize it with .Fn MDXInit , run over the data with .Fn MDXUpdate , @@ -175,8 +181,8 @@ These functions appeared in .Ox 2.0 . .Sh BUGS Hans Dobbertin has shown collisions for the full version of MD4 and -found a collision in the compress function of MD5. The use of SHA or -RIPEMD-160 is recommended instead. +found a collision in the compress function of MD5. +The use of SHA or RIPEMD-160 is recommended instead. .Pp MD2 has only been licensed for use in Privacy Enhanced Mail. Use MD4 or MD5 if that isn't what you're doing. diff --git a/lib/libc/net/byteorder.3 b/lib/libc/net/byteorder.3 index 64a13d47baf..9d8fa7221f9 100644 --- a/lib/libc/net/byteorder.3 +++ b/lib/libc/net/byteorder.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: byteorder.3,v 1.7 1999/07/05 04:40:59 aaron Exp $ +.\" $OpenBSD: byteorder.3,v 1.8 2000/04/18 03:01:30 aaron Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -83,7 +83,8 @@ .Fn swap16 "u_int16_t val16" .Sh DESCRIPTION These routines convert 16- and 32-bit quantities between different -byte orderings. The +byte orderings. +The .Dq swap functions reverse the byte ordering of the given quantity, the others converts either from/to the native @@ -127,7 +128,8 @@ The swap functions are of the form: swap{size}. Names involving .Sq n convert quantities between network -byte order and host byte order. The last letter +byte order and host byte order. +The last letter .Pf ( Sq s or .Sq l ) @@ -136,7 +138,8 @@ for the traditional names for such quantities, .Li short and .Li long , -respectively. Today, the C concept of +respectively. +Today, the C concept of .Li short and .Li long @@ -176,5 +179,5 @@ functions appeared in .Bx 4.2 . .Sh BUGS On the vax, alpha, i386, and so far mips, -bytes are handled backwards from most everyone else in -the world. This is not expected to be fixed in the near future. +bytes are handled backwards from most everyone else in the world. +This is not expected to be fixed in the near future. diff --git a/lib/libc/net/ethers.3 b/lib/libc/net/ethers.3 index 39968f3e65e..8c5066a7602 100644 --- a/lib/libc/net/ethers.3 +++ b/lib/libc/net/ethers.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ethers.3,v 1.11 1999/07/05 04:40:59 aaron Exp $ +.\" $OpenBSD: ethers.3,v 1.12 2000/04/18 03:01:31 aaron Exp $ .\" .\" Written by roland@frob.com. Public domain. .\" @@ -41,15 +41,15 @@ function converts this structure into an string of the form .Dq xx:xx:xx:xx:xx:xx , consisting of 6 hexadecimal numbers separated -by colons. It returns a pointer to a static buffer that is reused for -each call. +by colons. +It returns a pointer to a static buffer that is reused for each call. The .Fn ether_aton converts an .Tn ASCII string of the same form and to a structure -containing the 6 octets of the address. It returns a pointer to a -static structure that is reused for each call. +containing the 6 octets of the address. +It returns a pointer to a static structure that is reused for each call. .Pp The .Fn ether_ntohost @@ -61,13 +61,15 @@ addresses, The .Fn ether_ntohost function looks up the given Ethernet address and writes the associated -host name into the character buffer passed. This buffer should be +host name into the character buffer passed. +This buffer should be .Dv MAXHOSTNAMELEN characters in size. The .Fn ether_hostton function looks up the given host name and writes the associated -Ethernet address into the structure passed. Both functions return +Ethernet address into the structure passed. +Both functions return zero if they find the requested host name or address, and \-1 if not. .Pp Each call reads @@ -90,8 +92,8 @@ function parses a line from the .Pa /etc/ethers file and fills in the passed .Li struct ether_addr -and character buffer with the Ethernet address and host name on the line. It -returns zero if the line was successfully parsed and \-1 if not. +and character buffer with the Ethernet address and host name on the line. +It returns zero if the line was successfully parsed and \-1 if not. The character buffer should be .Dv MAXHOSTNAMELEN characters in size. diff --git a/lib/libc/net/gethostbyname.3 b/lib/libc/net/gethostbyname.3 index aced5ba6167..f1353288c51 100644 --- a/lib/libc/net/gethostbyname.3 +++ b/lib/libc/net/gethostbyname.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: gethostbyname.3,v 1.14 2000/04/15 02:15:22 aaron Exp $ +.\" $OpenBSD: gethostbyname.3,v 1.15 2000/04/18 03:01:31 aaron Exp $ .\" .\" Copyright (c) 1983, 1987, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -166,12 +166,14 @@ connection. .Pp The .Fn herror -function prints an error message describing the failure. If its argument +function prints an error message describing the failure. +If its argument .Fa string is non-null, it is prepended to the message string and separated from it by a colon .Pq Ql \&: -and a space. The error message is printed with a trailing newline. +and a space. +The error message is printed with a trailing newline. The contents of the error message is the same as that returned by .Fn hstrerror with argument diff --git a/lib/libc/net/getifaddrs.3 b/lib/libc/net/getifaddrs.3 index fd36edb3cf6..d69e0f62f53 100644 --- a/lib/libc/net/getifaddrs.3 +++ b/lib/libc/net/getifaddrs.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getifaddrs.3,v 1.5 2000/04/16 13:48:53 itojun Exp $ +.\" $OpenBSD: getifaddrs.3,v 1.6 2000/04/18 03:01:31 aaron Exp $ .\" BSDI getifaddrs.3,v 2.5 2000/02/23 14:51:59 dab Exp .\" .\" Copyright (c) 1995, 1999 @@ -96,7 +96,8 @@ References the destination address on a P2P interface, if one exists, otherwise it is .Dv NULL . .It Fa ifa_data -References address family specific data. For +References address family specific data. +For .Dv AF_LINK addresses it contains a pointer to the .Li struct if_data diff --git a/lib/libc/net/getnameinfo.3 b/lib/libc/net/getnameinfo.3 index 8aee0716026..74690d0e416 100644 --- a/lib/libc/net/getnameinfo.3 +++ b/lib/libc/net/getnameinfo.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getnameinfo.3,v 1.5 2000/01/17 08:20:28 deraadt Exp $ +.\" $OpenBSD: getnameinfo.3,v 1.6 2000/04/18 03:01:31 aaron Exp $ .\" .\" Copyright (c) 1983, 1987, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -102,7 +102,7 @@ or .Fa servlen arguments. Otherwise, the caller must provide buffers large enough to hold the -nodename and the service name, including the terminating null characters. +nodename and the service name, including the terminating null characters. .Pp Unfortunately most systems do not provide constants that specify the maximum size of either a fully-qualified domain name or a service name. diff --git a/lib/libc/net/getnetent.3 b/lib/libc/net/getnetent.3 index 05478afdfbb..fba5505fec0 100644 --- a/lib/libc/net/getnetent.3 +++ b/lib/libc/net/getnetent.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getnetent.3,v 1.8 1999/07/05 04:40:59 aaron Exp $ +.\" $OpenBSD: getnetent.3,v 1.9 2000/04/18 03:01:31 aaron Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -84,8 +84,8 @@ A zero-terminated list of alternate names for the network. The type of the network number returned; currently only .Dv AF_INET . .It Fa n_net -The network number. Network numbers are returned in machine byte -order. +The network number. +Network numbers are returned in machine byte order. .El .Pp The @@ -96,7 +96,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 @@ -146,6 +147,6 @@ functions appeared in .Sh BUGS The data space used by these functions is static; if future use requires the data, it should be copied before any subsequent calls -to these functions overwrite it. Only Internet network numbers -are currently understood. Expecting network numbers to fit in no -more than 32 bits is naive. +to these functions overwrite it. +Only Internet network numbers are currently understood. +Expecting network numbers to fit in no more than 32 bits is naive. diff --git a/lib/libc/net/getprotoent.3 b/lib/libc/net/getprotoent.3 index 01f752ad5ff..e4e7e6ec45c 100644 --- a/lib/libc/net/getprotoent.3 +++ b/lib/libc/net/getprotoent.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getprotoent.3,v 1.5 1999/07/05 04:40:59 aaron Exp $ +.\" $OpenBSD: getprotoent.3,v 1.6 2000/04/18 03:01:32 aaron Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -92,7 +92,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 3ef95fb817a..21591cdcbba 100644 --- a/lib/libc/net/getservent.3 +++ b/lib/libc/net/getservent.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getservent.3,v 1.8 1999/07/05 04:40:59 aaron Exp $ +.\" $OpenBSD: getservent.3,v 1.9 2000/04/18 03:01:32 aaron Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -96,7 +96,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 1e38bdc0560..eb95f6c364a 100644 --- a/lib/libc/net/inet.3 +++ b/lib/libc/net/inet.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: inet.3,v 1.8 1999/07/05 04:40:59 aaron Exp $ +.\" $OpenBSD: inet.3,v 1.9 2000/04/18 03:01:32 aaron Exp $ .\" $NetBSD: inet.3,v 1.7 1997/06/18 02:25:24 lukem Exp $ .\" .\" Copyright (c) 1983, 1990, 1991, 1993 @@ -85,12 +85,13 @@ The function converts a presentation format address (that is, printable form as held in a character string) to network format (usually a .Li struct in_addr -or some other internal binary representation, in network byte order). It -returns 1 if the address was valid for the specified address family, or +or some other internal binary representation, in network byte order). +It returns 1 if the address was valid for the specified address family, or 0 if the address wasn't parseable in the specified address family, or \-1 if some system error occurred (in which case .Va errno -will have been set). This function is presently valid for +will have been set). +This function is presently valid for .Dv AF_INET and .Dv AF_INET6 . @@ -113,7 +114,8 @@ The function converts an address from network format (usually a .Li struct in_addr or some other binary form, in network byte order) to presentation format -(suitable for external display purposes). It returns +(suitable for external display purposes). +It returns .Dv NULL if a system error occurs (in which case, @@ -125,11 +127,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 @@ -155,8 +159,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 -that when an Internet address is viewed as a 32-bit +to the four bytes of an Internet address. +Note that when an Internet address is viewed as a 32-bit integer quantity on a system that uses little-endian byte order (such as the .Tn Intel 386, 486 @@ -214,16 +218,20 @@ every field (except for the case described in 2.). .It Due to the method of allocating certain styles of IPv6 addresses, it will be common for addresses to contain long -strings of zero bits. In order to make writing addresses +strings of zero bits. +In order to make writing addresses .Pp containing zero bits easier a special syntax is available to -compress the zeros. The use of +compress the zeros. +The use of .Dq \&:\&: indicates multiple groups -of 16 bits of zeros. The +of 16 bits of zeros. +The .Dq \&:\&: can only appear once in an -address. The +address. +The .Dq \&:\&: can also be used to compress the leading and/or trailing zeros in an address. .Pp @@ -248,7 +256,8 @@ dealing with a mixed environment of IPv4 and IPv6 nodes is x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values of the six high-order 16-bit pieces of the address, and the 'd's are the decimal values of the four low-order 8-bit pieces of the -address (standard IPv4 representation). Examples: +address (standard IPv4 representation). +Examples: .Bd -literal -offset indent 0:0:0:0:0:0:13.1.68.3 0:0:0:0:0:FFFF:129.144.52.38 @@ -281,10 +290,12 @@ The and .Nm inet_pton functions conforms to the IETF IPng BSD API and address formatting -specifications. Note that +specifications. +Note that .Nm inet_pton -does not accept 1-, 2-, or 3-part dotted addresses; all four parts -must be specified. This is a narrower input set than that accepted by +does not accept 1-, 2-, or 3-part dotted addresses; all four parts +must be specified. +This is a narrower input set than that accepted by .Nm inet_aton . .Sh HISTORY The diff --git a/lib/libc/net/inet6_rthdr_space.3 b/lib/libc/net/inet6_rthdr_space.3 index 439c2703572..6c84bdee78f 100644 --- a/lib/libc/net/inet6_rthdr_space.3 +++ b/lib/libc/net/inet6_rthdr_space.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: inet6_rthdr_space.3,v 1.4 2000/01/18 21:49:01 aaron Exp $ +.\" $OpenBSD: inet6_rthdr_space.3,v 1.5 2000/04/18 03:01:32 aaron Exp $ .\" .\" Copyright (c) 1983, 1987, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -70,8 +70,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: +functions that the application calls to build and examine a Routing header +Four functions build a Routing header: .Bl -hang .It Fn inet6_rthdr_space return #bytes required for ancillary data @@ -107,7 +107,8 @@ containing the specified number of .Fa segments .Pq 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/inet_net.3 b/lib/libc/net/inet_net.3 index 1eb157c429d..12b1a4daa0e 100644 --- a/lib/libc/net/inet_net.3 +++ b/lib/libc/net/inet_net.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: inet_net.3,v 1.4 1999/07/05 04:40:59 aaron Exp $ +.\" $OpenBSD: inet_net.3,v 1.5 2000/04/18 03:01:32 aaron Exp $ .\" $NetBSD: inet_net.3,v 1.1 1997/06/18 02:25:27 lukem Exp $ .\" .\" Copyright (c) 1997 The NetBSD Foundation, Inc. @@ -101,8 +101,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 network number. Note -that when an Internet network number is viewed as a 32-bit +to the four bytes of an Internet network number. +Note that when an Internet network number is viewed as a 32-bit integer quantity on a system that uses little-endian byte order (such as the Intel 386, 486, and Pentium processors) the bytes referred to above appear as diff --git a/lib/libc/net/link_addr.3 b/lib/libc/net/link_addr.3 index b7ada819975..29c2449f77e 100644 --- a/lib/libc/net/link_addr.3 +++ b/lib/libc/net/link_addr.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: link_addr.3,v 1.6 1999/07/05 04:40:59 aaron Exp $ +.\" $OpenBSD: link_addr.3,v 1.7 2000/04/18 03:01:32 aaron Exp $ .\" .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. @@ -108,7 +108,7 @@ The and .Fn link_ntoa functions appeared in -.Bx 4.3 Reno . +.Bx 4.3 Reno . .Sh BUGS The returned values for link_ntoa reside in a static memory area. diff --git a/lib/libc/net/net_addrcmp.3 b/lib/libc/net/net_addrcmp.3 index c29624dc878..8f7de8ef445 100644 --- a/lib/libc/net/net_addrcmp.3 +++ b/lib/libc/net/net_addrcmp.3 @@ -26,7 +26,8 @@ returns 0. .Pp The .Fa sa_len -fields are compared first. If they do not match, +fields are compared first. +If they do not match, .Fn net_addrcmp returns \-1 or 1 if .Li sa1->sa_len @@ -36,7 +37,8 @@ respectively. .Pp Next, the .Fa sa_family -members are compared. If they do not match, +members are compared. +If they do not match, .Fn net_addrcmp returns \-1 or 1 if .Li sa1->sa_family @@ -51,7 +53,8 @@ and fields match, the protocol-specific data (the .Fa sa_data -field) is compared. If there's a match, both +field) is compared. +If there's a match, both .Fa sa1 and .Fa sa2 diff --git a/lib/libc/net/rcmd.3 b/lib/libc/net/rcmd.3 index ea71e40d71b..04230ef7745 100644 --- a/lib/libc/net/rcmd.3 +++ b/lib/libc/net/rcmd.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: rcmd.3,v 1.19 2000/04/15 11:46:02 aaron Exp $ +.\" $OpenBSD: rcmd.3,v 1.20 2000/04/18 03:01:33 aaron Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -65,7 +65,8 @@ The function is used by the superuser to execute a command on a remote machine using an authentication scheme based on reserved -port numbers. If the calling process is not setuid, the +port numbers. +If the calling process is not setuid, the .Ev RSH environment variable is set, and .Fa inport @@ -170,12 +171,12 @@ The and .Fn rresvport_af functions are used to obtain a socket with a privileged -address bound to it. This socket is suitable for use -by +address bound to it. +This socket is suitable for use by .Fn rcmd -and several other functions. Privileged Internet ports are those -in the range 0 to 1023. Only the superuser -is allowed to bind an address of this sort to a socket. +and several other functions. +Privileged Internet ports are those in the range 0 to 1023. +Only the superuser is allowed to bind an address of this sort to a socket. .Fn rresvport and .Fn rresvport_af diff --git a/lib/libc/regex/re_format.7 b/lib/libc/regex/re_format.7 index baf243d7cfa..55a97440dd1 100644 --- a/lib/libc/regex/re_format.7 +++ b/lib/libc/regex/re_format.7 @@ -1,4 +1,4 @@ -.\" $OpenBSD: re_format.7,v 1.8 2000/03/14 21:31:45 aaron Exp $ +.\" $OpenBSD: re_format.7,v 1.9 2000/04/18 03:01:33 aaron Exp $ .\" .\" Copyright (c) 1997, Phillip F Knaack. All rights reserved. .\" @@ -62,7 +62,8 @@ may not be fully portable to other 1003.2 implementations. .Pp A (modern) RE is one\(dg or more non-empty\(dg .Em branches , -separated by `|'. It matches anything that matches one of the branches. +separated by `|'. +It matches anything that matches one of the branches. .Pp A branch is one\(dg or more .Em pieces , diff --git a/lib/libc/rpc/bindresvport.3 b/lib/libc/rpc/bindresvport.3 index 8564bc7bc07..ec1b559c6cf 100644 --- a/lib/libc/rpc/bindresvport.3 +++ b/lib/libc/rpc/bindresvport.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: bindresvport.3,v 1.17 2000/01/26 08:40:15 deraadt Exp $ +.\" $OpenBSD: bindresvport.3,v 1.18 2000/04/18 03:01:33 aaron Exp $ .\" .Dd August 9, 1997 .Dt BINDRESVPORT 3 @@ -38,7 +38,8 @@ If the value of .Va sin->sin_port is non-zero, .Fn bindresvport -attempts to use the specified port. If that fails, it +attempts to use the specified port. +If that fails, it chooses another privileged port number automatically. .Pp It is legal to pass null pointer to diff --git a/lib/libc/rpc/getrpcent.3 b/lib/libc/rpc/getrpcent.3 index 17ae973f9e3..62bbf9783df 100644 --- a/lib/libc/rpc/getrpcent.3 +++ b/lib/libc/rpc/getrpcent.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getrpcent.3,v 1.5 1999/07/09 13:35:22 aaron Exp $ +.\" $OpenBSD: getrpcent.3,v 1.6 2000/04/18 03:01:33 aaron Exp $ .\" .Dd December 14, 1987 .Dt GETRPCENT 3 @@ -54,7 +54,8 @@ The rpc program number for this service. reads the next line of the file, opening the file if necessary. .Pp .Fn setrpcent -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 10c501569e7..cd427bbebaa 100644 --- a/lib/libc/rpc/getrpcport.3 +++ b/lib/libc/rpc/getrpcport.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getrpcport.3,v 1.4 1997/07/21 19:59:40 deraadt Exp $ +.\" $OpenBSD: getrpcport.3,v 1.5 2000/04/18 03:01:34 aaron Exp $ .\" .Dd October 6, 1987 .Dt GETRPCPORT 3 @@ -22,7 +22,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.3 b/lib/libc/rpc/rpc.3 index a37ee5231ad..d9510c88dd1 100644 --- a/lib/libc/rpc/rpc.3 +++ b/lib/libc/rpc/rpc.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: rpc.3,v 1.20 2000/04/15 02:15:23 aaron Exp $ +.\" $OpenBSD: rpc.3,v 1.21 2000/04/18 03:01:34 aaron Exp $ .\" Mostly converted to mandoc by Theo de Raadt, Tue Feb 24 04:04:46 MST 1998 .\" .Dd February 16, 1988 @@ -240,8 +240,8 @@ this routine. is like .Fn callrpc , except the call message is broadcast to all locally -connected broadcast nets. Each time it receives a -response, this routine calls +connected broadcast nets. +Each time it receives a response, this routine calls .Fa eachresult , whose form is: .Bd -literal -offset indent @@ -267,8 +267,8 @@ status. .Pp .Sy Warning: broadcast sockets are limited in size to the -maximum transfer unit of the data link. For Ethernet, -this value is 1500 bytes. +maximum transfer unit of the data link. +For Ethernet, this value is 1500 bytes. .Pp .Fn clnt_call is a macro that calls the remote procedure @@ -294,10 +294,11 @@ is the time allowed for results to come back. .Fn clnt_destroy is a macro that destroys the client's .Tn RPC -handle. Destruction usually involves deallocation -of private data structures, including +handle. +Destruction usually involves deallocation of private data structures, including .Fa clnt -itself. Use of +itself. +Use of .Fa clnt is undefined after calling .Fn clnt_destroy . @@ -312,8 +313,8 @@ is a generic client creation routine. identifies the name of the remote host where the server is located. .Fa proto -indicates which kind of transport protocol to use. The -currently supported values for this field are \(lqudp\(rq +indicates which kind of transport protocol to use. +The currently supported values for this field are \(lqudp\(rq and \(lqtcp\(rq. Default timeouts are set, but can be modified using .Fn clnt_control . @@ -321,7 +322,8 @@ Default timeouts are set, but can be modified using .Sy Warning: Using .Tn UDP -has its shortcomings. Since +has its shortcomings. +Since .Tn UDP-based .Tn RPC messages can only hold up to 8 Kbytes of encoded data, @@ -334,7 +336,8 @@ about a client object. .Fa req indicates the type of operation, and .Fa info -is a pointer to the information. For both +is a pointer to the information. +For both .Tn UDP and .Tn TCP , @@ -377,8 +380,8 @@ is a macro that frees any data allocated by the .Tn RPC/XDR system when it decoded the results of an .Tn RPC -call. The -parameter +call. +The parameter .Fa out is the address of the results, and .Fa outproc @@ -447,7 +450,8 @@ but instead of sending a message to the standard error indicating why an .Tn RPC call failed, return a pointer to a string which contains -the message. Unlike +the message. +Unlike .Fn clnt_perror , it does not append a .Tn NEWLINE @@ -503,7 +507,8 @@ This allows simulation of and acquisition of .Tn RPC overheads, such as round trip times, without any -kernel interference. This routine returns +kernel interference. +This routine returns .Tn NULL if it fails. .Pp @@ -516,15 +521,16 @@ version .Fa versnum ; the client uses .Tn TCP/IP -as a transport. The remote program is located at Internet -address +as a transport. +The remote program is located at Internet address .Fa *addr . If .Fa addr\->sin_port is zero, then it is set to the actual port that the remote program is listening on (the remote .Xr portmap 8 -service is consulted for this information). The parameter +service is consulted for this information). +The parameter .Fa sockp is a socket; if it is .Fa RPC_ANYSOCK , @@ -554,15 +560,16 @@ on .Fa versnum ; the client uses use .Tn UDP/IP -as a transport. The remote program is located at Internet -address +as a transport. +The remote program is located at Internet address .Fa addr . If .Fa addr\->sin_port is zero, then it is set to actual port that the remote program is listening on (the remote .Xr portmap 8 -service is consulted for this information). The parameter +service is consulted for this information). +The parameter .Fa sockp is a socket; if it is .Fa RPC_ANYSOCK , @@ -633,7 +640,8 @@ the .Tn RPC system failured to contact the remote .Xr portmap 8 -service. In the latter case, the global variable +service. +In the latter case, the global variable .Fn rpc_createerr contains the .Tn RPC @@ -655,8 +663,8 @@ The parameter .Fa *portp will be modified to the program's port number if the procedure -succeeds. The definitions of other parameters are discussed -in +succeeds. +The definitions of other parameters are discussed in .Fn callrpc and .Fn clnt_call . @@ -674,7 +682,8 @@ and .Fa port on the machine's .Xr portmap 8 -service. The value of +service. +The value of .Fa protocol is most likely .B @@ -694,15 +703,16 @@ and .Fa ports on the machine's .Xr portmap 8 -service. This routine returns one if it succeeds, zero -otherwise. +service. +This routine returns one if it succeeds, zero otherwise. .Pp .Fn registerrpc will register a procedure .Fa procname with the .Tn RPC -service package. If a request arrives for program +service package. +If a request arrives for program .Fa prognum , version .Fa versnum , @@ -731,7 +741,8 @@ for restrictions. is a global variable whose value is set by any .Tn RPC client creation routine -that does not succeed. Use the routine +that does not succeed. +Use the routine .Fn clnt_pcreateerror to print the reason why. .Pp @@ -743,7 +754,8 @@ service transport handle, Destruction usually involves deallocation of private data structures, including .Fa xprt -itself. Use of +itself. +Use of .Fa xprt is undefined after calling this routine. .Pp @@ -798,8 +810,8 @@ descriptors. .Fa svc_fds is similar to .Fa svc_fedset , -but limited to 32 descriptors. This -interface is obsoleted by +but limited to 32 descriptors. +This interface is obsoleted by .Fa svc_fdset . .Pp .Fn svc_freeargs @@ -859,7 +871,8 @@ have been serviced. .Fn svc_getreq is similar to .Fa svc_getreqset , -but limited to 32 descriptors. This interface is obsoleted by +but limited to 32 descriptors. +This interface is obsoleted by .Fa svc_getreqset . .Pp .Fn svc_register @@ -873,7 +886,8 @@ If .Fa protocol is zero, the service is not registered with the .Xr portmap 8 -service. If +service. +If .Fa protocol is non-zero, then a mapping of the triple .Fa [ prognum , versnum , protocol] @@ -899,12 +913,14 @@ The routine returns one if it succeeds, and zero otherwise. .Pp .Fn svc_run -never returns. It waits for +never returns. +It waits for .Tn RPC requests to arrive, and calls the appropriate service procedure using .Fn svc_getreq -when one arrives. This procedure is usually waiting for a +when one arrives. +This procedure is usually waiting for a .Xr select 2 system call to return. .Pp @@ -912,7 +928,8 @@ system call to return. is called by an .Tn RPC service's dispatch routine to send the results of a -remote procedure call. The parameter +remote procedure call. +The parameter .Fa xprt is the request's associated transport handle; .Fa outproc @@ -936,7 +953,8 @@ a remote procedure call due to an authentication error. .Pp .Fn svcerr_decode is called by a service dispatch routine that cannot successfully -decode its parameters. See also +decode its parameters. +See also .Fn svc_getargs . .Pp .Fn svcerr_noproc @@ -946,13 +964,15 @@ the procedure number that the caller requests. .Fn svcerr_noprog is called when the desired program is not registered with the .Tn RPC -package. Service implementors usually do not need this routine. +package. +Service implementors usually do not need this routine. .Pp .Fn svcerr_progvers is called when the desired version of a program is not registered with the .Tn RPC -package. Service implementors usually do not need this routine. +package. +Service implementors usually do not need this routine. .Pp .Fn svcerr_systemerr is called by a service dispatch routine when it detects a system @@ -964,15 +984,15 @@ it may call this routine. .Fn svcerr_weakauth is called by a service dispatch routine that refuses to perform a remote procedure call due to insufficient -authentication parameters. The routine calls +authentication parameters. +The routine calls .Fa "svcerr_auth(xprt, AUTH_TOOWEAK)" . .Pp .Fn svcraw_create is a routine which creates a toy .Tn RPC -service transport, to which it returns a pointer. The -transport -is really a buffer within the process's address space, +service transport, to which it returns a pointer. +The transport is really a buffer within the process's address space, so the corresponding .Tn RPC client should live in the same @@ -1001,15 +1021,16 @@ which may be in which case a new socket is created. If the socket is not bound to a local .Tn TCP -port, then this routine binds it to an arbitrary port. Upon -completion, +port, then this routine binds it to an arbitrary port. +Upon completion, .Fa xprt\->xp_sock is the transport's socket descriptor, and .Fa xprt\->xp_port is the transport's port number. This routine returns .Tn NULL -if it fails. Since +if it fails. +Since .Tn TCP-based .Tn RPC uses buffered @@ -1018,16 +1039,15 @@ users may specify the size of buffers; values of zero choose suitable defaults. .Pp .Fn svcfd_create -will create a service on top of any open descriptor. Typically, -this -descriptor is a connected socket for a stream protocol such +will create a service on top of any open descriptor. +Typically, this descriptor is a connected socket for a stream protocol such as .Tn TCP . .Fa sendsize and .Fa recvsize -indicate sizes for the send and receive buffers. If they are -zero, a reasonable default is chosen. +indicate sizes for the send and receive buffers. +If they are zero, a reasonable default is chosen. .Pp .Fn svcudp_bufcreate is a routine which creates a @@ -1041,8 +1061,8 @@ which may be in which case a new socket is created. If the socket is not bound to a local .Tn UDP -port, then this routine binds it to an arbitrary port. Upon -completion, +port, then this routine binds it to an arbitrary port. +Upon completion, .Fa xprt\->xp_sock is the transport's socket descriptor, and .Fa xprt\->xp_port @@ -1060,9 +1080,8 @@ messages. .Fn xdr_accepted_reply is used for encoding .Tn RPC -reply messages. This routine is useful for users who -wish to generate -RPC-style +reply messages. +This routine is useful for users who wish to generate RPC-style messages without using the .Tn RPC package. @@ -1070,7 +1089,8 @@ package. .Fn xdr_authunix_parms is used for describing .Tn UNIX -credentials. This routine is useful for users +credentials. +This routine is useful for users who wish to generate these credentials without using the .Tn RPC authentication package. @@ -1138,7 +1158,8 @@ style messages without using the package. .Pp .Fn xprt_register -is used to register transport handles. After +is used to register transport handles. +After .Tn RPC service transport handles are created, they should register themselves with the @@ -1149,7 +1170,8 @@ This routine modifies the global variable Service implementors usually do not need this routine. .Pp .Fn xprt_unregister -is used to unregister a transport handle. Before an +is used to unregister a transport handle. +Before an .Tn RPC service transport handle is destroyed, it should unregister itself with the diff --git a/lib/libc/rpc/rpcauth.3 b/lib/libc/rpc/rpcauth.3 index 01c859454fd..ba53feae571 100644 --- a/lib/libc/rpc/rpcauth.3 +++ b/lib/libc/rpc/rpcauth.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: rpcauth.3,v 1.6 1999/07/02 20:58:00 aaron Exp $ +.\" $OpenBSD: rpcauth.3,v 1.7 2000/04/18 03:01:34 aaron Exp $ .\" Mostly converted to mandoc by Theo de Raadt, Tue Feb 24 04:04:46 MST 1998 .\" .Dd February 16, 1988 @@ -28,8 +28,8 @@ RPC functions described in .Fn auth_destroy is a macro that destroys the authentication information associated with .Fa auth . -Destruction usually involves deallocation of private data -structures. The use of +Destruction usually involves deallocation of private data structures. +The use of .Fa auth is undefined after calling .Fn auth_destroy . @@ -38,8 +38,8 @@ is undefined after calling creates and returns an .Tn RPC authentication handle that passes nonusable authentication -information with each remote procedure call. This is the -default authentication used by +information with each remote procedure call. +This is the default authentication used by .Tn RPC . .Pp .Fn authunix_create diff --git a/lib/libc/rpc/xdr.3 b/lib/libc/rpc/xdr.3 index 570cfe00e0b..429bb766f76 100644 --- a/lib/libc/rpc/xdr.3 +++ b/lib/libc/rpc/xdr.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: xdr.3,v 1.12 1999/07/09 13:35:22 aaron Exp $ +.\" $OpenBSD: xdr.3,v 1.13 2000/04/18 03:01:34 aaron Exp $ .\" Mostly converted to mandoc by Theo de Raadt, Tue Feb 24 04:04:46 MST 1998 .\" .Dd February 16, 1988 @@ -116,7 +116,8 @@ routines. .Pp .Fn xdr_array is a filter primitive that translates between variable-length arrays -and their corresponding external representations. The parameter +and their corresponding external representations. +The parameter .Fa arrp is the address of the pointer to the array, while .Fa sizep @@ -136,7 +137,8 @@ This routine returns one if it succeeds, zero otherwise. .Pp .Fn xdr_bool is a filter primitive that translates between booleans (C integers) -and their external representations. When encoding data, this +and their external representations. +When encoding data, this filter produces values of either one or zero. This routine returns one if it succeeds, zero otherwise. .Pp @@ -145,8 +147,8 @@ is a filter primitive that translates between counted byte strings and their external representations. The parameter .Fa sp -is the address of the string pointer. The length of the -string is located at address +is the address of the string pointer. +The length of the string is located at address .Fa sizep ; strings cannot be longer than .Fa maxsize . @@ -156,9 +158,8 @@ This routine returns one if it succeeds, zero otherwise. is a filter primitive that translates between C characters and their external representations. This routine returns one if it succeeds, zero otherwise. -Note: encoded characters are not packed, and occupy 4 bytes -each. For arrays of characters, it is worthwhile to -consider +Note: encoded characters are not packed, and occupy 4 bytes each. +For arrays of characters, it is worthwhile to consider .Fn xdr_bytes , .Fn xdr_opaque , or @@ -170,7 +171,8 @@ is a macro that invokes the destroy routine associated with the stream .Fa xdrs . Destruction usually involves freeing private data structures -associated with the stream. Using +associated with the stream. +Using .Fa xdrs after invoking .Fn xdr_destroy @@ -195,11 +197,13 @@ type and its external representations. This routine returns one if it succeeds, zero otherwise. .Pp .Fn xdr_free -is a generic freeing routine. The first argument is the +is a generic freeing routine. +The first argument is the .Tn XDR -routine for the object being freed. The second argument -is a pointer to the object itself. Note: the pointer passed -to this routine is +routine for the object being freed. +The second argument +is a pointer to the object itself. +Note: the pointer passed to this routine is .Fa not freed, but what it points to is freed (recursively). .Pp @@ -259,7 +263,8 @@ a chunk of memory at location .Fa addr whose length is no more than .Fa size -bytes long. The +bytes long. +The .Fa op determines the direction of the .Tn XDR @@ -288,7 +293,8 @@ execpt that it serializes .Dv NULL pointers, whereas .Fn xdr_reference -does not. Thus, +does not. +Thus, .Fn xdr_pointer can represent recursive data structures, such as binary trees or @@ -302,17 +308,18 @@ stream object pointed to by The stream's data is written to a buffer of size .Fa sendsize ; a value of zero indicates the system should use a suitable -default. The stream's data is read from a buffer of size +default. +The stream's data is read from a buffer of size .Fa recvsize ; it too can be set to a suitable default by passing a zero value. When a stream's output buffer is full, .Fn (*writeit) -is called. Similarly, when a stream's input buffer is empty, +is called. +Similarly, when a stream's input buffer is empty, .Fn (*readit) -is called. The behavior of these two routines is similar to -the -system calls +is called. +The behavior of these two routines is similar to the system calls .Fn read and .Fn write , @@ -337,7 +344,8 @@ streams created by The data in the output buffer is marked as a completed record, and the output buffer is optionally written out if .Fa sendnow -is non-zero. This routine returns one if it succeeds, zero otherwise. +is non-zero. +This routine returns one if it succeeds, zero otherwise. .Pp .Fn xdrrec_eof is a routine which can be invoked only on @@ -374,7 +382,8 @@ between its C form and its external representation. This routine returns one if it succeeds, zero otherwise. Warning: this routine does not understand .Dv NULL -pointers. Use +pointers. +Use .Fn xdr_pointer instead. .Pp @@ -432,7 +441,8 @@ stream, but never .Pp .Fn xdr_string is a filter primitive that translates between C strings and their -corresponding external representations. Strings cannot be longer than +corresponding external representations. +Strings cannot be longer than .Fa maxsize . Note: .Fa sp @@ -466,24 +476,27 @@ This routine returns one if it succeeds, zero otherwise. .Fn xdr_union is a filter primitive that translates between a discriminated C .Li union -and its corresponding external representation. It first -translates the discriminant of the union located at +and its corresponding external representation. +It first translates the discriminant of the union located at .Fa dscmp . This discriminant is always an .Li enum_t . Next the union located at .Fa unp -is translated. The parameter +is translated. +The parameter .Fa choices is a pointer to an array of .Li struct xdr_discrim -structures. Each structure contains an ordered pair of +structures. +Each structure contains an ordered pair of .Ft [ value , proc ]. If the union's discriminant is equal to the associated .Fa value , then the .Fa proc -is called to translate the union. The end of the +is called to translate the union. +The end of the .Li struct xdr_discrim structure array is denoted by a routine of value .Dv NULL . @@ -497,22 +510,25 @@ Returns one if it succeeds, zero otherwise. .Pp .Fn xdr_vector is a filter primitive that translates between fixed-length arrays -and their corresponding external representations. The parameter +and their corresponding external representations. +The parameter .Fa arrp is the address of the pointer to the array, while .Fa size -is the element count of the array. The parameter +is the element count of the array. +The parameter .Fa elsize is the size of each of the array's elements, and .Fa elproc is an .Tn XDR filter that translates between the array elements' C form, and their -external representation. This routine returns one if it succeeds, zero -otherwise. +external representation. +This routine returns one if it succeeds, zero otherwise. .Pp .Fn xdr_void -is a routine which always returns one. It may be passed to +is a routine which always returns one. +It may be passed to .Tn RPC routines that require a function parameter, but where nothing is to be done. .Pp diff --git a/lib/libc/stdio/fgets.3 b/lib/libc/stdio/fgets.3 index f27c4f09c3a..a37f92f02c7 100644 --- a/lib/libc/stdio/fgets.3 +++ b/lib/libc/stdio/fgets.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: fgets.3,v 1.9 2000/02/19 22:23:48 ericj Exp $ +.\" $OpenBSD: fgets.3,v 1.10 2000/04/18 03:01:34 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -146,7 +146,8 @@ be false in two other cases: .It If the last line in a file does not contain a newline, the string returned by .Fn fgets -will not contain a newline either. Thus +will not contain a newline either. +Thus .Fn strchr will return .Dv NULL diff --git a/lib/libc/stdio/mktemp.3 b/lib/libc/stdio/mktemp.3 index 91b0852dce2..2a26ee04fec 100644 --- a/lib/libc/stdio/mktemp.3 +++ b/lib/libc/stdio/mktemp.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: mktemp.3,v 1.20 2000/01/27 04:42:48 deraadt Exp $ +.\" $OpenBSD: mktemp.3,v 1.21 2000/04/18 03:01:34 aaron Exp $ .\" .\" Copyright (c) 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -98,8 +98,8 @@ The .Fn mkstemps function acts the same as .Fn mkstemp , -except it permits a suffix to exist in the template. The template -should be of the form +except it permits a suffix to exist in the template. +The template should be of the form .Pa /tmp/tmpXXXXXXsuffix . .Fn mkstemps is told the length of the suffix string, i.e., strlen("suffix"); diff --git a/lib/libc/stdio/printf.3 b/lib/libc/stdio/printf.3 index d76e8327b37..66c0aa25ea6 100644 --- a/lib/libc/stdio/printf.3 +++ b/lib/libc/stdio/printf.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: printf.3,v 1.24 2000/04/15 02:15:24 aaron Exp $ +.\" $OpenBSD: printf.3,v 1.25 2000/04/18 03:01:35 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -301,8 +301,9 @@ the field width. An optional precision, in the form of a period .Sq Cm \&. followed by an -optional digit string. If the digit string is omitted, the precision -is taken as zero. This gives the minimum number of digits to appear for +optional digit string. +If the digit string is omitted, the precision is taken as zero. +This gives the minimum number of digits to appear for .Cm d , .Cm i , .Cm o , @@ -438,7 +439,8 @@ or unsigned hexadecimal .Pf ( Cm x and .Cm X ) -notation. The letters +notation. +The letters .Cm abcdef are used for .Cm x @@ -554,8 +556,9 @@ No argument is converted. .It Cm % A .Ql % -is written. No argument is converted. The complete conversion specification -is +is written. +No argument is converted. +The complete conversion specification is .Ql %% . .El .Pp @@ -632,7 +635,8 @@ The functions .Fn asprintf and .Fn vasprintf -first appeared in the GNU C library. This implementation first appeared in +first appeared in the GNU C library. +This implementation first appeared in .Ox 2.3 . .Sh CAVEATS The conversion formats @@ -681,13 +685,14 @@ interface is not portable. Never print a user-supplied string directly as a format without using .Cm %s , as an attacker can put format specifiers in that string to mangle -your stack. Be sure to use the proper secure idiom: +your stack. +Be sure to use the proper secure idiom: .Bd -literal -offset indent snprintf(buffer, sizeof(buffer), "%s", string) .Ed .Pp -There is no way for printf to know the size of each argument passed. If -you use positional arguments you must ensure that all parameters, up to the -last positionally specified parameter, are used in the format string. This -allows for the format string to be parsed for this information. Failure -to do this will mean your code is non-portable and liable to fail. +There is no way for printf to know the size of each argument passed. +If you use positional arguments you must ensure that all parameters, up to the +last positionally specified parameter, are used in the format string. +This allows for the format string to be parsed for this information. +Failure to do this will mean your code is non-portable and liable to fail. diff --git a/lib/libc/stdio/putc.3 b/lib/libc/stdio/putc.3 index 0c28835d0f7..d6850646fc3 100644 --- a/lib/libc/stdio/putc.3 +++ b/lib/libc/stdio/putc.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: putc.3,v 1.3 1999/02/27 21:55:47 deraadt Exp $ +.\" $OpenBSD: putc.3,v 1.4 2000/04/18 03:01:35 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -67,7 +67,8 @@ to the output stream pointed to by .Fn putc acts essentially identically to .Fn fputc , -but is a macro that expands in-line. It may evaluate +but is a macro that expands in-line. +It may evaluate .Fa stream more than once, so arguments given to .Fn putc diff --git a/lib/libc/stdio/scanf.3 b/lib/libc/stdio/scanf.3 index e4603b2e4cf..d91cdeed345 100644 --- a/lib/libc/stdio/scanf.3 +++ b/lib/libc/stdio/scanf.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: scanf.3,v 1.5 2000/03/04 22:19:31 aaron Exp $ +.\" $OpenBSD: scanf.3,v 1.6 2000/04/18 03:01:35 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -145,7 +145,7 @@ Indicates that the conversion will be one of or .Cm n and the next pointer is a pointer to a -.Em short int +.Em short int (rather than .Em int ) . .It Cm l @@ -154,7 +154,7 @@ Indicates either that the conversion will be one of or .Cm n and the next pointer is a pointer to a -.Em long int +.Em long int (rather than .Em int ) , or that the conversion will be one of @@ -368,8 +368,8 @@ conversion. The value .Dv EOF is returned if an input failure occurs before any conversion such as an -end-of-file occurs. If an error or end-of-file occurs after conversion -has begun, +end-of-file occurs. +If an error or end-of-file occurs after conversion has begun, the number of conversions which were successfully completed is returned. .Sh SEE ALSO .Xr getc 3 , diff --git a/lib/libc/stdio/stdio.3 b/lib/libc/stdio/stdio.3 index b49d87d61e5..401a7f7c04a 100644 --- a/lib/libc/stdio/stdio.3 +++ b/lib/libc/stdio/stdio.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: stdio.3,v 1.11 2000/04/15 02:15:24 aaron Exp $ +.\" $OpenBSD: stdio.3,v 1.12 2000/04/18 03:01:35 aaron Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -51,22 +51,25 @@ interface. Input and output is mapped into logical data streams and the physical .Tn I/O -characteristics are concealed. The functions and macros are listed +characteristics are concealed. +The functions and macros are listed below; more information is available from the individual man pages. .Pp A stream is associated with an external file (which may be a physical device) by .Em opening -a file, which may involve creating a new file. Creating an -existing file causes its former contents to be discarded. +a file, which may involve creating a new file. +Creating an existing file causes its former contents to be discarded. If a file can support positioning requests (such as a disk file, as opposed to a terminal) then a .Em file position indicator associated with the stream is positioned at the start of the file (byte -zero), unless the file is opened with append mode. If append mode +zero), unless the file is opened with append mode. +If append mode is used, the position indicator will be placed at the end-of-file. The position indicator is maintained by subsequent reads, writes -and positioning requests. All input occurs as if the characters +and positioning requests. +All input occurs as if the characters were read by successive calls to the .Xr fgetc 3 function; all output takes place as if all characters were @@ -85,15 +88,17 @@ 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 -the +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 -of program termination may not close files properly and hence -buffered output may be lost. In particular, +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, .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. |