From 329223e6f229a55ee8fed800f358f30e994ed749 Mon Sep 17 00:00:00 2001 From: sheldonh Date: Thu, 2 Mar 2000 09:14:21 +0000 Subject: Remove single-space hard sentence breaks. These degrade the quality of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc. --- lib/libpthread/man/pthread_cancel.3 | 15 ++++++++++----- lib/libpthread/man/pthread_cleanup_pop.3 | 3 ++- lib/libpthread/man/pthread_cond_timedwait.3 | 3 ++- lib/libpthread/man/pthread_cond_wait.3 | 3 ++- lib/libpthread/man/pthread_create.3 | 21 +++++++++++++------- lib/libpthread/man/pthread_detach.3 | 18 +++++++++++------ lib/libpthread/man/pthread_exit.3 | 12 ++++++++---- lib/libpthread/man/pthread_join.3 | 9 ++++++--- lib/libpthread/man/pthread_key_create.3 | 21 +++++++++++++------- lib/libpthread/man/pthread_key_delete.3 | 12 ++++++++---- lib/libpthread/man/pthread_once.3 | 12 ++++++++---- lib/libpthread/man/pthread_setspecific.3 | 6 ++++-- lib/libpthread/man/pthread_testcancel.3 | 30 +++++++++++++++++++---------- 13 files changed, 110 insertions(+), 55 deletions(-) (limited to 'lib/libpthread/man') diff --git a/lib/libpthread/man/pthread_cancel.3 b/lib/libpthread/man/pthread_cancel.3 index 5d02554..dd03f61 100644 --- a/lib/libpthread/man/pthread_cancel.3 +++ b/lib/libpthread/man/pthread_cancel.3 @@ -14,11 +14,14 @@ The .Fn pthread_cancel function requests that .Fa thread -be canceled. The target thread's cancelability state and type determines -when the cancellation takes effect. When the cancellation is acted on, +be canceled. +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, @@ -31,7 +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 +is made available to any threads joining with the target. +The symbolic constant .Dv PTHREAD_CANCELED expands to a constant expression of type @@ -41,7 +45,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 +functions will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_cancel diff --git a/lib/libpthread/man/pthread_cleanup_pop.3 b/lib/libpthread/man/pthread_cleanup_pop.3 index faae8ba..009a85e 100644 --- a/lib/libpthread/man/pthread_cleanup_pop.3 +++ b/lib/libpthread/man/pthread_cleanup_pop.3 @@ -43,7 +43,8 @@ The function pops the top cleanup routine off of the current threads cleanup routine stack, and, if .Fa execute -is non-zero, it will execute the function. If there is no cleanup routine +is non-zero, it will execute the function. +If there is no cleanup routine then .Fn pthread_cleanup_pop does nothing. diff --git a/lib/libpthread/man/pthread_cond_timedwait.3 b/lib/libpthread/man/pthread_cond_timedwait.3 index 40cf5ec..15f4bb3 100644 --- a/lib/libpthread/man/pthread_cond_timedwait.3 +++ b/lib/libpthread/man/pthread_cond_timedwait.3 @@ -57,7 +57,8 @@ and the current thread requires 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 +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_cond_timedwait diff --git a/lib/libpthread/man/pthread_cond_wait.3 b/lib/libpthread/man/pthread_cond_wait.3 index 7e6da6c..e93114c 100644 --- a/lib/libpthread/man/pthread_cond_wait.3 +++ b/lib/libpthread/man/pthread_cond_wait.3 @@ -54,7 +54,8 @@ on .Sh RETURN VALUES If successful, the .Fn pthread_cond_wait -function will return zero. Otherwise an error number will be returned to +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_cond_wait diff --git a/lib/libpthread/man/pthread_create.3 b/lib/libpthread/man/pthread_create.3 index cdc28a5..3e1ed04 100644 --- a/lib/libpthread/man/pthread_create.3 +++ b/lib/libpthread/man/pthread_create.3 @@ -45,11 +45,14 @@ 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 +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 +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 @@ -59,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 @@ -85,7 +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 +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_create diff --git a/lib/libpthread/man/pthread_detach.3 b/lib/libpthread/man/pthread_detach.3 index a3fffc6..120248d 100644 --- a/lib/libpthread/man/pthread_detach.3 +++ b/lib/libpthread/man/pthread_detach.3 @@ -46,20 +46,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 -of errno as it did for some drafts of the standard. These early drafts -also passed a pointer to pthread_t as the argument. Beware! +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 errno 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 ff452ca..a5ff1b9 100644 --- a/lib/libpthread/man/pthread_exit.3 +++ b/lib/libpthread/man/pthread_exit.3 @@ -45,12 +45,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 @@ -71,14 +73,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. .Pp diff --git a/lib/libpthread/man/pthread_join.3 b/lib/libpthread/man/pthread_join.3 index e32ad40..2e5ae40 100644 --- a/lib/libpthread/man/pthread_join.3 +++ b/lib/libpthread/man/pthread_join.3 @@ -59,10 +59,12 @@ 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 +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 @@ -72,7 +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 +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_join diff --git a/lib/libpthread/man/pthread_key_create.3 b/lib/libpthread/man/pthread_key_create.3 index 76fc187..376ecf2 100644 --- a/lib/libpthread/man/pthread_key_create.3 +++ b/lib/libpthread/man/pthread_key_create.3 @@ -44,9 +44,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 @@ -54,19 +56,23 @@ 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 +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 +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. @@ -75,7 +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 +and returns zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_key_create diff --git a/lib/libpthread/man/pthread_key_delete.3 b/lib/libpthread/man/pthread_key_delete.3 index 39fb19e..25f110f 100644 --- a/lib/libpthread/man/pthread_key_delete.3 +++ b/lib/libpthread/man/pthread_key_delete.3 @@ -49,12 +49,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 @@ -62,7 +64,8 @@ results in undefined behavior. .Pp The .Fn pthread_key_delete -function is callable from within destructor functions. Destructor functions +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 @@ -71,7 +74,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 +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_key_delete diff --git a/lib/libpthread/man/pthread_once.3 b/lib/libpthread/man/pthread_once.3 index 2dcea49..8cd894a 100644 --- a/lib/libpthread/man/pthread_once.3 +++ b/lib/libpthread/man/pthread_once.3 @@ -51,7 +51,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 @@ -61,14 +62,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 @@ -90,7 +93,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 +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS None. diff --git a/lib/libpthread/man/pthread_setspecific.3 b/lib/libpthread/man/pthread_setspecific.3 index 89a416f..ca141de 100644 --- a/lib/libpthread/man/pthread_setspecific.3 +++ b/lib/libpthread/man/pthread_setspecific.3 @@ -47,7 +47,8 @@ function associates a thread-specific value with a .Fa key obtained via a previous call to .Fn pthread_key_create . -Different threads man bind different values to the same key. These values are +Different threads man bind different values to the same key. +These values are typically pointers to blocks of dynamically allocated memory that have been reserved for use by the calling thread. .Pp @@ -67,7 +68,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 +function will return zero. +Otherwise an error number will be returned to indicate the error. .Sh ERRORS .Fn pthread_setspecific diff --git a/lib/libpthread/man/pthread_testcancel.3 b/lib/libpthread/man/pthread_testcancel.3 index 670c47c..d911d2c 100644 --- a/lib/libpthread/man/pthread_testcancel.3 +++ b/lib/libpthread/man/pthread_testcancel.3 @@ -55,13 +55,15 @@ 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. .Pp .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 +receipt of a cancellation request. +The thread may control cancellation in a number of ways. .Pp Each thread maintains its own @@ -79,7 +81,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. @@ -114,7 +117,8 @@ If successful, the .Fn pthread_setcancelstate and .Fn pthread_setcanceltype -functions will return zero. Otherwise, an error number shall be returned to +functions will return zero. +Otherwise, an error number shall be returned to indicate the error. .Pp The @@ -122,22 +126,27 @@ The and .Fn pthread_setcanceltype functions are used to control the points at which a thread may be -asynchronously canceled. For cancellation control to be usable in modular +asynchronously canceled. +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 +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. .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 canceled while executing some sequence of actions. If an object +thread is canceled 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 canceled, contrary to the wish of the client that disabled. @@ -146,7 +155,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 -- cgit v1.1