summaryrefslogtreecommitdiffstats
path: root/lib/libpthread/man
diff options
context:
space:
mode:
authorsheldonh <sheldonh@FreeBSD.org>2000-03-02 09:14:21 +0000
committersheldonh <sheldonh@FreeBSD.org>2000-03-02 09:14:21 +0000
commit329223e6f229a55ee8fed800f358f30e994ed749 (patch)
tree5d5e6c715ccfb778a29f10e1ea16f06731edbda8 /lib/libpthread/man
parent05f0a865546b5e0b902987be72a75a7b0ef85d09 (diff)
downloadFreeBSD-src-329223e6f229a55ee8fed800f358f30e994ed749.zip
FreeBSD-src-329223e6f229a55ee8fed800f358f30e994ed749.tar.gz
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.
Diffstat (limited to 'lib/libpthread/man')
-rw-r--r--lib/libpthread/man/pthread_cancel.315
-rw-r--r--lib/libpthread/man/pthread_cleanup_pop.33
-rw-r--r--lib/libpthread/man/pthread_cond_timedwait.33
-rw-r--r--lib/libpthread/man/pthread_cond_wait.33
-rw-r--r--lib/libpthread/man/pthread_create.321
-rw-r--r--lib/libpthread/man/pthread_detach.318
-rw-r--r--lib/libpthread/man/pthread_exit.312
-rw-r--r--lib/libpthread/man/pthread_join.39
-rw-r--r--lib/libpthread/man/pthread_key_create.321
-rw-r--r--lib/libpthread/man/pthread_key_delete.312
-rw-r--r--lib/libpthread/man/pthread_once.312
-rw-r--r--lib/libpthread/man/pthread_setspecific.36
-rw-r--r--lib/libpthread/man/pthread_testcancel.330
13 files changed, 110 insertions, 55 deletions
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
OpenPOWER on IntegriCloud