diff options
author | Mike Pechkin <mpech@cvs.openbsd.org> | 2002-05-01 08:03:31 +0000 |
---|---|---|
committer | Mike Pechkin <mpech@cvs.openbsd.org> | 2002-05-01 08:03:31 +0000 |
commit | 41434dbdbf3099a023505b5b3915bf4d9b778ee1 (patch) | |
tree | 1ca936fb3301ad4347fcc3a38fd2c83e87a15817 | |
parent | 04e9f1abe6384e852ca0207d882814dab9237dd4 (diff) |
o) start new sentence on a new line;
o) always close .Bl tags;
o) fix usage of .Xr;
millert@ ok
84 files changed, 715 insertions, 517 deletions
diff --git a/lib/libc/db/man/hcreate.3 b/lib/libc/db/man/hcreate.3 index 3b26e926ae3..2afc1f9b211 100644 --- a/lib/libc/db/man/hcreate.3 +++ b/lib/libc/db/man/hcreate.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: hcreate.3,v 1.2 2001/08/06 10:42:25 mpech Exp $ +.\" $OpenBSD: hcreate.3,v 1.3 2002/05/01 08:03:29 mpech Exp $ .\" $NetBSD: hcreate.3,v 1.2.4.1 2001/03/13 21:19:18 he Exp $ .\" .\" Copyright (c) 1999 The NetBSD Foundation, Inc. @@ -65,7 +65,8 @@ function allocates and initializes the table. The .Fa nel argument specifies an estimate of the maximum number of entries to be held -by the table. Unless further memory allocation fails, supplying an +by the table. +Unless further memory allocation fails, supplying an insufficient .Fa nel value will not result in functional harm, although a performance degradation @@ -85,8 +86,9 @@ the data can no longer be accessed. .Pp The .Fn hsearch -function is used to search to the hash table. It returns a pointer into the -hash table indicating the address of an item. The +function is used to search to the hash table. +It returns a pointer into the hash table indicating the address of an item. +The .Fa item argument is of type .Dv ENTRY , @@ -121,7 +123,8 @@ and .Fa data elements of .Fa item -are used directly by the new table entry. The storage for the +are used directly by the new table entry. +The storage for the key must not be modified during the lifetime of the hash table. .It Dv FIND Search the hash table without inserting @@ -130,7 +133,8 @@ Search the hash table without inserting .Sh RETURN VALUES If successful, the .Fn hcreate -function returns a non-zero value. Otherwise, a value of 0 is returned and +function returns a non-zero value. +Otherwise, a value of 0 is returned and .Va errno is set to indicate the error. .Pp diff --git a/lib/libc/db/man/recno.3 b/lib/libc/db/man/recno.3 index 9f9f95db4f8..20af91bfc99 100644 --- a/lib/libc/db/man/recno.3 +++ b/lib/libc/db/man/recno.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: recno.3,v 1.11 2001/08/06 10:42:25 mpech Exp $ +.\" $OpenBSD: recno.3,v 1.12 2002/05/01 08:03:29 mpech Exp $ .\" $NetBSD: recno.3,v 1.6 1996/05/03 21:26:51 cgd Exp $ .\" .\" Copyright (c) 1997, Phillip F Knaack. All rights reserved. @@ -195,6 +195,7 @@ using the interface to create a new record will cause the creation of multiple, empty records if the record number is more than one greater than the largest record currently in the database. +.El .Sh ERRORS The .Fa recno diff --git a/lib/libc/gen/fpgetmask.3 b/lib/libc/gen/fpgetmask.3 index f136158b815..53cb643bf26 100644 --- a/lib/libc/gen/fpgetmask.3 +++ b/lib/libc/gen/fpgetmask.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: fpgetmask.3,v 1.1 2002/02/16 05:17:51 pvalchev Exp $ +.\" $OpenBSD: fpgetmask.3,v 1.2 2002/05/01 08:03:29 mpech Exp $ .\" $NetBSD: fpgetmask.3,v 1.3 2001/09/16 02:57:03 wiz Exp $ .\" .\" Copyright (c) 1999 The NetBSD Foundation, Inc. @@ -102,8 +102,8 @@ function will cause future operations to use the specified dynamic mode. .It Em Note : On some architectures, instructions can optionally specify static rounding modes and exception enables that will supersede the specified -dynamic mode. On other architectures, these features may not be fully -supported. +dynamic mode. +On other architectures, these features may not be fully supported. .El .Pp The diff --git a/lib/libc/gen/sysctl.3 b/lib/libc/gen/sysctl.3 index 5f77fd082ed..f73df5f3d90 100644 --- a/lib/libc/gen/sysctl.3 +++ b/lib/libc/gen/sysctl.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sysctl.3,v 1.85 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: sysctl.3,v 1.86 2002/05/01 08:03:29 mpech Exp $ .\" .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. @@ -546,17 +546,20 @@ The third level name selects the System V style IPC facility. .Pp .Bl -tag -width "123456" .It Li KERN_SYSVIPC_MSG_INFO -Return information on the System V style message facility. The +Return information on the System V style message facility. +The .Sy msg_sysctl_info structure is defined in .Aq Pa sys/msg.h . .It Li KERN_SYSVIPC_SEM_INFO -Return information on the System V style semaphore facility. The +Return information on the System V style semaphore facility. +The .Sy sem_sysctl_info structure is defined in .Aq Pa sys/sem.h . .It Li KERN_SYSVIPC_SHM_INFO -Return information on the System V style shared memory facility. The +Return information on the System V style shared memory facility. +The .Sy shm_sysctl_info structure is defined in .Aq Pa sys/shm.h . @@ -917,7 +920,8 @@ Note that routers will never accept ICMP redirect packets, and the variable is meaningful on IP hosts only. .It Li icmp.redirtimeout The variable specifies lifetime of routing entries generated by incoming -ICMP redirect. The default timeout is 10 minutes. +ICMP redirect. +The default timeout is 10 minutes. .It Li tcp.rfc1323 Returns 1 if RFC1323 extensions to .Tn TCP @@ -1080,7 +1084,8 @@ and for more details. .It Li ip6.log_interval This variable permits adjusting the amount of logs generated by the -IPv6 packet forwarding engine. The value indicates the number of +IPv6 packet forwarding engine. +The value indicates the number of seconds of interval which must elapse between log output. .It Li ip6.hdrnestlimit The number of IPv6 extension headers permitted on incoming IPv6 packets. diff --git a/lib/libc/net/getrrsetbyname.3 b/lib/libc/net/getrrsetbyname.3 index 25bb539f71b..710a5624c87 100644 --- a/lib/libc/net/getrrsetbyname.3 +++ b/lib/libc/net/getrrsetbyname.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getrrsetbyname.3,v 1.5 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: getrrsetbyname.3,v 1.6 2002/05/01 08:03:29 mpech Exp $ .\" .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" @@ -67,7 +67,8 @@ and are in uncompressed DNS wire format. Properties of the rdataset are represented in the .Li rri_flags -bitfield. If the +bitfield. +If the .Dv RRSET_VALIDATED bit is set, the data has been DNSSEC validated and the signatures verified. diff --git a/lib/libc/ohash/ohash_interval.3 b/lib/libc/ohash/ohash_interval.3 index b58ae732dcd..f181ed5fba4 100644 --- a/lib/libc/ohash/ohash_interval.3 +++ b/lib/libc/ohash/ohash_interval.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ohash_interval.3,v 1.3 2001/09/24 12:19:24 espie Exp $ +.\" $OpenBSD: ohash_interval.3,v 1.4 2002/05/01 08:03:29 mpech Exp $ .\" .\" Copyright (c) 2001 Marc Espie. .\" @@ -48,7 +48,8 @@ .Fn ohash_qlookup "struct ohash *h" "const char *start" .Sh DESCRIPTION These functions are commonly used to simplify open hashing usage, and use -similar conventions. They operate indifferently on null-terminated strings +similar conventions. +They operate indifferently on null-terminated strings .Po by setting .Fa *pend diff --git a/lib/libc/posix1e/posix1e.3 b/lib/libc/posix1e/posix1e.3 index a15d887b5df..de88b5a26de 100644 --- a/lib/libc/posix1e/posix1e.3 +++ b/lib/libc/posix1e/posix1e.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: posix1e.3,v 1.4 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: posix1e.3,v 1.5 2002/05/01 08:03:29 mpech Exp $ .\" .\" Copyright (c) 2000 Robert N. M. Watson .\" All rights reserved. @@ -34,8 +34,8 @@ .Nd introduction to the POSIX.1e security API .Sh DESCRIPTION The IEEE POSIX.1e specification never left draft form, but the interfaces -it describes are now widely used despite inherent limitations. Currently, -only a few of the interfaces and features are implemented in +it describes are now widely used despite inherent limitations. +Currently, only a few of the interfaces and features are implemented in .Ox , although efforts are underway to complete the integration at this time. .Pp @@ -54,14 +54,16 @@ development at this time. POSIX.1e assigns security labels to all objects, extending the security functionality described in POSIX.1. These additional labels provide fine-grained discretionary access control, fine-grained capabilities, -and labels necessary for mandatory access control. POSIX.2c describes +and labels necessary for mandatory access control. +POSIX.2c describes a set of userland utilities for manipulating these labels. .Sh SEE ALSO .Xr extattr 9 .Sh STANDARDS POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion of the draft continues on the cross-platform POSIX.1e implementation -mailing list. To join this list, see the +mailing list. +To join this list, see the .Ox POSIX.1e implementation page for more information. diff --git a/lib/libc/stdio/printf.3 b/lib/libc/stdio/printf.3 index fb34315e99d..eb2e5977f0b 100644 --- a/lib/libc/stdio/printf.3 +++ b/lib/libc/stdio/printf.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: printf.3,v 1.36 2001/09/06 04:40:55 millert Exp $ +.\" $OpenBSD: printf.3,v 1.37 2002/05/01 08:03:29 mpech Exp $ .\" .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -387,7 +387,8 @@ argument, or that a following .Cm n conversion corresponds to a pointer to a .Li quad int -argument. The use of +argument. +The use of .Cm q has been depreciated as conversion character. .It diff --git a/lib/libc/sys/ioctl.2 b/lib/libc/sys/ioctl.2 index 8aa51ae9261..4a0d402f990 100644 --- a/lib/libc/sys/ioctl.2 +++ b/lib/libc/sys/ioctl.2 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ioctl.2,v 1.11 2001/07/30 01:12:43 deraadt Exp $ +.\" $OpenBSD: ioctl.2,v 1.12 2002/05/01 08:03:29 mpech Exp $ .\" $NetBSD: ioctl.2,v 1.5 1995/02/27 12:33:47 cgd Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 @@ -56,7 +56,8 @@ requests. .Pp The argument .Fa d -must be an open file descriptor. The third argument is called +must be an open file descriptor. +The third argument is called .Fa arg and contains additional information needed by this device to perform the requested function. diff --git a/lib/libc/time/strftime.3 b/lib/libc/time/strftime.3 index 3537f491705..683295c2986 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.13 2001/07/15 20:13:45 nate Exp $ +.\" $OpenBSD: strftime.3,v 1.14 2002/05/01 08:03:30 mpech Exp $ .\" .Dd January 18, 1998 .Dt STRFTIME 3 @@ -137,7 +137,8 @@ is replaced by the time in the format is replaced by the locale's representation of 12-hour clock time using AM/PM notation. .It Cm \&%S -is replaced by the second as a decimal number (00-61). The range of +is replaced by the second as a decimal number (00-61). +The range of seconds is (00-61) instead of (00-59) to allow for the periodic occurance of leap seconds and double leap seconds. .It Cm %s diff --git a/lib/libc_r/man/flockfile.3 b/lib/libc_r/man/flockfile.3 index cfcae20b8d5..83785f65e5f 100644 --- a/lib/libc_r/man/flockfile.3 +++ b/lib/libc_r/man/flockfile.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: flockfile.3,v 1.6 1999/07/07 10:50:05 aaron Exp $ +.\" $OpenBSD: flockfile.3,v 1.7 2002/05/01 08:03:30 mpech Exp $ .\" David Leonard <d@openbsd.org>, 1998. Public domain. .Dd August 20, 1998 .Dt FLOCKFILE 3 @@ -24,7 +24,8 @@ and .Fn funlockfile functions provide for explicit application-level locking of stdio .Ft "FILE *" -objects. These functions can be used by a thread to delineate a sequence +objects. +These functions can be used by a thread to delineate a sequence of I/O statements that are to be executed as a unit. .Pp The @@ -51,14 +52,17 @@ function. .Pp Logically, there is a lock count associated with each .Ft "FILE *" -object. This count is implicitly intialized to zero when the +object. +This count is implicitly intialized to zero when the .Ft "FILE *" -object is created. The +object is created. +The .Ft "FILE *" object is unlocked when the count is zero. When the count is positive, a single thread owns the .Ft "FILE *" -object. When the +object. +When the .Fn flockfile function is called, if the count is zero or if the count is positive and the caller owns the @@ -68,7 +72,8 @@ Otherwise, the calling thread is suspended, waiting for the count to return to zero. Each call to .Fn funlockfile -decrements the count. This allows matching calls to +decrements the count. +This allows matching calls to .Fn flockfile (or successful calls to .Fn ftrylockfile ) diff --git a/lib/libc_r/man/pthread_attr_init.3 b/lib/libc_r/man/pthread_attr_init.3 index 742012783a4..318b27d5a6b 100644 --- a/lib/libc_r/man/pthread_attr_init.3 +++ b/lib/libc_r/man/pthread_attr_init.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_attr_init.3,v 1.2 2000/04/12 21:48:02 aaron Exp $ +.\" $OpenBSD: pthread_attr_init.3,v 1.3 2002/05/01 08:03:30 mpech Exp $ .\" Manual page derived from TOG's UNIX98 documentation. .Dd January 6, 2000 .Dt PTHREAD_ATTR_INIT 3 @@ -25,8 +25,8 @@ attributes used by a given implementation. The resulting attribute object (possibly modified by setting individual attribute values), when used by .Xr pthread_create 3 , -defines the attributes of the thread created. A single attributes -object can be used in multiple simultaneous calls to +defines the attributes of the thread created. +A single attributes object can be used in multiple simultaneous calls to .Xr pthread_create 3 . .Pp The @@ -37,15 +37,16 @@ attributes object. An implementation may cause to set .Fa attr to an implementation-dependent -invalid value. The behaviour of using the attribute after it has +invalid value. +The behaviour of using the attribute after it has been destroyed is undefined. .Sh RETURN VALUE Upon successful completion, .Fn pthread_attr_init and .Fn pthread_attr_destroy -return a value of 0. Otherwise, an error -number is returned to indicate the error. +return a value of 0. +Otherwise, an error number is returned to indicate the error. .Sh ERRORS The .Fn pthread_attr_init diff --git a/lib/libc_r/man/pthread_attr_setdetachstate.3 b/lib/libc_r/man/pthread_attr_setdetachstate.3 index 408383879f0..1f0dfa45ef8 100644 --- a/lib/libc_r/man/pthread_attr_setdetachstate.3 +++ b/lib/libc_r/man/pthread_attr_setdetachstate.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_attr_setdetachstate.3,v 1.3 2001/08/06 10:42:26 mpech Exp $ +.\" $OpenBSD: pthread_attr_setdetachstate.3,v 1.4 2002/05/01 08:03:30 mpech Exp $ .\" Manual page derived from TOG's UNIX98 documentation. .Dd January 6, 2000 .Dt PTHREAD_ATTR_SETDETACHSTATE 3 @@ -17,7 +17,8 @@ The .Va detachstate attribute controls whether the thread is created in -a detached state. If the thread is created detached, then use of +a detached state. +If the thread is created detached, then use of the ID of the newly created thread by the .Xr pthread_detach 3 or @@ -51,7 +52,8 @@ using a value of causes all threads created with .Fa attr -to be in the joinable state. The default value of the +to be in the joinable state. +The default value of the .Va detachstate attribute is .Dv PTHREAD_CREATE_JOINABLE . diff --git a/lib/libc_r/man/pthread_attr_setstackaddr.3 b/lib/libc_r/man/pthread_attr_setstackaddr.3 index dec5d0fc999..7254e83cceb 100644 --- a/lib/libc_r/man/pthread_attr_setstackaddr.3 +++ b/lib/libc_r/man/pthread_attr_setstackaddr.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_attr_setstackaddr.3,v 1.3 2000/04/15 02:15:26 aaron Exp $ +.\" $OpenBSD: pthread_attr_setstackaddr.3,v 1.4 2002/05/01 08:03:30 mpech Exp $ .\" Manual page derived from TOG's UNIX98 documentation. .Dd January 6, 2000 .Dt PTHREAD_ATTR_SETSTACKADDR 3 @@ -28,8 +28,8 @@ object. The .Va stackaddr attribute specifies the location of storage to be -used for the created thread's stack. The size of the storage is at -least +used for the created thread's stack. +The size of the storage is at least .Dv PTHREAD_STACK_MIN . .Sh RETURN VALUE Upon successful completion, diff --git a/lib/libc_r/man/pthread_cancel.3 b/lib/libc_r/man/pthread_cancel.3 index d03467a8c73..1d9fad5c5ce 100644 --- a/lib/libc_r/man/pthread_cancel.3 +++ b/lib/libc_r/man/pthread_cancel.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_cancel.3,v 1.9 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_cancel.3,v 1.10 2002/05/01 08:03:30 mpech Exp $ .\" .Dd January 17, 1999 .Dt PTHREAD_CANCEL 3 @@ -15,11 +15,13 @@ The .Fn pthread_cancel function requests that .Fa thread -be cancelled. The target thread's cancelability state and type determines -when the cancellation takes effect. When the cancellation is acted on, -the cancellation cleanup handlers for +be cancelled. +The target thread's cancelability state and type determines +when the cancellation takes effect. +When the cancellation is acted on, the cancellation cleanup handlers for .Fa thread -are called. When the last cancellation cleanup handler returns, +are called. +When the last cancellation cleanup handler returns, the thread-specific data destructor functions will be called for .Fa thread . When the last destructor function returns, @@ -32,8 +34,8 @@ respect to the calling thread returning from .Pp A status of .Dv PTHREAD_CANCELED -is made available to any threads joining with the target. The symbolic -constant +is made available to any threads joining with the target. +The symbolic constant .Dv PTHREAD_CANCELED expands to a constant expression of type .Ft "(void *)" @@ -42,8 +44,8 @@ whose value matches no pointer to an object in memory nor the value .Sh RETURN VALUES If successful, the .Fn pthread_cancel -functions will return zero. Otherwise an error number will be returned to -indicate the error. +functions will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_cancel will fail if: diff --git a/lib/libc_r/man/pthread_cleanup_pop.3 b/lib/libc_r/man/pthread_cleanup_pop.3 index c642070445a..ec6ebbb0f61 100644 --- a/lib/libc_r/man/pthread_cleanup_pop.3 +++ b/lib/libc_r/man/pthread_cleanup_pop.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_cleanup_pop.3,v 1.6 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_cleanup_pop.3,v 1.7 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> .\" All rights reserved. @@ -45,8 +45,8 @@ The function pops the top cleanup routine off of the current thread's cleanup routine stack, and, if .Fa execute -is non-zero, it will execute the function. If there is no cleanup routine -then +is non-zero, it will execute the function. +If there is no cleanup routine then .Fn pthread_cleanup_pop does nothing. .Sh RETURN VALUES diff --git a/lib/libc_r/man/pthread_cond_timedwait.3 b/lib/libc_r/man/pthread_cond_timedwait.3 index 22c2df147a0..dc0db2b463b 100644 --- a/lib/libc_r/man/pthread_cond_timedwait.3 +++ b/lib/libc_r/man/pthread_cond_timedwait.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_cond_timedwait.3,v 1.7 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_cond_timedwait.3,v 1.8 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> .\" All rights reserved. @@ -59,8 +59,8 @@ and the current thread reaquires the lock on .Sh RETURN VALUES If successful, the .Fn pthread_cond_timedwait -function will return zero. Otherwise an error number will be returned to -indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_cond_timedwait will fail if: diff --git a/lib/libc_r/man/pthread_cond_wait.3 b/lib/libc_r/man/pthread_cond_wait.3 index 70fe207baf4..a9158c1a554 100644 --- a/lib/libc_r/man/pthread_cond_wait.3 +++ b/lib/libc_r/man/pthread_cond_wait.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_cond_wait.3,v 1.7 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_cond_wait.3,v 1.8 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> .\" All rights reserved. @@ -48,7 +48,8 @@ variable specified by and unblocks the mutex specified by .Fa mutex . The waiting thread unblocks only after another thread calls -.Xr pthread_cond_signal 3 , or +.Xr pthread_cond_signal 3 , +or .Xr pthread_cond_broadcast 3 with the same condition variable, and the current thread reacquires the lock on @@ -56,8 +57,8 @@ on .Sh RETURN VALUES If successful, the .Fn pthread_cond_wait -function will return zero. Otherwise an error number will be returned to -indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_cond_wait will fail if: diff --git a/lib/libc_r/man/pthread_create.3 b/lib/libc_r/man/pthread_create.3 index 8bae34329dc..71eeb0ee11d 100644 --- a/lib/libc_r/man/pthread_create.3 +++ b/lib/libc_r/man/pthread_create.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_create.3,v 1.8 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_create.3,v 1.9 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -47,12 +47,13 @@ The .Fn pthread_create function is used to create a new thread, with attributes specified by .Fa attr , -within a process. If +within a process. +If .Fa attr is NULL, the default attributes are used. If the attributes specified by .Fa attr -are modified later, the thread's attributes are not affected. Upon -successful completion +are modified later, the thread's attributes are not affected. +Upon successful completion .Fn pthread_create will store the ID of the created thread in the location specified by .Fa thread . @@ -61,15 +62,18 @@ The thread is created executing .Fa start_routine with .Fa arg -as its sole argument. If the +as its sole argument. +If the .Fa start_routine returns, the effect is as if there was an implicit call to .Fn pthread_exit using the return value of .Fa start_routine -as the exit status. Note that the thread in which +as the exit status. +Note that the thread in which .Fn main -was originally invoked differs from this. When it returns from +was originally invoked differs from this. +When it returns from .Fn main , the effect is as if there was an implicit call to .Fn exit @@ -87,8 +91,8 @@ The set of signals pending for the new thread is empty. .Sh RETURN VALUES If successful, the .Fn pthread_create -function will return zero. Otherwise an error number will be returned to -indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_create will fail if: diff --git a/lib/libc_r/man/pthread_detach.3 b/lib/libc_r/man/pthread_detach.3 index 4aa837643aa..cd30b2c6e7b 100644 --- a/lib/libc_r/man/pthread_detach.3 +++ b/lib/libc_r/man/pthread_detach.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_detach.3,v 1.9 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_detach.3,v 1.10 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996-1998 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -48,22 +48,26 @@ The function is used to indicate to the implementation that storage for the thread .Fa thread -can be reclaimed when the thread terminates. If +can be reclaimed when the thread terminates. +If .Fa thread has not terminated, .Fn pthread_detach -will not cause it to terminate. The effect of multiple +will not cause it to terminate. +The effect of multiple .Fn pthread_detach calls on the same target thread is unspecified. .Sh RETURN VALUES If successful, the .Fn pthread_detach -function will return zero. Otherwise an error number will be returned to -indicate the error. Note that the function does not change the value +function will return zero. +Otherwise an error number will be returned to indicate the error. +Note that the function does not change the value of .Va errno -as it did for some drafts of the standard. These early drafts -also passed a pointer to pthread_t as the argument. Beware! +as it did for some drafts of the standard. +These early drafts also passed a pointer to pthread_t as the argument. +Beware! .Sh ERRORS .Fn pthread_detach will fail if: diff --git a/lib/libc_r/man/pthread_exit.3 b/lib/libc_r/man/pthread_exit.3 index db1b4fbf03f..6c1153e9e94 100644 --- a/lib/libc_r/man/pthread_exit.3 +++ b/lib/libc_r/man/pthread_exit.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_exit.3,v 1.9 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_exit.3,v 1.10 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -47,12 +47,14 @@ The .Fn pthread_exit function terminates the calling thread and makes the value .Fa value_ptr -available to any successful join with the terminating thread. Any +available to any successful join with the terminating thread. +Any cancellation cleanup handlers that have been pushed and are not yet popped are popped in the reverse order that they were pushed and then executed. After all cancellation handlers have been executed, if the thread has any thread-specific data, appropriate destructor functions are called in an -unspecified order. Thread termination does not release any application +unspecified order. +Thread termination does not release any application visible process resources, including, but not limited to, mutexes and file descriptors, nor does it perform any process level cleanup actions, including, but not limited to, calling @@ -73,14 +75,16 @@ that was invoked as the result of an implicit or explicit call to .Fn pthread_exit . .Pp After a thread has terminated, the result of access to local (auto) -variables of the thread is undefined. Thus, references to local variables +variables of the thread is undefined. +Thus, references to local variables of the exiting thread should not be used for the .Fn pthread_exit .Fa value_ptr parameter value. .Pp The process will exit with an exit status of 0 after the last thread has -been terminated. The behavior is as if the implementation called +been terminated. +The behavior is as if the implementation called .Fn exit with a zero argument at thread termination time. .Sh RETURN VALUES diff --git a/lib/libc_r/man/pthread_join.3 b/lib/libc_r/man/pthread_join.3 index 4399970816a..5af3f3e28b9 100644 --- a/lib/libc_r/man/pthread_join.3 +++ b/lib/libc_r/man/pthread_join.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_join.3,v 1.7 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_join.3,v 1.8 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996-1998 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -61,10 +61,11 @@ by the terminating thread is stored in the location referenced by .Fa value_ptr . When a .Fn pthread_join -returns successfully, the target thread has been terminated. The results -of multiple simultaneous calls to +returns successfully, the target thread has been terminated. +The results of multiple simultaneous calls to .Fn pthread_join -specifying the same target thread are undefined. If the thread calling +specifying the same target thread are undefined. +If the thread calling .Fn pthread_join is cancelled, then the target thread is not detached. .Pp @@ -73,8 +74,8 @@ A thread that has exited but remains unjoined counts against .Sh RETURN VALUES If successful, the .Fn pthread_join -function will return zero. Otherwise an error number will be returned to -indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_join will fail if: diff --git a/lib/libc_r/man/pthread_key_create.3 b/lib/libc_r/man/pthread_key_create.3 index 08ba9ea7e3e..0f5aa51c5dc 100644 --- a/lib/libc_r/man/pthread_key_create.3 +++ b/lib/libc_r/man/pthread_key_create.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_key_create.3,v 1.6 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_key_create.3,v 1.7 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -46,9 +46,11 @@ The .Fn pthread_key_create function creates a thread-specific data key visible to all threads in the -process. Key values provided by +process. +Key values provided by .Fn pthread_key_create -are opaque objects used to locate thread-specific data. Although the same +are opaque objects used to locate thread-specific data. +Although the same key value may be used by different threads, the values bound to the key by .Fn pthread_setspecific @@ -56,19 +58,21 @@ are maintained on a per-thread basis and persist for the life of the calling thread. .Pp Upon key creation, the value NULL is associated with the new key in all -active threads. Upon thread creation, the value NULL is associated with all +active threads. +Upon thread creation, the value NULL is associated with all defined keys in the new thread. .Pp -An optional destructor function may be associated with each key value. At -thread exit, if a key value has a non-NULL destructor pointer, and the +An optional destructor function may be associated with each key value. +At thread exit, if a key value has a non-NULL destructor pointer, and the thread has a non-NULL value associated with the key, the function pointed -to is called with the current associated value as its sole argument. The -order of destructor calls is unspecified if more than one destructor exists +to is called with the current associated value as its sole argument. +The order of destructor calls is unspecified if more than one destructor exists for a thread when it exits. .Pp If, after all the destructors have been called for all non-NULL values with associated destructors, there are still some non-NULL values with -associated destructors, then the process is repeated. If, after at least +associated destructors, then the process is repeated. +If, after at least [PTHREAD_DESTRUCTOR_ITERATIONS] iterations of destructor calls for outstanding non-NULL values, there are still some non-NULL values with associated destructors, the implementation stops calling destructors. @@ -77,8 +81,8 @@ If successful, the .Fn pthread_key_create function will store the newly created key value at the location specified by .Fa key -and returns zero. Otherwise an error number will be returned to indicate -the error. +and returns zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_key_create will fail if: diff --git a/lib/libc_r/man/pthread_key_delete.3 b/lib/libc_r/man/pthread_key_delete.3 index 02c1ee952a1..121c2d87253 100644 --- a/lib/libc_r/man/pthread_key_delete.3 +++ b/lib/libc_r/man/pthread_key_delete.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_key_delete.3,v 1.7 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: pthread_key_delete.3,v 1.8 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -51,12 +51,14 @@ The thread-specific data values associated with .Fa key need not be NULL at the time that .Fn pthread_key_delete -is called. It is the responsibility of the application to free any +is called. +It is the responsibility of the application to free any application storage or perform any cleanup actions for data structures related to the deleted key or associated thread-specific data in any threads; this cleanup can be done either before or after .Fn pthread_key_delete -is called. Any attempt to use +is called. +Any attempt to use .Fa key following the call to .Fn pthread_key_delete @@ -64,8 +66,8 @@ results in undefined behavior. .Pp The .Fn pthread_key_delete -function is callable from within destructor functions. Destructor functions -are not invoked by +function is callable from within destructor functions. +Destructor functions are not invoked by .Fn pthread_key_delete . Any destructor function that may have been associated with .Fa key @@ -73,8 +75,8 @@ will no longer be called upon thread exit. .Sh RETURN VALUES If successful, the .Fn pthread_key_delete -function will return zero. Otherwise an error number will be returned to -indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_key_delete will fail if: diff --git a/lib/libc_r/man/pthread_main_np.3 b/lib/libc_r/man/pthread_main_np.3 index 8120bea381f..76e73a3676e 100644 --- a/lib/libc_r/man/pthread_main_np.3 +++ b/lib/libc_r/man/pthread_main_np.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_main_np.3,v 1.2 2002/02/21 20:44:45 fgsch Exp $ +.\" $OpenBSD: pthread_main_np.3,v 1.3 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 2001 Peter Valchev <pvalchev@openbsd.org>. .\" All rights reserved. @@ -32,6 +32,7 @@ if the calling thread is the main thread if the calling thread is not the main thread .It -1 if the thread initialization has not completed +.El .Sh SEE ALSO .Xr pthread_self 3 , .Xr pthreads 3 diff --git a/lib/libc_r/man/pthread_once.3 b/lib/libc_r/man/pthread_once.3 index 4e1ae2a02de..83e40014787 100644 --- a/lib/libc_r/man/pthread_once.3 +++ b/lib/libc_r/man/pthread_once.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_once.3,v 1.9 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_once.3,v 1.10 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -55,7 +55,8 @@ by any thread in a process, with a given .Fa once_control , will call the .Fn init_routine -with no arguments. Subsequent calls to +with no arguments. +Subsequent calls to .Fn pthread_once with the same .Fa once_control @@ -65,14 +66,16 @@ On return from .Fn pthread_once , it is guaranteed that .Fn init_routine -has completed. The +has completed. +The .Fa once_control parameter is used to determine whether the associated initialization routine has been called. .Pp The function .Fn pthread_once -is not a cancellation point. However, if +is not a cancellation point. +However, if .Fn init_routine is a cancellation point and is cancelled, the effect on .Fa once_control is as if @@ -93,8 +96,8 @@ has automatic storage duration or is not initialized by .Sh RETURN VALUES If successful, the .Fn pthread_once -function will return zero. Otherwise an error number will be returned to -indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS None. .Sh STANDARDS diff --git a/lib/libc_r/man/pthread_rwlockattr_destroy.3 b/lib/libc_r/man/pthread_rwlockattr_destroy.3 index 90d99791832..34ef04ad608 100644 --- a/lib/libc_r/man/pthread_rwlockattr_destroy.3 +++ b/lib/libc_r/man/pthread_rwlockattr_destroy.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_rwlockattr_destroy.3,v 1.6 2000/04/12 21:48:02 aaron Exp $ +.\" $OpenBSD: pthread_rwlockattr_destroy.3,v 1.7 2002/05/01 08:03:30 mpech Exp $ .\" Copyright (c) 1998 Alex Nash .\" All rights reserved. .\" @@ -44,8 +44,8 @@ previously created with .Sh RETURN VALUES If successful, the .Fn pthread_rwlockattr_destroy -function will return zero. Otherwise an error number will be returned -to indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh SEE ALSO .Xr pthread_rwlockattr_init 3 .Sh STANDARDS diff --git a/lib/libc_r/man/pthread_rwlockattr_getpshared.3 b/lib/libc_r/man/pthread_rwlockattr_getpshared.3 index e4398ad892d..f5cb3b83e5a 100644 --- a/lib/libc_r/man/pthread_rwlockattr_getpshared.3 +++ b/lib/libc_r/man/pthread_rwlockattr_getpshared.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_rwlockattr_getpshared.3,v 1.6 2000/04/12 21:48:03 aaron Exp $ +.\" $OpenBSD: pthread_rwlockattr_getpshared.3,v 1.7 2002/05/01 08:03:30 mpech Exp $ .\" Copyright (c) 1998 Alex Nash .\" All rights reserved. .\" @@ -39,7 +39,8 @@ The .Fn pthread_rwlockattr_getpshared function is used to get the process shared setting of a read/write -lock attribute object. The setting is returned via +lock attribute object. +The setting is returned via .Fa pshared , and may be one of two values: .Bl -hang -offset flag -width 123456789012345678901234 @@ -48,14 +49,14 @@ Any thread of any process that has access to the memory where the read/write lock resides can manipulate the lock. .It Ar PTHREAD_PROCESS_PRIVATE Only threads created within the same process as the thread that -initialized the read/write lock can manipulate the lock. This is -the default value. +initialized the read/write lock can manipulate the lock. +This is the default value. .El .Sh RETURN VALUES If successful, the .Fn pthread_rwlockattr_getpshared -function will return zero. Otherwise an error number will be returned -to indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh SEE ALSO .Xr pthread_rwlock_init 3 , .Xr pthread_rwlockattr_init 3 , diff --git a/lib/libc_r/man/pthread_rwlockattr_init.3 b/lib/libc_r/man/pthread_rwlockattr_init.3 index a9e13090d08..14a2fd8dbee 100644 --- a/lib/libc_r/man/pthread_rwlockattr_init.3 +++ b/lib/libc_r/man/pthread_rwlockattr_init.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_rwlockattr_init.3,v 1.5 2000/04/12 21:48:03 aaron Exp $ +.\" $OpenBSD: pthread_rwlockattr_init.3,v 1.6 2002/05/01 08:03:30 mpech Exp $ .\" Copyright (c) 1998 Alex Nash .\" All rights reserved. .\" @@ -42,8 +42,8 @@ function is used to initialize a read/write lock attributes object. .Sh RETURN VALUES If successful, the .Fn pthread_rwlockattr_init -function will return zero. Otherwise an error number will be returned -to indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh SEE ALSO .Xr pthread_rwlock_init 3 , .Xr pthread_rwlockattr_destroy 3 , diff --git a/lib/libc_r/man/pthread_rwlockattr_setpshared.3 b/lib/libc_r/man/pthread_rwlockattr_setpshared.3 index d44cdcdfbc6..292940f15e4 100644 --- a/lib/libc_r/man/pthread_rwlockattr_setpshared.3 +++ b/lib/libc_r/man/pthread_rwlockattr_setpshared.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_rwlockattr_setpshared.3,v 1.5 2000/04/12 21:48:03 aaron Exp $ +.\" $OpenBSD: pthread_rwlockattr_setpshared.3,v 1.6 2002/05/01 08:03:30 mpech Exp $ .\" Copyright (c) 1998 Alex Nash .\" All rights reserved. .\" @@ -50,14 +50,14 @@ Any thread of any process that has access to the memory where the read/write lock resides can manipulate the lock. .It Ar PTHREAD_PROCESS_PRIVATE Only threads created within the same process as the thread that -initialized the read/write lock can manipulate the lock. This is -the default value. +initialized the read/write lock can manipulate the lock. +This is the default value. .El .Sh RETURN VALUES If successful, the .Fn pthread_rwlockattr_setpshared -function will return zero. Otherwise an error number will be returned -to indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh SEE ALSO .Xr pthread_rwlock_init 3 , .Xr pthread_rwlockattr_init 3 , diff --git a/lib/libc_r/man/pthread_setspecific.3 b/lib/libc_r/man/pthread_setspecific.3 index b64d052f192..977bce59b6f 100644 --- a/lib/libc_r/man/pthread_setspecific.3 +++ b/lib/libc_r/man/pthread_setspecific.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_setspecific.3,v 1.9 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_setspecific.3,v 1.10 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -69,8 +69,8 @@ may result in lost storage or infinite loops. .Sh RETURN VALUES If successful, the .Fn pthread_setspecific -function will return zero. Otherwise an error number will be returned to -indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_setspecific will fail if: diff --git a/lib/libc_r/man/pthread_testcancel.3 b/lib/libc_r/man/pthread_testcancel.3 index 84fef8dbb57..cd0fcd6933e 100644 --- a/lib/libc_r/man/pthread_testcancel.3 +++ b/lib/libc_r/man/pthread_testcancel.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_testcancel.3,v 1.8 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: pthread_testcancel.3,v 1.9 2002/05/01 08:03:30 mpech Exp $ .\" .Dd January 17, 1999 .Dt PTHREAD_TESTCANCEL 3 @@ -64,13 +64,14 @@ respectively. .Pp The .Fn pthread_testcancel -function creates a cancellation point in the calling thread. The +function creates a cancellation point in the calling thread. +The .Fn pthread_testcancel function has no effect if cancelability is disabled. .Ss Cancelability States The cancelability state of a thread determines the action taken upon -receipt of a cancellation request. The thread may control cancellation in -a number of ways. +receipt of a cancellation request. +The thread may control cancellation in a number of ways. .Pp Each thread maintains its own .Dq cancelability state @@ -87,7 +88,8 @@ new or pending cancellation requests may be acted upon at any time. When cancelability is enabled and the cancelability type is .Dv PTHREAD_CANCEL_DEFERRED , cancellation requests are held pending until a cancellation point (see -below) is reached. If cancelability is disabled, the setting of the +below) is reached. +If cancelability is disabled, the setting of the cancelability type has no immediate effect as all cancellation requests are held pending; however, once cancelability is enabled again the new type will be in effect. @@ -122,30 +124,33 @@ If successful, the .Fn pthread_setcancelstate and .Fn pthread_setcanceltype -functions will return zero. Otherwise, an error number shall be returned to -indicate the error. +functions will return zero. +Otherwise, an error number shall be returned to indicate the error. .Pp The .Fn pthread_setcancelstate and .Fn pthread_setcanceltype functions are used to control the points at which a thread may be -asynchronously cancelled. For cancellation control to be usable in modular +asynchronously cancelled. +For cancellation control to be usable in modular fashion, some rules must be followed. .Pp For purposes of this discussion, consider an object to be a generalization of a procedure. It is a set of procedures and global variables written as -a unit and called by clients not known by the object. Objects may depend -on other objects. +a unit and called by clients not known by the object. +Objects may depend on other objects. .Pp First, cancelability should only be disabled on entry to an object, never -explicitly enabled. On exit from an object, the cancelability state should +explicitly enabled. +On exit from an object, the cancelability state should always be restored to its value on entry to the object. .Pp This follows from a modularity argument: if the client of an object (or the client of an object that uses that object) has disabled cancelability, it is because the client doesn't want to have to worry about how to clean up if the -thread is cancelled while executing some sequence of actions. If an object +thread is cancelled while executing some sequence of actions. +If an object is called in such a state and it enables cancelability and a cancellation request is pending for that thread, then the thread will be cancelled, contrary to the wish of the client that disabled. @@ -154,7 +159,8 @@ Second, the cancelability type may be explicitly set to either .Em deferred or .Em asynchronous -upon entry to an object. But as with the cancelability state, on exit from +upon entry to an object. +But as with the cancelability state, on exit from an object that cancelability type should always be restored to its value on entry to the object. .Pp diff --git a/lib/libc_r/man/pthreads.3 b/lib/libc_r/man/pthreads.3 index ebf34d84ac5..daa8cd929a8 100644 --- a/lib/libc_r/man/pthreads.3 +++ b/lib/libc_r/man/pthreads.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthreads.3,v 1.17 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: pthreads.3,v 1.18 2002/05/01 08:03:30 mpech Exp $ .\" David Leonard <d@openbsd.org>, 1998. Public domain. .Dd August 17, 1998 .Dt PTHREADS 3 @@ -23,7 +23,8 @@ option. The .Dv SIGINFO signal can be sent to a threaded process to have the library show the state of -all of its threads. The information is sent to the process' +all of its threads. +The information is sent to the process' controlling tty and describes each thread's ID, state (see @@ -185,8 +186,8 @@ Enables verbose signal output. .It Ev LIBC_R_DEBUG Display thread status every time the garbage collection thread runs, -approximately once every 10 seconds. The status display verbosity is -controled by the +approximately once every 10 seconds. +The status display verbosity is controled by the .Ev PTHREAD_DEBUG environment variable. .El @@ -240,7 +241,8 @@ The library contains a scheduler that uses the process virtual interval timer to pre-empt running threads. This means that using .Xr setitimer 2 -to alter the process virtual timer will have undefined effects. The +to alter the process virtual timer will have undefined effects. +The .Dv SIGVTALRM will never be delivered to threads in a process. .Pp diff --git a/lib/libc_r/man/sem_getvalue.3 b/lib/libc_r/man/sem_getvalue.3 index 244548aa321..25a109102d3 100644 --- a/lib/libc_r/man/sem_getvalue.3 +++ b/lib/libc_r/man/sem_getvalue.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sem_getvalue.3,v 1.2 2002/02/20 05:29:37 fgsch Exp $ +.\" $OpenBSD: sem_getvalue.3,v 1.3 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. .\" All rights reserved. @@ -68,6 +68,7 @@ conforms to .St -p1003.1-96 . .Pp The value of the semaphore is never negative, even if there are threads blocked -on the semaphore. POSIX is somewhat ambiguous in its wording with regard to +on the semaphore. +POSIX is somewhat ambiguous in its wording with regard to what the value of the semaphore should be if there are blocked waiting threads, but this behavior is conformant, given the wording of the specification. diff --git a/lib/libc_r/man/sem_wait.3 b/lib/libc_r/man/sem_wait.3 index 3ead247bd20..00d5a2fe4f3 100644 --- a/lib/libc_r/man/sem_wait.3 +++ b/lib/libc_r/man/sem_wait.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sem_wait.3,v 1.3 2002/02/20 05:29:37 fgsch Exp $ +.\" $OpenBSD: sem_wait.3,v 1.4 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. .\" All rights reserved. @@ -54,7 +54,8 @@ The .Fn sem_trywait function decrements (locks) the semaphore pointed to by .Fa sem -only if the value is non-zero. Otherwise, the semaphore is not decremented and +only if the value is non-zero. +Otherwise, the semaphore is not decremented and an error is returned. .Sh RETURN VALUES .Rv -std sem_wait diff --git a/lib/libcompat/4.3/insque.3 b/lib/libcompat/4.3/insque.3 index af76566722a..8c6b6d7cc02 100644 --- a/lib/libcompat/4.3/insque.3 +++ b/lib/libcompat/4.3/insque.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: insque.3,v 1.5 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: insque.3,v 1.6 2002/05/01 08:03:30 mpech Exp $ .\" Copyright (c) 1993 John Brezak .\" All rights reserved. .\" @@ -58,7 +58,8 @@ These interfaces are available from the compatibility library, libcompat. .Fn insque and .Fn remque -manipulate queues built from doubly linked lists. Each element in the queue +manipulate queues built from doubly linked lists. +Each element in the queue must begin with a "struct qelem". .Sh DIAGNOSTICS These functions are not atomic unless that machine architecture allows it. diff --git a/lib/libcompat/4.3/re_comp.3 b/lib/libcompat/4.3/re_comp.3 index 10f2bb42906..c1489580137 100644 --- a/lib/libcompat/4.3/re_comp.3 +++ b/lib/libcompat/4.3/re_comp.3 @@ -67,7 +67,8 @@ function returns 0 if the string .Fa s was compiled successfully; otherwise a string containing an -error message is returned. If +error message is returned. +If .Fn re_comp is passed 0 or a null string, it returns without changing the currently compiled regular expression. diff --git a/lib/libcompat/4.3/rexec.3 b/lib/libcompat/4.3/rexec.3 index 97cac56522b..2976b93ff4d 100644 --- a/lib/libcompat/4.3/rexec.3 +++ b/lib/libcompat/4.3/rexec.3 @@ -99,7 +99,8 @@ output from the command (unit 2) on this channel, and will also accept bytes on this channel as being .Tn UNIX signal numbers, to be -forwarded to the process group of the command. The diagnostic +forwarded to the process group of the command. +The diagnostic information returned does not include remote authorization failure, as the secondary connection is set up after authorization has been verified. diff --git a/lib/libkeynote/keynote.1 b/lib/libkeynote/keynote.1 index 7af0cbbf41f..1a9733d30f8 100644 --- a/lib/libkeynote/keynote.1 +++ b/lib/libkeynote/keynote.1 @@ -1,4 +1,4 @@ -.\" $OpenBSD: keynote.1,v 1.21 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: keynote.1,v 1.22 2002/05/01 08:03:30 mpech Exp $ .\" .\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) .\" @@ -146,7 +146,8 @@ is expected to already be included in the field of the assertion, either directly or indirectly (i.e., through use of a .Fa Local-Constants -attribute). Furthermore, the assertion must have a +attribute). +Furthermore, the assertion must have a .Fa Signature field (even if it is empty), as the signature is computed on everything between the diff --git a/lib/libkeynote/keynote.3 b/lib/libkeynote/keynote.3 index 56f48c09a5a..9028709586f 100644 --- a/lib/libkeynote/keynote.3 +++ b/lib/libkeynote/keynote.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: keynote.3,v 1.32 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: keynote.3,v 1.33 2002/05/01 08:03:30 mpech Exp $ .\" .\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) .\" @@ -556,7 +556,8 @@ of action authorizers in .Fa env is a linked list of .Fa struct environment -structures. The +structures. +The .Fa env_name , .Fa env_value , and @@ -836,7 +837,8 @@ On success, this function returns .Dv SIGRESULT_TRUE if the signature could be verified, or .Dv SIGRESULT_FALSE -otherwise. On failure, this function returns \-1 and sets +otherwise. +On failure, this function returns \-1 and sets .Va keynote_errno to .Er ERROR_MEMORY diff --git a/lib/libkeynote/keynote.4 b/lib/libkeynote/keynote.4 index 33f5bf8ae3c..27ae71e90a6 100644 --- a/lib/libkeynote/keynote.4 +++ b/lib/libkeynote/keynote.4 @@ -1,4 +1,4 @@ -.\" $OpenBSD: keynote.4,v 1.21 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: keynote.4,v 1.22 2002/05/01 08:03:30 mpech Exp $ .\" .\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) .\" @@ -239,7 +239,8 @@ A KeyNote assertion contains a sequence of sections, called .Sq fields , each of which specifying one aspect of the assertion's semantics. Fields start with an identifier at the beginning of a line and continue -until the next field is encountered. For example: +until the next field is encountered. +For example: .Bd -literal KeyNote-Version: 2 Comment: A simple, if contrived, email certificate for user mab @@ -298,7 +299,8 @@ attributes with names or values longer than 2048 characters. .Pp Attribute values are inherently untyped and are represented as character strings by default. -Attribute values may contain any non-NUL ASCII character. Numeric attribute +Attribute values may contain any non-NUL ASCII character. +Numeric attribute values should first be converted to an ASCII text representation by the invoking application, e.g., the value 1234.5 would be represented by the string @@ -326,8 +328,8 @@ Highest-order (maximum) compliance value in query. .It _VALUES Linearly ordered set of compliance value in query. .It _ACTION_AUTHORIZERS -Names of principals directly authorizing action in query. Comma -separated. +Names of principals directly authorizing action in query. +Comma separated. .El .Pp In addition, attributes with names of the form @@ -372,7 +374,8 @@ The public key of the message's signer would be given in the attribute .Sh QUERY SEMANTICS The discussion in the following sections assume some familiarity with -assertion syntax. Please refer to +assertion syntax. +Please refer to .Xr keynote 5 for more details on the syntax. .Sh QUERY PARAMETERS @@ -403,7 +406,8 @@ a very large namespace). .Sh ACTION REQUESTER At least one Principal must be identified in each query as the .Sq requester -of the action. Actions may be requested by several principals, each +of the action. +Actions may be requested by several principals, each considered to have individually requested it. This allows policies that require multiple authorizations, e.g., .Sq two person control . @@ -420,7 +424,8 @@ query. In many applications, this will be Boolean, e.g., the ordered sets {FALSE, TRUE} or {REJECT, APPROVE}. Other applications may require a range of possible values, e.g., -{No_Access, Limited_Access, Full_Access}. Note that applications should +{No_Access, Limited_Access, Full_Access}. +Note that applications should include in this set only compliance value names that are actually returned by the assertions. .Pp @@ -429,7 +434,8 @@ the query are available in the special attributes named .Qq _MIN_TRUST and .Qq _MAX_TRUST , -respectively. The complete set of query compliance values is made +respectively. +The complete set of query compliance values is made available in ascending order (from _MIN_TRUST to _MAX_TRUST) in the special attribute named .Qq _VALUES . @@ -470,7 +476,7 @@ and the Assertion Compliance Values of all assertions identifying .Aq X in the Authorizer field. -.fi +.El .Sh DIRECT AUTHORIZATION VALUE The Direct Authorization Value of a principal .Aq X @@ -550,7 +556,8 @@ the possible compliance value set would contain the values .Qq guest_access (by clause (3)) and .Qq full_access -(by clause (4)). If the ordered set of compliance values +(by clause (4)). +If the ordered set of compliance values given in the query (in ascending order) is .Pf { Ns Qo no_access .Qc , diff --git a/lib/libkeynote/keynote.5 b/lib/libkeynote/keynote.5 index 030a0bc4663..7c0a4802968 100644 --- a/lib/libkeynote/keynote.5 +++ b/lib/libkeynote/keynote.5 @@ -1,4 +1,4 @@ -.\" $OpenBSD: keynote.5,v 1.10 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: keynote.5,v 1.11 2002/05/01 08:03:30 mpech Exp $ .\" .\" The author of this code is Angelos D. Keromytis (angelos@dsl.cis.upenn.edu) .\" @@ -44,24 +44,26 @@ see RFC 2704. .Pp KeyNote assertions are divided into sections, called .Sq fields , -that serve various semantic functions. Each field starts with an +that serve various semantic functions. +Each field starts with an identifying label at the beginning of a line, followed by the .Qq \: -character and the field's contents. There can be at most one field per -line. +character and the field's contents. +There can be at most one field per line. .Pp A field may be continued over more than one line by indenting subsequent lines with at least one ASCII SPACE or TAB character. Whitespace (a SPACE, TAB, or NEWLINE character) separates tokens but -is otherwise ignored outside of quoted strings. Comments with a -leading octothorp character ('#') may begin in any column. +is otherwise ignored outside of quoted strings. +Comments with a leading octothorp character ('#') may begin in any column. .Pp One mandatory field is required in all assertions: Authorizer .Pp Six optional fields may also appear: Comment, Conditions, KeyNote-Version, Licensees, Local-Constants, Signature. .Pp -All field names are case-insensitive. The +All field names are case-insensitive. +The .Qq KeyNote-Version field, if present, appears first. The .Qq Signature @@ -194,13 +196,16 @@ operator has higher precedence than the operator. .Sh DEREFERENCED ATTRIBUTES Action attributes provide the primary mechanism for applications to -pass information to assertions. Attribute names are strings from a +pass information to assertions. +Attribute names are strings from a limited character set (see below), and attribute values are -represented internally as strings. An attribute is dereferenced simply -by using its name. In general, KeyNote allows the use of an attribute -anywhere a string literal is permitted. +represented internally as strings. +An attribute is dereferenced simply by using its name. +In general, KeyNote allows the use of an attribute anywhere a string literal +is permitted. .Pp -Attributes are dereferenced as strings by default. When required, +Attributes are dereferenced as strings by default. +When required, dereferenced attributes can be converted to integers or floating point numbers with the type conversion operators .Qq \@ @@ -229,7 +234,8 @@ dereferenced as a string and the value zero when dereferenced as an integer or float. .Pp Attribute names may be given literally or calculated from string -expressions and may be recursively dereferenced. In the simplest case, +expressions and may be recursively dereferenced. +In the simplest case, an attribute is dereferenced simply by using its name outside of quotes; e.g., the string value of the attribute named .Qq foo @@ -309,7 +315,8 @@ Cryptographic identifiers are also lexically encoded as strings: .Ed .Pp Unlike Opaque Identifiers, however, Cryptographic Identifier strings -have a special form. To be interpreted by KeyNote (for signature +have a special form. +To be interpreted by KeyNote (for signature verification), an identifier string should be of the form: .Bd -literal <IDString>:: <ALGORITHM>":"<ENCODEDBITS> ; @@ -317,15 +324,16 @@ verification), an identifier string should be of the form: .Pp .Qq ALGORITHM is an ASCII substring that describes the algorithms to be -used in interpreting the key's bits. The ALGORITHM identifies the -major cryptographic algorithm (e.g., RSA +used in interpreting the key's bits. +The ALGORITHM identifies the major cryptographic algorithm (e.g., RSA .Bq RSA78 , DSA .Bq DSA94 , etc.), structured format (e.g., PKCS1 .Bq PKCS1 ) , -and key bit encoding (e.g., HEX or BASE64). By convention, the ALGORITHM +and key bit encoding (e.g., HEX or BASE64). +By convention, the ALGORITHM substring starts with an alphabetic character and can contain letters, digits, underscores, or dashes (i.e., it should match the regular expression .Qo Ns Bo a-zA-Z @@ -345,8 +353,8 @@ canonical form for the purposes of any internal comparisons between them; see RFC 2704 for more details. .Sh KEYNOTE-VERSION FIELD The KeyNote-Version field identifies the version of the KeyNote -assertion language under which the assertion was written. The -KeyNote-Version field is of the form: +assertion language under which the assertion was written. +The KeyNote-Version field is of the form: .Bd -literal <VersionField>:: "KeyNote-Version:" <VersionString> ; <VersionString>:: <StringLiteral> @@ -566,7 +574,8 @@ If an attribute dereferenced as a number cannot be properly converted to be zero. .Sh COMMENT FIELD The Comment field allows assertions to be annotated with information -describing their purpose. It is of the form: +describing their purpose. +It is of the form: .Bd -literal <CommentField>:: "Comment:" <text> ; .Ed diff --git a/lib/libkvm/kvm_getloadavg.3 b/lib/libkvm/kvm_getloadavg.3 index fc59c01688c..929ac2660bd 100644 --- a/lib/libkvm/kvm_getloadavg.3 +++ b/lib/libkvm/kvm_getloadavg.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: kvm_getloadavg.3,v 1.5 2000/03/04 15:29:56 aaron Exp $ +.\" $OpenBSD: kvm_getloadavg.3,v 1.6 2002/05/01 08:03:30 mpech Exp $ .\" $NetBSD: kvm_getloadavg.3,v 1.2 1996/03/18 22:33:26 thorpej Exp $ .\" .\" Copyright (c) 1992, 1993 @@ -59,8 +59,8 @@ samples are retrieved and assigned to successive elements of The system imposes a maximum of 3 samples, representing averages over the last 1, 5, and 15 minutes, respectively. .Sh RETURN VALUES -If the load average was unobtainable, \-1 is returned. Otherwise, -the number of samples actually retrieved is returned. +If the load average was unobtainable, \-1 is returned. +Otherwise, the number of samples actually retrieved is returned. .Sh SEE ALSO .Xr uptime 1 , .Xr getloadavg 3 , diff --git a/lib/libocurses/ocurses.3 b/lib/libocurses/ocurses.3 index 6c632338206..789c6b3c574 100644 --- a/lib/libocurses/ocurses.3 +++ b/lib/libocurses/ocurses.3 @@ -47,8 +47,10 @@ .Op Ar libraries .Sh DESCRIPTION These routines give the user a method of updating screens with reasonable -optimization. They keep an image of the current screen, -and the user sets up an image of a new one. Then the +optimization. +They keep an image of the current screen, +and the user sets up an image of a new one. +Then the .Fn refresh tells the routines to make the current screen look like the new one. In order to initialize the routines, the routine diff --git a/lib/libossaudio/ossaudio.3 b/lib/libossaudio/ossaudio.3 index 127487a9457..a0326ba903b 100644 --- a/lib/libossaudio/ossaudio.3 +++ b/lib/libossaudio/ossaudio.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ossaudio.3,v 1.5 2001/08/18 19:33:30 brad Exp $ +.\" $OpenBSD: ossaudio.3,v 1.6 2002/05/01 08:03:30 mpech Exp $ .\" $NetBSD: ossaudio.3,v 1.12 2001/05/19 17:23:39 jdolecek Exp $ .\" .\" Copyright (c) 1997 The NetBSD Foundation, Inc. @@ -65,8 +65,8 @@ The emulation is incomplete. .Pp The emulation only covers .Va ioctl() , -there are other differences as well. E.g., on a write -that would block in non-blocking mode Linux returns +there are other differences as well. +E.g., on a write that would block in non-blocking mode Linux returns .Dv EINTR whereas .Ox 2.3 diff --git a/lib/libpcap/pcap.3 b/lib/libpcap/pcap.3 index 0570a9fe705..8ae36a94aaa 100644 --- a/lib/libpcap/pcap.3 +++ b/lib/libpcap/pcap.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pcap.3,v 1.22 2001/12/17 22:29:47 dugsong Exp $ +.\" $OpenBSD: pcap.3,v 1.23 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1994, 1996, 1997 .\" The Regents of the University of California. All rights reserved. @@ -81,7 +81,8 @@ .Fn pcap_dump_close "pcap_dumper_t *p" .Sh DESCRIPTION .Nm -provides a high level interface to packet capture systems. All packets +provides a high level interface to packet capture systems. +All packets on the network, even those destined for other hosts, are accessible through this mechanism. .Sh ROUTINES @@ -121,8 +122,8 @@ is called to open a .Dq savefile for reading. .Fa fname -specifies the name of the file to open. The file has -the same format as those used by +specifies the name of the file to open. +The file has the same format as those used by .Xr tcpdump 8 . .\" and .\" .BR tcpslice(1) . @@ -153,7 +154,8 @@ struct as returned by or .Fn pcap_open_live . .Fa fname -specifies the name of the file to open. If +specifies the name of the file to open. +If .Dv NULL is returned, .Fn pcap_geterr @@ -188,9 +190,11 @@ is filled in with an appropriate error message. .Fn pcap_dispatch is used to collect and process packets. .Fa cnt -specifies the maximum number of packets to process before returning. A +specifies the maximum number of packets to process before returning. +A .Fa cnt -of \-1 processes all the packets received in one buffer. A +of \-1 processes all the packets received in one buffer. +A .Fa cnt of 0 processes all packets until an error occurs, .Tn EOF @@ -206,7 +210,8 @@ a pointer to the struct (which precede the actual network headers and data), and a .Fa u_char -pointer to the packet data. The number of packets read is returned. +pointer to the packet data. +The number of packets read is returned. Zero is returned when .Tn EOF is reached in a savefile. @@ -313,8 +318,10 @@ returns the stream associated with the savefile. .Fn pcap_stats returns 0 and fills in a .Fa pcap_stat -struct. The values represent packet statistics from the start of the -run to the time of the call. If there is an error or the under lying +struct. +The values represent packet statistics from the start of the +run to the time of the call. +If there is an error or the under lying packet capture doesn't support packet statistics, \-1 is returned and the error text can be obtained with .Fn pcap_perror diff --git a/lib/libpthread/man/flockfile.3 b/lib/libpthread/man/flockfile.3 index cfcae20b8d5..83785f65e5f 100644 --- a/lib/libpthread/man/flockfile.3 +++ b/lib/libpthread/man/flockfile.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: flockfile.3,v 1.6 1999/07/07 10:50:05 aaron Exp $ +.\" $OpenBSD: flockfile.3,v 1.7 2002/05/01 08:03:30 mpech Exp $ .\" David Leonard <d@openbsd.org>, 1998. Public domain. .Dd August 20, 1998 .Dt FLOCKFILE 3 @@ -24,7 +24,8 @@ and .Fn funlockfile functions provide for explicit application-level locking of stdio .Ft "FILE *" -objects. These functions can be used by a thread to delineate a sequence +objects. +These functions can be used by a thread to delineate a sequence of I/O statements that are to be executed as a unit. .Pp The @@ -51,14 +52,17 @@ function. .Pp Logically, there is a lock count associated with each .Ft "FILE *" -object. This count is implicitly intialized to zero when the +object. +This count is implicitly intialized to zero when the .Ft "FILE *" -object is created. The +object is created. +The .Ft "FILE *" object is unlocked when the count is zero. When the count is positive, a single thread owns the .Ft "FILE *" -object. When the +object. +When the .Fn flockfile function is called, if the count is zero or if the count is positive and the caller owns the @@ -68,7 +72,8 @@ Otherwise, the calling thread is suspended, waiting for the count to return to zero. Each call to .Fn funlockfile -decrements the count. This allows matching calls to +decrements the count. +This allows matching calls to .Fn flockfile (or successful calls to .Fn ftrylockfile ) diff --git a/lib/libpthread/man/pthread_attr_init.3 b/lib/libpthread/man/pthread_attr_init.3 index 742012783a4..318b27d5a6b 100644 --- a/lib/libpthread/man/pthread_attr_init.3 +++ b/lib/libpthread/man/pthread_attr_init.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_attr_init.3,v 1.2 2000/04/12 21:48:02 aaron Exp $ +.\" $OpenBSD: pthread_attr_init.3,v 1.3 2002/05/01 08:03:30 mpech Exp $ .\" Manual page derived from TOG's UNIX98 documentation. .Dd January 6, 2000 .Dt PTHREAD_ATTR_INIT 3 @@ -25,8 +25,8 @@ attributes used by a given implementation. The resulting attribute object (possibly modified by setting individual attribute values), when used by .Xr pthread_create 3 , -defines the attributes of the thread created. A single attributes -object can be used in multiple simultaneous calls to +defines the attributes of the thread created. +A single attributes object can be used in multiple simultaneous calls to .Xr pthread_create 3 . .Pp The @@ -37,15 +37,16 @@ attributes object. An implementation may cause to set .Fa attr to an implementation-dependent -invalid value. The behaviour of using the attribute after it has +invalid value. +The behaviour of using the attribute after it has been destroyed is undefined. .Sh RETURN VALUE Upon successful completion, .Fn pthread_attr_init and .Fn pthread_attr_destroy -return a value of 0. Otherwise, an error -number is returned to indicate the error. +return a value of 0. +Otherwise, an error number is returned to indicate the error. .Sh ERRORS The .Fn pthread_attr_init diff --git a/lib/libpthread/man/pthread_attr_setdetachstate.3 b/lib/libpthread/man/pthread_attr_setdetachstate.3 index 408383879f0..1f0dfa45ef8 100644 --- a/lib/libpthread/man/pthread_attr_setdetachstate.3 +++ b/lib/libpthread/man/pthread_attr_setdetachstate.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_attr_setdetachstate.3,v 1.3 2001/08/06 10:42:26 mpech Exp $ +.\" $OpenBSD: pthread_attr_setdetachstate.3,v 1.4 2002/05/01 08:03:30 mpech Exp $ .\" Manual page derived from TOG's UNIX98 documentation. .Dd January 6, 2000 .Dt PTHREAD_ATTR_SETDETACHSTATE 3 @@ -17,7 +17,8 @@ The .Va detachstate attribute controls whether the thread is created in -a detached state. If the thread is created detached, then use of +a detached state. +If the thread is created detached, then use of the ID of the newly created thread by the .Xr pthread_detach 3 or @@ -51,7 +52,8 @@ using a value of causes all threads created with .Fa attr -to be in the joinable state. The default value of the +to be in the joinable state. +The default value of the .Va detachstate attribute is .Dv PTHREAD_CREATE_JOINABLE . diff --git a/lib/libpthread/man/pthread_attr_setstackaddr.3 b/lib/libpthread/man/pthread_attr_setstackaddr.3 index dec5d0fc999..7254e83cceb 100644 --- a/lib/libpthread/man/pthread_attr_setstackaddr.3 +++ b/lib/libpthread/man/pthread_attr_setstackaddr.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_attr_setstackaddr.3,v 1.3 2000/04/15 02:15:26 aaron Exp $ +.\" $OpenBSD: pthread_attr_setstackaddr.3,v 1.4 2002/05/01 08:03:30 mpech Exp $ .\" Manual page derived from TOG's UNIX98 documentation. .Dd January 6, 2000 .Dt PTHREAD_ATTR_SETSTACKADDR 3 @@ -28,8 +28,8 @@ object. The .Va stackaddr attribute specifies the location of storage to be -used for the created thread's stack. The size of the storage is at -least +used for the created thread's stack. +The size of the storage is at least .Dv PTHREAD_STACK_MIN . .Sh RETURN VALUE Upon successful completion, diff --git a/lib/libpthread/man/pthread_cancel.3 b/lib/libpthread/man/pthread_cancel.3 index d03467a8c73..1d9fad5c5ce 100644 --- a/lib/libpthread/man/pthread_cancel.3 +++ b/lib/libpthread/man/pthread_cancel.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_cancel.3,v 1.9 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_cancel.3,v 1.10 2002/05/01 08:03:30 mpech Exp $ .\" .Dd January 17, 1999 .Dt PTHREAD_CANCEL 3 @@ -15,11 +15,13 @@ The .Fn pthread_cancel function requests that .Fa thread -be cancelled. The target thread's cancelability state and type determines -when the cancellation takes effect. When the cancellation is acted on, -the cancellation cleanup handlers for +be cancelled. +The target thread's cancelability state and type determines +when the cancellation takes effect. +When the cancellation is acted on, the cancellation cleanup handlers for .Fa thread -are called. When the last cancellation cleanup handler returns, +are called. +When the last cancellation cleanup handler returns, the thread-specific data destructor functions will be called for .Fa thread . When the last destructor function returns, @@ -32,8 +34,8 @@ respect to the calling thread returning from .Pp A status of .Dv PTHREAD_CANCELED -is made available to any threads joining with the target. The symbolic -constant +is made available to any threads joining with the target. +The symbolic constant .Dv PTHREAD_CANCELED expands to a constant expression of type .Ft "(void *)" @@ -42,8 +44,8 @@ whose value matches no pointer to an object in memory nor the value .Sh RETURN VALUES If successful, the .Fn pthread_cancel -functions will return zero. Otherwise an error number will be returned to -indicate the error. +functions will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_cancel will fail if: diff --git a/lib/libpthread/man/pthread_cleanup_pop.3 b/lib/libpthread/man/pthread_cleanup_pop.3 index c642070445a..ec6ebbb0f61 100644 --- a/lib/libpthread/man/pthread_cleanup_pop.3 +++ b/lib/libpthread/man/pthread_cleanup_pop.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_cleanup_pop.3,v 1.6 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_cleanup_pop.3,v 1.7 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> .\" All rights reserved. @@ -45,8 +45,8 @@ The function pops the top cleanup routine off of the current thread's cleanup routine stack, and, if .Fa execute -is non-zero, it will execute the function. If there is no cleanup routine -then +is non-zero, it will execute the function. +If there is no cleanup routine then .Fn pthread_cleanup_pop does nothing. .Sh RETURN VALUES diff --git a/lib/libpthread/man/pthread_cond_timedwait.3 b/lib/libpthread/man/pthread_cond_timedwait.3 index 22c2df147a0..dc0db2b463b 100644 --- a/lib/libpthread/man/pthread_cond_timedwait.3 +++ b/lib/libpthread/man/pthread_cond_timedwait.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_cond_timedwait.3,v 1.7 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_cond_timedwait.3,v 1.8 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> .\" All rights reserved. @@ -59,8 +59,8 @@ and the current thread reaquires the lock on .Sh RETURN VALUES If successful, the .Fn pthread_cond_timedwait -function will return zero. Otherwise an error number will be returned to -indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_cond_timedwait will fail if: diff --git a/lib/libpthread/man/pthread_cond_wait.3 b/lib/libpthread/man/pthread_cond_wait.3 index 70fe207baf4..a9158c1a554 100644 --- a/lib/libpthread/man/pthread_cond_wait.3 +++ b/lib/libpthread/man/pthread_cond_wait.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_cond_wait.3,v 1.7 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_cond_wait.3,v 1.8 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> .\" All rights reserved. @@ -48,7 +48,8 @@ variable specified by and unblocks the mutex specified by .Fa mutex . The waiting thread unblocks only after another thread calls -.Xr pthread_cond_signal 3 , or +.Xr pthread_cond_signal 3 , +or .Xr pthread_cond_broadcast 3 with the same condition variable, and the current thread reacquires the lock on @@ -56,8 +57,8 @@ on .Sh RETURN VALUES If successful, the .Fn pthread_cond_wait -function will return zero. Otherwise an error number will be returned to -indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_cond_wait will fail if: diff --git a/lib/libpthread/man/pthread_create.3 b/lib/libpthread/man/pthread_create.3 index 8bae34329dc..71eeb0ee11d 100644 --- a/lib/libpthread/man/pthread_create.3 +++ b/lib/libpthread/man/pthread_create.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_create.3,v 1.8 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_create.3,v 1.9 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -47,12 +47,13 @@ The .Fn pthread_create function is used to create a new thread, with attributes specified by .Fa attr , -within a process. If +within a process. +If .Fa attr is NULL, the default attributes are used. If the attributes specified by .Fa attr -are modified later, the thread's attributes are not affected. Upon -successful completion +are modified later, the thread's attributes are not affected. +Upon successful completion .Fn pthread_create will store the ID of the created thread in the location specified by .Fa thread . @@ -61,15 +62,18 @@ The thread is created executing .Fa start_routine with .Fa arg -as its sole argument. If the +as its sole argument. +If the .Fa start_routine returns, the effect is as if there was an implicit call to .Fn pthread_exit using the return value of .Fa start_routine -as the exit status. Note that the thread in which +as the exit status. +Note that the thread in which .Fn main -was originally invoked differs from this. When it returns from +was originally invoked differs from this. +When it returns from .Fn main , the effect is as if there was an implicit call to .Fn exit @@ -87,8 +91,8 @@ The set of signals pending for the new thread is empty. .Sh RETURN VALUES If successful, the .Fn pthread_create -function will return zero. Otherwise an error number will be returned to -indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_create will fail if: diff --git a/lib/libpthread/man/pthread_detach.3 b/lib/libpthread/man/pthread_detach.3 index 4aa837643aa..cd30b2c6e7b 100644 --- a/lib/libpthread/man/pthread_detach.3 +++ b/lib/libpthread/man/pthread_detach.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_detach.3,v 1.9 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_detach.3,v 1.10 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996-1998 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -48,22 +48,26 @@ The function is used to indicate to the implementation that storage for the thread .Fa thread -can be reclaimed when the thread terminates. If +can be reclaimed when the thread terminates. +If .Fa thread has not terminated, .Fn pthread_detach -will not cause it to terminate. The effect of multiple +will not cause it to terminate. +The effect of multiple .Fn pthread_detach calls on the same target thread is unspecified. .Sh RETURN VALUES If successful, the .Fn pthread_detach -function will return zero. Otherwise an error number will be returned to -indicate the error. Note that the function does not change the value +function will return zero. +Otherwise an error number will be returned to indicate the error. +Note that the function does not change the value of .Va errno -as it did for some drafts of the standard. These early drafts -also passed a pointer to pthread_t as the argument. Beware! +as it did for some drafts of the standard. +These early drafts also passed a pointer to pthread_t as the argument. +Beware! .Sh ERRORS .Fn pthread_detach will fail if: diff --git a/lib/libpthread/man/pthread_exit.3 b/lib/libpthread/man/pthread_exit.3 index db1b4fbf03f..6c1153e9e94 100644 --- a/lib/libpthread/man/pthread_exit.3 +++ b/lib/libpthread/man/pthread_exit.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_exit.3,v 1.9 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_exit.3,v 1.10 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -47,12 +47,14 @@ The .Fn pthread_exit function terminates the calling thread and makes the value .Fa value_ptr -available to any successful join with the terminating thread. Any +available to any successful join with the terminating thread. +Any cancellation cleanup handlers that have been pushed and are not yet popped are popped in the reverse order that they were pushed and then executed. After all cancellation handlers have been executed, if the thread has any thread-specific data, appropriate destructor functions are called in an -unspecified order. Thread termination does not release any application +unspecified order. +Thread termination does not release any application visible process resources, including, but not limited to, mutexes and file descriptors, nor does it perform any process level cleanup actions, including, but not limited to, calling @@ -73,14 +75,16 @@ that was invoked as the result of an implicit or explicit call to .Fn pthread_exit . .Pp After a thread has terminated, the result of access to local (auto) -variables of the thread is undefined. Thus, references to local variables +variables of the thread is undefined. +Thus, references to local variables of the exiting thread should not be used for the .Fn pthread_exit .Fa value_ptr parameter value. .Pp The process will exit with an exit status of 0 after the last thread has -been terminated. The behavior is as if the implementation called +been terminated. +The behavior is as if the implementation called .Fn exit with a zero argument at thread termination time. .Sh RETURN VALUES diff --git a/lib/libpthread/man/pthread_join.3 b/lib/libpthread/man/pthread_join.3 index 4399970816a..5af3f3e28b9 100644 --- a/lib/libpthread/man/pthread_join.3 +++ b/lib/libpthread/man/pthread_join.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_join.3,v 1.7 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_join.3,v 1.8 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996-1998 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -61,10 +61,11 @@ by the terminating thread is stored in the location referenced by .Fa value_ptr . When a .Fn pthread_join -returns successfully, the target thread has been terminated. The results -of multiple simultaneous calls to +returns successfully, the target thread has been terminated. +The results of multiple simultaneous calls to .Fn pthread_join -specifying the same target thread are undefined. If the thread calling +specifying the same target thread are undefined. +If the thread calling .Fn pthread_join is cancelled, then the target thread is not detached. .Pp @@ -73,8 +74,8 @@ A thread that has exited but remains unjoined counts against .Sh RETURN VALUES If successful, the .Fn pthread_join -function will return zero. Otherwise an error number will be returned to -indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_join will fail if: diff --git a/lib/libpthread/man/pthread_key_create.3 b/lib/libpthread/man/pthread_key_create.3 index 08ba9ea7e3e..0f5aa51c5dc 100644 --- a/lib/libpthread/man/pthread_key_create.3 +++ b/lib/libpthread/man/pthread_key_create.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_key_create.3,v 1.6 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_key_create.3,v 1.7 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -46,9 +46,11 @@ The .Fn pthread_key_create function creates a thread-specific data key visible to all threads in the -process. Key values provided by +process. +Key values provided by .Fn pthread_key_create -are opaque objects used to locate thread-specific data. Although the same +are opaque objects used to locate thread-specific data. +Although the same key value may be used by different threads, the values bound to the key by .Fn pthread_setspecific @@ -56,19 +58,21 @@ are maintained on a per-thread basis and persist for the life of the calling thread. .Pp Upon key creation, the value NULL is associated with the new key in all -active threads. Upon thread creation, the value NULL is associated with all +active threads. +Upon thread creation, the value NULL is associated with all defined keys in the new thread. .Pp -An optional destructor function may be associated with each key value. At -thread exit, if a key value has a non-NULL destructor pointer, and the +An optional destructor function may be associated with each key value. +At thread exit, if a key value has a non-NULL destructor pointer, and the thread has a non-NULL value associated with the key, the function pointed -to is called with the current associated value as its sole argument. The -order of destructor calls is unspecified if more than one destructor exists +to is called with the current associated value as its sole argument. +The order of destructor calls is unspecified if more than one destructor exists for a thread when it exits. .Pp If, after all the destructors have been called for all non-NULL values with associated destructors, there are still some non-NULL values with -associated destructors, then the process is repeated. If, after at least +associated destructors, then the process is repeated. +If, after at least [PTHREAD_DESTRUCTOR_ITERATIONS] iterations of destructor calls for outstanding non-NULL values, there are still some non-NULL values with associated destructors, the implementation stops calling destructors. @@ -77,8 +81,8 @@ If successful, the .Fn pthread_key_create function will store the newly created key value at the location specified by .Fa key -and returns zero. Otherwise an error number will be returned to indicate -the error. +and returns zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_key_create will fail if: diff --git a/lib/libpthread/man/pthread_key_delete.3 b/lib/libpthread/man/pthread_key_delete.3 index 02c1ee952a1..121c2d87253 100644 --- a/lib/libpthread/man/pthread_key_delete.3 +++ b/lib/libpthread/man/pthread_key_delete.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_key_delete.3,v 1.7 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: pthread_key_delete.3,v 1.8 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -51,12 +51,14 @@ The thread-specific data values associated with .Fa key need not be NULL at the time that .Fn pthread_key_delete -is called. It is the responsibility of the application to free any +is called. +It is the responsibility of the application to free any application storage or perform any cleanup actions for data structures related to the deleted key or associated thread-specific data in any threads; this cleanup can be done either before or after .Fn pthread_key_delete -is called. Any attempt to use +is called. +Any attempt to use .Fa key following the call to .Fn pthread_key_delete @@ -64,8 +66,8 @@ results in undefined behavior. .Pp The .Fn pthread_key_delete -function is callable from within destructor functions. Destructor functions -are not invoked by +function is callable from within destructor functions. +Destructor functions are not invoked by .Fn pthread_key_delete . Any destructor function that may have been associated with .Fa key @@ -73,8 +75,8 @@ will no longer be called upon thread exit. .Sh RETURN VALUES If successful, the .Fn pthread_key_delete -function will return zero. Otherwise an error number will be returned to -indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_key_delete will fail if: diff --git a/lib/libpthread/man/pthread_main_np.3 b/lib/libpthread/man/pthread_main_np.3 index 8120bea381f..76e73a3676e 100644 --- a/lib/libpthread/man/pthread_main_np.3 +++ b/lib/libpthread/man/pthread_main_np.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_main_np.3,v 1.2 2002/02/21 20:44:45 fgsch Exp $ +.\" $OpenBSD: pthread_main_np.3,v 1.3 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 2001 Peter Valchev <pvalchev@openbsd.org>. .\" All rights reserved. @@ -32,6 +32,7 @@ if the calling thread is the main thread if the calling thread is not the main thread .It -1 if the thread initialization has not completed +.El .Sh SEE ALSO .Xr pthread_self 3 , .Xr pthreads 3 diff --git a/lib/libpthread/man/pthread_once.3 b/lib/libpthread/man/pthread_once.3 index 4e1ae2a02de..83e40014787 100644 --- a/lib/libpthread/man/pthread_once.3 +++ b/lib/libpthread/man/pthread_once.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_once.3,v 1.9 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_once.3,v 1.10 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -55,7 +55,8 @@ by any thread in a process, with a given .Fa once_control , will call the .Fn init_routine -with no arguments. Subsequent calls to +with no arguments. +Subsequent calls to .Fn pthread_once with the same .Fa once_control @@ -65,14 +66,16 @@ On return from .Fn pthread_once , it is guaranteed that .Fn init_routine -has completed. The +has completed. +The .Fa once_control parameter is used to determine whether the associated initialization routine has been called. .Pp The function .Fn pthread_once -is not a cancellation point. However, if +is not a cancellation point. +However, if .Fn init_routine is a cancellation point and is cancelled, the effect on .Fa once_control is as if @@ -93,8 +96,8 @@ has automatic storage duration or is not initialized by .Sh RETURN VALUES If successful, the .Fn pthread_once -function will return zero. Otherwise an error number will be returned to -indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS None. .Sh STANDARDS diff --git a/lib/libpthread/man/pthread_rwlockattr_destroy.3 b/lib/libpthread/man/pthread_rwlockattr_destroy.3 index 90d99791832..34ef04ad608 100644 --- a/lib/libpthread/man/pthread_rwlockattr_destroy.3 +++ b/lib/libpthread/man/pthread_rwlockattr_destroy.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_rwlockattr_destroy.3,v 1.6 2000/04/12 21:48:02 aaron Exp $ +.\" $OpenBSD: pthread_rwlockattr_destroy.3,v 1.7 2002/05/01 08:03:30 mpech Exp $ .\" Copyright (c) 1998 Alex Nash .\" All rights reserved. .\" @@ -44,8 +44,8 @@ previously created with .Sh RETURN VALUES If successful, the .Fn pthread_rwlockattr_destroy -function will return zero. Otherwise an error number will be returned -to indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh SEE ALSO .Xr pthread_rwlockattr_init 3 .Sh STANDARDS diff --git a/lib/libpthread/man/pthread_rwlockattr_getpshared.3 b/lib/libpthread/man/pthread_rwlockattr_getpshared.3 index e4398ad892d..f5cb3b83e5a 100644 --- a/lib/libpthread/man/pthread_rwlockattr_getpshared.3 +++ b/lib/libpthread/man/pthread_rwlockattr_getpshared.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_rwlockattr_getpshared.3,v 1.6 2000/04/12 21:48:03 aaron Exp $ +.\" $OpenBSD: pthread_rwlockattr_getpshared.3,v 1.7 2002/05/01 08:03:30 mpech Exp $ .\" Copyright (c) 1998 Alex Nash .\" All rights reserved. .\" @@ -39,7 +39,8 @@ The .Fn pthread_rwlockattr_getpshared function is used to get the process shared setting of a read/write -lock attribute object. The setting is returned via +lock attribute object. +The setting is returned via .Fa pshared , and may be one of two values: .Bl -hang -offset flag -width 123456789012345678901234 @@ -48,14 +49,14 @@ Any thread of any process that has access to the memory where the read/write lock resides can manipulate the lock. .It Ar PTHREAD_PROCESS_PRIVATE Only threads created within the same process as the thread that -initialized the read/write lock can manipulate the lock. This is -the default value. +initialized the read/write lock can manipulate the lock. +This is the default value. .El .Sh RETURN VALUES If successful, the .Fn pthread_rwlockattr_getpshared -function will return zero. Otherwise an error number will be returned -to indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh SEE ALSO .Xr pthread_rwlock_init 3 , .Xr pthread_rwlockattr_init 3 , diff --git a/lib/libpthread/man/pthread_rwlockattr_init.3 b/lib/libpthread/man/pthread_rwlockattr_init.3 index a9e13090d08..14a2fd8dbee 100644 --- a/lib/libpthread/man/pthread_rwlockattr_init.3 +++ b/lib/libpthread/man/pthread_rwlockattr_init.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_rwlockattr_init.3,v 1.5 2000/04/12 21:48:03 aaron Exp $ +.\" $OpenBSD: pthread_rwlockattr_init.3,v 1.6 2002/05/01 08:03:30 mpech Exp $ .\" Copyright (c) 1998 Alex Nash .\" All rights reserved. .\" @@ -42,8 +42,8 @@ function is used to initialize a read/write lock attributes object. .Sh RETURN VALUES If successful, the .Fn pthread_rwlockattr_init -function will return zero. Otherwise an error number will be returned -to indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh SEE ALSO .Xr pthread_rwlock_init 3 , .Xr pthread_rwlockattr_destroy 3 , diff --git a/lib/libpthread/man/pthread_rwlockattr_setpshared.3 b/lib/libpthread/man/pthread_rwlockattr_setpshared.3 index d44cdcdfbc6..292940f15e4 100644 --- a/lib/libpthread/man/pthread_rwlockattr_setpshared.3 +++ b/lib/libpthread/man/pthread_rwlockattr_setpshared.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_rwlockattr_setpshared.3,v 1.5 2000/04/12 21:48:03 aaron Exp $ +.\" $OpenBSD: pthread_rwlockattr_setpshared.3,v 1.6 2002/05/01 08:03:30 mpech Exp $ .\" Copyright (c) 1998 Alex Nash .\" All rights reserved. .\" @@ -50,14 +50,14 @@ Any thread of any process that has access to the memory where the read/write lock resides can manipulate the lock. .It Ar PTHREAD_PROCESS_PRIVATE Only threads created within the same process as the thread that -initialized the read/write lock can manipulate the lock. This is -the default value. +initialized the read/write lock can manipulate the lock. +This is the default value. .El .Sh RETURN VALUES If successful, the .Fn pthread_rwlockattr_setpshared -function will return zero. Otherwise an error number will be returned -to indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh SEE ALSO .Xr pthread_rwlock_init 3 , .Xr pthread_rwlockattr_init 3 , diff --git a/lib/libpthread/man/pthread_setspecific.3 b/lib/libpthread/man/pthread_setspecific.3 index b64d052f192..977bce59b6f 100644 --- a/lib/libpthread/man/pthread_setspecific.3 +++ b/lib/libpthread/man/pthread_setspecific.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_setspecific.3,v 1.9 2002/02/21 20:12:19 fgsch Exp $ +.\" $OpenBSD: pthread_setspecific.3,v 1.10 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. .\" All rights reserved. @@ -69,8 +69,8 @@ may result in lost storage or infinite loops. .Sh RETURN VALUES If successful, the .Fn pthread_setspecific -function will return zero. Otherwise an error number will be returned to -indicate the error. +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_setspecific will fail if: diff --git a/lib/libpthread/man/pthread_testcancel.3 b/lib/libpthread/man/pthread_testcancel.3 index 84fef8dbb57..cd0fcd6933e 100644 --- a/lib/libpthread/man/pthread_testcancel.3 +++ b/lib/libpthread/man/pthread_testcancel.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthread_testcancel.3,v 1.8 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: pthread_testcancel.3,v 1.9 2002/05/01 08:03:30 mpech Exp $ .\" .Dd January 17, 1999 .Dt PTHREAD_TESTCANCEL 3 @@ -64,13 +64,14 @@ respectively. .Pp The .Fn pthread_testcancel -function creates a cancellation point in the calling thread. The +function creates a cancellation point in the calling thread. +The .Fn pthread_testcancel function has no effect if cancelability is disabled. .Ss Cancelability States The cancelability state of a thread determines the action taken upon -receipt of a cancellation request. The thread may control cancellation in -a number of ways. +receipt of a cancellation request. +The thread may control cancellation in a number of ways. .Pp Each thread maintains its own .Dq cancelability state @@ -87,7 +88,8 @@ new or pending cancellation requests may be acted upon at any time. When cancelability is enabled and the cancelability type is .Dv PTHREAD_CANCEL_DEFERRED , cancellation requests are held pending until a cancellation point (see -below) is reached. If cancelability is disabled, the setting of the +below) is reached. +If cancelability is disabled, the setting of the cancelability type has no immediate effect as all cancellation requests are held pending; however, once cancelability is enabled again the new type will be in effect. @@ -122,30 +124,33 @@ If successful, the .Fn pthread_setcancelstate and .Fn pthread_setcanceltype -functions will return zero. Otherwise, an error number shall be returned to -indicate the error. +functions will return zero. +Otherwise, an error number shall be returned to indicate the error. .Pp The .Fn pthread_setcancelstate and .Fn pthread_setcanceltype functions are used to control the points at which a thread may be -asynchronously cancelled. For cancellation control to be usable in modular +asynchronously cancelled. +For cancellation control to be usable in modular fashion, some rules must be followed. .Pp For purposes of this discussion, consider an object to be a generalization of a procedure. It is a set of procedures and global variables written as -a unit and called by clients not known by the object. Objects may depend -on other objects. +a unit and called by clients not known by the object. +Objects may depend on other objects. .Pp First, cancelability should only be disabled on entry to an object, never -explicitly enabled. On exit from an object, the cancelability state should +explicitly enabled. +On exit from an object, the cancelability state should always be restored to its value on entry to the object. .Pp This follows from a modularity argument: if the client of an object (or the client of an object that uses that object) has disabled cancelability, it is because the client doesn't want to have to worry about how to clean up if the -thread is cancelled while executing some sequence of actions. If an object +thread is cancelled while executing some sequence of actions. +If an object is called in such a state and it enables cancelability and a cancellation request is pending for that thread, then the thread will be cancelled, contrary to the wish of the client that disabled. @@ -154,7 +159,8 @@ Second, the cancelability type may be explicitly set to either .Em deferred or .Em asynchronous -upon entry to an object. But as with the cancelability state, on exit from +upon entry to an object. +But as with the cancelability state, on exit from an object that cancelability type should always be restored to its value on entry to the object. .Pp diff --git a/lib/libpthread/man/pthreads.3 b/lib/libpthread/man/pthreads.3 index ebf34d84ac5..daa8cd929a8 100644 --- a/lib/libpthread/man/pthreads.3 +++ b/lib/libpthread/man/pthreads.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pthreads.3,v 1.17 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: pthreads.3,v 1.18 2002/05/01 08:03:30 mpech Exp $ .\" David Leonard <d@openbsd.org>, 1998. Public domain. .Dd August 17, 1998 .Dt PTHREADS 3 @@ -23,7 +23,8 @@ option. The .Dv SIGINFO signal can be sent to a threaded process to have the library show the state of -all of its threads. The information is sent to the process' +all of its threads. +The information is sent to the process' controlling tty and describes each thread's ID, state (see @@ -185,8 +186,8 @@ Enables verbose signal output. .It Ev LIBC_R_DEBUG Display thread status every time the garbage collection thread runs, -approximately once every 10 seconds. The status display verbosity is -controled by the +approximately once every 10 seconds. +The status display verbosity is controled by the .Ev PTHREAD_DEBUG environment variable. .El @@ -240,7 +241,8 @@ The library contains a scheduler that uses the process virtual interval timer to pre-empt running threads. This means that using .Xr setitimer 2 -to alter the process virtual timer will have undefined effects. The +to alter the process virtual timer will have undefined effects. +The .Dv SIGVTALRM will never be delivered to threads in a process. .Pp diff --git a/lib/libpthread/man/sem_getvalue.3 b/lib/libpthread/man/sem_getvalue.3 index 244548aa321..25a109102d3 100644 --- a/lib/libpthread/man/sem_getvalue.3 +++ b/lib/libpthread/man/sem_getvalue.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sem_getvalue.3,v 1.2 2002/02/20 05:29:37 fgsch Exp $ +.\" $OpenBSD: sem_getvalue.3,v 1.3 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. .\" All rights reserved. @@ -68,6 +68,7 @@ conforms to .St -p1003.1-96 . .Pp The value of the semaphore is never negative, even if there are threads blocked -on the semaphore. POSIX is somewhat ambiguous in its wording with regard to +on the semaphore. +POSIX is somewhat ambiguous in its wording with regard to what the value of the semaphore should be if there are blocked waiting threads, but this behavior is conformant, given the wording of the specification. diff --git a/lib/libpthread/man/sem_wait.3 b/lib/libpthread/man/sem_wait.3 index 3ead247bd20..00d5a2fe4f3 100644 --- a/lib/libpthread/man/sem_wait.3 +++ b/lib/libpthread/man/sem_wait.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: sem_wait.3,v 1.3 2002/02/20 05:29:37 fgsch Exp $ +.\" $OpenBSD: sem_wait.3,v 1.4 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. .\" All rights reserved. @@ -54,7 +54,8 @@ The .Fn sem_trywait function decrements (locks) the semaphore pointed to by .Fa sem -only if the value is non-zero. Otherwise, the semaphore is not decremented and +only if the value is non-zero. +Otherwise, the semaphore is not decremented and an error is returned. .Sh RETURN VALUES .Rv -std sem_wait diff --git a/lib/libusbhid/usbhid.3 b/lib/libusbhid/usbhid.3 index fbfc61077bb..066d3a8da34 100644 --- a/lib/libusbhid/usbhid.3 +++ b/lib/libusbhid/usbhid.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: usbhid.3,v 1.2 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: usbhid.3,v 1.3 2002/05/01 08:03:30 mpech Exp $ .\" $NetBSD: usb.3,v 1.14 2001/04/09 12:09:49 wiz Exp $ .\" .\" Copyright (c) 1999 Lennart Augustsson <augustss@netbsd.org> @@ -96,11 +96,11 @@ A report descriptor can be obtained by calling .Fn hid_get_report_desc with a file descriptor obtained by opening a .Xr uhid 4 -device. Alternatively a data buffer containing the report descriptor can be -passed into +device. +Alternatively a data buffer containing the report descriptor can be passed into .Fn hid_use_report_desc . -The data is copied into an internal structure. When the report descriptor -is no longer needed it should be freed by calling +The data is copied into an internal structure. +When the report descriptor is no longer needed it should be freed by calling .Fn hid_dispose_report_desc . The type .Fa report_desc_t @@ -113,8 +113,8 @@ fails it will return To parse the report descriptor the .Fn hid_start_parse function should be called with a report descriptor and a set that -describes which items that are interesting. The set is obtained -by or-ing together values +describes which items that are interesting. +The set is obtained by or-ing together values .Fa "(1 << k)" where .Fa k @@ -144,17 +144,18 @@ can be found in and the meaning of the components in the USB HID documentation. .Pp Data should be read/written to the device in the size of -the report. The size of a report (of a certain kind) can be -computed by the +the report. +The size of a report (of a certain kind) can be computed by the .Fn hid_report_size -function. If the report is prefixed by an ID byte it is -stored at +function. +If the report is prefixed by an ID byte it is stored at .Fa idp , otherwise it will contain 0. .Pp To locate a single item the .Fn hid_locate -function can be used. It should be given the usage code of +function can be used. +It should be given the usage code of the item and its kind and it will fill the item and return non-zero if the item was found. .Ss NAME TRANSLATION FUNCTIONS @@ -179,7 +180,8 @@ if it cannot be found. Before any of these functions can be called the usage table must be parsed, this is done by calling .Fn hid_init -with the name of the table. Passing +with the name of the table. +Passing .Fa NULL to this function will cause it to use the default table. .Ss DATA EXTRACTION FUNCTIONS diff --git a/lib/libutil/fparseln.3 b/lib/libutil/fparseln.3 index d2be79cde04..fb1234a73ef 100644 --- a/lib/libutil/fparseln.3 +++ b/lib/libutil/fparseln.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: fparseln.3,v 1.4 2000/01/05 18:51:11 deraadt Exp $ +.\" $OpenBSD: fparseln.3,v 1.5 2002/05/01 08:03:30 mpech Exp $ .\" $NetBSD: fparseln.3,v 1.7 1999/07/02 15:49:12 simonb Exp $ .\" .\" Copyright (c) 1997 Christos Zoulas. All rights reserved. @@ -49,7 +49,8 @@ function returns a pointer to the next logical line from the stream referenced by .Fa stream . This string is null terminated and dynamically allocated on each -invocation. It is the responsibility of the caller to free the pointer. +invocation. +It is the responsibility of the caller to free the pointer. .Pp By default, if a character is escaped, both it and the preceding escape character will be present in the returned string. diff --git a/lib/libutil/opendev.3 b/lib/libutil/opendev.3 index da874e58597..9c9e3f15cf3 100644 --- a/lib/libutil/opendev.3 +++ b/lib/libutil/opendev.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: opendev.3,v 1.14 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: opendev.3,v 1.15 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 2000, Todd C. Miller. All rights reserved. .\" Copyright (c) 1996, Jason Downs. All rights reserved. @@ -39,7 +39,8 @@ The .Fn opendev function opens a device using the .Dq short form -name. This is typically +name. +This is typically .Dq sd0 or .Dq sd0c , diff --git a/lib/libutil/openpty.3 b/lib/libutil/openpty.3 index 6d7052a7a13..f752b5c6080 100644 --- a/lib/libutil/openpty.3 +++ b/lib/libutil/openpty.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: openpty.3,v 1.7 2001/07/13 22:14:07 millert Exp $ +.\" $OpenBSD: openpty.3,v 1.8 2002/05/01 08:03:30 mpech Exp $ .\" Copyright (c) 1995 .\" The Regents of the University of California. All rights reserved. .\" @@ -103,12 +103,14 @@ function combines .Fn fork , and .Fn login_tty -to creates a new process operating in a pseudo-tty. The file +to creates a new process operating in a pseudo-tty. +The file descriptor of the master side of the pseudo-tty is returned in .Fa amaster , and the filename of the slave in .Fa name -if it is non-null. The +if it is non-null. +The .Fa termp and .Fa winp @@ -122,7 +124,8 @@ or .Fn forkpty is not successful, \-1 is returned and .Va errno -is set to indicate the error. Otherwise, +is set to indicate the error. +Otherwise, .Fn openpty , .Fn login_tty , and the child process of diff --git a/lib/libutil/pw_getconf.3 b/lib/libutil/pw_getconf.3 index c7a89a92000..f184a9cc3cd 100644 --- a/lib/libutil/pw_getconf.3 +++ b/lib/libutil/pw_getconf.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pw_getconf.3,v 1.7 2001/06/18 21:09:23 millert Exp $ +.\" $OpenBSD: pw_getconf.3,v 1.8 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de> .\" All rights reserved. @@ -64,7 +64,8 @@ an empty string will be returned in data. .Pp For default values the key .Pa default -can be used. This might be useful when no entry was found +can be used. +This might be useful when no entry was found for a specific key or option. .Pp An empty string is also returned for other errors. diff --git a/lib/libutil/pw_init.3 b/lib/libutil/pw_init.3 index 672555cbc5b..18a90493a2b 100644 --- a/lib/libutil/pw_init.3 +++ b/lib/libutil/pw_init.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pw_init.3,v 1.4 1999/09/23 04:12:01 alex Exp $ +.\" $OpenBSD: pw_init.3,v 1.5 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1995 .\" The Regents of the University of California. All rights reserved. @@ -69,7 +69,8 @@ .Fn pw_error "const char *name" "int err" "int eval" .Sh DESCRIPTION These functions are designed as conveniences for interactive programs -which update the passwd file and do nothing else. They generally +which update the passwd file and do nothing else. +They generally handle errors by printing out a message to the standard error stream and possibly aborting the process. .Pp @@ -83,7 +84,8 @@ disabling most signals. The .Fn pw_setdir function sets an alternative directory where the rest of the functions looks -for password-related files. Use this if you are writing utilities that should +for password-related files. +Use this if you are writing utilities that should be able to handle password files outside of /etc. .Pp The @@ -91,7 +93,8 @@ The function transforms filenames so that they end up in the directory specified to the latest .Fn pw_setdir -call. The rule is that all directories are stripped off the given name and +call. +The rule is that all directories are stripped off the given name and only the filename is appended to the directory. .Pp The @@ -104,7 +107,8 @@ if EDITOR is not set) on the file .Pa /etc/ptmp if .Fa filename -is NULL). If +is NULL). +If .Fa notsetuid is nonzero, .Fn pw_edit @@ -170,7 +174,8 @@ is empty. The .Fn pw_error function displays an error message, aborts the current passwd update, -and exits the current process. If +and exits the current process. +If .Fa err is non-zero, a warning message beginning with .Fa name diff --git a/lib/libutil/pw_lock.3 b/lib/libutil/pw_lock.3 index 78d42acba54..d109dc79c64 100644 --- a/lib/libutil/pw_lock.3 +++ b/lib/libutil/pw_lock.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: pw_lock.3,v 1.8 2001/08/26 03:28:30 millert Exp $ +.\" $OpenBSD: pw_lock.3,v 1.9 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1995 .\" The Regents of the University of California. All rights reserved. @@ -65,13 +65,15 @@ function attempts to lock the passwd database by creating the file .Pa /etc/ptmp with an exclusive lock (using .Xr flock 2 -semantics) and returns the file descriptor of that file. If +semantics) and returns the file descriptor of that file. +If .Fa retries is greater than zero, .Fn pw_lock will try multiple times to open .Pa /etc/ptmp , -waiting one second between tries. In addition to being a lock file, +waiting one second between tries. +In addition to being a lock file, .Pa /etc/ptmp will also hold the contents of the new passwd file. .Pp diff --git a/lib/libutil/scsi.3 b/lib/libutil/scsi.3 index 28d372a11f4..2a71b75947c 100644 --- a/lib/libutil/scsi.3 +++ b/lib/libutil/scsi.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: scsi.3,v 1.6 2000/11/10 00:06:27 deraadt Exp $ +.\" $OpenBSD: scsi.3,v 1.7 2002/05/01 08:03:30 mpech Exp $ .\" Copyright (c) 1994 HD Associates (hd@world.std.com) .\" All rights reserved. .\" @@ -79,7 +79,8 @@ use the SCIOCCOMMAND of the SCSI subsystem to provide user level access to SCSI commands. The programmer must know the SCSI CDB (Command Descriptor -Block) to perform the desired command. These functions assist in +Block) to perform the desired command. +These functions assist in building up the CDB, submitting it to the SCSI subsystem, and decoding the result. .Pp @@ -89,7 +90,8 @@ command before using the library directly - simple programs are best implemented as scripts using that facility. .Pp To provide for security, -not all devices accept the SCIOCCOMAND ioctl. It is accepted by the +not all devices accept the SCIOCCOMAND ioctl. +It is accepted by the control device for tape drives, partition D for disk drives, partition C for CD ROM drives, and any "unknown" device. The "super scsi" @@ -145,8 +147,8 @@ determined by the argument. .Pp .Fr buf -is the data buffer used during the SCSI data phase. If it is NULL it -is allocated via malloc and +is the data buffer used during the SCSI data phase. +If it is NULL it is allocated via malloc and .Ar scsireq->databuf is set to point to the newly allocated memory. .Pp @@ -171,17 +173,17 @@ indicates a data out phase (a transfer out of the user buffer). .Pp .Fr fmt is a CDB format specifier used to build up the SCSI CDB. -This text string is made up of a list of field specifiers. Field -specifiers specify the value for each CDB field (including indicating +This text string is made up of a list of field specifiers. +Field specifiers specify the value for each CDB field (including indicating that the value be taken from the next argument in the variable argument list), the width -of the field in bits or bytes, and an optional name. White space is -ignored, and the pound sign ('#') introduces a comment that ends at the -end of the current line. +of the field in bits or bytes, and an optional name. +White space is ignored, and the pound sign ('#') introduces a comment that +ends at the end of the current line. .Pp The optional name is the first part of a field specifier and -is in curly braces. The text in curly braces in this example are -the names: +is in curly braces. +The text in curly braces in this example are the names: .Bd -literal -offset indent .Fr "{PS} v:b1 {Reserved} 0:b1 {Page Code} v:b6 # Mode select page" .Ed @@ -277,8 +279,8 @@ described above in .Fn scsireq_decode . .Pp .Fn scsireq_encode -encodes the data phase section of the structure. The encoding is -handled identically as the encoding of the CDB structure by +encodes the data phase section of the structure. +The encoding is handled identically as the encoding of the CDB structure by .Fn scsireq_build .Pp .Fn scsireq_enter @@ -330,11 +332,14 @@ returns the result of the ioctl call. .Xr scsi 4 , .Xr scsi 8 .Sh BUGS -This only works completely for the 1542C. The host adapter code +This only works completely for the 1542C. +The host adapter code that sets up the residual amount of data transfer has to be added -to each individual adapter. This library is usable on the other +to each individual adapter. +This library is usable on the other host adapters; however, the SCSI driver pretends that the proper -amount of data is always transferred. If you have an Adaptec 174x +amount of data is always transferred. +If you have an Adaptec 174x and can hack contact dufault@hda.com and you can have the code to calculate residual data for the 174x series to integrate and test. .Sh HISTORY @@ -342,7 +347,8 @@ Many systems have comparable interfaces to permit a user to construct a SCSI command in user space. .Pp The data structure is almost identical to the SGI /dev/scsi data -structure. If anyone knows the name of the authors it should +structure. +If anyone knows the name of the authors it should go here; Peter Dufault first read about it in a 1989 Sun Expert magazine. .Pp Peter Dufault implemented a clone of SGI's interface in 386bsd that diff --git a/lib/libutil/uucplock.3 b/lib/libutil/uucplock.3 index 07b19a68869..c52cb84630f 100644 --- a/lib/libutil/uucplock.3 +++ b/lib/libutil/uucplock.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: uucplock.3,v 1.12 2001/08/06 10:42:26 mpech Exp $ +.\" $OpenBSD: uucplock.3,v 1.13 2002/05/01 08:03:30 mpech Exp $ .\" .\" All rights reserved. .\" @@ -123,7 +123,8 @@ the reason for failure is returned. .Fn uu_lockerr uses the current value of .Va errno -to determine the exact error. Care should be made not to allow +to determine the exact error. +Care should be made not to allow .Va errno to be changed between calls to .Fn uu_lock @@ -134,8 +135,8 @@ and may return any of the following values: .Pp .Dv UU_LOCK_OK : -The transfer was successful. The specified process now holds the device -lock. +The transfer was successful. +The specified process now holds the device lock. .Pp .Dv UU_LOCK_OWNER_ERR : The current process does not already own a lock on the specified device. @@ -148,8 +149,8 @@ If .Fn uu_lock returns one of the error values above, the global value .Va errno -can be used to determine the cause. Refer to the respective manual pages -for further details. +can be used to determine the cause. +Refer to the respective manual pages for further details. .Pp .Fn uu_unlock will set the global variable @@ -170,6 +171,7 @@ the stale lock. .Pp The calling process must have write permissions to the .Pa /var/spool/lock -directory. There is no mechanism in place to ensure that the +directory. +There is no mechanism in place to ensure that the permissions of this directory are the same as those of the serial devices that might be locked. diff --git a/lib/libwrap/hosts_access.3 b/lib/libwrap/hosts_access.3 index 1901301aae5..5f2db60fc80 100644 --- a/lib/libwrap/hosts_access.3 +++ b/lib/libwrap/hosts_access.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: hosts_access.3,v 1.7 2001/09/06 15:04:34 mpech Exp $ +.\" $OpenBSD: hosts_access.3,v 1.8 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1997, Jason Downs. All rights reserved. .\" @@ -54,17 +54,20 @@ .Sh DESCRIPTION The routines described in this document are part of the .Nm libwrap.a -library. They implement a rule-based access control language with +library. +They implement a rule-based access control language with optional shell commands that are executed when a rule fires. .Pp .Fn request_init initializes a structure with information about a client request. .Fn request_set -updates an already initialized request structure. Both functions take a +updates an already initialized request structure. +Both functions take a variable-length list of key-value pairs and return their first argument. -The argument lists are terminated with a zero key value. All string-valued -arguments are copied. The expected keys (and corresponding value types) are: +The argument lists are terminated with a zero key value. +All string-valued arguments are copied. +The expected keys (and corresponding value types) are: .Bl -tag -width XXXXXXXXXXXXXXXXXXXXXXXX .It "RQ_FILE (int)" The file descriptor associated with the request. @@ -91,7 +94,8 @@ The name of the user on whose behalf the client host makes the request. .Fn hosts_access consults the access control tables described in the .Xr hosts_access 5 -manual page. When internal endpoint information is available, host names +manual page. +When internal endpoint information is available, host names and client user names are looked up on demand, using the request structure as a cache. .Fn hosts_access @@ -104,7 +108,8 @@ and .Fn hosts_access routines with a perhaps more convenient interface (though it does not pass on enough information to support automated client username -lookups). The client host address, client host name and username +lookups). +The client host address, client host name and username arguments should contain valid data or STRING_UNKNOWN. .Fn hosts_ctl returns zero if access should be denied. @@ -114,9 +119,9 @@ The and .Fa deny_severity variables determine -how accepted and rejected requests may be logged. They must be provided -by the caller and may be modified by rules in the access control -tables. +how accepted and rejected requests may be logged. +They must be provided +by the caller and may be modified by rules in the access control tables. .Sh DIAGNOSTICS Problems are reported via the syslog daemon. .Sh SEE ALSO diff --git a/lib/libwrap/hosts_access.5 b/lib/libwrap/hosts_access.5 index 32a48d87dc1..b00b72ae29b 100644 --- a/lib/libwrap/hosts_access.5 +++ b/lib/libwrap/hosts_access.5 @@ -1,4 +1,4 @@ -.\" $OpenBSD: hosts_access.5,v 1.13 2001/09/06 15:04:34 mpech Exp $ +.\" $OpenBSD: hosts_access.5,v 1.14 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1997, Jason Downs. All rights reserved. .\" @@ -41,8 +41,9 @@ .Sh DESCRIPTION This manual page describes a simple access control language that is based on client (host name/address, user name), and server (process -name, host name/address) patterns. Examples are given at the end. The -impatient reader is encouraged to skip to the EXAMPLES section for a +name, host name/address) patterns. +Examples are given at the end. +The impatient reader is encouraged to skip to the EXAMPLES section for a quick introduction. .Pp An extended version of the access control language is described in the @@ -58,8 +59,8 @@ is the process name of a network daemon process, and is the name and/or address of a host requesting service. Network daemon process names are specified in the inetd configuration file. .Sh ACCESS CONTROL FILES -The access control software consults two files. The search stops -at the first match: +The access control software consults two files. +The search stops at the first match: .Bl -bullet -tag -width XXX .It Access will be granted when a (daemon,client) pair matches an entry in @@ -76,17 +77,17 @@ Otherwise, access will be granted. .El .Pp A non-existing access control file is treated as if it were an empty -file. Thus, access control can be turned off by providing no access -control files. +file. +Thus, access control can be turned off by providing no access control files. .Sh ACCESS CONTROL RULES -Each access control file consists of zero or more lines of text. These -lines are processed in order of appearance. The search terminates when a -match is found. +Each access control file consists of zero or more lines of text. +These lines are processed in order of appearance. +The search terminates when a match is found. .Bl -bullet -tag -width XXX .It A newline character is ignored when it is preceded by a backslash -character. This permits you to break up long lines so that they are -easier to edit. +character. +This permits you to break up long lines so that they are easier to edit. .It Blank lines or lines that begin with a .Sq # @@ -133,8 +134,8 @@ A string that begins with a .Ns . .Sc character. A host name is matched if -the last components of its name match the specified pattern. For -example, the pattern +the last components of its name match the specified pattern. +For example, the pattern .Sq .tue.nl matches the host name .Sq wzv.win.tue.nl . @@ -143,8 +144,9 @@ A string that ends with a .So .Ns . .Sc -character. A host address is matched if its first numeric fields match the -given string. For example, the pattern +character. +A host address is matched if its first numeric fields match the given string. +For example, the pattern .So 131.155. .Sc @@ -154,9 +156,10 @@ network (131.155.x.x). A string that begins with an .Sq @ character is treated as an NIS -(formerly YP) netgroup name. A host name is matched if it is a host -member of the specified netgroup. Netgroup matches are not supported -for daemon process names or for client user names. +(formerly YP) netgroup name. +A host name is matched if it is a host member of the specified netgroup. +Netgroup matches are not supported for daemon process names or for client +user names. .It An expression of the form .Sq n.n.n.n/m.m.m.m @@ -203,15 +206,17 @@ The universal wildcard, always matches. Matches any host whose name does not contain a dot character. .It UNKNOWN Matches any user whose name is unknown, and matches any host whose name -or address are unknown. This pattern should be used with care: -host names may be unavailable due to temporary name server problems. A -network address will be unavailable when the software cannot figure out +or address are unknown. +This pattern should be used with care: +host names may be unavailable due to temporary name server problems. +A network address will be unavailable when the software cannot figure out what type of network it is talking to. .It KNOWN Matches any user whose name is known, and matches any host whose name -and address are known. This pattern should be used with care: -host names may be unavailable due to temporary name server problems. A -network address will be unavailable when the software cannot figure out +and address are known. +This pattern should be used with care: +host names may be unavailable due to temporary name server problems. +A network address will be unavailable when the software cannot figure out what type of network it is talking to. .\" .IP PARANOID .\" Matches any host whose name does not match its address. When tcpd is @@ -228,7 +233,8 @@ this construct matches anything that matches unless it matches .Ar list_2 . The EXCEPT operator can be used in daemon_lists and in -client_lists. The EXCEPT operator can be nested: if the control +client_lists. +The EXCEPT operator can be nested: if the control language would permit the use of parentheses, .Sq a EXCEPT b EXCEPT c would parse as @@ -293,25 +299,29 @@ process_name@host_pattern : client_list ... .Ed .Pp Patterns like these can be used when the machine has different internet -addresses with different internet hostnames. Service providers can use +addresses with different internet hostnames. +Service providers can use this facility to offer FTP, GOPHER or WWW archives with internet names -that may even belong to different organizations. See also the +that may even belong to different organizations. +See also the .Sq twist option in the .Xr hosts_options 5 -document. Many systems can have more than one internet address on one physical +document. +Many systems can have more than one internet address on one physical interface; with other systems you may have to resort to SLIP or PPP pseudo interfaces that live in a dedicated network address space. .Pp The host_pattern obeys the same syntax rules as host names and -addresses in client_list context. Usually, server endpoint information +addresses in client_list context. +Usually, server endpoint information is available only with connection-oriented services. .Sh CLIENT USERNAME LOOKUP When the client host supports the RFC 931 protocol or one of its descendants (TAP, IDENT, RFC 1413) the wrapper programs can retrieve -additional information about the owner of a connection. Client username -information, when available, is logged together with the client host -name, and can be used to match patterns like: +additional information about the owner of a connection. +Client username information, when available, is logged together with the +client host name, and can be used to match patterns like: .Pp .Bd -unfilled -offset indent daemon_list : ... user_pattern@host_pattern ... @@ -319,7 +329,8 @@ daemon_list : ... user_pattern@host_pattern ... .Pp The daemon wrappers can be configured at compile time to perform rule-driven username lookups (default) or to always interrogate the -client host. In the case of rule-driven username lookups, the above +client host. +In the case of rule-driven username lookups, the above rule would cause username lookup only when both the .Ar daemon_list and the @@ -327,13 +338,13 @@ and the match. .Pp A user pattern has the same syntax as a daemon process pattern, so the -same wildcards apply (netgroup membership is not supported). One -should not get carried away with username lookups, though. +same wildcards apply (netgroup membership is not supported). +One should not get carried away with username lookups, though. .Bl -bullet -tag -width XXX .It The client username information cannot be trusted when it is needed -most, i.e., when the client system has been compromised. In general, -ALL and (UN)KNOWN are the only user name patterns that make sense. +most, i.e., when the client system has been compromised. +In general, ALL and (UN)KNOWN are the only user name patterns that make sense. .It Username lookups are possible only with TCP-based services, and only when the client host runs a suitable daemon; in all other cases the @@ -343,8 +354,8 @@ result is "unknown". .\" lookups are blocked by a firewall. The wrapper README document .\" describes a procedure to find out if your kernel has this bug. .It -Username lookups may cause noticeable delays for non-UNIX users. The -default timeout for username lookups is 10 seconds: too short to cope +Username lookups may cause noticeable delays for non-UNIX users. +The default timeout for username lookups is 10 seconds: too short to cope with slow networks, but long enough to irritate PC users. .El .Pp @@ -360,9 +371,9 @@ but would perform username lookups with all other systems. .Sh DETECTING ADDRESS SPOOFING ATTACKS A flaw in the sequence number generator of many TCP/IP implementations allows intruders to easily impersonate trusted hosts and to break in -via, for example, the remote shell service. The IDENT (RFC931 etc.) -service can be used to detect such and other host address spoofing -attacks. +via, for example, the remote shell service. +The IDENT (RFC931 etc.) +service can be used to detect such and other host address spoofing attacks. .Pp Before accepting a client request, the wrappers can use the IDENT service to find out that the client did not send the request at all. @@ -373,15 +384,17 @@ is strong evidence of a host spoofing attack. .Pp A positive IDENT lookup result (the client matches .Sq KNOWN@host ) -is less trustworthy. It is possible for an intruder to spoof both the +is less trustworthy. +It is possible for an intruder to spoof both the client connection and the IDENT lookup, although doing so is much -harder than spoofing just a client connection. It may also be that -the client\'s IDENT server is lying. +harder than spoofing just a client connection. +It may also be that the client\'s IDENT server is lying. .Pp Note: IDENT lookups don\'t work with UDP services. .Sh EXAMPLES The language is flexible enough that different types of access control -policy can be expressed with a minimum of fuss. Although the language +policy can be expressed with a minimum of fuss. +Although the language uses two access control tables, the most common policies can be implemented with one of the tables being trivial or even empty. .Pp @@ -390,12 +403,13 @@ allow table is scanned before the deny table, that the search terminates when a match is found, and that access is granted when no match is found at all. .Pp -The examples use host and domain names. They can be improved by +The examples use host and domain names. +They can be improved by including address and/or network/netmask information, to reduce the impact of temporary name server lookup failures. .Sh MOSTLY CLOSED -In this case, access is denied by default. Only explicitly authorized -hosts are permitted access. +In this case, access is denied by default. +Only explicitly authorized hosts are permitted access. .Pp The default policy (no access) is implemented with a trivial deny file: @@ -427,7 +441,8 @@ The first rule permits access from hosts in the local domain (no .Sc in the host name) and from members of the .Ar some_netgroup -netgroup. The second rule permits access from all hosts in the +netgroup. +The second rule permits access from all hosts in the .Ar foobar.edu domain (notice the leading dot), with the exception of .Ar terminalserver.foobar.edu . @@ -436,8 +451,9 @@ Here, access is granted by default; only explicitly specified hosts are refused service. .Pp The default policy (access granted) makes the allow file redundant so -that it can be omitted. The explicitly non-authorized hosts are listed -in the deny file. For example: +that it can be omitted. +The explicitly non-authorized hosts are listed in the deny file. +For example: .Pp .Bd -unfilled -offset indent /etc/hosts.deny: @@ -451,9 +467,10 @@ The first rule denies some hosts and domains all services; the second rule still permits finger requests from other hosts and domains. .Sh BOOBY TRAPS The next example permits tftp requests from hosts in the local domain -(notice the leading dot). Requests from any other hosts are denied. -Instead of the requested file, a finger probe is sent to the offending -host. The result is mailed to the superuser. +(notice the leading dot). +Requests from any other hosts are denied. +Instead of the requested file, a finger probe is sent to the offending host. +The result is mailed to the superuser. .Pp .Bd -unfilled -offset indent /etc/hosts.allow: @@ -473,9 +490,9 @@ tftpd: ALL: (/some/where/safe_finger -l @%h | \\ The .Nm safe_finger command comes with the tcpd wrapper and should be -installed in a suitable place. It limits possible damage from data sent -by the remote finger server. It gives better protection than the -standard finger command. +installed in a suitable place. +It limits possible damage from data sent by the remote finger server. +It gives better protection than the standard finger command. .Pp The expansion of the %h (client host) and %d (service name) sequences is described in the section on shell commands. @@ -493,7 +510,8 @@ control rule; when the length of an access control rule exceeds the capacity of an internal buffer; when an access control rule is not terminated by a newline character; when the result of %<letter> expansion would overflow an internal buffer; when a system call fails -that shouldn\'t. All problems are reported via the syslog daemon. +that shouldn\'t. +All problems are reported via the syslog daemon. .Sh FILES .Bl -tag -width /etc/hosts.allow -compact .It Pa /etc/hosts.allow diff --git a/lib/libwrap/hosts_options.5 b/lib/libwrap/hosts_options.5 index 94677c2da34..ec265beca62 100644 --- a/lib/libwrap/hosts_options.5 +++ b/lib/libwrap/hosts_options.5 @@ -1,4 +1,4 @@ -.\" $OpenBSD: hosts_options.5,v 1.6 2001/09/06 15:04:34 mpech Exp $ +.\" $OpenBSD: hosts_options.5,v 1.7 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 1997, Jason Downs. All rights reserved. .\" @@ -53,27 +53,30 @@ daemon_list : client_list : option : option ... The first two fields are described in the .Xr hosts_access 5 manual page. -The remainder of the rules is a list of zero or more options. Any ":" +The remainder of the rules is a list of zero or more options. +Any ":" characters within options should be protected with a backslash. .Pp -An option is of the form "keyword" or "keyword value". Options are -processed in the specified order. Some options are subjected to -%<letter> substitutions. For the sake of backwards compatibility with +An option is of the form "keyword" or "keyword value". +Options are processed in the specified order. +Some options are subjected to %<letter> substitutions. +For the sake of backwards compatibility with earlier versions, an "=" is permitted between keyword and value. .Sh LOGGING .Bl -tag -width "severity mail.info" .It "severity mail.info" .It "severity notice" -Change the severity level at which the event will be logged. Facility -names (such as mail) are optional, and are not supported on systems -with older syslog implementations. The severity option can be used -to emphasize or to ignore specific events. +Change the severity level at which the event will be logged. +Facility names (such as mail) are optional, and are not supported +on systems with older syslog implementations. +The severity option can be used to emphasize or to ignore specific events. .El .Sh ACCESS CONTROL .Bl -tag -width allow .It "allow" .It "deny" -Grant (deny) service. These options must appear at the end of a rule. +Grant (deny) service. +These options must appear at the end of a rule. .El .Pp The @@ -105,9 +108,11 @@ Notice the leading dot on the domain name patterns. .It "spawn shell_command" Execute, in a child process, the specified shell command, after performing the %<letter> expansions described in the hosts_access(5) -manual page. The command is executed with stdin, stdout and stderr +manual page. +The command is executed with stdin, stdout and stderr connected to the null device, so that it won\'t mess up the -conversation with the client host. Example: +conversation with the client host. +Example: .Bd -unfilled -offset indent spawn (/some/where/safe_finger -l @%h | /usr/ucb/mail root) & .Ed @@ -118,15 +123,17 @@ remote host. .Pp The example uses the "safe_finger" command instead of the regular "finger" command, to limit possible damage from data sent by the finger -server. The "safe_finger" command is part of the daemon wrapper +server. +The "safe_finger" command is part of the daemon wrapper package; it is a wrapper around the regular finger command that filters the data sent by the remote host. .It "twist shell_command" Replace the current process by an instance of the specified shell command, after performing the %<letter> expansions described in the .Xr hosts_access 5 -manual page. Stdin, stdout and stderr are connected to -the client process. This option must appear at the end of a rule. +manual page. +Stdin, stdout and stderr are connected to the client process. +This option must appear at the end of a rule. .Pp To send a customized bounce message to the client instead of running the real ftp daemon: @@ -155,11 +162,11 @@ the client process; UDP requires other I/O primitives. .Sh NETWORK OPTIONS .Bl -tag -width "linger number_of_seconds" .It "keepalive" -Causes the server to periodically send a message to the client. The -connection is considered broken when the client does not respond. The -keepalive option can be useful when users turn off their machine while -it is still connected to a server. The keepalive option is not useful -for datagram (UDP) services. +Causes the server to periodically send a message to the client. +The connection is considered broken when the client does not respond. +The keepalive option can be useful when users turn off their machine while +it is still connected to a server. +The keepalive option is not useful for datagram (UDP) services. .It "linger number_of_seconds" Specifies how long the kernel will try to deliver not-yet delivered data after the server process closes a connection. @@ -168,11 +175,14 @@ data after the server process closes a connection. .Bl -tag -width "rfc931 [ timeout_in_seconds ]" .It "rfc931 [ timeout_in_seconds ]" Look up the client user name with the RFC 931 (TAP, IDENT, RFC 1413) -protocol. This option is silently ignored in case of services based on -transports other than TCP. It requires that the client system runs an +protocol. +This option is silently ignored in case of services based on +transports other than TCP. +It requires that the client system runs an RFC 931 (IDENT, etc.) -compliant daemon, and may cause noticeable -delays with connections from non-UNIX clients. The timeout period is -optional. If no timeout is specified a compile-time defined default +delays with connections from non-UNIX clients. +The timeout period is optional. +If no timeout is specified a compile-time defined default value is taken. .El .Sh MISCELLANEOUS @@ -194,25 +204,27 @@ manual page). Warning: banners are supported for connection-oriented (TCP) network services only. .It "nice [ number ]" -Change the nice value of the process (default 10). Specify a positive -value to spend more CPU resources on other processes. +Change the nice value of the process (default 10). +Specify a positive value to spend more CPU resources on other processes. .It "setenv name value" -Place a (name, value) pair into the process environment. The value is -subjected to %<letter> expansions and may contain whitespace (but +Place a (name, value) pair into the process environment. +The value is subjected to %<letter> expansions and may contain whitespace (but leading and trailing blanks are stripped off). .Pp Warning: many network daemons reset their environment before spawning a login or shell process. .It "umask 022" -Like the umask command that is built into the shell. An umask of 022 +Like the umask command that is built into the shell. +An umask of 022 prevents the creation of files with group and world write permission. The umask argument should be an octal number. .It "user nobody" .It "user nobody.kmem" Assume the privileges of the "nobody" userid (or user "nobody", group -"kmem"). The first form is useful with inetd implementations that run -all services with root privilege. The second form is useful for -services that need special group privileges only. +"kmem"). +The first form is useful with inetd implementations that run all services with +root privilege. +The second form is useful for services that need special group privileges only. .El .Sh DIAGNOSTICS When a syntax error is found in an access control rule, the error diff --git a/lib/libwrap/rfc1413.3 b/lib/libwrap/rfc1413.3 index 59d2a11e6aa..fa3d4a7b3a1 100644 --- a/lib/libwrap/rfc1413.3 +++ b/lib/libwrap/rfc1413.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: rfc1413.3,v 1.4 2002/04/30 16:31:42 mpech Exp $ +.\" $OpenBSD: rfc1413.3,v 1.5 2002/05/01 08:03:30 mpech Exp $ .\" .\" Copyright (c) 2001, Bob Beck. All rights reserved. .\" @@ -44,7 +44,8 @@ .Fn rfc1413 retrieves a user name from a remote system using the .Nm ident -protocol described in rfc 1413. It is implenented in the +protocol described in rfc 1413. +It is implenented in the .Nm libwrap.a library. .Pp @@ -69,7 +70,8 @@ strips the trailing CRLF from the returned value and stores up to .Nm "dsize - 1" bytes of the returned username into .Nm dest, -always terminating with a nul byte. In this case 0 is returned. +always terminating with a nul byte. +In this case 0 is returned. .Fn rfc1413 returns -1 if any failure occurs such that it was unable to retrieve the remote username. @@ -79,8 +81,8 @@ retrieve the remote username. The ident protocol only works on TCP sockets. .Pp Ident connections are made unencrypted, and nothing prevents the -remote server from lying about who the user is. Consequently, ident -should never be used to authenticate users. ident is however, quite -useful for logging users of connections from multiuser machines that -can be trusted not to lie about it. +remote server from lying about who the user is. +Consequently, ident should never be used to authenticate users. +ident is however, quite useful for logging users of connections +from multiuser machines that can be trusted not to lie about it. \" @(#) hosts_access.3 1.8 96/02/11 17:01:26 |