diff options
| author |   aaron <aaron@openbsd.org> | 2000-10-18 05:12:06 +0000 |
|---|---|---|
| committer | aaron <aaron@openbsd.org> | 2000-10-18 05:12:06 +0000 |
| commit | ea418ffe85da8239e30bb1c3e28466cf6b8f685e (patch) | |
| tree | 01651b197bba18ec88ec6a378fec58207d2f3632 /lib/libc | |
| parent | get the bounds checking right for the data used in copyout() in several (diff) | |
| download | wireguard-openbsd-ea418ffe85da8239e30bb1c3e28466cf6b8f685e.tar.xz wireguard-openbsd-ea418ffe85da8239e30bb1c3e28466cf6b8f685e.zip | |
Another round of man page cleanup, this time to remove more hard sentence
breaks and getting rid of short lines, making these files easier to work with.
Diffstat (limited to 'lib/libc')
93 files changed, 972 insertions, 1007 deletions
diff --git a/lib/libc/db/man/ndbm.3 b/lib/libc/db/man/ndbm.3 index fe1f0e9e0a9..bd53b8464ac 100644 --- a/lib/libc/db/man/ndbm.3 +++ b/lib/libc/db/man/ndbm.3 @@ -1,5 +1,5 @@ .\" David Leonard, 1998. Placed in the public domain. -.\" $OpenBSD: ndbm.3,v 1.10 2000/04/18 02:31:36 aaron Exp $ +.\" $OpenBSD: ndbm.3,v 1.11 2000/10/18 05:12:07 aaron Exp $ .Dd May 13, 1998 .Dt NDBM 3 .Os @@ -87,11 +87,11 @@ When storing, the parameter must be one of: .Bl -tag -width DBM_REPLACE -offset indent .It Dv DBM_INSERT -Only insert new keys into the database. Existing key/content pairs -are untouched. +Only insert new keys into the database. +Existing key/content pairs are untouched. .It Dv DBM_REPLACE -Replace any existing entry with the same key. Any previously -stored records with the same key are lost. +Replace any existing entry with the same key. +Any previously stored records with the same key are lost. .El .Pp The diff --git a/lib/libc/gen/login_cap.3 b/lib/libc/gen/login_cap.3 index b2e2c18c917..8c6889d1365 100644 --- a/lib/libc/gen/login_cap.3 +++ b/lib/libc/gen/login_cap.3 @@ -29,7 +29,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $OpenBSD: login_cap.3,v 1.2 2000/08/20 19:05:37 millert Exp $ +.\" $OpenBSD: login_cap.3,v 1.3 2000/10/18 05:12:07 aaron Exp $ .\" BSDI $From: login_cap.3,v 1.4 1997/11/07 16:22:27 jch Exp $ .\" .Dd July 16, 1996 @@ -117,7 +117,8 @@ The argument refers to the type of authentication being performed. This is used to override the standard .Li auth -entry in the database. By convention this should be of the form "auth-type". +entry in the database. +By convention this should be of the form "auth-type". Future releases may remove the requirement for the "auth-" prefix and add it if it is missing. If @@ -138,8 +139,8 @@ and .Fn login_getcaptime functions all query the database entry for a field named .Ar cap . -If the field is found, its value is returned. If the field is not -found, the value specified by +If the field is found, its value is returned. +If the field is not found, the value specified by .Ar def is returned. If an error is encountered while trying to find the field, @@ -150,7 +151,8 @@ See for a discussion of the various textual forms the value may take. The .Fn login_getcapbool -function is slightly different. It returns +function is slightly different. +It returns .Ar def if no capabilities were found for this class (typically meaning that the default class was used and the @@ -184,7 +186,8 @@ Only the .Nm LOGIN_SETRESOURCES , and .Nm LOGIN_SETUMASK -bits are used. (See +bits are used. +(See .Fn setusercontext below). It returns 0 on success and -1 on failure. @@ -270,8 +273,8 @@ is allocated via when the specified capability is present and thus it is the responsibility of the caller to .Fn free -this space. However, if the the capability was not found or an error -occurred and +this space. +However, if the the capability was not found or an error occurred and .Fa def or .Fa err diff --git a/lib/libc/gen/nlist.3 b/lib/libc/gen/nlist.3 index dc0d7567fd5..7f21bba124e 100644 --- a/lib/libc/gen/nlist.3 +++ b/lib/libc/gen/nlist.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: nlist.3,v 1.7 1999/09/26 00:04:07 aaron Exp $ +.\" $OpenBSD: nlist.3,v 1.8 2000/10/18 05:12:07 aaron Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -44,9 +44,9 @@ .Sh DESCRIPTION The .Fn nlist -function -retrieves name list entries from the symbol table of an -executable file. (See +function retrieves name list entries from the symbol table of an +executable file. +(See .Xr a.out 5 . ) The argument .Fa \&nl diff --git a/lib/libc/gen/sysctl.3 b/lib/libc/gen/sysctl.3 index cb4e146eea3..59b46b8c678 100644 --- a/lib/libc/gen/sysctl.3 +++ b/lib/libc/gen/sysctl.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sysctl.3,v 1.55 2000/10/14 13:04:25 deraadt Exp $ +.\" $OpenBSD: sysctl.3,v 1.56 2000/10/18 05:12:07 aaron Exp $ .\" .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. @@ -210,7 +210,7 @@ and bits to be cleared. As detailed in .Xr securelevel 7 , -this variable may not be changed if the securelevel is > 0. +this variable may not be changed if the securelevel is > 0. .El .Ss CTL_HW The string and integer information available for the @@ -1168,8 +1168,9 @@ Return the system wide virtual memory statistics. The returned data consists of a .Li struct vmtotal . .It Dv VM_SWAPENCRYPT -Contains statistics about swap encryption. The string and integer -information available for the third level is detailed below. +Contains statistics about swap encryption. +The string and integer information available for the third level is +detailed below. .Bl -column "Third level nameXXXXXX" "struct loadavgXXX" -offset indent .It Sy Third level name Type Changeable .It Dv SWPENC_ENABLE No " integer yes" @@ -1181,20 +1182,20 @@ information available for the third level is detailed below. .It Dv SWPENC_ENABLE Set to 1 to enable swap encryption for all processes. A 0 disables swap encryption. -Pages still on swap receive a grandfather clause. Turning this -option on does not affect legacy swap data already on the disk, +Pages still on swap receive a grandfather clause. +Turning this option on does not affect legacy swap data already on the disk, but all newly written data will be encrypted. When swap encryption is turned on, automatic .Xr crash 8 dumps are disabled. .It Dv SWPENC_CREATED -The number of encryption keys that have been randomly created. The -swap partition is divided into sections of normally 512KB. Each section -has its own encryption key. +The number of encryption keys that have been randomly created. +The swap partition is divided into sections of normally 512KB. +Each section has its own encryption key. .It Dv SWPENC_DELETED The number of encryption keys that have been deleted, thus effectivly -erasing the data that has been encrypted with them. Encryption -keys are deleted when their reference counter reaches zero. +erasing the data that has been encrypted with them. +Encryption keys are deleted when their reference counter reaches zero. .El .El .Ss CTL_VFS diff --git a/lib/libc/net/ipx.3 b/lib/libc/net/ipx.3 index c1a52e14d51..c4c94943729 100644 --- a/lib/libc/net/ipx.3 +++ b/lib/libc/net/ipx.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ipx.3,v 1.6 2000/09/22 14:47:33 millert Exp $ +.\" $OpenBSD: ipx.3,v 1.7 2000/10/18 05:12:07 aaron Exp $ .\" .\" Copyright (c) 1986, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -103,7 +103,8 @@ It is interpreted as octal is there is a leading and there are no super-octal digits. Otherwise, it is converted as a decimal number. .Sh RETURN VALUES -None. (See +None. +(See .Sx BUGS . ) .Sh SEE ALSO .Xr ns 4 , diff --git a/lib/libc/net/ns.3 b/lib/libc/net/ns.3 index 24e69c8388e..2f695af090b 100644 --- a/lib/libc/net/ns.3 +++ b/lib/libc/net/ns.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ns.3,v 1.5 1999/07/05 04:41:00 aaron Exp $ +.\" $OpenBSD: ns.3,v 1.6 2000/10/18 05:12:07 aaron Exp $ .\" .\" Copyright (c) 1986, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -108,7 +108,8 @@ It is interpreted as octal is there is a leading and there are no super-octal digits. Otherwise, it is converted as a decimal number. .Sh RETURN VALUES -None. (See +None. +(See .Sx BUGS . ) .Sh SEE ALSO .Xr hosts 5 , diff --git a/lib/libc/string/strlcpy.3 b/lib/libc/string/strlcpy.3 index 5acbcce148f..ee7864db082 100644 --- a/lib/libc/string/strlcpy.3 +++ b/lib/libc/string/strlcpy.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: strlcpy.3,v 1.8 2000/06/01 04:02:05 millert Exp $ +.\" $OpenBSD: strlcpy.3,v 1.9 2000/10/18 05:12:07 aaron Exp $ .\" .\" Copyright (c) 1998, 2000 Todd C. Miller <Todd.Miller@courtesan.com> .\" All rights reserved. @@ -68,7 +68,8 @@ and .Fn strlcat only operate on true .Dq C -strings. This means that for +strings. +This means that for .Fn strlcpy .Fa src must be NUL-terminated and for diff --git a/lib/libc/sys/_exit.2 b/lib/libc/sys/_exit.2 index a59cf5f27d2..78902b87c66 100644 --- a/lib/libc/sys/_exit.2 +++ b/lib/libc/sys/_exit.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: _exit.2,v 1.9 1999/09/22 22:03:59 aaron Exp $ +.\" $OpenBSD: _exit.2,v 1.10 2000/10/18 05:12:08 aaron Exp $ .\" $NetBSD: _exit.2,v 1.6 1995/02/27 12:31:34 cgd Exp $ .\" .\" Copyright (c) 1980, 1993 @@ -47,8 +47,7 @@ .Sh DESCRIPTION The .Fn _exit -function -terminates a process with the following consequences: +function terminates a process with the following consequences: .Bl -bullet .It All open file descriptors in the calling process are closed. @@ -57,18 +56,15 @@ A process in this state may not be killed, as it is already dying. .It If the parent process of the calling process has an outstanding .Xr wait 2 -call -or catches the +call or catches the .Dv SIGCHLD -signal, -it is notified of the calling process's termination and +signal, it is notified of the calling process's termination and .Fa status is set as defined by .Xr wait 2 . .It The parent process ID of all of the calling process's existing child -processes are set to 1; the initialization process -(see the +processes are set to 1; the initialization process (see the .Sx DEFINITIONS section of .Xr intro 2 ) @@ -80,8 +76,7 @@ of the group have now exited; see .Sx Orphaned Process Group in .Xr intro 2 ) , -and if any member of the orphaned group is stopped, -the +and if any member of the orphaned group is stopped, the .Dv SIGHUP and .Dv SIGCONT diff --git a/lib/libc/sys/accept.2 b/lib/libc/sys/accept.2 index 5c02f84dc09..f0fbab7ee0f 100644 --- a/lib/libc/sys/accept.2 +++ b/lib/libc/sys/accept.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: accept.2,v 1.9 1999/08/15 13:14:11 deraadt Exp $ +.\" $OpenBSD: accept.2,v 1.10 2000/10/18 05:12:08 aaron Exp $ .\" $NetBSD: accept.2,v 1.7 1996/01/31 20:14:42 mycroft Exp $ .\" .\" Copyright (c) 1983, 1990, 1991, 1993 @@ -56,32 +56,27 @@ and is listening for connections after a .Xr listen 2 . The .Fn accept -argument -extracts the first connection request -on the queue of pending connections, creates -a new socket with the same properties of -.Fa s -and allocates a new file descriptor -for the socket. If no pending connections are -present on the queue, and the socket is not marked -as non-blocking, +argument extracts the first connection request on the queue of pending +connections, creates a new socket with the same properties of +.Fa s , +and allocates a new file descriptor for the socket. +If no pending connections are present on the queue, +and the socket is not marked as non-blocking, .Fn accept blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue, .Fn accept returns an error as described below. -The accepted socket -may not be used -to accept more connections. The original socket +The accepted socket may not be used to accept more connections. +The original socket .Fa s remains open. .Pp The argument .Fa addr -is a result parameter that is filled in with -the address of the connecting entity, -as known to the communications layer. +is a result parameter that is filled in with the address of the connecting +entity as known to the communications layer. The exact format of the .Fa addr parameter is determined by the domain in which the communication @@ -93,8 +88,7 @@ amount of space pointed to by .Fa addr ; on return it will contain the actual length (in bytes) of the address returned. -This call -is used with connection-based socket types, currently with +This call is used with connection-based socket types, currently with .Dv SOCK_STREAM . .Pp It is possible to @@ -105,18 +99,15 @@ a socket for the purposes of doing an .Fn accept by selecting it for read. .Pp -For certain protocols which require an explicit confirmation, -such as +For certain protocols which require an explicit confirmation, such as .Tn ISO or .Tn DATAKIT , .Fn accept -can be thought of -as merely dequeuing the next connection +can be thought of as merely dequeuing the next connection request and not implying confirmation. -Confirmation can be implied by a normal read or write on the new -file descriptor, and rejection can be implied by closing the -new socket. +Confirmation can be implied by a normal read or write on the new file +descriptor, and rejection can be implied by closing the new socket. .Pp One can obtain user connection request data without confirming the connection by issuing a @@ -131,12 +122,12 @@ request. Similarly, one can provide user connection rejection information by issuing a .Xr sendmsg 2 -call with providing only the control information, -or by calling +call with providing only the control information, or by calling .Xr setsockopt 2 . .Sh RETURN VALUES -The call returns \-1 on error. If it succeeds, it returns a non-negative -integer that is a descriptor for the accepted socket. +The call returns \-1 on error. +If it succeeds, it returns a non-negative integer that is a descriptor +for the accepted socket. .Sh ERRORS The .Fn accept @@ -156,8 +147,7 @@ has not yet been called). .It Bq Er EFAULT The .Fa addr -parameter is not in a writable part of the -user address space. +parameter is not in a writable part of the user address space. .It Bq Er EWOULDBLOCK The socket is marked non-blocking and no connections are present to be accepted. diff --git a/lib/libc/sys/access.2 b/lib/libc/sys/access.2 index 7f92ae7f7a7..bd84c3892ed 100644 --- a/lib/libc/sys/access.2 +++ b/lib/libc/sys/access.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: access.2,v 1.7 1999/06/29 14:09:49 aaron Exp $ +.\" $OpenBSD: access.2,v 1.8 2000/10/18 05:12:08 aaron Exp $ .\" $NetBSD: access.2,v 1.7 1995/02/27 12:31:44 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -47,8 +47,7 @@ .Sh DESCRIPTION The .Fn access -function checks the accessibility of the -file named by +function checks the accessibility of the file named by .Fa path for the access permissions indicated by .Fa mode . @@ -84,9 +83,8 @@ and .Sh RETURN VALUES If .Fa path -cannot be found or if any of the desired access modes would -not be granted, then a \-1 value is returned; otherwise -a 0 value is returned. +cannot be found or if any of the desired access modes would not be granted, +then a \-1 value is returned; otherwise a 0 value is returned. .Sh ERRORS Access to the file is denied if: .Bl -tag -width Er @@ -108,13 +106,15 @@ Write access is requested for a file on a read-only file system. Write access is requested for a pure procedure (shared text) file presently being executed. .It Bq Er EACCES -Permission bits of the file mode do not permit the requested -access, or search permission is denied on a component of the -path prefix. The owner of a file has permission checked with -respect to the ``owner'' read, write, and execute mode bits, -members of the file's group other than the owner have permission -checked with respect to the ``group'' mode bits, and all -others have permissions checked with respect to the ``other'' +Permission bits of the file mode do not permit the requested access, +or search permission is denied on a component of the path prefix. +The owner of a file has permission checked with respect to the +.Dq owner +read, write, and execute mode bits, members of the file's group other +than the owner have permission checked with respect to the +.Dq group +mode bits, and all others have permissions checked with respect to the +.Dq other mode bits. .It Bq Er EFAULT .Fa path @@ -133,7 +133,6 @@ The .Fn access function conforms to .St -p1003.1-90 . -.Sh CAVEAT +.Sh CAVEATS .Fn access -is a potential security hole and -should never be used. +is a potential security hole and should never be used. diff --git a/lib/libc/sys/acct.2 b/lib/libc/sys/acct.2 index 0021e57673e..aa0a345cf26 100644 --- a/lib/libc/sys/acct.2 +++ b/lib/libc/sys/acct.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: acct.2,v 1.7 2000/04/15 11:46:02 aaron Exp $ +.\" $OpenBSD: acct.2,v 1.8 2000/10/18 05:12:08 aaron Exp $ .\" $NetBSD: acct.2,v 1.6 1995/02/27 12:31:47 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -47,8 +47,7 @@ .Sh DESCRIPTION The .Fn acct -call enables or disables the collection of system accounting -records. +call enables or disables the collection of system accounting records. If .Fa file is @@ -56,15 +55,13 @@ is accounting is disabled. If .Fa file -is an existing, -null-terminated pathname, record collection is enabled and for -every process initiated which terminates under normal -conditions an accounting record is appended to +is an existing, null-terminated pathname, record collection is enabled +and for every process initiated which terminates under normal conditions +an accounting record is appended to .Fa file . -Abnormal conditions of termination are reboots -or other fatal system problems. -Records for processes which never terminate can not be -produced by +Abnormal conditions of termination are reboots or other +fatal system problems. +Records for processes which never terminate can not be produced by .Fn acct . .Pp For more information on the record structure used by diff --git a/lib/libc/sys/adjtime.2 b/lib/libc/sys/adjtime.2 index 592292bc308..e6e4f3dc1c1 100644 --- a/lib/libc/sys/adjtime.2 +++ b/lib/libc/sys/adjtime.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: adjtime.2,v 1.9 2000/04/15 11:46:02 aaron Exp $ +.\" $OpenBSD: adjtime.2,v 1.10 2000/10/18 05:12:08 aaron Exp $ .\" $NetBSD: adjtime.2,v 1.5 1995/10/12 15:40:44 jtc Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -48,21 +48,17 @@ .Fn adjtime makes small adjustments to the system time, as returned by .Xr gettimeofday 2 , -advancing or retarding it -by the time specified by the timeval +advancing or retarding it by the time specified by the timeval .Fa delta . If .Fa delta -is negative, the clock is -slowed down by incrementing it more slowly than normal until -the correction is complete. +is negative, the clock is slowed down by incrementing it more slowly +than normal until the correction is complete. If .Fa delta -is positive, a larger increment than normal -is used. +is positive, a larger increment than normal is used. The skew used to perform the correction is generally a fraction of one percent. -Thus, the time is always -a monotonically increasing function. +Thus, the time is always a monotonically increasing function. A time correction from an earlier call to .Fn adjtime may not be finished when @@ -70,10 +66,8 @@ may not be finished when is called again. If .Fa olddelta -is non-null, -the structure pointed to will contain, upon return, the -number of microseconds still to be corrected -from the earlier call. +is non-null, the structure pointed to will contain, upon return, the +number of microseconds still to be corrected from the earlier call. .Pp This call may be used by time servers that synchronize the clocks of computers in a local area network. diff --git a/lib/libc/sys/bind.2 b/lib/libc/sys/bind.2 index f77b52e2964..75033392221 100644 --- a/lib/libc/sys/bind.2 +++ b/lib/libc/sys/bind.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: bind.2,v 1.9 2000/01/26 08:40:14 deraadt Exp $ +.\" $OpenBSD: bind.2,v 1.10 2000/10/18 05:12:08 aaron Exp $ .\" $NetBSD: bind.2,v 1.8 1995/10/12 15:40:46 jtc Exp $ .\" .\" Copyright (c) 1983, 1993 @@ -48,11 +48,9 @@ .Sh DESCRIPTION .Fn bind assigns a name to an unnamed socket. -When a socket is created -with +When a socket is created with .Xr socket 2 -it exists in a name space (address family) -but has no name assigned. +it exists in a name space (address family) but has no name assigned. .Fn bind requests that .Fa name @@ -97,8 +95,7 @@ has inadequate permission to access it. .It Bq Er EFAULT The .Fa name -parameter is not in a valid part of the user -address space. +parameter is not in a valid part of the user address space. .El .Pp The following errors are specific to binding names in the UNIX domain. diff --git a/lib/libc/sys/brk.2 b/lib/libc/sys/brk.2 index c24a5940133..7f4ff721d07 100644 --- a/lib/libc/sys/brk.2 +++ b/lib/libc/sys/brk.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: brk.2,v 1.11 2000/04/15 02:15:24 aaron Exp $ +.\" $OpenBSD: brk.2,v 1.12 2000/10/18 05:12:08 aaron Exp $ .\" $NetBSD: brk.2,v 1.7 1995/02/27 12:31:57 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -58,8 +58,7 @@ left over from earlier days before the advent of virtual memory management. .Ef The .Fn brk -function -sets the break or lowest address +function sets the break or lowest address of a process's data segment (uninitialized data) to .Fa addr (immediately above bss). @@ -143,10 +142,9 @@ to support the expansion. .Xr end 3 , .Xr malloc 3 .Sh BUGS -Setting the break may fail due to a temporary lack of -swap space. It is not possible to distinguish this -from a failure caused by exceeding the maximum size of -the data segment without consulting +Setting the break may fail due to a temporary lack of swap space. +It is not possible to distinguish this from a failure caused by exceeding +the maximum size of the data segment without consulting .Xr getrlimit . .Sh HISTORY A diff --git a/lib/libc/sys/chdir.2 b/lib/libc/sys/chdir.2 index 7fc397c01f9..173c0bbfd5b 100644 --- a/lib/libc/sys/chdir.2 +++ b/lib/libc/sys/chdir.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: chdir.2,v 1.5 1999/06/29 14:09:51 aaron Exp $ +.\" $OpenBSD: chdir.2,v 1.6 2000/10/18 05:12:08 aaron Exp $ .\" $NetBSD: chdir.2,v 1.7 1995/02/27 12:32:00 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -53,22 +53,19 @@ The argument points to the pathname of a directory. The .Fn chdir -function -causes the named directory -to become the current working directory, that is, -the starting point for path searches of pathnames not beginning with -a slash, -.Ql / . +function causes the named directory to become the current working directory, +that is, the starting point for path searches of pathnames not beginning with +a slash +.Pq Ql / . .Pp The .Fn fchdir -function -causes the directory referenced by +function causes the directory referenced by .Fa fd to become the current working directory, the starting point for path searches of pathnames not beginning with -a slash, -.Ql / . +a slash +.Pq Ql / . .Pp In order for a directory to become the current directory, a process must have execute (search) access to the directory. @@ -76,8 +73,7 @@ a process must have execute (search) access to the directory. Upon successful completion, a value of 0 is returned. Otherwise, a value of \-1 is returned and .Va errno -is set to indicate -the error. +is set to indicate the error. .Sh ERRORS .Fn chdir will fail and the current working directory will be unchanged if @@ -96,8 +92,7 @@ The named directory does not exist. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .It Bq Er EACCES -Search permission is denied for any component of -the path name. +Search permission is denied for any component of the pathname. .It Bq Er EFAULT .Fa path points outside the process's allocated address space. @@ -129,6 +124,5 @@ is expected to conform to .Sh HISTORY The .Fn fchdir -function call -appeared in +function call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/chflags.2 b/lib/libc/sys/chflags.2 index 22d252647b2..5338ec8d8db 100644 --- a/lib/libc/sys/chflags.2 +++ b/lib/libc/sys/chflags.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: chflags.2,v 1.14 2000/04/15 11:46:02 aaron Exp $ +.\" $OpenBSD: chflags.2,v 1.15 2000/10/18 05:12:08 aaron Exp $ .\" $NetBSD: chflags.2,v 1.6 1995/02/27 12:32:03 cgd Exp $ .\" .\" Copyright (c) 1989, 1993 @@ -49,8 +49,7 @@ .Ft int .Fn fchflags "int fd" "unsigned int flags" .Sh DESCRIPTION -The file whose name -is given by +The file whose name is given by .Fa path or referenced by the descriptor .Fa fd @@ -164,6 +163,6 @@ error occurred while reading from or writing to the file system. The .Fn chflags and -.Nm fchflags +.Fn fchflags functions first appeared in .Bx 4.4 . diff --git a/lib/libc/sys/chmod.2 b/lib/libc/sys/chmod.2 index 57925f7f989..9ede4ff66dd 100644 --- a/lib/libc/sys/chmod.2 +++ b/lib/libc/sys/chmod.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: chmod.2,v 1.9 2000/04/15 11:46:02 aaron Exp $ +.\" $OpenBSD: chmod.2,v 1.10 2000/10/18 05:12:08 aaron Exp $ .\" $NetBSD: chmod.2,v 1.7 1995/02/27 12:32:06 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -51,28 +51,22 @@ .Sh DESCRIPTION The function .Fn chmod -sets the file permission bits -of the file -specified by the pathname +sets the file permission bits of the file specified by the pathname .Fa path to .Fa mode . .Fn fchmod -sets the permission bits of the specified -file descriptor +sets the permission bits of the specified file descriptor .Fa fd . .Fn chmod -verifies that the process owner (user) either owns -the file specified by +verifies that the process owner (user) either owns the file specified by .Fa path (or .Fa fd ) , -or -is the superuser. +or is the superuser. A mode is created from .Em or'd -permission bit masks -defined in +permission bit masks defined in .Aq Pa sys/stat.h : .Pp .Bd -literal -offset indent -compact @@ -102,26 +96,25 @@ The .Em sticky bit ) indicates to the system which executable files are shareable (the default) and the system maintains the program text of the files -in the swap area. The sticky bit may only be set by the super user -on shareable executable files. +in the swap area. +The sticky bit may only be set by the superuser on shareable executable files. .Pp If mode .Dv ISVTX -(the `sticky bit') is set on a directory, -an unprivileged user may not delete or rename -files of other users in that directory. The sticky bit may be -set by any user on a directory which the user owns or has appropriate -permissions. +(the +.Dq sticky bit ) +is set on a directory, an unprivileged user may not delete or rename +files of other users in that directory. +The sticky bit may be set by any user on a directory which the user owns +or has appropriate permissions. For more details of the properties of the sticky bit, see .Xr sticky 8 . .Pp -Writing or changing the owner of a file -turns off the set-user-ID and set-group-ID bits -unless the user is the superuser. -This makes the system somewhat more secure -by protecting set-user-ID (set-group-ID) files -from remaining set-user-ID (set-group-ID) if they are modified, -at the expense of a degree of compatibility. +Writing or changing the owner of a file turns off the set-user-ID and +set-group-ID bits unless the user is the superuser. +This makes the system somewhat more secure by protecting +set-user-ID (set-group-ID) files from remaining set-user-ID (set-group-ID) +if they are modified, at the expense of a degree of compatibility. .Sh RETURN VALUES Upon successful completion, a value of 0 is returned. Otherwise, a value of \-1 is returned and @@ -190,6 +183,5 @@ function is expected to conform to .Sh HISTORY The .Fn fchmod -function call -appeared in +function call appeared in .Bx 4.2 . diff --git a/lib/libc/sys/chown.2 b/lib/libc/sys/chown.2 index 1b75cafd7a3..07d4f9895b8 100644 --- a/lib/libc/sys/chown.2 +++ b/lib/libc/sys/chown.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: chown.2,v 1.8 2000/04/15 11:46:03 aaron Exp $ +.\" $OpenBSD: chown.2,v 1.9 2000/10/18 05:12:08 aaron Exp $ .\" $NetBSD: chown.2,v 1.10 1995/10/12 15:40:47 jtc Exp $ .\" .\" Copyright (c) 1980, 1991, 1993, 1994 @@ -52,8 +52,7 @@ .Ft int .Fn fchown "int fd" "uid_t owner" "gid_t group" .Sh DESCRIPTION -The owner ID and group ID of the file (or link) -named by +The owner ID and group ID of the file (or link) named by .Fa path or referenced by .Fa fd @@ -63,15 +62,12 @@ and .Fa group . The owner of a file may change the .Fa group -to a group of which -he or she is a member, -but the change +to a group of which he or she is a member, but the change .Fa owner capability is restricted to the superuser. .Pp .Fn chown -clears the set-user-ID and set-group-ID bits -on the file +clears the set-user-ID and set-group-ID bits on the file to prevent accidental or mischievous creation of set-user-ID and set-group-ID programs. .Pp diff --git a/lib/libc/sys/chroot.2 b/lib/libc/sys/chroot.2 index cd7b6eadbb1..9fbfd97ee32 100644 --- a/lib/libc/sys/chroot.2 +++ b/lib/libc/sys/chroot.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: chroot.2,v 1.9 2000/04/15 11:46:03 aaron Exp $ +.\" $OpenBSD: chroot.2,v 1.10 2000/10/18 05:12:08 aaron Exp $ .\" $NetBSD: chroot.2,v 1.7 1995/02/27 12:32:12 cgd Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -52,9 +52,8 @@ NUL. .Fn chroot causes .Fa dirname -to become the root directory, -that is, the starting point for path searches of pathnames -beginning with +to become the root directory, that is, the starting point for path +searches of pathnames beginning with .Ql / . .Pp In order for a directory to become the root directory @@ -72,8 +71,8 @@ tree than the altered root directory. .Pp This call is restricted to the superuser. .Sh RETURN VALUES -Upon successful completion, a value of 0 is returned. Otherwise, -a value of \-1 is returned and +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and .Va errno is set to indicate an error. .Sh ERRORS diff --git a/lib/libc/sys/clock_gettime.2 b/lib/libc/sys/clock_gettime.2 index b538c1e24b0..cbcac6c5c8d 100644 --- a/lib/libc/sys/clock_gettime.2 +++ b/lib/libc/sys/clock_gettime.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: clock_gettime.2,v 1.11 2000/04/15 11:46:03 aaron Exp $ +.\" $OpenBSD: clock_gettime.2,v 1.12 2000/10/18 05:12:08 aaron Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -92,7 +92,8 @@ system call even when the system is secure. .Pp The resolution (granularity) of a clock is returned by the .Fn clock_getres -call. This value is placed in a (non-null) +call. +This value is placed in a (non-null) .Fa *tp . .Sh RETURN VALUES A 0 return value indicates that the call succeeded. @@ -122,6 +123,8 @@ A user other than the superuser attempted to set the time. .Sh STANDARDS The .Fn clock_gettime , -etc. +.Fn clock_settime , +and +.Fn clock_setres functions conform to .St -p1003.1b-93 . diff --git a/lib/libc/sys/close.2 b/lib/libc/sys/close.2 index 8a3295ab47c..cd119218b70 100644 --- a/lib/libc/sys/close.2 +++ b/lib/libc/sys/close.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: close.2,v 1.8 1999/06/29 14:09:53 aaron Exp $ +.\" $OpenBSD: close.2,v 1.9 2000/10/18 05:12:08 aaron Exp $ .\" $NetBSD: close.2,v 1.5 1995/02/27 12:32:14 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993, 1994 @@ -59,7 +59,8 @@ on the last close of a .Xr socket 2 associated naming information and queued data are discarded; on the last close of a file holding an advisory lock -the lock is released. However, the semantics of System V and +the lock is released. +However, the semantics of System V and .St -p1003.1-88 dictate that all .Xr fcntl 2 @@ -83,8 +84,8 @@ all descriptors for the new child process reference the same objects as they did in the parent before the fork. If a new process is then to be run using .Xr execve 2 , -the process would normally inherit these descriptors. Most -of the descriptors can be rearranged with +the process would normally inherit these descriptors. +Most of the descriptors can be rearranged with .Xr dup2 2 or deleted with .Fn close diff --git a/lib/libc/sys/dup.2 b/lib/libc/sys/dup.2 index 6b7a4842637..09ebf6cd98f 100644 --- a/lib/libc/sys/dup.2 +++ b/lib/libc/sys/dup.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: dup.2,v 1.7 1999/06/29 14:09:53 aaron Exp $ +.\" $OpenBSD: dup.2,v 1.8 2000/10/18 05:12:08 aaron Exp $ .\" $NetBSD: dup.2,v 1.4 1995/02/27 12:32:21 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -56,16 +56,13 @@ the calling process .Fn dup oldd ) . The argument .Fa oldd -is a small non-negative integer index in -the per-process descriptor table. The value must be less -than the size of the table, which is returned by +is a small non-negative integer index in the per-process descriptor table. +The value must be less than the size of the table, which is returned by .Xr getdtablesize 3 . -The new descriptor returned by the call -is the lowest numbered descriptor +The new descriptor returned by the call is the lowest numbered descriptor currently not in use by the process. .Pp -The object referenced by the descriptor does not distinguish -between +The object referenced by the descriptor does not distinguish between .Fa oldd and .Fa newd @@ -94,8 +91,8 @@ In .Fn dup2 , the value of the new descriptor .Fa newd -is specified. If this descriptor is already -in use, the descriptor is first deallocated as if a +is specified. +If this descriptor is already in use, it is first deallocated as if a .Xr close 2 call had been done first. .Sh RETURN VALUES diff --git a/lib/libc/sys/execve.2 b/lib/libc/sys/execve.2 index b26a3801433..8a82b979af6 100644 --- a/lib/libc/sys/execve.2 +++ b/lib/libc/sys/execve.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: execve.2,v 1.15 2000/09/25 07:06:26 fgsch Exp $ +.\" $OpenBSD: execve.2,v 1.16 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: execve.2,v 1.9 1995/02/27 12:32:25 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -56,8 +56,9 @@ This file is either an executable object file, or a file of data for an interpreter. An executable object file consists of an identifying header, followed by pages of data representing the initial program (text) -and initialized data pages. Additional pages may be specified -by the header to be initialized with zero data; see +and initialized data pages. +Additional pages may be specified by the header to be initialized +with zero data; see .Xr a.out 5 . .Pp An interpreter file begins with a line of the form: @@ -83,8 +84,9 @@ and the name of the originally file becomes the second argument; otherwise, the name of the originally .Fn execve Ap d -file becomes the first argument. The original arguments are shifted over to -become the subsequent arguments. The zeroth argument, normally the name of the +file becomes the first argument. +The original arguments are shifted over to become the subsequent arguments. +The zeroth argument, normally the name of the .Fn execve Ap d file, is left unchanged. .Pp @@ -93,8 +95,9 @@ The argument is a pointer to a null-terminated array of character pointers to null-terminated character strings. These strings construct the argument list to be made available to the new -process. At least one argument must be present in -the array; by custom, the first element should be +process. +At least one argument must be present in the array; +by custom, the first element should be the name of the executed program (for example, the last component of .Fa path ) . .Pp @@ -126,7 +129,8 @@ many libraries make assumptions about the use of these 3 file descriptors. .Pp Signals set to be ignored in the calling process are set to be ignored in the -new process. Signals which are set to be caught in the calling process image +new process. +Signals which are set to be caught in the calling process image are set to default action in the new process image. Blocked signals remain blocked regardless of changes to the signal action. The signal stack is reset to be undefined (see @@ -265,15 +269,6 @@ During startup of an .Em interpreter , the system file table was found to be full. .El -.Sh CAVEAT -If a program is -.Em setuid -to a non-superuser, but is executed when -the real -.Em uid -is -.Dq root , -then the program has some of the powers of a superuser as well. .Sh SEE ALSO .Xr _exit 2 , .Xr fork 2 , @@ -285,3 +280,11 @@ The .Fn execve function call appeared in .Bx 4.2 . +.Sh CAVEATS +If a program is +.Em setuid +to a non-superuser, but is executed when the real +.Em uid +is +.Dq root , +then the program has some of the powers of a superuser as well. diff --git a/lib/libc/sys/fcntl.2 b/lib/libc/sys/fcntl.2 index 1e3d1b54b51..123c64d9111 100644 --- a/lib/libc/sys/fcntl.2 +++ b/lib/libc/sys/fcntl.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: fcntl.2,v 1.17 1999/07/05 06:08:05 aaron Exp $ +.\" $OpenBSD: fcntl.2,v 1.18 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: fcntl.2,v 1.6 1995/02/27 12:32:29 cgd Exp $ .\" .\" Copyright (c) 1983, 1993 @@ -286,7 +286,8 @@ but may not start or extend before the beginning of the file. A lock is set to extend to the largest possible value of the file offset for that file if .Fa l_len -is set to zero. If +is set to zero. +If .Fa l_whence and .Fa l_start diff --git a/lib/libc/sys/fhopen.2 b/lib/libc/sys/fhopen.2 index e5cd243e02d..5182758c94c 100644 --- a/lib/libc/sys/fhopen.2 +++ b/lib/libc/sys/fhopen.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: fhopen.2,v 1.3 2000/06/29 05:37:09 aaron Exp $ +.\" $OpenBSD: fhopen.2,v 1.4 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: fhopen.2,v 1.2 1999/12/02 21:42:36 kleink Exp $ .\" .\" Copyright (c) 1999 National Aeronautics & Space Administration @@ -62,13 +62,15 @@ opens the file referenced by .Fa fhp for reading and/or writing as specified by the argument .Fa flags -and returns the file descriptor to the calling process. The +and returns the file descriptor to the calling process. +The .Fa flags are specified by .Em or Ns 'ing together the flags used for the .Xr open 2 -call. All said flags are valid except for +call. +All said flags are valid except for .Dv O_CREAT . .Pp .Fn fhstat diff --git a/lib/libc/sys/flock.2 b/lib/libc/sys/flock.2 index e59e47e46a3..27e66928fe3 100644 --- a/lib/libc/sys/flock.2 +++ b/lib/libc/sys/flock.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: flock.2,v 1.11 1999/06/29 14:09:54 aaron Exp $ +.\" $OpenBSD: flock.2,v 1.12 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: flock.2,v 1.5 1995/02/27 12:32:32 cgd Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -63,8 +63,7 @@ or .Dv LOCK_EX with the optional addition of .Dv LOCK_NB . -To unlock -an existing lock +To unlock an existing lock .Dv operation should be .Dv LOCK_UN . @@ -91,26 +90,25 @@ the appropriate lock type; this results in the previous lock being released and the new lock applied (possibly after other processes have gained and released the lock). .Pp -Requesting a lock on an object that is already locked -normally causes the caller to be blocked until the lock may be -acquired. If +Requesting a lock on an object that is already locked normally causes +the caller to be blocked until the lock may be acquired. +If .Dv LOCK_NB is included in .Fa operation , -then this will not happen; instead the call will fail and -the error +then this will not happen; instead the call will fail and the error .Er EWOULDBLOCK will be returned. .Sh NOTES -Locks are on files, not file descriptors. That is, file descriptors -duplicated through +Locks are on files, not file descriptors. +That is, file descriptors duplicated through .Xr dup 2 or .Xr fork 2 do not result in multiple instances of a lock, but rather multiple -references to a single lock. If a process holding a lock on a file -forks and the child explicitly unlocks the file, the parent will -lose its lock. +references to a single lock. +If a process holding a lock on a file forks and the child explicitly +unlocks the file, the parent will lose its lock. .Pp Processes blocked awaiting a lock may be awakened by signals. .Sh RETURN VALUES diff --git a/lib/libc/sys/fork.2 b/lib/libc/sys/fork.2 index f19dc2d3458..06c9915cad3 100644 --- a/lib/libc/sys/fork.2 +++ b/lib/libc/sys/fork.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: fork.2,v 1.9 1999/06/29 14:09:55 aaron Exp $ +.\" $OpenBSD: fork.2,v 1.10 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: fork.2,v 1.6 1995/02/27 12:32:36 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -80,9 +80,9 @@ Upon successful completion, .Fn fork returns a value of 0 to the child process and returns the process ID of the child -process to the parent process. Otherwise, a value of \-1 is returned -to the parent process, no child process is created, and the global -variable +process to the parent process. +Otherwise, a value of \-1 is returned to the parent process, +no child process is created, and the global variable .Va errno is set to indicate the error. .Sh ERRORS @@ -96,8 +96,8 @@ This limit is configuration-dependent. .It Bq Er EAGAIN The limit .Dv RLIMIT_NPROC -on the total number of -processes under execution by the user ID would be exceeded. +on the total number of processes under execution by the user ID +would be exceeded. .It Bq Er ENOMEM There is insufficient swap space for the new process. .El diff --git a/lib/libc/sys/fsync.2 b/lib/libc/sys/fsync.2 index e910c1e5909..9a015a47821 100644 --- a/lib/libc/sys/fsync.2 +++ b/lib/libc/sys/fsync.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: fsync.2,v 1.5 1999/06/29 14:09:55 aaron Exp $ +.\" $OpenBSD: fsync.2,v 1.6 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: fsync.2,v 1.4 1995/02/27 12:32:38 cgd Exp $ .\" .\" Copyright (c) 1983, 1993 @@ -53,12 +53,11 @@ This normally results in all in-core modified copies of buffers for the associated file to be written to a disk. .Pp .Fn fsync -should be used by programs that require a file to be -in a known state, for example, in building a simple transaction -facility. +should be used by programs that require a file to be in a known state, +for example, in building a simple transaction facility. .Sh RETURN VALUES -A 0 value is returned on success. A \-1 value indicates -an error. +A 0 value is returned on success. +A \-1 value indicates an error. .Sh ERRORS The .Fn fsync diff --git a/lib/libc/sys/getdirentries.2 b/lib/libc/sys/getdirentries.2 index 5dc21d9bd87..fe998aa5698 100644 --- a/lib/libc/sys/getdirentries.2 +++ b/lib/libc/sys/getdirentries.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getdirentries.2,v 1.8 1999/06/29 14:09:55 aaron Exp $ +.\" $OpenBSD: getdirentries.2,v 1.9 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: getdirentries.2,v 1.7 1995/10/12 15:40:50 jtc Exp $ .\" .\" Copyright (c) 1989, 1991, 1993 @@ -76,8 +76,7 @@ char d_name[MAXNAMELEN + 1]; /* see below */ .Pp The .Fa d_fileno -entry is a number which is unique for each -distinct file in the filesystem. +entry is a number which is unique for each distinct file in the filesystem. Files that are linked by hard links (see .Xr link 2 ) have the same diff --git a/lib/libc/sys/getfh.2 b/lib/libc/sys/getfh.2 index 34a6c53b15d..fdcc4bd14ca 100644 --- a/lib/libc/sys/getfh.2 +++ b/lib/libc/sys/getfh.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getfh.2,v 1.6 1999/06/29 14:09:56 aaron Exp $ +.\" $OpenBSD: getfh.2,v 1.7 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: getfh.2,v 1.7 1995/10/12 15:40:53 jtc Exp $ .\" .\" Copyright (c) 1989, 1991, 1993 @@ -95,6 +95,5 @@ error occurred while reading from or writing to the file system. .Sh HISTORY The .Fn getfh -function -first appeared in +function first appeared in .Bx 4.4 . diff --git a/lib/libc/sys/getgroups.2 b/lib/libc/sys/getgroups.2 index 713515f4222..26948fc36f7 100644 --- a/lib/libc/sys/getgroups.2 +++ b/lib/libc/sys/getgroups.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getgroups.2,v 1.6 1999/06/29 14:09:59 aaron Exp $ +.\" $OpenBSD: getgroups.2,v 1.7 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: getgroups.2,v 1.8 1995/02/27 12:32:57 cgd Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -85,8 +85,7 @@ is smaller than the number of groups in the group set. .It Bq Er EFAULT The argument .Fa gidset -specifies -an invalid address. +specifies an invalid address. .El .Sh SEE ALSO .Xr setgroups 2 , diff --git a/lib/libc/sys/getitimer.2 b/lib/libc/sys/getitimer.2 index 57e59e37431..320d3d269f8 100644 --- a/lib/libc/sys/getitimer.2 +++ b/lib/libc/sys/getitimer.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getitimer.2,v 1.11 1999/07/02 20:58:01 aaron Exp $ +.\" $OpenBSD: getitimer.2,v 1.12 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: getitimer.2,v 1.6 1995/10/12 15:40:54 jtc Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -89,7 +89,8 @@ is non-zero, it specifies a value to be used in reloading when the timer expires. Setting .Fa it_value -to 0 disables a timer. Setting +to 0 disables a timer. +Setting .Fa it_interval to 0 causes a timer to be disabled after its next expiration (assuming .Fa it_value @@ -101,7 +102,8 @@ system clock are rounded up to this resolution .Pp The .Dv ITIMER_REAL -timer decrements in real time. A +timer decrements in real time. +A .Dv SIGALRM signal is delivered when this timer expires. @@ -109,23 +111,23 @@ delivered when this timer expires. The .Dv ITIMER_VIRTUAL timer decrements in process virtual time. -It runs only when the process is executing. A +It runs only when the process is executing. +A .Dv SIGVTALRM -signal -is delivered when it expires. +signal is delivered when it expires. .Pp The .Dv ITIMER_PROF timer decrements both in process virtual time and -when the system is running on behalf of the process. It is designed -to be used by interpreters in statistically profiling the execution -of interpreted programs. +when the system is running on behalf of the process. +It is designed to be used by interpreters in statistically profiling +the execution of interpreted programs. Each time the .Dv ITIMER_PROF timer expires, the .Dv SIGPROF -signal is -delivered. Because this signal may interrupt in-progress +signal is delivered. +Because this signal may interrupt in-progress system calls, programs using this timer must be prepared to restart interrupted system calls. .Sh NOTES @@ -156,9 +158,9 @@ Adds two timers and stores the result in .Va res Ns . .El .Sh RETURN VALUES -If the calls succeed, a value of 0 is returned. If an error occurs, -the value \-1 is returned, and a more precise error code is placed -in the global variable +If the calls succeed, a value of 0 is returned. +If an error occurs, the value \-1 is returned, and a more precise +error code is placed in the global variable .Va errno . .Sh ERRORS .Fn getitimer @@ -173,8 +175,7 @@ parameter specified a bad address. .It Bq Er EINVAL A .Fa value -parameter specified a time that was too large -to be handled. +parameter specified a time that was too large to be handled. .El .Sh SEE ALSO .Xr gettimeofday 2 , diff --git a/lib/libc/sys/getlogin.2 b/lib/libc/sys/getlogin.2 index f8a82f8b1cc..faa9929e696 100644 --- a/lib/libc/sys/getlogin.2 +++ b/lib/libc/sys/getlogin.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getlogin.2,v 1.8 2000/04/15 11:46:03 aaron Exp $ +.\" $OpenBSD: getlogin.2,v 1.9 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: getlogin.2,v 1.4 1995/02/27 12:33:03 cgd Exp $ .\" .\" Copyright (c) 1989, 1991, 1993 @@ -50,9 +50,8 @@ .Sh DESCRIPTION The .Fn getlogin -routine -returns the login name of the user associated with the current session, -as previously set by +routine returns the login name of the user associated with the current +session, as previously set by .Fn setlogin . The name is normally associated with a login shell at the time a session is created, @@ -77,7 +76,8 @@ If the name has not been set, it returns .Dv NULL . If a call to .Fn setlogin -succeeds, a value of 0 is returned. If +succeeds, a value of 0 is returned. +If .Fn setlogin fails, a value of \-1 is returned and an error code is placed in the global location diff --git a/lib/libc/sys/getpeername.2 b/lib/libc/sys/getpeername.2 index fb321ca80e6..e1c6f1f48f4 100644 --- a/lib/libc/sys/getpeername.2 +++ b/lib/libc/sys/getpeername.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getpeername.2,v 1.13 2000/01/22 12:00:42 aaron Exp $ +.\" $OpenBSD: getpeername.2,v 1.14 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: getpeername.2,v 1.6 1995/10/12 15:40:56 jtc Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -47,11 +47,9 @@ .Fn getpeername "int s" "struct sockaddr *name" "socklen_t *namelen" .Sh DESCRIPTION .Fn getpeername -returns the address information of the peer connected to -socket +returns the address information of the peer connected to socket .Fa s . -One common -use occurs when a process inherits an open socket, such as +One common use occurs when a process inherits an open socket, such as TCP servers forked from .Xr inetd 8 . In this scenario, @@ -65,15 +63,21 @@ takes three parameters: Contains the file descriptor of the socket who's peer should be looked up. .Pp .Fa name -Points to a sockaddr structure that will hold the address information -for the connected peer. +Points to a +.Li sockaddr +structure that will hold the address information for the connected peer. Normal use requires one to use a structure -specific to the protocol family in use, such as sockaddr_in (IPv4) -or sockaddr_in6 (IPv6), cast to a (struct sockaddr *). +specific to the protocol family in use, such as +.Li sockaddr_in +(IPv4) or +.Li sockaddr_in6 +(IPv6), cast to a (struct sockaddr *). .Pp For greater portability, especially with the newer protocol families, the new -struct sockaddr_storage should be used. sockaddr_storage is -large enough to hold any of the other sockaddr_* variants. +.Li struct sockaddr_storage +should be used. +.Li sockaddr_storage +is large enough to hold any of the other sockaddr_* variants. On return, it can be cast to the correct sockaddr type, based the protocol family contained in its ss_family field. .Pp diff --git a/lib/libc/sys/getpid.2 b/lib/libc/sys/getpid.2 index 7b52243ac82..4c1c08cdb26 100644 --- a/lib/libc/sys/getpid.2 +++ b/lib/libc/sys/getpid.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getpid.2,v 1.6 1999/06/29 14:10:00 aaron Exp $ +.\" $OpenBSD: getpid.2,v 1.7 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: getpid.2,v 1.5 1995/02/27 12:33:12 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -50,15 +50,12 @@ .Fn getppid void .Sh DESCRIPTION .Fn getpid -returns -the process ID of -the calling process. -The ID is guaranteed to be unique and is -useful for constructing temporary file names. +returns the process ID of the calling process. +The ID is guaranteed to be unique and is useful for constructing +temporary file names. .Pp .Fn getppid -returns the process ID of the parent -of the calling process. +returns the process ID of the parent of the calling process. .Sh ERRORS The .Fn getpid diff --git a/lib/libc/sys/getpriority.2 b/lib/libc/sys/getpriority.2 index d300f7ed3cb..b840d35b1c0 100644 --- a/lib/libc/sys/getpriority.2 +++ b/lib/libc/sys/getpriority.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getpriority.2,v 1.6 2000/04/15 11:46:03 aaron Exp $ +.\" $OpenBSD: getpriority.2,v 1.7 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: getpriority.2,v 1.4 1995/02/27 12:33:15 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -49,8 +49,8 @@ .Ft int .Fn setpriority "int which" "int who" "int prio" .Sh DESCRIPTION -The scheduling -priority of the process, process group, or user, as indicated by +The scheduling priority of the process, process group, or user, +as indicated by .Fa which and .Fa who @@ -71,8 +71,7 @@ is interpreted relative to .Fa which (a process identifier for .Dv PRIO_PROCESS , -process group -identifier for +process group identifier for .Dv PRIO_PGRP , and a user ID for .Dv PRIO_USER ) . @@ -80,16 +79,19 @@ A zero value of .Fa who denotes the current process, process group, or user. .Fa prio -is a value in the range \-20 to 20. The default priority is 0; +is a value in the range \-20 to 20. +The default priority is 0; lower priorities cause more favorable scheduling. .Pp The .Fn getpriority call returns the highest priority (lowest numerical value) -enjoyed by any of the specified processes. The +enjoyed by any of the specified processes. +The .Fn setpriority call sets the priorities of all of the specified processes -to the specified value. Only the superuser may lower priorities. +to the specified value. +Only the superuser may lower priorities. .Sh RETURN VALUES Since .Fn getpriority diff --git a/lib/libc/sys/getrlimit.2 b/lib/libc/sys/getrlimit.2 index e8f5bbdc55c..afcc0ae04ae 100644 --- a/lib/libc/sys/getrlimit.2 +++ b/lib/libc/sys/getrlimit.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getrlimit.2,v 1.10 2000/04/15 11:46:03 aaron Exp $ +.\" $OpenBSD: getrlimit.2,v 1.11 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: getrlimit.2,v 1.8 1995/10/12 15:40:58 jtc Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -96,11 +96,12 @@ this defines how far a program's stack segment may be extended. Stack extension is performed automatically by the system. .El .Pp -A resource limit is specified as a soft limit and a hard limit. When a -soft limit is exceeded a process may receive a signal (for example, if -the cpu time or file size is exceeded), but it will be allowed to +A resource limit is specified as a soft limit and a hard limit. +When a soft limit is exceeded a process may receive a signal (for example, +if the cpu time or file size is exceeded), but it will be allowed to continue execution until it reaches the hard limit (or modifies -its resource limit). The +its resource limit). +The .Em rlimit structure is used to specify the hard and soft limits on a resource, .Bd -literal -offset indent @@ -110,8 +111,8 @@ struct rlimit { }; .Ed .Pp -Only the superuser may raise the maximum limits. Other users -may only alter +Only the superuser may raise the maximum limits. +Other users may only alter .Fa rlim_cur within the range from 0 to .Fa rlim_max @@ -150,16 +151,16 @@ A file I/O operation that would create a file larger that the process' soft limit will cause the write to fail and a signal .Dv SIGXFSZ to be -generated; this normally terminates the process, but may be caught. When -the soft cpu time limit is exceeded, a signal +generated; this normally terminates the process, but may be caught. +When the soft cpu time limit is exceeded, a signal .Dv SIGXCPU is sent to the offending process. .Sh RETURN VALUES A 0 return value indicates that the call succeeded, changing -or returning the resource limit. A return value of \-1 indicates -that an error occurred, and an error code is stored in the global -location +or returning the resource limit. +A return value of \-1 indicates that an error occurred, and an error code +is stored in the global variable .Va errno . .Sh ERRORS .Fn getrlimit @@ -174,8 +175,7 @@ is invalid. .It Bq Er EPERM The limit specified to .Fn setrlimit -would have -raised the maximum limit value, and the caller is not the superuser. +would have raised the maximum limit value, and the caller is not the superuser. .El .Sh SEE ALSO .Xr csh 1 , diff --git a/lib/libc/sys/getrusage.2 b/lib/libc/sys/getrusage.2 index 627df5928c7..f08c11eabe8 100644 --- a/lib/libc/sys/getrusage.2 +++ b/lib/libc/sys/getrusage.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getrusage.2,v 1.6 1999/06/29 14:10:01 aaron Exp $ +.\" $OpenBSD: getrusage.2,v 1.7 2000/10/18 05:12:09 aaron Exp $ .\" .\" Copyright (c) 1985, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -94,8 +94,8 @@ the maximum resident set size utilized (in kilobytes). .It Fa ru_ixrss an \*(lqintegral\*(rq value indicating the amount of memory used by the text segment -that was also shared among other processes. This value is expressed -in units of kilobytes * ticks-of-execution. +that was also shared among other processes. +This value is expressed in units of kilobytes * ticks-of-execution. .It Fa ru_idrss an integral value of the amount of unshared memory residing in the data segment of a process (expressed in units of diff --git a/lib/libc/sys/getsockname.2 b/lib/libc/sys/getsockname.2 index 8251bbbd80d..c960ed77f6a 100644 --- a/lib/libc/sys/getsockname.2 +++ b/lib/libc/sys/getsockname.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getsockname.2,v 1.13 2000/01/22 12:00:43 aaron Exp $ +.\" $OpenBSD: getsockname.2,v 1.14 2000/10/18 05:12:09 aaron Exp $ .\" $NetBSD: getsockname.2,v 1.6 1995/10/12 15:41:00 jtc Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -77,21 +77,28 @@ takes three parameters: Contains the file desriptor for the socket to be looked up. .Pp .Fa name -points to a sockaddr structure which will hold the resulting -address information. Normal use requires one to use a structure -specific to the protocol family in use, such as sockaddr_in (IPv4) -or sockaddr_in6 (IPv6), cast to a (struct sockaddr *). +points to a +.Li sockaddr +structure which will hold the resulting address information. +Normal use requires one to use a structure +specific to the protocol family in use, such as +.Li sockaddr_in +(IPv4) or +.Li sockaddr_in6 +(IPv6), cast to a (struct sockaddr *). .Pp For greater portability (such as newer protocol families) the new -structure sockaddr_storage exists. sockaddr_storage is -large enough to hold any of the other sockaddr_* variants. +structure sockaddr_storage exists. +.Li sockaddr_storage +is large enough to hold any of the other sockaddr_* variants. On return, it should be cast to the correct sockaddr type, according to the current protocol family. .Pp .Fa namelen Indicates the amount of space pointed to by .Fa name , -in bytes. Upon return, +in bytes. +Upon return, .Fa namelen is set to the actual size of the returned address information. .Pp diff --git a/lib/libc/sys/getsockopt.2 b/lib/libc/sys/getsockopt.2 index 3f04eca96f8..0c8a99b9e18 100644 --- a/lib/libc/sys/getsockopt.2 +++ b/lib/libc/sys/getsockopt.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getsockopt.2,v 1.15 2000/04/15 02:15:24 aaron Exp $ +.\" $OpenBSD: getsockopt.2,v 1.16 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: getsockopt.2,v 1.7 1995/02/27 12:33:29 cgd Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -54,8 +54,9 @@ and .Fn setsockopt manipulate the .Em options -associated with a socket. Options may exist at multiple -protocol levels; they are always present at the uppermost +associated with a socket. +Options may exist at multiple protocol levels; +they are always present at the uppermost .Dq socket level. .Pp @@ -65,10 +66,9 @@ To manipulate options at the socket level, .Fa level is specified as .Dv SOL_SOCKET . -To manipulate options at any -other level the protocol number of the appropriate protocol -controlling the option is supplied. For example, -to indicate that an option is to be interpreted by the +To manipulate options at any other level the protocol number of the +appropriate protocol controlling the option is supplied. +For example, to indicate that an option is to be interpreted by the .Tn TCP protocol, .Fa level @@ -86,15 +86,15 @@ are used to access option values for For .Fn getsockopt they identify a buffer in which the value for the -requested option(s) are to be returned. For +requested option(s) are to be returned. +For .Fn getsockopt , .Fa optlen is a value-result parameter, initially containing the size of the buffer pointed to by .Fa optval , -and modified on return to indicate the actual size of -the value returned. If no option value is -to be supplied or returned, +and modified on return to indicate the actual size of the value returned. +If no option value is to be supplied or returned, .Fa optval may be .Dv NULL . @@ -104,12 +104,9 @@ and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file .Ao Pa sys/socket.h Ac -contains definitions for -socket level options, described below. -Options at other protocol levels vary in format and -name; consult the appropriate entries in -section -4 of the manual. +contains definitions for socket level options, described below. +Options at other protocol levels vary in format and name; +consult the appropriate entries in section 4 of the manual. .Pp Most socket-level options utilize an .Li int @@ -132,7 +129,7 @@ and use a .Li struct timeval parameter, defined in -.Ao Pa sys/time.h Ac . +.Aq Pa sys/time.h . .Pp The following options are recognized at the socket level. Except as noted, each may be examined with @@ -161,29 +158,26 @@ and set with .Dv SO_DEBUG enables debugging in the underlying protocol modules. .Dv SO_REUSEADDR -indicates that the rules used in validating addresses supplied -in a +indicates that the rules used in validating addresses supplied in a .Xr bind 2 call should allow reuse of local addresses. .Dv SO_REUSEPORT -allows completely duplicate bindings by multiple processes -if they all set +allows completely duplicate bindings by multiple processes if they all set .Dv SO_REUSEPORT before binding the port. This option permits multiple instances of a program to each receive UDP/IP multicast or broadcast datagrams destined for the bound port. .Dv SO_KEEPALIVE -enables the -periodic transmission of messages on a connected socket. Should the -connected party fail to respond to these messages, the connection is -considered broken and processes using the socket are notified via a +enables the periodic transmission of messages on a connected socket. +Should the connected party fail to respond to these messages, the connection +is considered broken and processes using the socket are notified via a .Dv SIGPIPE signal when attempting to send data. .Dv SO_DONTROUTE indicates that outgoing messages should -bypass the standard routing facilities. Instead, messages are directed -to the appropriate network interface according to the network portion -of the destination address. +bypass the standard routing facilities. +Instead, messages are directed to the appropriate network interface +according to the network portion of the destination address. .Pp .Dv SO_LINGER controls the action taken when unsent messages @@ -215,9 +209,8 @@ on the socket. Broadcast was a privileged operation in earlier versions of the system. With protocols that support out-of-band data, the .Dv SO_OOBINLINE -option -requests that out-of-band data be placed in the normal data input queue -as received; it will then be accessible with +option requests that out-of-band data be placed in the normal data input +queue as received; it will then be accessible with .Xr recv 2 or .Xr read 2 @@ -276,10 +269,9 @@ It accepts a parameter with the number of seconds and microseconds used to limit waits for output operations to complete. If a send operation has blocked for this much time, -it returns with a partial count -or with the error +it returns with a partial count or with the error .Er EWOULDBLOCK -if no data were sent. +if no data was sent. In the current implementation, this timer is restarted each time additional data are delivered to the protocol, implying that the limit applies to output portions ranging in size @@ -310,8 +302,7 @@ returns the type of the socket, such as .Dv SOCK_STREAM ; it is useful for servers that inherit sockets on startup. .Dv SO_ERROR -returns any pending error on the socket and clears -the error status. +returns any pending error on the socket and clears the error status. It may be used to check for asynchronous errors on connected datagram sockets or for other asynchronous errors. .Sh RETURN VALUES diff --git a/lib/libc/sys/gettimeofday.2 b/lib/libc/sys/gettimeofday.2 index 279cd8ce1a9..890f33e1494 100644 --- a/lib/libc/sys/gettimeofday.2 +++ b/lib/libc/sys/gettimeofday.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: gettimeofday.2,v 1.10 2000/04/15 11:46:03 aaron Exp $ +.\" $OpenBSD: gettimeofday.2,v 1.11 2000/10/18 05:12:10 aaron Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -57,10 +57,13 @@ zone is obtained with the .Fn gettimeofday call, and set with the .Fn settimeofday -call. The time is expressed in seconds and microseconds -since midnight (0 hour), January 1, 1970. The resolution of the system -clock is hardware dependent, and the time may be updated continuously or -in ``ticks.'' If +call. +The time is expressed in seconds and microseconds +since midnight (0 hour), January 1, 1970. +The resolution of the system clock is hardware dependent, and the time +may be updated continuously or in +.Dq ticks . +If .Fa tp or .Fa tzp diff --git a/lib/libc/sys/getuid.2 b/lib/libc/sys/getuid.2 index 405c74e4b87..8b02ba40551 100644 --- a/lib/libc/sys/getuid.2 +++ b/lib/libc/sys/getuid.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getuid.2,v 1.6 1999/06/16 08:45:12 alex Exp $ +.\" $OpenBSD: getuid.2,v 1.7 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: getuid.2,v 1.6 1995/02/27 12:33:37 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -54,8 +54,7 @@ The function returns the real user ID of the calling process. The .Fn geteuid -function -returns the effective user ID of the calling process. +function returns the effective user ID of the calling process. .Pp The real user ID is that of the user who has invoked the program. As the effective user ID diff --git a/lib/libc/sys/intro.2 b/lib/libc/sys/intro.2 index 283a1d4faee..b1271fa1e2a 100644 --- a/lib/libc/sys/intro.2 +++ b/lib/libc/sys/intro.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: intro.2,v 1.16 2000/04/15 11:46:03 aaron Exp $ +.\" $OpenBSD: intro.2,v 1.17 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: intro.2,v 1.6 1995/02/27 12:33:41 cgd Exp $ .\" .\" Copyright (c) 1980, 1983, 1986, 1991, 1993 @@ -95,7 +95,8 @@ An asynchronous signal (such as or .Dv SIGQUIT ) was caught by the process during the execution of an interruptible -function. If the signal handler performs a normal return, the +function. +If the signal handler performs a normal return, the interrupted function call will seem to have returned the error condition. .It Er 5 EIO Em "Input/output error" . Some physical input or output error occurred. @@ -169,8 +170,8 @@ not a directory, when a directory was expected. .It Er 21 EISDIR Em "Is a directory" . An attempt was made to open a directory with write mode specified. .It Er 22 EINVAL Em "Invalid argument" . -Some invalid argument was supplied. (For example, -specifying an undefined signal to a +Some invalid argument was supplied. +(For example, specifying an undefined signal to a .Xr signal 3 or .Xr kill 2 @@ -212,8 +213,7 @@ An function was issued on a socket, pipe or .Tn FIFO . .It Er 30 EROFS Em "Read-only file system" . -An attempt was made to modify a file or directory -was made +An attempt was made to modify a file or directory was made on a file system that was read-only at the time. .It Er 31 EMLINK Em "Too many links" . Maximum allowable hard links to a single file has been exceeded (limit @@ -233,8 +233,7 @@ available space (perhaps exceeded precision). This is a temporary condition and later calls to the same routine may complete normally. .It Er 36 EINPROGRESS Em "Operation now in progress" . -An operation that takes a long time to complete (such as -a +An operation that takes a long time to complete (such as a .Xr connect 2 ) was attempted on a non-blocking object (see .Xr fcntl 2 ) . @@ -250,7 +249,8 @@ A message sent on a socket was larger than the internal message buffer or some other network limit. .It Er 41 EPROTOTYPE Em "Protocol wrong type for socket" . A protocol was specified that does not support the semantics of the -socket type requested. For example, you cannot use the +socket type requested. +For example, you cannot use the .Tn ARPA Internet .Tn UDP @@ -299,8 +299,8 @@ The host you were connected to crashed and rebooted. .It Er 53 ECONNABORTED Em "Software caused connection abort" . A connection abort was caused internal to your host machine. .It Er 54 ECONNRESET Em "Connection reset by peer" . -A connection was forcibly closed by a peer. This normally -results from a loss of the connection on the remote socket +A connection was forcibly closed by a peer. +This normally results from a loss of the connection on the remote socket due to a timeout or a reboot. .It Er 55 ENOBUFS Em "\&No buffer space available" . An operation on a socket or pipe was not performed because @@ -308,8 +308,7 @@ the system lacked sufficient buffer space or because a queue was full. .It Er 56 EISCONN Em "Socket is already connected" . A .Xr connect 2 -request was made on an already connected socket; or, -a +request was made on an already connected socket; or, a .Xr sendto 2 or .Xr sendmsg 2 @@ -333,12 +332,13 @@ A or .Xr send 2 request failed because the connected party did not -properly respond after a period of time. (The timeout -period is dependent on the communication protocol.) +properly respond after a period of time. +(The timeout period is dependent on the communication protocol.) .It Er 61 ECONNREFUSED Em "Connection refused" . No connection could be made because the target machine actively -refused it. This usually results from trying to connect -to a service that is inactive on the foreign host. +refused it. +This usually results from trying to connect to a service that is +inactive on the foreign host. .It Er 62 ELOOP Em "Too many levels of symbolic links" . A path name lookup involved more than 8 symbolic links. .It Er 63 ENAMETOOLONG Em "File name too long" . @@ -420,7 +420,8 @@ filesystem may be mounted. .Bl -tag -width Ds .It Process ID Each active process in the system is uniquely identified by a non-negative -integer called a process ID. The range of this ID is from 1 to 32766. +integer called a process ID. +The range of this ID is from 1 to 32766. .It Parent Process ID A new process is created by a currently active process; (see .Xr fork 2 ) . @@ -430,9 +431,9 @@ the parent process ID of each child is set to the ID of a system process, .Xr init 8 . .It Process Group Each active process is a member of a process group that is identified by -a non-negative integer called the process group ID. This is the process -ID of the group leader. This grouping permits the signaling of related -processes (see +a non-negative integer called the process group ID. +This is the process ID of the group leader. +This grouping permits the signaling of related processes (see .Xr termios 4 ) and the job control mechanisms of .Xr csh 1 . @@ -485,8 +486,8 @@ termed the real user ID. .Pp Each user is also a member of one or more groups. One of these groups is distinguished from others and -used in implementing accounting facilities. The positive -integer corresponding to this distinguished group is termed +used in implementing accounting facilities. +The positive integer corresponding to this distinguished group is termed the real group ID. .Pp All processes have a real user ID and real group ID. @@ -502,8 +503,8 @@ group IDs, and it is unspecified whether the effective group ID is a member of the list.) .Pp The effective user ID and effective group ID are initially the -process's real user ID and real group ID respectively. Either -may be modified through execution of a set-user-ID or set-group-ID +process's real user ID and real group ID respectively. +Either may be modified through execution of a set-user-ID or set-group-ID file (possibly by one its ancestors) (see .Xr execve 2 ) . By convention, the effective group ID (the first member of the group access @@ -511,8 +512,8 @@ list) is duplicated, so that the execution of a set-group-ID program does not result in the loss of the original (real) group ID. .Pp The group access list is a set of group IDs -used only in determining resource accessibility. Access checks -are performed as described below in ``File Access Permissions''. +used only in determining resource accessibility. +Access checks are performed as described below in ``File Access Permissions''. .It Saved Set User ID and Saved Set Group ID When a process executes a new file, the effective user ID is set to the owner of the file if the file is set-user-ID, and the effective @@ -687,16 +688,17 @@ for more information about the types available and their properties. .Pp Each instance of the system supports some number of sets of -communications protocols. Each protocol set supports addresses -of a certain format. An Address Family is the set of addresses -for a specific group of protocols. Each socket has an address -chosen from the address family in which the socket was created. +communications protocols. +Each protocol set supports addresses of a certain format. +An Address Family is the set of addresses for a specific group of protocols. +Each socket has an address chosen from the address family in which the +socket was created. .El .Sh SEE ALSO .Xr intro 3 , .Xr perror 3 .Sh HISTORY An -.Nm intro +.Nm manual page appeared in .At v6 . diff --git a/lib/libc/sys/kill.2 b/lib/libc/sys/kill.2 index 6fd0065f654..831907d67d2 100644 --- a/lib/libc/sys/kill.2 +++ b/lib/libc/sys/kill.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: kill.2,v 1.12 2000/04/15 11:46:03 aaron Exp $ +.\" $OpenBSD: kill.2,v 1.13 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: kill.2,v 1.7 1995/02/27 12:33:53 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -88,13 +88,13 @@ this is a variant of If the user has superuser privileges, the signal is sent to all processes excluding system processes and the process sending the signal. -If the user is not the super user, the signal is sent to all processes +If the user is not the superuser, the signal is sent to all processes with the same uid as the user excluding the process sending the signal. No error is returned if any process could be signaled. .El .Pp -Setuid and setgid processes are dealt with slightly differently. For -the non-root user, to prevent attacks against such processes, some signal +Setuid and setgid processes are dealt with slightly differently. +For the non-root user, to prevent attacks against such processes, some signal deliveries are not permitted and return the error .Er EPERM . The following signals are allowed through to this class of processes: diff --git a/lib/libc/sys/link.2 b/lib/libc/sys/link.2 index a809afc7fbd..c1153ff90ec 100644 --- a/lib/libc/sys/link.2 +++ b/lib/libc/sys/link.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: link.2,v 1.12 2000/04/15 11:46:03 aaron Exp $ +.\" $OpenBSD: link.2,v 1.13 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: link.2,v 1.7 1995/02/27 12:34:01 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -47,8 +47,7 @@ .Sh DESCRIPTION The .Fn link -function call -atomically creates the specified directory entry (hard link) +function atomically creates the specified directory entry (hard link) .Fa name2 with the attributes of the underlying object pointed at by .Fa name1 . @@ -57,22 +56,16 @@ is incremented; .Fa name1 and .Fa name2 -share equal access and rights -to the -underlying object. +share equal access and rights to the underlying object. .Pp If .Fa name1 is removed, the file .Fa name2 -is not deleted and the link count of the -underlying object is -decremented. +is not deleted and the link count of the underlying object is decremented. .Pp .Fa name1 -must exist for the hard link to -succeed and -both +must exist for the hard link to succeed and both .Fa name1 and .Fa name2 @@ -81,8 +74,8 @@ As mandated by POSIX.1 .Fa name1 may not be a directory. .Sh RETURN VALUES -Upon successful completion, a value of 0 is returned. Otherwise, -a value of \-1 is returned and +Upon successful completion, a value of 0 is returned. +Otherwise, a value of \-1 is returned and .Va errno is set to indicate the error. .Sh ERRORS diff --git a/lib/libc/sys/lseek.2 b/lib/libc/sys/lseek.2 index 2f5ee755b3f..fce961194d9 100644 --- a/lib/libc/sys/lseek.2 +++ b/lib/libc/sys/lseek.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: lseek.2,v 1.8 1999/06/29 14:10:05 aaron Exp $ +.\" $OpenBSD: lseek.2,v 1.9 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: lseek.2,v 1.6 1995/02/27 12:34:09 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -49,15 +49,13 @@ The .Fn lseek function repositions the offset of the file descriptor .Fa fildes -to the -argument +to the argument .Fa offset according to the directive .Fa whence . The argument .Fa fildes -must be an open -file descriptor. +must be an open file descriptor. .Fn lseek repositions the file pointer .Fa fildes @@ -84,8 +82,7 @@ If .Fa whence is .Dv SEEK_END , -the offset is set to the size of the -file plus +the offset is set to the size of the file plus .Fa offset bytes. .El @@ -93,22 +90,20 @@ bytes. The .Fn lseek function allows the file offset to be set beyond the end -of the existing end-of-file of the file. If data is later written -at this point, subsequent reads of the data in the gap return -bytes of zeros (until data is actually written into the gap). +of the existing end-of-file of the file. +If data is later written at this point, subsequent reads of the data in the +gap return bytes of zeros (until data is actually written into the gap). .Pp -Some devices are incapable of seeking. The value of the pointer -associated with such a device is undefined. +Some devices are incapable of seeking. +The value of the pointer associated with such a device is undefined. .Sh RETURN VALUES Upon successful completion, .Fn lseek returns the resulting offset location as measured in bytes from the beginning of the file. -Otherwise, -a value of \-1 is returned and +Otherwise, a value of \-1 is returned and .Va errno -is set to indicate -the error. +is set to indicate the error. .Sh ERRORS .Fn lseek will fail and the file pointer will remain unchanged if: diff --git a/lib/libc/sys/mkdir.2 b/lib/libc/sys/mkdir.2 index 40997c077a0..0b68ab76eb4 100644 --- a/lib/libc/sys/mkdir.2 +++ b/lib/libc/sys/mkdir.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: mkdir.2,v 1.6 1999/06/29 14:10:06 aaron Exp $ +.\" $OpenBSD: mkdir.2,v 1.7 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: mkdir.2,v 1.8 1995/02/27 12:34:22 cgd Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -58,8 +58,8 @@ The directory's owner ID is set to the process's effective user ID. The directory's group ID is set to that of the parent directory in which it is created. .Sh RETURN VALUES -A 0 return value indicates success. A \-1 return value -indicates an error, and an error code is stored in +A 0 return value indicates success. +A \-1 return value indicates an error, and an error code is stored in .Va errno . .Sh ERRORS .Fn mkdir diff --git a/lib/libc/sys/mkfifo.2 b/lib/libc/sys/mkfifo.2 index 58282fd10c8..51092486f28 100644 --- a/lib/libc/sys/mkfifo.2 +++ b/lib/libc/sys/mkfifo.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: mkfifo.2,v 1.4 1999/06/29 14:10:06 aaron Exp $ +.\" $OpenBSD: mkfifo.2,v 1.5 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: mkfifo.2,v 1.8 1995/02/27 12:34:27 cgd Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 @@ -60,8 +60,8 @@ The fifo's owner ID is set to the process's effective user ID. The fifo's group ID is set to that of the parent directory in which it is created. .Sh RETURN VALUES -A 0 return value indicates success. A \-1 return value -indicates an error, and an error code is stored in +A 0 return value indicates success. +A \-1 return value indicates an error, and an error code is stored in .Va errno . .Sh ERRORS .Fn mkfifo diff --git a/lib/libc/sys/mknod.2 b/lib/libc/sys/mknod.2 index 06ff8c165ce..b4302a8d271 100644 --- a/lib/libc/sys/mknod.2 +++ b/lib/libc/sys/mknod.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: mknod.2,v 1.9 2000/08/12 22:21:50 millert Exp $ +.\" $OpenBSD: mknod.2,v 1.10 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: mknod.2,v 1.6 1995/02/27 12:34:33 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -61,7 +61,8 @@ If indicates a block or character special file, .Fa dev is a configuration dependent specification of a character or block -I/O device and the superblock of the device. If +I/O device and the superblock of the device. +If .Fa mode does not indicate a block special or character special device, .Fa dev @@ -120,7 +121,7 @@ The named file exists. points outside the process's allocated address space. .It Bq Er EINVAL The process is running within an alternate root directory, as -created by +created by .Xr chroot 2 . .El .Sh SEE ALSO diff --git a/lib/libc/sys/mmap.2 b/lib/libc/sys/mmap.2 index c23d2a2a0dd..de58e7f0886 100644 --- a/lib/libc/sys/mmap.2 +++ b/lib/libc/sys/mmap.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: mmap.2,v 1.19 1999/07/04 18:59:44 aaron Exp $ +.\" $OpenBSD: mmap.2,v 1.20 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: mmap.2,v 1.5 1995/06/24 10:48:59 cgd Exp $ .\" .\" Copyright (c) 1991, 1993 @@ -111,8 +111,8 @@ regions is used only for naming, and may be specified as \-1 if no name is associated with the region. .It Dv MAP_FILE -Mapped from a regular file or character-special device memory. (This is -the default mapping type, and need not be specified.) +Mapped from a regular file or character-special device memory. +(This is the default mapping type, and need not be specified.) .It Dv MAP_FIXED Do not permit the system to select a different address than the one specified. diff --git a/lib/libc/sys/msgctl.2 b/lib/libc/sys/msgctl.2 index 5342bce468c..68b90428bb2 100644 --- a/lib/libc/sys/msgctl.2 +++ b/lib/libc/sys/msgctl.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: msgctl.2,v 1.10 2000/04/15 11:46:03 aaron Exp $ +.\" $OpenBSD: msgctl.2,v 1.11 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: msgctl.2,v 1.2 1997/03/27 08:20:35 mikel Exp $ .\" .\" Copyright (c) 1995 Frank van der Linden @@ -124,7 +124,8 @@ or in the data structure associated with the message queue. The value of .Va msg_qbytes -can only be increased by the superuser. Values for +can only be increased by the superuser. +Values for .Va msg_qbytes that exceed the system limit .Pf ( Dv MSGMNB @@ -135,8 +136,8 @@ are silently truncated to that limit. .It Dv IPC_RMID Remove the message queue specified by .Fa msqid -and destroy the data associated with it. Only the superuser or a process -with an effective UID equal to the +and destroy the data associated with it. +Only the superuser or a process with an effective UID equal to the .Va msg_perm.cuid or .Va msg_perm.uid @@ -162,8 +163,8 @@ effective GID can match either or .Va msg_perm.gid . .Sh RETURN VALUES -Upon successful completion, a value of 0 is returned. Otherwise, \-1 is -returned and the global variable +Upon successful completion, a value of 0 is returned. +Otherwise, \-1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS diff --git a/lib/libc/sys/msgrcv.2 b/lib/libc/sys/msgrcv.2 index 3fd937b0e91..23f0ba16932 100644 --- a/lib/libc/sys/msgrcv.2 +++ b/lib/libc/sys/msgrcv.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: msgrcv.2,v 1.8 1999/06/29 14:10:09 aaron Exp $ +.\" $OpenBSD: msgrcv.2,v 1.9 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: msgrcv.2,v 1.2 1997/03/27 08:20:37 mikel Exp $ .\" .\" Copyright (c) 1995 Frank van der Linden @@ -67,23 +67,26 @@ has one of the following meanings: .Bl -bullet .It .Fa msgtyp -is greater than 0. The first message of type +is greater than 0. +The first message of type .Fa msgtyp will be received. .It .Fa msgtyp -is equal to 0. The first message on the queue will be received. +is equal to 0. +The first message on the queue will be received. .It .Fa msgtyp -is less than 0. The first message of the lowest message type that is +is less than 0. +The first message of the lowest message type that is less than or equal to the absolute value of .Fa msgtyp will be received. .El .Pp .Fa msgsz -specifies the maximum length of the requested message. If the received -message has a length greater than +specifies the maximum length of the requested message. +If the received message has a length greater than .Fa msgsz it will be silently truncated if the .Dv MSG_NOERROR @@ -99,7 +102,8 @@ depends on whether the .Dv IPC_NOWAIT flag is set in .Fa msgflg -or not. If +or not. +If .Dv IPC_NOWAIT is set, .Fn msgrcv @@ -120,7 +124,8 @@ The message queue is removed, in which case \-1 will be returned, and set to .Er EINVAL . .It -A signal is received and caught. \-1 is returned, and +A signal is received and caught. +\-1 is returned, and .Va errno set to .Er EINTR . diff --git a/lib/libc/sys/msgsnd.2 b/lib/libc/sys/msgsnd.2 index c7312193ef7..3dd3a4c08c7 100644 --- a/lib/libc/sys/msgsnd.2 +++ b/lib/libc/sys/msgsnd.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: msgsnd.2,v 1.7 1999/06/29 14:10:09 aaron Exp $ +.\" $OpenBSD: msgsnd.2,v 1.8 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: msgsnd.2,v 1.2 1997/03/27 08:20:36 mikel Exp $ .\" .\" Copyright (c) 1995 Frank van der Linden @@ -48,8 +48,8 @@ The function sends a message from the message queue specified in .Fa msqid . .Fa msgp -points to a structuer containing the message. This structure should -consist of the following members: +points to a structuer containing the message. +This structure should consist of the following members: .Bd -literal long mtype; /* message type */ char mtext[1]; /* body of message */ @@ -77,7 +77,8 @@ If .Fa msgflg has .Dv IPC_NOWAIT -mask set in it, the call will return immediately. If +mask set in it, the call will return immediately. +If .Fa msgflg does not have .Dv IPC_NOWAIT @@ -92,7 +93,8 @@ The messag queue is removed, in which case \-1 will be returned, and is set to .Er EINVAL . .It -The caller catches a signal. The call returns with +The caller catches a signal. +The call returns with .Va errno set to .Er EINTR . @@ -115,7 +117,8 @@ is set to the pid of the calling process. is set to the current time. .El .Sh RETURN VALUES -Upon successful completion, 0 is returned. Otherwise, \-1 is returned and +Upon successful completion, 0 is returned. +Otherwise, \-1 is returned and .Va errno is set to indicate the error. .Sh ERRORS diff --git a/lib/libc/sys/nanosleep.2 b/lib/libc/sys/nanosleep.2 index 85d5b99a0e8..c6493bcb94f 100644 --- a/lib/libc/sys/nanosleep.2 +++ b/lib/libc/sys/nanosleep.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: nanosleep.2,v 1.6 2000/01/05 02:02:14 pjanzen Exp $ +.\" $OpenBSD: nanosleep.2,v 1.7 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: nanosleep.2,v 1.1 1997/04/17 18:12:02 jtc Exp $ .\" .\" Copyright (c) 1986, 1991, 1993 @@ -46,8 +46,9 @@ .Fn nanosleep "const struct timespec *rqtp" "struct timespec *rmtp" .Sh DESCRIPTION .Fn nanosleep -suspends execution of the calling process for the time specified. An unmasked -signal will cause it to terminate the sleep early, regardless of the +suspends execution of the calling process for the time specified. +An unmasked signal will cause it to terminate the sleep early, +regardless of the .Dv SA_RESTART value on the interrupting signal. .Sh RETURN VALUES @@ -64,8 +65,7 @@ will be the \-1, and the global variable will be set to indicate the interruption. If .Fa rmtp -is non-null, -the timespec structure it references is updated to contain the +is non-null, the timespec structure it references is updated to contain the unslept amount (the request time minus the time actually slept). .Sh ERRORS If any of the following conditions occur, the @@ -79,8 +79,7 @@ Either .Fa rqtp or .Fa rmtp -points to memory that is not a valid part of the process -address space. +points to memory that is not a valid part of the process address space. .It Bq Er EINTR .Nm was interrupted by the delivery of a signal. diff --git a/lib/libc/sys/open.2 b/lib/libc/sys/open.2 index 8cd7e13b20f..a8acb4150f9 100644 --- a/lib/libc/sys/open.2 +++ b/lib/libc/sys/open.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: open.2,v 1.17 2000/09/30 16:17:20 millert Exp $ +.\" $OpenBSD: open.2,v 1.18 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: open.2,v 1.8 1995/02/27 12:35:14 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -86,7 +86,8 @@ O_NOFOLLOW if last path element is a symlink, don't follow it Opening a file with .Dv O_APPEND set causes each write on the file -to be appended to the end. If +to be appended to the end. +If .Dv O_TRUNC and a writing mode are specified and the file exists, the file is truncated to zero length. @@ -97,8 +98,8 @@ is set with and the file already exists, .Fn open -returns an error. This may be used to -implement a simple exclusive access locking mechanism. +returns an error. +This may be used to implement a simple exclusive access locking mechanism. If either of .Dv O_EXCL or @@ -111,7 +112,8 @@ link points to a non-existent name. If the .Dv O_NONBLOCK flag is specified, do not wait for the device or file to be ready or -available. If the +available. +If the .Fn open call would result in the process being blocked for some reason (e.g., waiting for diff --git a/lib/libc/sys/pipe.2 b/lib/libc/sys/pipe.2 index 3eb80aa5d3c..957f9bcf215 100644 --- a/lib/libc/sys/pipe.2 +++ b/lib/libc/sys/pipe.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pipe.2,v 1.7 1999/06/29 14:10:13 aaron Exp $ +.\" $OpenBSD: pipe.2,v 1.8 2000/10/18 05:12:10 aaron Exp $ .\" $NetBSD: pipe.2,v 1.6 1995/02/27 12:35:27 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -47,11 +47,9 @@ .Sh DESCRIPTION The .Fn pipe -function -creates a +function creates a .Em pipe , -which is an object allowing -unidirectional data flow, +which is an object allowing unidirectional data flow, and allocates a pair of file descriptors. The first descriptor connects to the .Em read end @@ -62,31 +60,24 @@ so that data written to .Fa fildes[1] appears on (i.e., can be read from) .Fa fildes[0] . -This allows the output of one program to be -sent -to another program: -the source's standard output is set up to be -the write end of the pipe, -and the sink's standard input is set up to be -the read end of the pipe. -The pipe itself persists until all its associated descriptors are -closed. +This allows the output of one program to be sent to another program: +the source's standard output is set up to be the write end of the pipe, +and the sink's standard input is set up to be the read end of the pipe. +The pipe itself persists until all its associated descriptors are closed. .Pp A pipe whose read or write end has been closed is considered .Em widowed . -Writing on such a pipe causes the writing process to receive -a +Writing on such a pipe causes the writing process to receive a .Dv SIGPIPE signal. Widowing a pipe is the only way to deliver end-of-file to a reader: after the reader consumes any buffered data, reading a widowed pipe returns a zero count. .Sh RETURN VALUES -On successful creation of the pipe, zero is returned. Otherwise, -a value of \-1 is returned and the variable +On successful creation of the pipe, zero is returned. +Otherwise, a value of \-1 is returned and the variable .Va errno -set to indicate the -error. +set to indicate the error. .Sh ERRORS The .Fn pipe @@ -99,8 +90,7 @@ The system file table is full. .It Bq Er EFAULT The .Fa fildes -buffer is in an invalid area of the process's address -space. +buffer is in an invalid area of the process's address space. .El .Sh SEE ALSO .Xr sh 1 , diff --git a/lib/libc/sys/poll.2 b/lib/libc/sys/poll.2 index e2af63826c5..30a65ba9889 100644 --- a/lib/libc/sys/poll.2 +++ b/lib/libc/sys/poll.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: poll.2,v 1.9 2000/08/09 12:59:28 aaron Exp $ +.\" $OpenBSD: poll.2,v 1.10 2000/10/18 05:12:11 aaron Exp $ .\" .\" Copyright (c) 1994 Jason R. Thorpe .\" All rights reserved. @@ -59,7 +59,8 @@ struct pollfd { .Pp The .Pa fd -member is an open file descriptor. The +member is an open file descriptor. +The .Pa events and .Pa revents @@ -70,10 +71,11 @@ The number of .Nm pollfd structures in the array. .It Pa timeout -Maximum interval to wait for the poll to complete, in milliseconds. If -this value is 0, then +Maximum interval to wait for the poll to complete, in milliseconds. +If this value is 0, then .Fn poll -will return immediately. If this value is less than 0, +will return immediately. +If this value is less than 0, .Fn poll will block indefinitely until a condition is found. .El @@ -84,11 +86,13 @@ bitmask and .Fn poll sets the .Pa revents -bitmask. Each call to +bitmask. +Each call to .Fn poll resets the .Pa revents -bitmask for accuracy. The condition flags in the bitmasks are defined as: +bitmask for accuracy. +The condition flags in the bitmasks are defined as: .Bl -tag -width POLLRDNORM .It Nm POLLIN Data is available on the file descriptor for reading. @@ -133,14 +137,15 @@ and their synonyms are for use only in the .Pa revents member of the .Nm pollfd -structure. An attempt to set any of these flags in the +structure. +An attempt to set any of these flags in the .Pa events member will generate an error condition. .Pp In addition to I/O multiplexing, .Fn poll -can be used to generate simple timeouts. This functionality may be achieved -by passing a null pointer for +can be used to generate simple timeouts. +This functionality may be achieved by passing a null pointer for .Pa fds . .Sh WARNINGS The @@ -151,8 +156,10 @@ Upon error, .Fn poll returns a \-1 and sets the global variable .Va errno -to indicate the error. If the timeout interval was reached before any events -occurred, a 0 is returned. Otherwise, +to indicate the error. +If the timeout interval was reached before any events occurred, +a 0 is returned. +Otherwise, .Fn poll returns the number of file descriptors for which .Pa revents diff --git a/lib/libc/sys/profil.2 b/lib/libc/sys/profil.2 index 2a4cf5d283e..7f4eccc6859 100644 --- a/lib/libc/sys/profil.2 +++ b/lib/libc/sys/profil.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: profil.2,v 1.6 1999/07/02 16:57:49 aaron Exp $ +.\" $OpenBSD: profil.2,v 1.7 2000/10/18 05:12:11 aaron Exp $ .\" $NetBSD: profil.2,v 1.3 1995/11/22 23:07:23 cgd Exp $ .\" .\" Copyright (c) 1993 @@ -50,10 +50,8 @@ .Sh DESCRIPTION The .Fn profil -function enables or disables -program counter profiling of the current process. -If profiling is enabled, -then at every clock tick, +function enables or disables program counter profiling of the current process. +If profiling is enabled, then at every clock tick, the kernel updates an appropriate count in the .Fa samples buffer. @@ -62,26 +60,24 @@ The buffer .Fa samples contains .Fa size -bytes and is divided into -a series of 16-bit bins. -Each bin counts the number of times the program counter -was in a particular address range in the process -when a clock tick occurred while profiling was enabled. -For a given program counter address, -the number of the corresponding bin is given -by the relation: +bytes and is divided into a series of 16-bit bins. +Each bin counts the number of times the program counter was in a particular +address range in the process when a clock tick occurred while profiling +was enabled. +For a given program counter address, the number of the corresponding bin +is given by the relation: .Bd -literal -offset indent [(pc - offset) / 2] * scale / 65536 .Ed .Pp The .Fa offset -parameter is the lowest address at which -the kernel takes program counter samples. +parameter is the lowest address at which the kernel takes program +counter samples. The .Fa scale -parameter ranges from 1 to 65536 and -can be used to change the span of the bins. +parameter ranges from 1 to 65536 and can be used to change the +span of the bins. A scale of 65536 maps each bin to 2 bytes of address range; a scale of 32768 gives 4 bytes, 16384 gives 8 bytes and so on. Intermediate values provide approximate intermediate ranges. @@ -95,11 +91,10 @@ value is nonzero and the buffer .Fa samples contains an illegal address, .Fn profil -returns \-1, -profiling is terminated and +returns \-1, profiling is terminated, and .Va errno is set appropriately. -Otherwise +Otherwise, .Fn profil returns 0. .Sh FILES diff --git a/lib/libc/sys/ptrace.2 b/lib/libc/sys/ptrace.2 index cbaf81ea788..cda3c16163b 100644 --- a/lib/libc/sys/ptrace.2 +++ b/lib/libc/sys/ptrace.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ptrace.2,v 1.7 1999/06/29 14:10:14 aaron Exp $ +.\" $OpenBSD: ptrace.2,v 1.8 2000/10/18 05:12:11 aaron Exp $ .\" $NetBSD: ptrace.2,v 1.3 1996/02/23 01:39:41 jtc Exp $ .\" .\" This file is in the public domain. @@ -15,17 +15,20 @@ .Fn ptrace "int request" "pid_t pid" "caddr_t addr" "int data" .Sh DESCRIPTION .Fn ptrace -provides tracing and debugging facilities. It allows one process (the +provides tracing and debugging facilities. +It allows one process (the .Em tracing process) to control another (the .Em traced -process). Most of the time, the traced process runs normally, but when +process). +Most of the time, the traced process runs normally, but when it receives a signal .Po see .Xr sigaction 2 .Pc , -it stops. The tracing process is expected to notice this via +it stops. +The tracing process is expected to notice this via .Xr wait 2 or the delivery of a .Dv SIGCHLD @@ -48,10 +51,11 @@ can be: .Bl -tag -width 12n .It Dv PT_TRACE_ME This request is the only one used by the traced process; it declares -that the process expects to be traced by its parent. All the other -arguments are ignored. (If the parent process does not expect to trace -the child, it will probably be rather confused by the results; once the -traced process stops, it cannot be made to continue except via +that the process expects to be traced by its parent. +All the other arguments are ignored. +(If the parent process does not expect to trace the child, it will +probably be rather confused by the results; once the traced process stops, +it cannot be made to continue except via .Eo \& .Fn ptrace .Ec \&.) @@ -68,20 +72,25 @@ be ignored. .It Dv PT_READ_I , Dv PT_READ_D These requests read a single .Li int -of data from the traced process' address space. Traditionally, +of data from the traced process' address space. +Traditionally, .Fn ptrace has allowed for machines with distinct address spaces for instruction and data, which is why there are two requests: conceptually, .Dv PT_READ_I reads from the instruction space and .Dv PT_READ_D -reads from the data space. In the current OpenBSD implementation, these -two requests are completely identical. The +reads from the data space. +In the current +.Ox +implementation, these +two requests are completely identical. +The .Fa addr argument specifies the address (in the traced process' virtual address -space) at which the read is to be done. This address does not have to -meet any alignment constraints. The value read is returned as the -return value from +space) at which the read is to be done. +This address does not have to meet any alignment constraints. +The value read is returned as the return value from .Eo \& .Fn ptrace .Ec . @@ -90,7 +99,8 @@ These requests parallel .Dv PT_READ_I and .Dv PT_READ_D , -except that they write rather than read. The +except that they write rather than read. +The .Fa data argument supplies the value to be written. .\" .It Dv PT_READ_U @@ -147,15 +157,17 @@ had been used with given as the signal to be delivered. .It Dv PT_ATTACH This request allows a process to gain control of an otherwise unrelated -process and begin tracing it. It does not need any cooperation from -the to-be-traced process. In this case, +process and begin tracing it. +It does not need any cooperation from the to-be-traced process. +In this case, .Fa pid specifies the process ID of the to-be-traced process, and the other two -arguments are ignored. This request requires that the target process -must have the same real UID as the tracing process, and that it must -not be executing a setuid or setgid executable. (If the tracing -process is running as root, these restrictions do not apply.) The -tracing process will see the newly traced process stop and may then +arguments are ignored. +This request requires that the target process must have the same real UID +as the tracing process, and that it must not be executing a set-user-ID +or set-group-ID executable. +(If the tracing process is running as root, these restrictions do not apply.) +The tracing process will see the newly traced process stop and may then control it as if it had been traced all along. .It Dv PT_DETACH This request is like @@ -166,8 +178,8 @@ succeeds, the traced process is no longer traced and continues execution normally. .El .Pp -Additionally, machine-specific requests can exist. On the SPARC, these -are: +Additionally, machine-specific requests can exist. +On the SPARC, these are: .Bl -tag -width 12n .It Dv PT_GETREGS This request reads the traced process' machine registers into the @@ -305,8 +317,8 @@ to return .Li -1 as a non-error value; to disambiguate, .Va errno -is set to zero and this should be checked. The possible -errors are: +is set to zero and this should be checked. +The possible errors are: .Bl -tag -width 4n .It Bq Er ESRCH No process having the specified process ID exists. @@ -343,8 +355,8 @@ was neither 0 nor a legal signal number. .Dv PT_GETFPREGS , or .Dv PT_SETFPREGS -was attempted on a process with no valid register set. (This is -normally true only of system processes.) +was attempted on a process with no valid register set. +(This is normally true only of system processes.) .El .It Bq Er EBUSY .Bl -bullet -compact @@ -377,7 +389,8 @@ above. On the SPARC, the PC is set to the provided PC value for .Dv PT_CONTINUE and similar calls, but the NPC is set willy-nilly to 4 greater than the -PC value. Using +PC value. +Using .Dv PT_GETREGS and .Dv PT_SETREGS diff --git a/lib/libc/sys/read.2 b/lib/libc/sys/read.2 index dcded040878..b1471a2e60c 100644 --- a/lib/libc/sys/read.2 +++ b/lib/libc/sys/read.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: read.2,v 1.16 2000/04/20 06:34:37 deraadt Exp $ +.\" $OpenBSD: read.2,v 1.17 2000/10/18 05:12:11 aaron Exp $ .\" $NetBSD: read.2,v 1.6 1995/02/27 12:35:47 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -111,8 +111,8 @@ Upon return from the pointer is incremented by the number of bytes actually read. .Pp Objects that are not capable of seeking always read from the current -position. The value of the pointer associated with such an -object is undefined. +position. +The value of the pointer associated with such an object is undefined. .Pp Upon successful completion, .Fn read @@ -135,8 +135,8 @@ exceedes the constant .Dv IOV_MAX . .Sh RETURN VALUES If successful, the -number of bytes actually read is returned. Upon reading end-of-file, -zero is returned. +number of bytes actually read is returned. +Upon reading end-of-file, zero is returned. Otherwise, a \-1 is returned and the global variable .Va errno is set to indicate the error. @@ -253,8 +253,7 @@ function appeared in .At V.4 . The .Fn readv -function call -appeared in +function call appeared in .Bx 4.2 . The .Fn read diff --git a/lib/libc/sys/reboot.2 b/lib/libc/sys/reboot.2 index 774f4da9652..8bc69c554ef 100644 --- a/lib/libc/sys/reboot.2 +++ b/lib/libc/sys/reboot.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: reboot.2,v 1.7 2000/04/15 11:46:04 aaron Exp $ +.\" $OpenBSD: reboot.2,v 1.8 2000/10/18 05:12:11 aaron Exp $ .\" $NetBSD: reboot.2,v 1.5 1995/02/27 12:36:02 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -100,8 +100,7 @@ Load the symbol table and enable a built-in debugger in the system. This option will have no useful function if the kernel is not configured for debugging. Several other options have different meaning if combined -with this option, although their use may not be possible -via the +with this option, although their use may not be possible via the .Fn reboot call. See @@ -153,12 +152,13 @@ The caller is not the superuser. .Xr init 8 , .Xr reboot 8 , .Xr savecore 8 -.Sh BUGS -Not all platforms support all possible arguments. For example, -.Dv RB_POWERDOWN -is supported only on the i386, sparc, and mac68k platforms. .Sh HISTORY The .Fn reboot function call appeared in .Bx 4.0 . +.Sh BUGS +Not all platforms support all possible arguments. +For example, +.Dv RB_POWERDOWN +is supported only on the i386, sparc, and mac68k platforms. diff --git a/lib/libc/sys/recv.2 b/lib/libc/sys/recv.2 index 9630db8a2b7..083f3ec758b 100644 --- a/lib/libc/sys/recv.2 +++ b/lib/libc/sys/recv.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: recv.2,v 1.23 2000/04/15 02:15:24 aaron Exp $ +.\" $OpenBSD: recv.2,v 1.24 2000/10/18 05:12:11 aaron Exp $ .\" $NetBSD: recv.2,v 1.6 1995/02/27 12:36:08 cgd Exp $ .\" .\" Copyright (c) 1983, 1990, 1991, 1993 @@ -55,9 +55,8 @@ .Fn recvfrom and .Fn recvmsg -are used to receive messages from a socket, -and may be used to receive data on a socket whether or not -it is connection-oriented. +are used to receive messages from a socket, and may be used to receive +data on a socket whether or not it is connection-oriented. .Pp If .Fa from @@ -84,7 +83,8 @@ parameter. As it is redundant, it may not be supported in future releases. .Pp On successful completion, all three routines return the number of -message bytes read. If a message is too long to fit in the supplied +message bytes read. +If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from (see .Xr socket 2 ) . @@ -211,8 +211,8 @@ set to .Pp The .Fa msg_flags -field is set on return according to the message received. It will contain -zero or more of the following values: +field is set on return according to the message received. +It will contain zero or more of the following values: .Bl -column MSG_CTRUNC -offset indent .It Dv MSG_EOR Ta Indicates end-of-record; @@ -234,8 +234,7 @@ Indicates that the packet was received as broadcast. Indicates that the packet was received as multicast. .El .Sh RETURN VALUES -These calls return the number of bytes received, or \-1 -if an error occurred. +These calls return the number of bytes received, or \-1 if an error occurred. .Sh ERRORS .Fn recv , .Fn recvfrom , diff --git a/lib/libc/sys/rename.2 b/lib/libc/sys/rename.2 index 67b774dbe7d..6ea22b43b7a 100644 --- a/lib/libc/sys/rename.2 +++ b/lib/libc/sys/rename.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: rename.2,v 1.7 1999/06/29 14:10:16 aaron Exp $ +.\" $OpenBSD: rename.2,v 1.8 2000/10/18 05:12:11 aaron Exp $ .\" $NetBSD: rename.2,v 1.7 1995/02/27 12:36:15 cgd Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -71,32 +71,6 @@ If the final component of is a symbolic link, the symbolic link is renamed, not the file or directory to which it points. -.Sh CAVEAT -The system can deadlock if a loop in the file system graph is present. -This loop takes the form of an entry in directory -.Ql Pa a , -say -.Ql Pa a/foo , -being a hard link to directory -.Ql Pa b , -and an entry in -directory -.Ql Pa b , -say -.Ql Pa b/bar , -being a hard link -to directory -.Ql Pa a . -When such a loop exists and two separate processes attempt to -perform -.Ql rename a/foo b/bar -and -.Ql rename b/bar a/foo , -respectively, -the system may deadlock attempting to lock -both directories for modification. -Hard links to directories should be -replaced by symbolic links by the system administrator. .Sh RETURN VALUES A 0 value is returned if the operation succeeds, otherwise .Fn rename @@ -165,9 +139,9 @@ The link named by .Fa to and the file named by .Fa from -are on different logical devices (file systems). Note that this error -code will not be returned if the implementation permits cross-device -links. +are on different logical devices (file systems). +Note that this error code will not be returned if the implementation +permits cross-device links. .It Bq Er ENOSPC The directory in which the entry for the new name is being placed cannot be extended because there is no space left on the file @@ -205,3 +179,29 @@ The .Fn rename function conforms to .St -p1003.1-88 . +.Sh CAVEATS +The system can deadlock if a loop in the file system graph is present. +This loop takes the form of an entry in directory +.Ql Pa a , +say +.Ql Pa a/foo , +being a hard link to directory +.Ql Pa b , +and an entry in +directory +.Ql Pa b , +say +.Ql Pa b/bar , +being a hard link +to directory +.Ql Pa a . +When such a loop exists and two separate processes attempt to +perform +.Ql rename a/foo b/bar +and +.Ql rename b/bar a/foo , +respectively, +the system may deadlock attempting to lock +both directories for modification. +Hard links to directories should be +replaced by symbolic links by the system administrator. diff --git a/lib/libc/sys/revoke.2 b/lib/libc/sys/revoke.2 index d9450546445..43f63964779 100644 --- a/lib/libc/sys/revoke.2 +++ b/lib/libc/sys/revoke.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: revoke.2,v 1.6 1999/07/07 17:06:08 art Exp $ +.\" $OpenBSD: revoke.2,v 1.7 2000/10/18 05:12:11 aaron Exp $ .\" $NetBSD: revoke.2,v 1.3 1995/10/12 15:41:11 jtc Exp $ .\" .\" Copyright (c) 1993 @@ -65,14 +65,14 @@ If the file is a special file for a device which is open, the device close function is called as if all open references to the file had been closed. .Pp -Access to a file may be revoked only by its owner or the super user. +Access to a file may be revoked only by its owner or the superuser. The .Nm revoke function is normally used to prepare a terminal device for a new login session, preventing any access by a previous user of the terminal. .Sh RETURN VALUES -A 0 value indicated that the call succeeded. A \-1 return value -indicates an error occurred and +A 0 value indicated that the call succeeded. +A \-1 return value indicates an error occurred and .Va errno is set to indicated the reason. .Sh ERRORS @@ -93,7 +93,7 @@ Too many symbolic links were encountered in translating the pathname. .Fa path points outside the process's allocated address space. .It Bq Er EPERM -The caller is neither the owner of the file nor the super user. +The caller is neither the owner of the file nor the superuser. .El .Sh SEE ALSO .Xr close 2 diff --git a/lib/libc/sys/rfork.2 b/lib/libc/sys/rfork.2 index 982aadd654b..dfc8313953f 100644 --- a/lib/libc/sys/rfork.2 +++ b/lib/libc/sys/rfork.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: rfork.2,v 1.14 1999/07/02 17:04:16 aaron Exp $ +.\" $OpenBSD: rfork.2,v 1.15 2000/10/18 05:12:11 aaron Exp $ .\" .\" This manual page is taken directly from Plan9, and modified to .\" describe the actual OpenBSD implementation. Permission for @@ -39,8 +39,8 @@ If set a new process is created; otherwise changes affect the current process. The current implementation requires this flag to always be set. .It Dv RFNOWAIT -If set, the child process will be dissociated from the parent. Upon -exit the child will not leave a status for the parent to collect. +If set, the child process will be dissociated from the parent. +Upon exit the child will not leave a status for the parent to collect. See .Xr wait 2 . .It Xo Dv RFNAMEG , Dv RFCNAMEG , @@ -59,10 +59,12 @@ Is mutually exclusive with .It Dv RFMEM If set, the kernel will force sharing of the entire address space. The child -will then inherit all the shared segments the parent process owns. Other segment -types will be unaffected. Subsequent forks by the parent will then -propagate the shared data and bss between children. The stack segment -is always split. May be set only with +will then inherit all the shared segments the parent process owns. +Other segment types will be unaffected. +Subsequent forks by the parent will then propagate the shared +data and bss between children. +The stack segment is always split. +May be set only with .Dv RFPROC . .El .Pp diff --git a/lib/libc/sys/select.2 b/lib/libc/sys/select.2 index f3959a85b06..145d1d9a15e 100644 --- a/lib/libc/sys/select.2 +++ b/lib/libc/sys/select.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: select.2,v 1.17 2000/04/15 02:15:24 aaron Exp $ +.\" $OpenBSD: select.2,v 1.18 2000/10/18 05:12:11 aaron Exp $ .\" $NetBSD: select.2,v 1.5 1995/06/27 22:32:28 cgd Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -105,9 +105,11 @@ to the maximum number of descriptors supported by the system. If .Fa timeout is a non-null pointer, it specifies a maximum interval to wait for the -selection to complete. If +selection to complete. +If .Fa timeout -is a null pointer, the select blocks indefinitely. To effect a poll, the +is a null pointer, the select blocks indefinitely. +To effect a poll, the .Fa timeout argument should be non-null, pointing to a zero-valued timeval structure. .Fa timeout @@ -126,15 +128,13 @@ may be given as null pointers if no descriptors are of interest. .Sh RETURN VALUES .Fn select returns the number of ready descriptors that are contained in -the descriptor sets, -or \-1 if an error occurred. +the descriptor sets, or \-1 is an error occurred. If the time limit expires, .Fn select returns 0. If .Fn select -returns with an error, -including one due to an interrupted call, +returns with an error, including one due to an interrupted call, the descriptor sets will be unmodified. .Sh ERRORS An error return from @@ -154,8 +154,8 @@ One of the descriptor sets specified an invalid descriptor. A signal was delivered before the time limit expired and before any of the selected events occurred. .It Bq Er EINVAL -The specified time limit is invalid. One of its components is -negative or too large. +The specified time limit is invalid. +One of its components is negative or too large. .El .Sh SEE ALSO .Xr accept 2 , @@ -189,8 +189,8 @@ system are also ready for large numbers of file descriptors. .Pp Alternatively, to be really safe, it is possible to allocate .Ft fd_set -bit-arrays dynamically. The idea is to permit a program to -work properly even if it is +bit-arrays dynamically. +The idea is to permit a program to work properly even if it is .Xr execve 2 Ns 'd with 4000 file descriptors pre-allocated. The following illustrates the technique which is used by diff --git a/lib/libc/sys/semctl.2 b/lib/libc/sys/semctl.2 index 7fa582ddb2b..17a9db5fe06 100644 --- a/lib/libc/sys/semctl.2 +++ b/lib/libc/sys/semctl.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: semctl.2,v 1.11 2000/04/15 11:46:04 aaron Exp $ +.\" $OpenBSD: semctl.2,v 1.12 2000/10/18 05:12:11 aaron Exp $ .\" $NetBSD: semctl.2,v 1.2 1997/03/27 08:20:40 mikel Exp $ .\" .\" Copyright (c) 1995 Frank van der Linden @@ -155,8 +155,8 @@ in the data structure associated with the message queue. .It Dv IPC_RMID Remove the semaphores associated with .Fa semid -from the system and destroy the data structures associated with it. Only the -superuser or a process with an effective UID equal to the +from the system and destroy the data structures associated with it. +Only the superuser or a process with an effective UID equal to the .Va sem_perm.cuid or .Va sem_perm.uid @@ -188,10 +188,11 @@ and .Dv GETZCNT operations, .Fn semctl -returns one of the values described above if successful. All other operations -will make +returns one of the values described above if successful. +All other operations will make .Fn semctl -return 0 if no errors occur. Otherwise \-1 is returned and +return 0 if no errors occur. +Otherwise \-1 is returned and .Va errno set to reflect the error. .Sh ERRORS diff --git a/lib/libc/sys/semget.2 b/lib/libc/sys/semget.2 index 3a5e58a517d..0e4d0a9cd93 100644 --- a/lib/libc/sys/semget.2 +++ b/lib/libc/sys/semget.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: semget.2,v 1.10 1999/06/29 14:10:17 aaron Exp $ +.\" $OpenBSD: semget.2,v 1.11 2000/10/18 05:12:11 aaron Exp $ .\" $NetBSD: semget.2,v 1.2 1997/03/27 08:20:41 mikel Exp $ .\" .\" Copyright (c) 1995 Frank van der Linden @@ -112,8 +112,8 @@ is set to 0 .El .Sh RETURN VALUES .Fn semget -returns a non-negative semaphore identifier if successful. Otherwise, \-1 -is returned and +returns a non-negative semaphore identifier if successful. +Otherwise, \-1 is returned and .Va errno is set to reflect the error. .Sh ERRORS diff --git a/lib/libc/sys/semop.2 b/lib/libc/sys/semop.2 index eb1e4123f07..1f1029d4c90 100644 --- a/lib/libc/sys/semop.2 +++ b/lib/libc/sys/semop.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: semop.2,v 1.8 1999/07/09 13:35:21 aaron Exp $ +.\" $OpenBSD: semop.2,v 1.9 2000/10/18 05:12:11 aaron Exp $ .\" $NetBSD: semop.2,v 1.1 1995/10/16 23:49:28 jtc Exp $ .\" .\" Copyright (c) 1995 Frank van der Linden @@ -44,13 +44,14 @@ .Fn semop "int semid" "struct sembuf *sops" "int nsops" .Sh DESCRIPTION .Fn semop -provides a number of atomic operations on a set of semaphores. The semaphore -set is specified by +provides a number of atomic operations on a set of semaphores. +The semaphore set is specified by .Fa semid . .Fa sops is an array of semaphore operations, .Fa nsops -is the number of operations in this array. The +is the number of operations in this array. +The .Va sembuf structures in the array contain the following members: .Bd -literal @@ -71,23 +72,27 @@ determines the action taken in the following way: .Bl -bullet .It .Va sem_op -is less than 0. The current process is blocked until the value of the +is less than 0. +The current process is blocked until the value of the semaphore is greater than or equal to the absolute value of .Va sem_op . The absolute value of .Va sem_op is then subtracted from the value of the semaphore, and the calling -process continues. Negative values of +process continues. +Negative values of .Va sem_op are thus used to enter critical regions. .It .Va sem_op -is greater than 0. Its value is added to the value of the specified -semaphore. This is used to leave critical regions. +is greater than 0. +Its value is added to the value of the specified semaphore. +This is used to leave critical regions. .It .Va sem_op -is equal to 0. The calling process is blocked until the value of the -specified semaphore reaches 0. +is equal to 0. +The calling process is blocked until the value of the specified +semaphore reaches 0. .El .Pp The behavior of each operation is influenced by the flags set in @@ -105,14 +110,14 @@ to .Er EAGAIN . .It Dv SEM_UNDO Keep track of the changes that this call makes to the value of a semaphore, -so that they can be undone when the calling process terminates. This is -useful to prevent other processes waiting on a semaphore to block forever, -should the process that has the semaphore locked terminate in a critical -section. +so that they can be undone when the calling process terminates. +This is useful to prevent other processes waiting on a semaphore to +block forever, should the process that has the semaphore locked +terminate in a critical section. .El .Sh RETURN VALUES -Upon successful completion, a value of 0 is returned. Otherwise, \-1 is -returned and the global variable +Upon successful completion, a value of 0 is returned. +Otherwise, \-1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS @@ -131,7 +136,8 @@ The calling process has no permission to access the specified semaphore set. .It Bq Er E2BIG The value of .Fa nsops -is too big. The maximum is specified in MAX_SOPS in <sys/sem.h> +is too big. +The maximum is specified in MAX_SOPS in <sys/sem.h> .It Bq Er EFBIG .Va sem_num in one of the sem_buf structures is less than 0, or greater than the actual @@ -158,4 +164,6 @@ In case of a removed semaphore identifier, .Va errno should be set to .Er EIDRM , -but OpenBSD does not define this error. +but +.Ox +does not define this error. diff --git a/lib/libc/sys/send.2 b/lib/libc/sys/send.2 index e5cb99fd318..080cd36db80 100644 --- a/lib/libc/sys/send.2 +++ b/lib/libc/sys/send.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: send.2,v 1.18 2000/03/14 21:31:40 aaron Exp $ +.\" $OpenBSD: send.2,v 1.19 2000/10/18 05:12:11 aaron Exp $ .\" $NetBSD: send.2,v 1.6 1996/01/15 01:17:18 thorpej Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -167,11 +167,11 @@ The destination address specified a host that is down. .It Bq Er ENETDOWN The destination address specified a network that is down. .It Bq Er ECONNREFUSED -The destination host rejected the message (or a previous one). This error -can only be returned by connected sockets. +The destination host rejected the message (or a previous one). +This error can only be returned by connected sockets. .It Bq Er ENOPROTOOPT -There was a problem sending the message. This error can only be returned by -connected sockets. +There was a problem sending the message. +This error can only be returned by connected sockets. .It Bq Er EDESTADDRREQ The socket is not connected, and no destination address was specified. .It Bq Er EISCONN diff --git a/lib/libc/sys/setuid.2 b/lib/libc/sys/setuid.2 index f7c06d00754..558700fa280 100644 --- a/lib/libc/sys/setuid.2 +++ b/lib/libc/sys/setuid.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: setuid.2,v 1.9 1999/07/02 20:58:01 aaron Exp $ +.\" $OpenBSD: setuid.2,v 1.10 2000/10/18 05:12:11 aaron Exp $ .\" $NetBSD: setuid.2,v 1.3 1995/02/27 12:37:06 cgd Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -57,29 +57,25 @@ .Sh DESCRIPTION The .Fn setuid -function -sets the real and effective -user IDs and the saved set-user-ID of the current process -to the specified value. +function sets the real and effective user IDs and the saved set-user-ID +of the current process to the specified value. The .Fn setuid -function is permitted if the effective user ID is that of the super user, -or if the specified user ID is the same as the effective user ID. If -not, but the specified user ID is the same as the real user ID, +function is permitted if the effective user ID is that of the superuser, +or if the specified user ID is the same as the effective user ID. +If not, but the specified user ID is the same as the real user ID, .Fn setuid will set the effective user ID to the real user ID. .Pp The .Fn setgid -function -sets the real and effective -group IDs and the saved set-group-ID of the current process -to the specified value. +function sets the real and effective groups IDs and the saved set-group-ID +of the current process to the specified value. The .Fn setgid -function is permitted if the effective user ID is that of the super user, -or if the specified group ID is the same as the effective group ID. If -not, but the specified group ID is the same as the real group ID, +function is permitted if the effective user ID is that of the superuser, +or if the specified group ID is the same as the effective group ID. +If not, but the specified group ID is the same as the real group ID, .Fn setgid will set the effective group ID to the real group ID. .Pp @@ -87,8 +83,7 @@ The .Fn seteuid function .Pq Fn setegid -sets the effective user ID (group ID) of the -current process. +sets the effective user ID (group ID) of the current process. The effective user ID may be set to the value of the real user ID or the saved set-user-ID (see .Xr intro 2 @@ -103,7 +98,7 @@ of the real group ID or the saved set-group-ID. Upon success, these functions return 0; otherwise \-1 is returned. .Pp -If the user is not the super user, or the uid +If the user is not the superuser, or the UID specified is not the real, effective ID, or saved ID, these functions return \-1. .Sh SEE ALSO diff --git a/lib/libc/sys/shmat.2 b/lib/libc/sys/shmat.2 index 8d93f37adfb..43b29eb7fab 100644 --- a/lib/libc/sys/shmat.2 +++ b/lib/libc/sys/shmat.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: shmat.2,v 1.10 2000/04/15 02:15:25 aaron Exp $ +.\" $OpenBSD: shmat.2,v 1.11 2000/10/18 05:12:11 aaron Exp $ .\" $NetBSD: shmat.2,v 1.2 1997/03/27 08:20:38 mikel Exp $ .\" .\" Copyright (c) 1995 Frank van der Linden @@ -49,14 +49,16 @@ .Fn shmat maps the shared memory segment associated with the shared memory identifier .Fa shmid -into the address space of the calling process. The address at which the -segment is mapped is determined by the +into the address space of the calling process. +The address at which the segment is mapped is determined by the .Fa shmaddr -parameter. If it is equal to 0, the system will pick an address itself. +parameter. +If it is equal to 0, the system will pick an address itself. Otherwise, an attempt is made to map the shared memory segment at the address .Fa shmaddr -specifies. If +specifies. +If .Dv SHM_RND is set in .Fa shmflg , @@ -79,7 +81,8 @@ from the calling process' address space. .Fa shmaddr must be a value returned by a prior .Fn shmat -call. A shared memory segment will remain existent until it is removed by +call. +A shared memory segment will remain existent until it is removed by a call to .Xr shmctl 2 with the @@ -90,8 +93,8 @@ command. returns the address at which the shared memory segment has been mapped into the calling process' address space when successful, .Fn shmdt -returns 0 on successful completion. Otherwise, a value of \-1 is returned, -and the global variable +returns 0 on successful completion. +Otherwise, a value of \-1 is returned, and the global variable .Va errno is set to indicate the error. .Sh ERRORS diff --git a/lib/libc/sys/shmctl.2 b/lib/libc/sys/shmctl.2 index e99cac41bd9..23b8f28a058 100644 --- a/lib/libc/sys/shmctl.2 +++ b/lib/libc/sys/shmctl.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: shmctl.2,v 1.11 2000/04/15 11:46:04 aaron Exp $ +.\" $OpenBSD: shmctl.2,v 1.12 2000/10/18 05:12:11 aaron Exp $ .\" $NetBSD: shmctl.2,v 1.3 1997/03/27 08:20:39 mikel Exp $ .\" .\" Copyright (c) 1995 Frank van der Linden @@ -125,8 +125,8 @@ in the data structure associated with the shared memory segment. .It Dv IPC_RMID Remove the shared memory segment specified by .Fa shmid -and destroy the data associated with it. Only the superuser or a process -with an effective UID equal to the +and destroy the data associated with it. +Only the superuser or a process with an effective UID equal to the .Va shm_perm.cuid or .Va shm_perm.uid @@ -149,8 +149,8 @@ effective GID can match either or .Va shm_perm.gid . .Sh RETURN VALUES -Upon successful completion, a value of 0 is returned. Otherwise, \-1 is -returned and the global variable +Upon successful completion, a value of 0 is returned. +Otherwise, \-1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS diff --git a/lib/libc/sys/sigaction.2 b/lib/libc/sys/sigaction.2 index 22678515836..b55a4c4dd87 100644 --- a/lib/libc/sys/sigaction.2 +++ b/lib/libc/sys/sigaction.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sigaction.2,v 1.23 2000/08/05 22:04:19 pjanzen Exp $ +.\" $OpenBSD: sigaction.2,v 1.24 2000/10/18 05:12:12 aaron Exp $ .\" $NetBSD: sigaction.2,v 1.7 1995/10/12 15:41:16 jtc Exp $ .\" .\" Copyright (c) 1980, 1990, 1993 @@ -62,7 +62,8 @@ struct sigaction { The system defines a set of signals that may be delivered to a process. Signal delivery resembles the occurrence of a hardware interrupt: the signal is normally blocked from further occurrence, the current process -context is saved, and a new one is built. A process may specify a +context is saved, and a new one is built. +A process may specify a .Em handler to which a signal is delivered, or specify that a signal is to be .Em ignored . @@ -75,7 +76,8 @@ in which case its delivery is postponed until it is The action to be taken on delivery is determined at the time of delivery. Normally, signal handlers execute on the current stack -of the process. This may be changed, on a per-handler basis, +of the process. +This may be changed, on a per-handler basis, so that signals are taken on a special .Em "signal stack" . .Pp @@ -86,9 +88,10 @@ but other signals may yet occur. A global .Em "signal mask" defines the set of signals currently blocked from delivery -to a process. The signal mask for a process is initialized -from that of its parent (normally empty). It -may be changed with a +to a process. +The signal mask for a process is initialized from that of its +parent (normally empty). +It may be changed with a .Xr sigprocmask 2 call, or when a signal is delivered to the process. .Pp @@ -111,10 +114,10 @@ function. When a caught signal is delivered, the current state of the process is saved, a new signal mask is calculated (as described below), -and the signal handler is invoked. The call to the handler -is arranged so that if the signal handling routine returns -normally the process will resume execution in the context -from before the signal's delivery. +and the signal handler is invoked. +The call to the handler is arranged so that if the signal handling routine +returns normally the process will resume execution in the context from +before the signal's delivery. If the process wishes to resume in a different context, then it must arrange to restore the previous context itself. .Pp @@ -203,8 +206,8 @@ If this bit is set when calling for the .Dv SIGCHLD signal, the system will not create zombie processes when children of -the calling process exit. If the calling process subsequently issues -a +the calling process exit. +If the calling process subsequently issues a .Xr wait 2 (or equivalent), it blocks until all of the calling process's child processes terminate, and then returns a value of \-1 with @@ -481,8 +484,7 @@ handler(sig, sip, scp) .Pp Here .Fa sig -is the signal number, into which the hardware faults and traps are -mapped. +is the signal number, into which the hardware faults and traps are mapped. If the .Dv SA_SIGINFO option is set, @@ -537,8 +539,7 @@ The .Dv SA_ONSTACK and .Dv SA_RESTART -flags are Berkeley extensions, -as are the signals +flags are Berkeley extensions, as are the signals .Dv SIGTRAP , .Dv SIGEMT , .Dv SIGBUS , @@ -560,7 +561,8 @@ The and .Dv SA_RESETHAND flags are intended for backwards compatibility with other operating -systems. The +systems. +The .Dv SA_NOCLDSTOP , .Dv SA_NOCLDWAIT , and diff --git a/lib/libc/sys/sigpending.2 b/lib/libc/sys/sigpending.2 index 043d76336ed..86a3aa83ed5 100644 --- a/lib/libc/sys/sigpending.2 +++ b/lib/libc/sys/sigpending.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sigpending.2,v 1.2 1998/07/06 18:28:36 deraadt Exp $ +.\" $OpenBSD: sigpending.2,v 1.3 2000/10/18 05:12:12 aaron Exp $ .\" $NetBSD: sigpending.2,v 1.2 1995/02/27 12:37:26 cgd Exp $ .\" .\" Copyright (c) 1993 @@ -57,8 +57,8 @@ Signals may be pending because they are currently masked, or transiently before delivery (although the latter case is not normally detectable). .Sh RETURN VALUES -A 0 value indicated that the call succeeded. A \-1 return value -indicates an error occurred and +A 0 value indicated that the call succeeded. +A \-1 return value indicates an error occurred and .Va errno is set to indicated the reason. .Sh ERRORS diff --git a/lib/libc/sys/sigprocmask.2 b/lib/libc/sys/sigprocmask.2 index 3b8e9ac9e15..a6ffd2c242c 100644 --- a/lib/libc/sys/sigprocmask.2 +++ b/lib/libc/sys/sigprocmask.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sigprocmask.2,v 1.4 1999/06/29 14:10:22 aaron Exp $ +.\" $OpenBSD: sigprocmask.2,v 1.5 2000/10/18 05:12:12 aaron Exp $ .\" $NetBSD: sigprocmask.2,v 1.6 1995/02/27 12:37:33 cgd Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -96,8 +96,8 @@ or .Dv SIGSTOP to be blocked. .Sh RETURN VALUES -A 0 value indicated that the call succeeded. A \-1 return value -indicates an error occurred and +A 0 value indicated that the call succeeded. +A \-1 return value indicates an error occurred and .Va errno is set to indicated the reason. .Sh ERRORS @@ -118,6 +118,5 @@ has a value other than those listed here. .Sh STANDARDS The .Fn sigprocmask -function call is expected to -conform to +function call is expected to conform to .St -p1003.1-88 . diff --git a/lib/libc/sys/sigsuspend.2 b/lib/libc/sys/sigsuspend.2 index 69b131564a3..8ef998085d3 100644 --- a/lib/libc/sys/sigsuspend.2 +++ b/lib/libc/sys/sigsuspend.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sigsuspend.2,v 1.6 2000/01/22 12:05:49 aaron Exp $ +.\" $OpenBSD: sigsuspend.2,v 1.7 2000/10/18 05:12:12 aaron Exp $ .\" $NetBSD: sigsuspend.2,v 1.4 1995/02/27 12:37:46 cgd Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -66,8 +66,7 @@ with the previous mask returned by .Sh RETURN VALUES The .Fn sigsuspend -function -always terminates by being interrupted, returning \-1 with +function always terminates by being interrupted, returning \-1 with .Va errno set to .Er EINTR . diff --git a/lib/libc/sys/socket.2 b/lib/libc/sys/socket.2 index c69415a8018..1439d243820 100644 --- a/lib/libc/sys/socket.2 +++ b/lib/libc/sys/socket.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: socket.2,v 1.17 2000/05/24 15:19:28 itojun Exp $ +.\" $OpenBSD: socket.2,v 1.18 2000/10/18 05:12:12 aaron Exp $ .\" $NetBSD: socket.2,v 1.5 1995/02/27 12:37:53 cgd Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -70,8 +70,8 @@ AF_IMPLINK (IMP \*(lqhost at IMP\*(rq link layer). .Pp The socket has the indicated .Fa type , -which specifies the semantics of communication. Currently -defined types are: +which specifies the semantics of communication. +Currently defined types are: .Pp .Bd -literal -offset indent -compact SOCK_STREAM @@ -113,11 +113,11 @@ The .Fa protocol specifies a particular protocol to be used with the socket. Normally only a single protocol exists to support a particular -socket type within a given protocol family. However, it is possible -that many protocols may exist, in which case a particular protocol -must be specified in this manner. The protocol number to use is -particular to the \*(lqcommunication domain\*(rq in which communication -is to take place; see +socket type within a given protocol family. +However, it is possible that many protocols may exist, +in which case a particular protocol must be specified in this manner. +The protocol number to use is particular to the \*(lqcommunication domain\*(rq +in which communication is to take place; see .Xr protocols 5 . A value of 0 for .Fa protocol @@ -126,13 +126,14 @@ socket type. .Pp Sockets of type .Dv SOCK_STREAM -are full-duplex byte streams, similar -to pipes. A stream socket must be in a +are full-duplex byte streams, similar to pipes. +A stream socket must be in a .Em connected -state before any data may be sent or received -on it. A connection to another socket is created with a +state before any data may be sent or received on it. +A connection to another socket is created with a .Xr connect 2 -call. Once connected, data may be transferred using +call. +Once connected, data may be transferred using .Xr read 2 and .Xr write 2 @@ -140,7 +141,8 @@ calls or some variant of the .Xr send 2 and .Xr recv 2 -calls. When a session has been completed a +calls. +When a session has been completed a .Xr close 2 may be performed. Out-of-band data may also be transmitted as described in @@ -150,35 +152,30 @@ and received as described in .Pp The communications protocols used to implement a .Dv SOCK_STREAM -insure that data -is not lost or duplicated. If a piece of data for which the -peer protocol has buffer space cannot be successfully transmitted -within a reasonable length of time, then -the connection is considered broken and calls -will indicate an error with -\-1 returns and with +ensure that data is not lost or duplicated. +If a piece of data for which the peer protocol has buffer space cannot +be successfully transmitted within a reasonable length of time, then the +connection is considered broken and calls will indicate an error with \-1 +returns and with .Er ETIMEDOUT as the specific code in the global variable .Va errno . The protocols optionally keep sockets .Dq warm -by forcing transmissions -roughly every minute in the absence of other activity. -An error is then indicated if no response can be -elicited on an otherwise +by forcing transmissions roughly every minute in the absence of other activity. +An error is then indicated if no response can be elicited on an otherwise idle connection for a extended period (e.g., 5 minutes). A .Dv SIGPIPE -signal is raised if a process sends -on a broken stream; this causes naive processes, -which do not handle the signal, to exit. +signal is raised if a process sends on a broken stream; this causes +naive processes, which do not handle the signal, to exit. .Pp .Dv SOCK_SEQPACKET sockets employ the same system calls as .Dv SOCK_STREAM -sockets. The only difference -is that +sockets. +The only difference is that .Xr read 2 calls will return only the amount of data requested, and any remaining in the arriving packet will be discarded. @@ -186,10 +183,10 @@ and any remaining in the arriving packet will be discarded. .Dv SOCK_DGRAM and .Dv SOCK_RAW -sockets allow sending of datagrams to correspondents -named in +sockets allow sending of datagrams to correspondents named in .Xr send 2 -calls. Datagrams are generally received with +calls. +Datagrams are generally received with .Xr recvfrom 2 , which returns the next datagram with its return address. .Pp @@ -199,9 +196,8 @@ call can be used to specify a process group to receive a .Dv SIGURG signal when the out-of-band data arrives. -It may also enable non-blocking I/O -and asynchronous notification of I/O events -via +It may also enable non-blocking I/O and asynchronous notification +of I/O events via .Dv SIGIO . .Pp The operation of sockets is controlled by socket level diff --git a/lib/libc/sys/swapctl.2 b/lib/libc/sys/swapctl.2 index c24cef7d4dc..1c4f1dc29af 100644 --- a/lib/libc/sys/swapctl.2 +++ b/lib/libc/sys/swapctl.2 @@ -51,7 +51,8 @@ configuration. .Pp The .Fa cmd -parameter specifies the operation to be performed. The +parameter specifies the operation to be performed. +The .Fa arg and .Fa misc @@ -64,7 +65,8 @@ If .Fa cmd is .Dv SWAP_NSWAP , -the current number of swap devices in the system is returned. The +the current number of swap devices in the system is returned. +The .Fa arg and .Fa misc @@ -76,9 +78,11 @@ is .Dv SWAP_STATS , the current statistics for swap devices are returned in the .Fa arg -parameter. No more than +parameter. +No more than .Fa misc -swap devices are returned. The +swap devices are returned. +The .Fa arg parameter should point to an array of at least .Fa misc @@ -138,8 +142,8 @@ case, except that they change the priority of a currently enabled swap device. .El .Pp When swapping is enabled on a block device, the first portion of the disk is -left unused to prevent any disklable present from being overwritten. This -space is allocated from the swap device when the +left unused to prevent any disklable present from being overwritten. +This space is allocated from the swap device when the .Dv SWAP_ON command is used. .Sh RETURN VALUES @@ -150,10 +154,12 @@ parameter is or .Dv SWAP_STATS , .Fn swapctl -returns the number of swap devices, if successful. The +returns the number of swap devices, if successful. +The .Dv SWAP_NSWAP -command is always successful. Otherwise it returns 0 on success and \-1 -on failure, setting the global variable +command is always successful. +Otherwise it returns 0 on success and \-1 on failure, +setting the global variable .Va errno to indicate the error. .Sh ERRORS @@ -169,7 +175,8 @@ characters, or an entire path name exceeded .Dv PATH_MAX characters. .It Bq Er ENOENT -The named device does not exist. For the +The named device does not exist. +For the .Dv SWAP_CTL command, the named device is not currently enabled for swapping. .It Bq Er EACCES diff --git a/lib/libc/sys/swapon.2 b/lib/libc/sys/swapon.2 index decae6e2bcb..5b79e9be08d 100644 --- a/lib/libc/sys/swapon.2 +++ b/lib/libc/sys/swapon.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: swapon.2,v 1.8 2000/04/15 11:46:04 aaron Exp $ +.\" $OpenBSD: swapon.2,v 1.9 2000/10/18 05:12:12 aaron Exp $ .\" $NetBSD: swapon.2,v 1.7 1995/02/27 12:38:21 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -48,13 +48,12 @@ .Fn swapon makes the block device .Fa special -available to the system for -allocation for paging and swapping. The names of potentially -available devices are known to the system and defined at system -configuration time. The size of the swap area on +available to the system for allocation for paging and swapping. +The names of potentially available devices are known to the system and +defined at system configuration time. +The size of the swap area on .Fa special -is calculated at the time the device is first made available -for swapping. +is calculated at the time the device is first made available for swapping. .Sh RETURN VALUES If an error has occurred, a value of \-1 is returned and .Va errno @@ -85,13 +84,11 @@ is not a block device. .It Bq Er EBUSY The device specified by .Fa special -has already -been made available for swapping +has already been made available for swapping .It Bq Er EINVAL The device configured by .Fa special -was not -configured into the system as a swap device. +was not configured into the system as a swap device. .It Bq Er ENXIO The major device number of .Fa special diff --git a/lib/libc/sys/sync.2 b/lib/libc/sys/sync.2 index fb269f355d0..e71b212a324 100644 --- a/lib/libc/sys/sync.2 +++ b/lib/libc/sys/sync.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sync.2,v 1.5 1999/06/29 14:10:26 aaron Exp $ +.\" $OpenBSD: sync.2,v 1.6 2000/10/18 05:12:12 aaron Exp $ .\" $NetBSD: sync.2,v 1.4 1995/02/27 12:38:41 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -48,21 +48,18 @@ The .Fn sync function forces a write of dirty (modified) buffers -in the block buffer cache out -to disk. The kernel keeps this information in core to reduce +in the block buffer cache out to disk. +The kernel keeps this information in core to reduce the number of disk I/O transfers required by the system. As information in the cache is lost after a system crash a .Fn sync -call is issued -frequently -by the user process +call is issued frequently by the user process .Xr update 8 (about every 30 seconds). .Pp The function .Xr fsync 2 -may be used to synchronize individual file descriptor -attributes. +may be used to synchronize individual file descriptor attributes. .Sh SEE ALSO .Xr fsync 2 , .Xr sync 8 , diff --git a/lib/libc/sys/sysarch.2 b/lib/libc/sys/sysarch.2 index 1ff9ab306ed..8151973342d 100644 --- a/lib/libc/sys/sysarch.2 +++ b/lib/libc/sys/sysarch.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sysarch.2,v 1.4 1999/07/02 20:58:01 aaron Exp $ +.\" $OpenBSD: sysarch.2,v 1.5 2000/10/18 05:12:12 aaron Exp $ .\" $NetBSD: sysarch.2,v 1.4 1995/02/27 12:38:47 cgd Exp $ .\" .\" Copyright (c) 1980, 1991 Regents of the University of California. @@ -46,25 +46,21 @@ .Fn sysarch "int number" "char *args" .Sh DESCRIPTION .Fn sysarch -performs the architecture-dependent function -specified by +performs the architecture-dependent function specified by .Fa number with the arguments specified by the .Fa args pointer. .Fa args -is a pointer to a structure defining the actual -arguments of the function. -Symbolic constants and argument structures -for the architecture-dependent +is a pointer to a structure defining the actual arguments of the function. +Symbolic constants and argument structures for the architecture-dependent functions can be found in the header file .Ao Pa machine/sysarch.h Ac . .Pp The .Fn sysarch -system call should never be called directly by -user programs. Instead, they should access -its functions using the architecture-dependent +system call should never be called directly by user programs. +Instead, they should access its functions using the architecture-dependent library. .Sh RETURN VALUES See the manual pages for specific architecture-dependent function calls diff --git a/lib/libc/sys/truncate.2 b/lib/libc/sys/truncate.2 index e07a0a353f1..0b40eee3e1a 100644 --- a/lib/libc/sys/truncate.2 +++ b/lib/libc/sys/truncate.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: truncate.2,v 1.8 2000/07/21 21:52:14 naddy Exp $ +.\" $OpenBSD: truncate.2,v 1.9 2000/10/18 05:12:12 aaron Exp $ .\" $NetBSD: truncate.2,v 1.7 1995/02/27 12:39:00 cgd Exp $ .\" .\" Copyright (c) 1983, 1991, 1993 @@ -55,18 +55,16 @@ or referenced by .Fa fd to be truncated or extended to .Fa length -bytes in size. If the file -was larger than this size, the extra data -is lost. -If the file was smaller than this size, -it will be extended as if by writing bytes -with the value zero. +bytes in size. +If the file was larger than this size, the extra data is lost. +If the file was smaller than this size, it will be extended as if by +writing bytes with the value zero. With .Fn ftruncate , the file must be open for writing. .Sh RETURN VALUES -A value of 0 is returned if the call succeeds. If the call -fails a \-1 is returned, and the global variable +A value of 0 is returned if the call succeeds. +If the call fails a \-1 is returned, and the global variable .Va errno specifies the error. .Sh ERRORS @@ -124,8 +122,8 @@ is not open for writing. .Sh SEE ALSO .Xr open 2 .Sh BUGS -These calls should be generalized to allow ranges -of bytes in a file to be discarded. +These calls should be generalized to allow ranges of bytes in a file +to be discarded. .Pp Use of .Fn truncate diff --git a/lib/libc/sys/umask.2 b/lib/libc/sys/umask.2 index 77b7b4eafcf..05491d19007 100644 --- a/lib/libc/sys/umask.2 +++ b/lib/libc/sys/umask.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: umask.2,v 1.4 1999/06/29 14:10:27 aaron Exp $ +.\" $OpenBSD: umask.2,v 1.5 2000/10/18 05:12:12 aaron Exp $ .\" $NetBSD: umask.2,v 1.6 1995/02/27 12:39:06 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -50,9 +50,8 @@ The .Fn umask routine sets the process's file mode creation mask to .Fa numask -and returns the previous value of the mask. The 9 low-order -access permission -bits of +and returns the previous value of the mask. +The 9 low-order access permission bits of .Fa numask are used by system calls, including .Xr open 2 , @@ -60,12 +59,10 @@ are used by system calls, including .Xr mkfifo 2 and .Xr mknod 2 -to turn off corresponding bits -requested in file mode. +to turn off corresponding bits requested in the file mode. (See .Xr chmod 2 ) . -This clearing allows each user to restrict the default access -to his files. +This clearing allows each user to restrict the default access to his files. .Pp The default mask value is S_IWGRP|S_IWOTH (022, write access for the owner only). @@ -85,6 +82,5 @@ function is always successful. .Sh STANDARDS The .Fn umask -function call is expected to -conform to +function call is expected to conform to .St -p1003.1-88 . diff --git a/lib/libc/sys/unlink.2 b/lib/libc/sys/unlink.2 index 0b7c557459a..ec0ca0bfa36 100644 --- a/lib/libc/sys/unlink.2 +++ b/lib/libc/sys/unlink.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: unlink.2,v 1.10 2000/07/07 18:21:37 aaron Exp $ +.\" $OpenBSD: unlink.2,v 1.11 2000/10/18 05:12:12 aaron Exp $ .\" $NetBSD: unlink.2,v 1.7 1995/02/27 12:39:13 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -47,8 +47,7 @@ .Sh DESCRIPTION The .Fn unlink -function -removes the link named by +function removes the link named by .Fa path from its directory and decrements the link count of the file which was referenced by the link. diff --git a/lib/libc/sys/vfork.2 b/lib/libc/sys/vfork.2 index 351a2f3324f..0d0dd3cdf95 100644 --- a/lib/libc/sys/vfork.2 +++ b/lib/libc/sys/vfork.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: vfork.2,v 1.12 1999/09/27 02:00:13 aaron Exp $ +.\" $OpenBSD: vfork.2,v 1.13 2000/10/18 05:12:12 aaron Exp $ .\" $NetBSD: vfork.2,v 1.8 1997/07/10 07:54:13 mikel Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -48,7 +48,8 @@ .Fn vfork was originally used to create new processes without fully copying the address space of the old process, which is horrendously inefficient in a paged -environment. It was useful when the purpose of +environment. +It was useful when the purpose of .Xr fork 2 would have been to create a new system context for an .Xr execve 2 . @@ -83,17 +84,13 @@ The function call appeared in .Bx 2.9 . .Sh BUGS -To avoid a possible deadlock situation, -processes that are children in the middle -of a +To avoid a possible deadlock situation, processes that are children +in the middle of a .Fn vfork are never sent .Dv SIGTTOU or .Dv SIGTTIN -signals; rather, -output or +signals; rather, output or .Xr ioctl 2 -calls -are allowed -and input attempts result in an end-of-file indication. +calls are allowed and input attempts result in an end-of-file indication. diff --git a/lib/libc/sys/wait.2 b/lib/libc/sys/wait.2 index 7ce0ef63d9e..9b0140324ba 100644 --- a/lib/libc/sys/wait.2 +++ b/lib/libc/sys/wait.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: wait.2,v 1.9 1999/06/29 14:10:31 aaron Exp $ +.\" $OpenBSD: wait.2,v 1.10 2000/10/18 05:12:12 aaron Exp $ .\" $NetBSD: wait.2,v 1.6 1995/02/27 12:39:37 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993, 1994 @@ -65,8 +65,7 @@ information is available for a terminated child process, or a signal is received. On return from a successful .Fn wait -call, -the +call, the .Fa status area contains termination information about the process that exited as defined below. @@ -102,26 +101,23 @@ equals the absolute value of .Pp The .Fa status -parameter is defined below. The +parameter is defined below. +The .Fa options parameter contains the bitwise .Tn OR of any of the following options. The .Dv WNOHANG -option -is used to indicate that the call should not block if +option is used to indicate that the call should not block if there are no processes that wish to report status. If the .Dv WUNTRACED -option is set, -children of the current process that are stopped -due to a +option is set, children of the current process that are stopped due to a .Dv SIGTTIN , SIGTTOU , SIGTSTP , or .Dv SIGSTOP -signal also have -their status reported. +signal also have their status reported. .Pp If .Fa rusage @@ -132,12 +128,9 @@ for stopped processes). .Pp When the .Dv WNOHANG -option is specified and no processes -wish to report status, +option is specified and no processes wish to report status, .Fn wait4 -returns a -process ID -of 0. +returns a process ID of 0. .Pp The .Fn waitpid @@ -168,8 +161,7 @@ True if the process terminated due to receipt of a signal. True if the process has not terminated, but has stopped and can be restarted. This macro can be true only if the wait call specified the .Dv WUNTRACED -option -or if the child process is being traced (see +option or if the child process is being traced (see .Xr ptrace 2 ) . .El .Pp @@ -179,8 +171,7 @@ produce the remaining status information about the child process: .It Fn WEXITSTATUS status If .Fn WIFEXITED status -is true, evaluates to the low-order 8 bits -of the argument passed to +is true, evaluates to the low-order 8 bits of the argument passed to .Xr _exit 2 or .Xr exit 3 @@ -199,8 +190,8 @@ containing an image of the process when the signal was received. .It Fn WSTOPSIG status If .Fn WIFSTOPPED status -is true, evaluates to the number of the signal -that caused the process to stop. +is true, evaluates to the number of the signal that caused the process +to stop. .El .Sh NOTES See @@ -215,11 +206,9 @@ process 1 ID (the init process ID). .Pp If a signal is caught while any of the .Fn wait -calls is pending, -the call may be interrupted or restarted when the signal-catching routine -returns, -depending on the options in effect for the signal; -see +calls is pending, the call may be interrupted or restarted when the +signal-catching routine returns, depending on the options in effect +for the signal; see .Xr intro 2 , System call restart. .Sh RETURN VALUES @@ -227,8 +216,8 @@ If .Fn wait returns due to a stopped or terminated child process, the process ID of the child -is returned to the calling process. Otherwise, a value of \-1 -is returned and +is returned to the calling process. +Otherwise, a value of \-1 is returned and .Va errno is set to indicate the error. .Pp @@ -237,21 +226,16 @@ If .Fn wait3 or .Fn waitpid -returns due to a stopped -or terminated child process, the process ID of the child -is returned to the calling process. -If there are no children not previously awaited, -\-1 is returned with +returns due to a stopped or terminated child process, the process ID +of the child is returned to the calling process. +If there are no children not previously awaited, \-1 is returned with .Va errno set to .Bq Er ECHILD . Otherwise, if .Dv WNOHANG -is specified and there are -no stopped or exited children, -0 is returned. -If an error is detected or a caught signal aborts the call, -a value of \-1 +is specified and there are no stopped or exited children, 0 is returned. +If an error is detected or a caught signal aborts the call, a value of \-1 is returned and .Va errno is set to indicate the error. @@ -260,8 +244,7 @@ is set to indicate the error. will fail and return immediately if: .Bl -tag -width Er .It Bq Er ECHILD -The calling process has no existing unwaited-for -child processes. +The calling process has no existing unwaited-for child processes. .It Bq Er EFAULT The .Fa status @@ -270,8 +253,7 @@ or arguments point to an illegal address. (May not be detected before exit of a child process.) .It Bq Er EINTR -The call was interrupted by a caught signal, -or the signal did not have the +The call was interrupted by a caught signal, or the signal did not have the .Dv SA_RESTART flag set. .It Bq Er EINVAL @@ -291,8 +273,7 @@ and are not specified by POSIX. The .Fn WCOREDUMP -macro -and the ability to restart a pending +macro and the ability to restart a pending .Fn wait call are extensions to the POSIX interface. .Sh SEE ALSO diff --git a/lib/libc/sys/write.2 b/lib/libc/sys/write.2 index e2bf3d95162..860932e0d59 100644 --- a/lib/libc/sys/write.2 +++ b/lib/libc/sys/write.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: write.2,v 1.20 2000/04/20 06:34:37 deraadt Exp $ +.\" $OpenBSD: write.2,v 1.21 2000/10/18 05:12:12 aaron Exp $ .\" $NetBSD: write.2,v 1.6 1995/02/27 12:39:43 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -64,8 +64,7 @@ of data to the object referenced by the descriptor from the buffer pointed to by .Fa buf . .Fn writev -performs the same action, but gathers the output data -from the +performs the same action, but gathers the output data from the .Fa iovcnt buffers specified by the members of the .Fa iov @@ -98,13 +97,11 @@ in memory from which data should be written. .Fn writev and .Fn pwritev -will always write a complete area before proceeding -to the next. +will always write a complete area before proceeding to the next. .Pp On objects capable of seeking, the .Fn write -starts at a position -given by the pointer associated with +starts at a position given by the pointer associated with .Fa d (see .Xr lseek 2 ) . @@ -113,17 +110,15 @@ Upon return from the pointer is incremented by the number of bytes which were written. .Pp Objects that are not capable of seeking always write from the current -position. The value of the pointer associated with such an object -is undefined. +position. +The value of the pointer associated with such an object is undefined. .Pp If the real user is not the superuser, then .Fn write clears the set-user-ID bit on a file. -This prevents penetration of system security -by a user who +This prevents penetration of system security by a user who .Dq captures -a writable set-user-ID file -owned by the superuser. +a writable set-user-ID file owned by the superuser. .Pp If .Fn write @@ -136,8 +131,7 @@ to flow control, .Fn write and .Fn writev -may write fewer bytes than requested; -the return value must be noted, +may write fewer bytes than requested; the return value must be noted, and the remainder of the operation should be retried when possible. .Pp Note that @@ -150,7 +144,8 @@ exceedes the constant .Dv IOV_MAX . .Sh RETURN VALUES Upon successful completion the number of bytes which were written -is returned. Otherwise, a \-1 is returned and the global variable +is returned. +Otherwise, a \-1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS @@ -179,16 +174,15 @@ The pointer associated with .Fa d was negative. .It Bq Er ENOSPC -There is no free space remaining on the file system -containing the file. +There is no free space remaining on the file system containing the file. .It Bq Er EDQUOT -The user's quota of disk blocks on the file system -containing the file has been exhausted. +The user's quota of disk blocks on the file system containing the file +has been exhausted. .It Bq Er EIO An I/O error occurred while reading from or writing to the file system. .It Bq Er EAGAIN -The file was marked for non-blocking I/O, -and no data could be written immediately. +The file was marked for non-blocking I/O, and no data could be +written immediately. .El .Pp In addition, @@ -200,8 +194,8 @@ may return the following error: .It Bq Er EFAULT Part of .Fa iov -or data to be written to the file -points outside the process's allocated address space. +or data to be written to the file points outside the process's +allocated address space. .It Bq Er EINVAL .Fa nbytes was larger than @@ -273,18 +267,15 @@ Proper loops should use .Sh HISTORY The .Fn pwritev -function call -appeared in +function call appeared in .Ox 2.7 . The .Fn pwrite -function call -appeared in +function call appeared in .At V.4 . The .Fn writev -function call -appeared in +function call appeared in .Bx 4.2 . The .Fn write diff --git a/lib/libc/time/strftime.3 b/lib/libc/time/strftime.3 index eee1d0bbc9c..b858b5c6c76 100644 --- a/lib/libc/time/strftime.3 +++ b/lib/libc/time/strftime.3 @@ -34,7 +34,7 @@ .\" SUCH DAMAGE. .\" .\" from: @(#)strftime.3 5.12 (Berkeley) 6/29/91 -.\" $OpenBSD: strftime.3,v 1.11 2000/09/06 23:05:11 millert Exp $ +.\" $OpenBSD: strftime.3,v 1.12 2000/10/18 05:12:12 aaron Exp $ .\" .Dd January 18, 1998 .Dt STRFTIME 3 @@ -154,7 +154,8 @@ is replaced by the weekday (Monday as the first day of the week) as a decimal number (1-7). .It Cm \&%V is replaced by the week number of the year (Monday as the first day of -the week) as a decimal number (01-53). If the week containing January +the week) as a decimal number (01-53). +If the week containing January 1 has four or more days in the new year, then it is week 1; otherwise it is week 53 of the previous year, and the next week is week 1. .It Cm \&%W @@ -215,15 +216,17 @@ and conversion specifications are extensions. .Pp Use of the ISO 8601 conversions may produce non-intuitive results. -Week 01 of a year is per definition the first week which has the -Thursday in this year, which is equivalent to the week which contains -the fourth day of January. In other words, the first week of a new -year is the week which has the majority of its days in the new year. +Week 01 of a year is per definition the first week which has the Thursday +in this year, which is equivalent to the week which contains the fourth +day of January. +In other words, the first week of a new year is the week which has the +majority of its days in the new year. Week 01 might also contain days from the previous year and the week before week 01 of a year is the last week (52 or 53) of the previous -year even if it contains days from the new year. A week starts with -Monday (day 1) and ends with Sunday (day 7). For example, the first -week of the year 1997 lasts from 1996-12-30 to 1997-01-05. +year even if it contains days from the new year. +A week starts with Monday (day 1) and ends with Sunday (day 7). +For example, the first week of the year 1997 lasts from +1996-12-30 to 1997-01-05. .Sh BUGS There is no conversion specification for the phase of the moon. .Pp @@ -233,7 +236,8 @@ will always NUL terminate .Fa buf , other implementations may not do so when .Fa maxsiz -is not large enough to store the entire time string. The contents of +is not large enough to store the entire time string. +The contents of .Fa buf are implementation specific in this case. .\" @(#)newstrftime.3 7.14 diff --git a/lib/libc/time/strptime.3 b/lib/libc/time/strptime.3 index ac055129b88..771bc06b8c3 100644 --- a/lib/libc/time/strptime.3 +++ b/lib/libc/time/strptime.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: strptime.3,v 1.6 2000/03/04 22:19:32 aaron Exp $ +.\" $OpenBSD: strptime.3,v 1.7 2000/10/18 05:12:12 aaron Exp $ .\" .\" Copyright (c) 1997, 1998 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -55,17 +55,20 @@ using the format specified by .Pp The .Fa format -string consists of zero or more directives. A directive is composed -of either one or more whitespace as defined by +string consists of zero or more directives. +A directive is composed of either one or more whitespace as defined by .Fn isspace , an ordinary character (neither `%' nor a whitespace), or a conversion -specification. A conversion specification consists of a percent sign `%' +specification. +A conversion specification consists of a percent sign `%' followed by one or two conversion characters which specify the -replacement required. There must be whitespace or other +replacement required. +There must be whitespace or other non-alphanumeric characters between any two conversion specifications. .Pp The LC_TIME category defines the locale values for the conversion -specifications. The following conversion specifications are supported: +specifications. +The following conversion specifications are supported: .Bl -tag -width "xxxx" .It Cm \&%a the day of week, using the locale's weekday names; @@ -150,7 +153,8 @@ the date, using the locale's date format. .It Cm \&%X the time, using the locale's time format. .It Cm \&%y -the year within the current century. When a century is not otherwise +the year within the current century. +When a century is not otherwise specified, values in the range 69-99 refer to years in the twentieth century (1969 to 1999 inclusive); values in the range 00-68 refer to years in the twenty-first century (2000 to 2068 inclusive). @@ -158,7 +162,8 @@ Leading zeros are permitted but not required. .It Cm \&%Y the year, including the century (i.e., 1998). .It Cm \&%% -A `%' is written. No argument is converted. +A `%' is written. +No argument is converted. .El .Ss Modified conversion specifications For compatibility, certain conversion specifications can be modified @@ -168,7 +173,8 @@ and .Cm O modifier characters to indicate that an alternative format or specification should be used rather than the one normally used by the -unmodified conversion specification. As there are currently neither +unmodified conversion specification. +As there are currently neither alternative formats nor specifications supported by the system, the behavior will be as if the unmodified conversion specification were used. @@ -180,7 +186,8 @@ such as month and weekday names. If successful, the .Nm function returns a pointer to the character following the last character -parsed. Otherwise, a null pointer is returned. +parsed. +Otherwise, a null pointer is returned. .Sh SEE ALSO .Xr strftime 3 .Sh STANDARDS diff --git a/lib/libc/time/tzset.3 b/lib/libc/time/tzset.3 index daafc4533e7..09511907565 100644 --- a/lib/libc/time/tzset.3 +++ b/lib/libc/time/tzset.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: tzset.3,v 1.11 1999/07/09 13:35:21 aaron Exp $ +.\" $OpenBSD: tzset.3,v 1.12 2000/10/18 05:12:13 aaron Exp $ .Dd May 24, 1999 .Dt TZSET 3 .Os @@ -73,13 +73,14 @@ Three or more bytes that are the designation for the standard .Pq Ar std or summer .Pq Ar dst -time zone. Only +time zone. +Only .Ar std is required; if .Ar dst is missing, then summer time does not apply in this locale. -Upper and lowercase letters are explicitly allowed. Any characters -except a leading colon +Upper and lowercase letters are explicitly allowed. +Any characters except a leading colon .Pq Sq \&: , digits, comma .Pq Sq \&, , @@ -106,20 +107,25 @@ The minutes .Pq Ar mm and seconds .Pq Ar ss -are optional. The hour +are optional. +The hour .Pq Ar hh -is required and may be a single digit. The +is required and may be a single digit. +The .Ar offset following .Ar std -is required. If no +is required. +If no .Ar offset follows .Ar dst , -summer time is assumed to be one hour ahead of standard time. One or -more digits may be used; the value is always interpreted as a decimal -number. The hour must be between zero and 24, and the minutes (and -seconds) -- if present -- between zero and 59. If preceded by a +summer time is assumed to be one hour ahead of standard time. +One or more digits may be used; the value is always interpreted as a +decimal number. +The hour must be between zero and 24, and the minutes (and +seconds) -- if present -- between zero and 59. +If preceded by a .Dq \&- , the time zone shall be east of the Prime Meridian; otherwise it shall be west (which may be indicated by an optional preceding @@ -143,7 +149,8 @@ where the first describes when the change from standard to summer time occurs and the second .Ar date -describes when the change back happens. Each +describes when the change back happens. +Each .Ar time field describes when, in current local time, the change to the other time is made. @@ -161,8 +168,8 @@ The Julian day \&<\&= 365 .Pc . Leap days are not counted; that is, in all years -- including leap -years -- February 28 is day 59 and March 1 is day 60. It is -impossible to explicitly refer to the occasional February 29. +years -- February 28 is day 59 and March 1 is day 60. +It is impossible to explicitly refer to the occasional February 29. .It Ar n The zero-based Julian day .Po @@ -202,10 +209,11 @@ the last day in month .Ar m .Dc -which may occur in either the fourth or the fifth week. Week 1 is the -first week in which the +which may occur in either the fourth or the fifth week. +Week 1 is the first week in which the .Ar d Ns th -day occurs. Day zero is Sunday. +day occurs. +Day zero is Sunday. .El .Pp The @@ -218,7 +226,8 @@ except that no leading sign or .Dq \&+ .Pc -is allowed. The default, if +is allowed. +The default, if .Ar time is not given, is .Cm 02:00:00 . diff --git a/lib/libc/time/zic.8 b/lib/libc/time/zic.8 index f442ff3f1a4..e5e8f7fbcd0 100644 --- a/lib/libc/time/zic.8 +++ b/lib/libc/time/zic.8 @@ -1,4 +1,4 @@ -.\" $OpenBSD: zic.8,v 1.12 2000/04/16 16:24:04 d Exp $ +.\" $OpenBSD: zic.8,v 1.13 2000/10/18 05:12:13 aaron Exp $ .Dd May 23, 1999 .Dt ZIC 8 .Os @@ -120,7 +120,8 @@ may be used to repeat the value of the .Em FROM field. .It Cm TYPE -Gives the type of year in which the rule applies. If +Gives the type of year in which the rule applies. +If .Em TYPE is .Dq Fl @@ -128,7 +129,8 @@ then the rule applies in all years between .Em FROM and .Em TO -inclusive. If +inclusive. +If .Em TYPE is something else, then .Nm diff --git a/lib/libc/yp/ypclnt.3 b/lib/libc/yp/ypclnt.3 index d0a1470cf23..09a2010e6c9 100644 --- a/lib/libc/yp/ypclnt.3 +++ b/lib/libc/yp/ypclnt.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ypclnt.3,v 1.11 2000/03/14 21:31:45 aaron Exp $ +.\" $OpenBSD: ypclnt.3,v 1.12 2000/10/18 05:12:13 aaron Exp $ .\" .\" Copyright (c) 1996 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -80,8 +80,8 @@ .Sh DESCRIPTION The .Nm ypclnt -suite provides an interface to the YP subsystem. For a general description -of the YP subsystem, see +suite provides an interface to the YP subsystem. +For a general description of the YP subsystem, see .Xr yp 8 . .Pp For all functions, input values begin with @@ -90,11 +90,12 @@ and output values begin with .Pa out . Any output values of type .Em char ** -should be the addresses of uninitialized character pointers. Memory will be -allocated by the YP client routines using +should be the addresses of uninitialized character pointers. +Memory will be allocated by the YP client routines using .Fn malloc . This memory can later be freed by the user if there is no additional need for -the data stored there. For +the data stored there. +For .Pa outkey and .Pa outval , @@ -111,9 +112,11 @@ All occurrences of .Pa indomain and .Pa inmap -must be non-null, NUL-terminated strings. All input strings which also have +must be non-null, NUL-terminated strings. +All input strings which also have a corresponding length parameter cannot be null unless the corresponding -length value is zero. Such strings need not be NUL-terminated. +length value is zero. +Such strings need not be NUL-terminated. .Pp All YP lookup calls (the functions .Fn yp_all , @@ -122,8 +125,8 @@ All YP lookup calls (the functions .Fn yp_match , .Fn yp_next , .Fn yp_order ) -require a YP domain name and a YP map name. The default domain name may be -obtained by calling +require a YP domain name and a YP map name. +The default domain name may be obtained by calling .Fn yp_get_default_domain , and should thus be used before all other YP calls in a client program. The value it places @@ -133,13 +136,15 @@ is suitable for use as the parameter to all subsequent YP calls. .Pp In order for YP lookup calls to succeed, the client process must be bound -to a YP server process. The client process need not explicitly bind to -the server, as it happens automatically whenever a lookup occurs. +to a YP server process. +The client process need not explicitly bind to the server, as it happens +automatically whenever a lookup occurs. The function .Fn yp_bind is provided for a backup strategy, e.g., a local file, when a YP server process -is not available. Each binding uses one socket descriptor on the client -process, which may be explicitly freed using +is not available. +Each binding uses one socket descriptor on the client process, which may +be explicitly freed using .Fn yp_unbind , which frees all per-process and per-node resources to bind the domain and marks the domain unbound. @@ -163,8 +168,8 @@ Provides the value associated with the given key. .It Fn yp_first Provides the first key-value pair from the given map in the named domain. .It Fn yp_next -Provides the next key-value pair in the given map. To obtain the second pair, -the +Provides the next key-value pair in the given map. +To obtain the second pair, the .Pa inkey value should be the .Pa outkey @@ -183,7 +188,8 @@ and .Dq next are particular to the type of YP map being accessed, and thus there is no guarantee of lexical -order. The only guarantees provided with +order. +The only guarantees provided with .Fn yp_first and .Fn yp_next , @@ -195,26 +201,28 @@ exactly once, and if the entire procedure is repeated, the order will be the same. .Pp If the server is heaviliy loaded or the server fails for some reason, the -domain being used may become unbound. If this happens, and the client process +domain being used may become unbound. +If this happens, and the client process re-binds, the retrieval rules will break: some entries may be seen twice, and -others not at all. For this reason, the function +others not at all. +For this reason, the function .Fn yp_all provides a better solution for reading all of the entries in a particular map. .It Fn yp_all This function provides a way to transfer an entire map from -the server to the client process with a single request. This transfer -uses TCP, unlike all other functions in the +the server to the client process with a single request. +This transfer uses TCP, unlike all other functions in the .Nm ypclnt -suite, which use UDP. The entire transaction occurs in a single RPC -request-response. The third argument to this function provides a way -to supply the name of a function to process each key-value pair in the -map. +suite, which use UDP. +The entire transaction occurs in a single RPC request-response. +The third argument to this function provides a way to supply the name +of a function to process each key-value pair in the map. .Fn yp_all returns after the entire transaction is complete, or the .Pa foreach -function decides that it does not want any more key-value pairs. The third -argument to +function decides that it does not want any more key-value pairs. +The third argument to .Fn yp_all is: .Bd -literal -offset indent @@ -226,7 +234,8 @@ struct ypall_callback *incallback { .Pp The .Em char *data -argument is an opaque pointer for use by the callback function. The +argument is an opaque pointer for use by the callback function. +The .Pa foreach function should return non-zero when it no longer wishes to process key-value pairs, at which time @@ -257,7 +266,8 @@ layer error code as described in .Nm <rpcsvc/ypclnt.h> . .It Fa inkey, inval The key and value arguments are somewhat different here than described -above. In this case, the memory pointed to by +above. +In this case, the memory pointed to by .Fa inkey and .Fa inval @@ -266,7 +276,8 @@ is private to and is overwritten with each subsequent key-value pair; therefore, the .Pa foreach function should do something useful with the contents of that memory during -each iteration. If the key-value pairs are not terminated with either +each iteration. +If the key-value pairs are not terminated with either .Ql \en or .Ql \e0 @@ -276,11 +287,12 @@ function, either. .It Fa indata This is the contents of the .Pa incallback->data -element of the callback structure. It is provided as a means to share -state between the +element of the callback structure. +It is provided as a means to share state between the .Pa foreach -function and the user code. Its use is completely optional: cast it to -something useful or simply ignore it. +function and the user code. +Its use is completely optional: cast it to something useful or simply +ignore it. .El .It Fn yp_order Returns the order number for a map. @@ -324,10 +336,11 @@ Cannot communicate with portmap. .It Bq Er YPERR_RESRC A resource allocation failure occurred. .It Bq Er YPERR_RPC -An RPC failure has occurred. The domain has been marked unbound. +An RPC failure has occurred. +The domain has been marked unbound. .It Bq Er YPERR_VERS -Client/server version mismatch. If the server is running version 1 -of the YP protocol, +Client/server version mismatch. +If the server is running version 1 of the YP protocol, .Fn yp_all functionality does not exist. .It Bq Er YPERR_BIND |