--- linuxthreads/man/pthread_atfork.man | 36 ++--- linuxthreads/man/pthread_attr_init.man | 132 ++++++++++----------- linuxthreads/man/pthread_cancel.man | 98 +++++++-------- linuxthreads/man/pthread_cleanup_push.man | 66 +++++----- linuxthreads/man/pthread_cond_init.man | 114 +++++++++--------- linuxthreads/man/pthread_condattr_init.man | 14 +- linuxthreads/man/pthread_create.man | 36 ++--- linuxthreads/man/pthread_detach.man | 31 ++-- linuxthreads/man/pthread_equal.man | 6 linuxthreads/man/pthread_exit.man | 18 +- linuxthreads/man/pthread_join.man | 64 +++++----- linuxthreads/man/pthread_key_create.man | 62 ++++----- linuxthreads/man/pthread_kill_other_threads_np.man | 22 +-- linuxthreads/man/pthread_mutex_init.man | 92 +++++++------- linuxthreads/man/pthread_mutexattr_init.man | 62 ++++----- linuxthreads/man/pthread_mutexattr_setkind_np.man | 20 +-- linuxthreads/man/pthread_once.man | 18 +- linuxthreads/man/pthread_self.man | 12 - linuxthreads/man/pthread_setschedparam.man | 62 ++++----- linuxthreads/man/pthread_sigmask.man | 86 ++++++------- linuxthreads/man/sem_init.man | 88 +++++++------- 21 files changed, 568 insertions(+), 571 deletions(-) --- a/linuxthreads/man/pthread_atfork.man +++ b/linuxthreads/man/pthread_atfork.man @@ -10,44 +10,44 @@ .SH DESCRIPTION -!pthread_atfork! registers handler functions to be called just before -and just after a new process is created with !fork!(2). The |prepare| +\fBpthread_atfork\fP registers handler functions to be called just before +and just after a new process is created with \fBfork\fP(2). The \fIprepare\fP handler will be called from the parent process, just before the new -process is created. The |parent| handler will be called from the parent -process, just before !fork!(2) returns. The |child| handler will be -called from the child process, just before !fork!(2) returns. +process is created. The \fIparent\fP handler will be called from the parent +process, just before \fBfork\fP(2) returns. The \fIchild\fP handler will be +called from the child process, just before \fBfork\fP(2) returns. -One or several of the three handlers |prepare|, |parent| and |child| -can be given as !NULL!, meaning that no handler needs to be called at +One or several of the three handlers \fIprepare\fP, \fIparent\fP and \fIchild\fP +can be given as \fBNULL\fP, meaning that no handler needs to be called at the corresponding point. -!pthread_atfork! can be called several times to install several sets -of handlers. At !fork!(2) time, the |prepare| handlers are called in -LIFO order (last added with !pthread_atfork!, first called before !fork!), -while the |parent| and |child| handlers are called in FIFO order +\fBpthread_atfork\fP can be called several times to install several sets +of handlers. At \fBfork\fP(2) time, the \fIprepare\fP handlers are called in +LIFO order (last added with \fBpthread_atfork\fP, first called before \fBfork\fP), +while the \fIparent\fP and \fIchild\fP handlers are called in FIFO order (first added, first called). -To understand the purpose of !pthread_atfork!, recall that !fork!(2) +To understand the purpose of \fBpthread_atfork\fP, recall that \fBfork\fP(2) duplicates the whole memory space, including mutexes in their current locking state, but only the calling thread: other threads are not running in the child process. The mutexes are not usable after the -!fork! and must be initialized with |pthread_mutex_init| in the child +\fBfork\fP and must be initialized with \fIpthread_mutex_init\fP in the child process. This is a limitation of the current implementation and might or might not be present in future versions. .SH "RETURN VALUE" -!pthread_atfork! returns 0 on success and a non-zero error code on error. +\fBpthread_atfork\fP returns 0 on success and a non-zero error code on error. .SH ERRORS .TP -!ENOMEM! +\fBENOMEM\fP insufficient memory available to register the handlers. .SH AUTHOR Xavier Leroy .SH "SEE ALSO" -!fork!(2), -!pthread_mutex_lock!(3), -!pthread_mutex_unlock!(3). +\fBfork\fP(2), +\fBpthread_mutex_lock\fP(3), +\fBpthread_mutex_unlock\fP(3). --- a/linuxthreads/man/pthread_attr_init.man +++ b/linuxthreads/man/pthread_attr_init.man @@ -45,27 +45,27 @@ .SH DESCRIPTION Setting attributes for threads is achieved by filling a -thread attribute object |attr| of type !pthread_attr_t!, then passing it as -second argument to !pthread_create!(3). Passing !NULL! is equivalent to +thread attribute object \fIattr\fP of type \fBpthread_attr_t\fP, then passing it as +second argument to \fBpthread_create\fP(3). Passing \fBNULL\fP is equivalent to passing a thread attribute object with all attributes set to their default values. -!pthread_attr_init! initializes the thread attribute object |attr| and +\fBpthread_attr_init\fP initializes the thread attribute object \fIattr\fP and fills it with default values for the attributes. (The default values are listed below for each attribute.) -Each attribute |attrname| (see below for a list of all attributes) can -be individually set using the function !pthread_attr_set!|attrname| -and retrieved using the function !pthread_attr_get!|attrname|. +Each attribute \fIattrname\fP (see below for a list of all attributes) can +be individually set using the function \fBpthread_attr_set\fP\fIattrname\fP +and retrieved using the function \fBpthread_attr_get\fP\fIattrname\fP. -!pthread_attr_destroy! destroys a thread attribute object, which -must not be reused until it is reinitialized. !pthread_attr_destroy! +\fBpthread_attr_destroy\fP destroys a thread attribute object, which +must not be reused until it is reinitialized. \fBpthread_attr_destroy\fP does nothing in the LinuxThreads implementation. Attribute objects are consulted only when creating a new thread. The same attribute object can be used for creating several threads. Modifying an attribute object after a call to -!pthread_create! does not change the attributes of the thread +\fBpthread_create\fP does not change the attributes of the thread previously created. The following thread attributes are supported: @@ -73,149 +73,149 @@ .SS detachstate Control whether the thread is created in the joinable state (value -!PTHREAD_CREATE_JOINABLE!) or in the detached state -(!PTHREAD_CREATE_DETACHED!). +\fBPTHREAD_CREATE_JOINABLE\fP) or in the detached state +(\fBPTHREAD_CREATE_DETACHED\fP). -Default value: !PTHREAD_CREATE_JOINABLE!. +Default value: \fBPTHREAD_CREATE_JOINABLE\fP. In the joinable state, another thread can synchronize on the thread -termination and recover its termination code using !pthread_join!(3), +termination and recover its termination code using \fBpthread_join\fP(3), but some of the thread resources are kept allocated after the thread terminates, and reclaimed only when another thread performs -!pthread_join!(3) on that thread. +\fBpthread_join\fP(3) on that thread. In the detached state, the thread resources are immediately freed when -it terminates, but !pthread_join!(3) cannot be used to synchronize on +it terminates, but \fBpthread_join\fP(3) cannot be used to synchronize on the thread termination. A thread created in the joinable state can later be put in the -detached thread using !pthread_detach!(3). +detached state using \fBpthread_detach\fP(3). .SS schedpolicy Select the scheduling policy for the thread: one of -!SCHED_OTHER! (regular, non-realtime scheduling), -!SCHED_RR! (realtime, round-robin) or -!SCHED_FIFO! (realtime, first-in first-out). See -!sched_setpolicy!(2) for more information on scheduling policies. +\fBSCHED_OTHER\fP (regular, non-realtime scheduling), +\fBSCHED_RR\fP (realtime, round-robin) or +\fBSCHED_FIFO\fP (realtime, first-in first-out). See +\fBsched_setpolicy\fP(2) for more information on scheduling policies. -Default value: !SCHED_OTHER!. +Default value: \fBSCHED_OTHER\fP. -The realtime scheduling policies !SCHED_RR! and !SCHED_FIFO! are +The realtime scheduling policies \fBSCHED_RR\fP and \fBSCHED_FIFO\fP are available only to processes with superuser privileges. The scheduling policy of a thread can be changed after creation with -!pthread_setschedparam!(3). +\fBpthread_setschedparam\fP(3). .SS schedparam Contain the scheduling parameters (essentially, the scheduling -priority) for the thread. See !sched_setparam!(2) for more information +priority) for the thread. See \fBsched_setparam\fP(2) for more information on scheduling parameters. Default value: priority is 0. -This attribute is not significant if the scheduling policy is !SCHED_OTHER!; -it only matters for the realtime policies !SCHED_RR! and !SCHED_FIFO!. +This attribute is not significant if the scheduling policy is \fBSCHED_OTHER\fP; +it only matters for the realtime policies \fBSCHED_RR\fP and \fBSCHED_FIFO\fP. The scheduling priority of a thread can be changed after creation with -!pthread_setschedparam!(3). +\fBpthread_setschedparam\fP(3). .SS inheritsched Indicate whether the scheduling policy and scheduling parameters for the newly created thread are determined by the values of the -|schedpolicy| and |schedparam| attributes (value -!PTHREAD_EXPLICIT_SCHED!) or are inherited from the parent thread -(value !PTHREAD_INHERIT_SCHED!). +\fIschedpolicy\fP and \fIschedparam\fP attributes (value +\fBPTHREAD_EXPLICIT_SCHED\fP) or are inherited from the parent thread +(value \fBPTHREAD_INHERIT_SCHED\fP). -Default value: !PTHREAD_EXPLICIT_SCHED!. +Default value: \fBPTHREAD_EXPLICIT_SCHED\fP. .SS scope Define the scheduling contention scope for the created thread. The only value supported in the LinuxThreads implementation is -!PTHREAD_SCOPE_SYSTEM!, meaning that the threads contend for CPU time +\fBPTHREAD_SCOPE_SYSTEM\fP, meaning that the threads contend for CPU time with all processes running on the machine. In particular, thread priorities are interpreted relative to the priorities of all other processes on the machine. The other value specified by the standard, -!PTHREAD_SCOPE_PROCESS!, means that scheduling contention occurs only +\fBPTHREAD_SCOPE_PROCESS\fP, means that scheduling contention occurs only between the threads of the running process: thread priorities are interpreted relative to the priorities of the other threads of the process, regardless of the priorities of other processes. -!PTHREAD_SCOPE_PROCESS! is not supported in LinuxThreads. +\fBPTHREAD_SCOPE_PROCESS\fP is not supported in LinuxThreads. -Default value: !PTHREAD_SCOPE_SYSTEM!. +Default value: \fBPTHREAD_SCOPE_SYSTEM\fP. .SH "RETURN VALUE" All functions return 0 on success and a non-zero error code on error. -On success, the !pthread_attr_get!|attrname| functions also store the -current value of the attribute |attrname| in the location pointed to +On success, the \fBpthread_attr_get\fP\fIattrname\fP functions also store the +current value of the attribute \fIattrname\fP in the location pointed to by their second argument. .SH ERRORS -The !pthread_attr_setdetachstate! function returns the following error +The \fBpthread_attr_setdetachstate\fP function returns the following error codes on error: .RS .TP -!EINVAL! -the specified |detachstate| is not one of !PTHREAD_CREATE_JOINABLE! or -!PTHREAD_CREATE_DETACHED!. +\fBEINVAL\fP +the specified \fIdetachstate\fP is not one of \fBPTHREAD_CREATE_JOINABLE\fP or +\fBPTHREAD_CREATE_DETACHED\fP. .RE -The !pthread_attr_setschedparam! function returns the following error +The \fBpthread_attr_setschedparam\fP function returns the following error codes on error: .RS .TP -!EINVAL! -the priority specified in |param| is outside the range of allowed -priorities for the scheduling policy currently in |attr| -(1 to 99 for !SCHED_FIFO! and !SCHED_RR!; 0 for !SCHED_OTHER!). +\fBEINVAL\fP +the priority specified in \fIparam\fP is outside the range of allowed +priorities for the scheduling policy currently in \fIattr\fP +(1 to 99 for \fBSCHED_FIFO\fP and \fBSCHED_RR\fP; 0 for \fBSCHED_OTHER\fP). .RE -The !pthread_attr_setschedpolicy! function returns the following error +The \fBpthread_attr_setschedpolicy\fP function returns the following error codes on error: .RS .TP -!EINVAL! -the specified |policy| is not one of !SCHED_OTHER!, !SCHED_FIFO!, or -!SCHED_RR!. +\fBEINVAL\fP +the specified \fIpolicy\fP is not one of \fBSCHED_OTHER\fP, \fBSCHED_FIFO\fP, or +\fBSCHED_RR\fP. .TP -!ENOTSUP! -|policy| is !SCHED_FIFO! or !SCHED_RR!, and the effective user of the +\fBENOTSUP\fP +\fIpolicy\fP is \fBSCHED_FIFO\fP or \fBSCHED_RR\fP, and the effective user of the calling process is not super-user. .RE -The !pthread_attr_setinheritsched! function returns the following error +The \fBpthread_attr_setinheritsched\fP function returns the following error codes on error: .RS .TP -!EINVAL! -the specified |inherit| is not one of !PTHREAD_INHERIT_SCHED! or -!PTHREAD_EXPLICIT_SCHED!. +\fBEINVAL\fP +the specified \fIinherit\fP is not one of \fBPTHREAD_INHERIT_SCHED\fP or +\fBPTHREAD_EXPLICIT_SCHED\fP. .RE -The !pthread_attr_setscope! function returns the following error +The \fBpthread_attr_setscope\fP function returns the following error codes on error: .RS .TP -!EINVAL! -the specified |scope| is not one of !PTHREAD_SCOPE_SYSTEM! or -!PTHREAD_SCOPE_PROCESS!. +\fBEINVAL\fP +the specified \fIscope\fP is not one of \fBPTHREAD_SCOPE_SYSTEM\fP or +\fBPTHREAD_SCOPE_PROCESS\fP. .TP -!ENOTSUP! -the specified |scope| is !PTHREAD_SCOPE_PROCESS! (not supported). +\fBENOTSUP\fP +the specified \fIscope\fP is \fBPTHREAD_SCOPE_PROCESS\fP (not supported). .RE .SH AUTHOR Xavier Leroy .SH "SEE ALSO" -!pthread_create!(3), -!pthread_join!(3), -!pthread_detach!(3), -!pthread_setschedparam!(3). +\fBpthread_create\fP(3), +\fBpthread_join\fP(3), +\fBpthread_detach\fP(3), +\fBpthread_setschedparam\fP(3). --- a/linuxthreads/man/pthread_cancel.man +++ b/linuxthreads/man/pthread_cancel.man @@ -27,119 +27,119 @@ immediately, or defer it till it reaches a cancellation point. When a thread eventually honors a cancellation request, it performs as -if !pthread_exit(PTHREAD_CANCELED)! has been called at that point: +if \fBpthread_exit(PTHREAD_CANCELED)\fP has been called at that point: all cleanup handlers are executed in reverse order, finalization functions for thread-specific data are called, and finally the thread -stops executing with the return value !PTHREAD_CANCELED!. See -!pthread_exit!(3) for more information. +stops executing with the return value \fBPTHREAD_CANCELED\fP. See +\fBpthread_exit\fP(3) for more information. -!pthread_cancel! sends a cancellation request to the thread denoted -by the |thread| argument. +\fBpthread_cancel\fP sends a cancellation request to the thread denoted +by the \fIthread\fP argument. -!pthread_setcancelstate! changes the cancellation state for the +\fBpthread_setcancelstate\fP changes the cancellation state for the calling thread -- that is, whether cancellation requests are ignored -or not. The |state| argument is the new cancellation state: either -!PTHREAD_CANCEL_ENABLE! to enable cancellation, or -!PTHREAD_CANCEL_DISABLE! to disable cancellation (cancellation -requests are ignored). If |oldstate| is not !NULL!, the previous -cancellation state is stored in the location pointed to by |oldstate|, +or not. The \fIstate\fP argument is the new cancellation state: either +\fBPTHREAD_CANCEL_ENABLE\fP to enable cancellation, or +\fBPTHREAD_CANCEL_DISABLE\fP to disable cancellation (cancellation +requests are ignored). If \fIoldstate\fP is not \fBNULL\fP, the previous +cancellation state is stored in the location pointed to by \fIoldstate\fP, and can thus be restored later by another call to -!pthread_setcancelstate!. +\fBpthread_setcancelstate\fP. -!pthread_setcanceltype! changes the type of responses to cancellation +\fBpthread_setcanceltype\fP changes the type of responses to cancellation requests for the calling thread: asynchronous (immediate) or deferred. -The |type| argument is the new cancellation type: either -!PTHREAD_CANCEL_ASYNCHRONOUS! to cancel the calling thread as soon as -the cancellation request is received, or !PTHREAD_CANCEL_DEFERRED! to +The \fItype\fP argument is the new cancellation type: either +\fBPTHREAD_CANCEL_ASYNCHRONOUS\fP to cancel the calling thread as soon as +the cancellation request is received, or \fBPTHREAD_CANCEL_DEFERRED\fP to keep the cancellation request pending until the next cancellation -point. If |oldtype| is not !NULL!, the previous -cancellation state is stored in the location pointed to by |oldtype|, +point. If \fIoldtype\fP is not \fBNULL\fP, the previous +cancellation state is stored in the location pointed to by \fIoldtype\fP, and can thus be restored later by another call to -!pthread_setcanceltype!. +\fBpthread_setcanceltype\fP. -Threads are always created by !pthread_create!(3) with cancellation +Threads are always created by \fBpthread_create\fP(3) with cancellation enabled and deferred. That is, the initial cancellation state is -!PTHREAD_CANCEL_ENABLE! and the initial type is -!PTHREAD_CANCEL_DEFERRED!. +\fBPTHREAD_CANCEL_ENABLE\fP and the initial type is +\fBPTHREAD_CANCEL_DEFERRED\fP. Cancellation points are those points in the program execution where a test for pending cancellation requests is performed and cancellation is executed if positive. The following POSIX threads functions are cancellation points: -!pthread_join!(3) +\fBpthread_join\fP(3) .br -!pthread_cond_wait!(3) +\fBpthread_cond_wait\fP(3) .br -!pthread_cond_timedwait!(3) +\fBpthread_cond_timedwait\fP(3) .br -!pthread_testcancel!(3) +\fBpthread_testcancel\fP(3) .br -!sem_wait!(3) +\fBsem_wait\fP(3) .br -!sigwait!(3) +\fBsigwait\fP(3) All other POSIX threads functions are guaranteed not to be cancellation points. That is, they never perform cancellation in deferred cancellation mode. -!pthread_testcancel! does nothing except testing for pending +\fBpthread_testcancel\fP does nothing except testing for pending cancellation and executing it. Its purpose is to introduce explicit checks for cancellation in long sequences of code that do not call cancellation point functions otherwise. .SH "RETURN VALUE" -!pthread_cancel!, !pthread_setcancelstate! and -!pthread_setcanceltype! return 0 on success and a non-zero error code +\fBpthread_cancel\fP, \fBpthread_setcancelstate\fP and +\fBpthread_setcanceltype\fP return 0 on success and a non-zero error code on error. .SH ERRORS -!pthread_cancel! returns the following error code on error: +\fBpthread_cancel\fP returns the following error code on error: .RS .TP -!ESRCH! -no thread could be found corresponding to that specified by the |thread| ID. +\fBESRCH\fP +no thread could be found corresponding to that specified by the \fIthread\fP ID. .RE -!pthread_setcancelstate! returns the following error code on error: +\fBpthread_setcancelstate\fP returns the following error code on error: .RS .TP -!EINVAL! -the |state| argument is not !PTHREAD_CANCEL_ENABLE! nor -!PTHREAD_CANCEL_DISABLE! +\fBEINVAL\fP +the \fIstate\fP argument is not \fBPTHREAD_CANCEL_ENABLE\fP nor +\fBPTHREAD_CANCEL_DISABLE\fP .RE -!pthread_setcanceltype! returns the following error code on error: +\fBpthread_setcanceltype\fP returns the following error code on error: .RS .TP -!EINVAL! -the |type| argument is not !PTHREAD_CANCEL_DEFERRED! nor -!PTHREAD_CANCEL_ASYNCHRONOUS! +\fBEINVAL\fP +the \fItype\fP argument is not \fBPTHREAD_CANCEL_DEFERRED\fP nor +\fBPTHREAD_CANCEL_ASYNCHRONOUS\fP .RE .SH AUTHOR Xavier Leroy .SH "SEE ALSO" -!pthread_exit!(3), -!pthread_cleanup_push!(3), -!pthread_cleanup_pop!(3). +\fBpthread_exit\fP(3), +\fBpthread_cleanup_push\fP(3), +\fBpthread_cleanup_pop\fP(3). .SH BUGS POSIX specifies that a number of system calls (basically, all -system calls that may block, such as !read!(2), !write!(2), !wait!(2), +system calls that may block, such as \fBread\fP(2), \fBwrite\fP(2), \fBwait\fP(2), etc.) and library functions that may call these system calls (e.g. -!fprintf!(3)) are cancellation points. LinuxThreads is not yet +\fBfprintf\fP(3)) are cancellation points. LinuxThreads is not yet integrated enough with the C library to implement this, and thus none of the C library functions is a cancellation point. For system calls at least, there is a workaround. Cancellation requests are transmitted to the target thread by sending it a signal. That signal will interrupt all blocking system calls, causing -them to return immediately with the !EINTR! error. So, checking for -cancellation during a !read! system call, for instance, can be +them to return immediately with the \fBEINTR\fP error. So, checking for +cancellation during a \fBread\fP system call, for instance, can be achieved as follows: .RS --- a/linuxthreads/man/pthread_cleanup_push.man +++ b/linuxthreads/man/pthread_cleanup_push.man @@ -21,7 +21,7 @@ .SH DESCRIPTION Cleanup handlers are functions that get called when a thread -terminates, either by calling !pthread_exit!(3) or because of +terminates, either by calling \fBpthread_exit\fP(3) or because of cancellation. Cleanup handlers are installed and removed following a stack-like discipline. @@ -32,41 +32,41 @@ normally. The best way to avoid this is, just before locking the mutex, to install a cleanup handler whose effect is to unlock the mutex. Cleanup handlers can be used similarly to free blocks allocated -with !malloc!(3) or close file descriptors on thread termination. +with \fBmalloc\fP(3) or close file descriptors on thread termination. -!pthread_cleanup_push! installs the |routine| function with argument -|arg| as a cleanup handler. From this point on to the matching -!pthread_cleanup_pop!, the function |routine| will be called with -arguments |arg| when the thread terminates, either through !pthread_exit!(3) +\fBpthread_cleanup_push\fP installs the \fIroutine\fP function with argument +\fIarg\fP as a cleanup handler. From this point on to the matching +\fBpthread_cleanup_pop\fP, the function \fIroutine\fP will be called with +arguments \fIarg\fP when the thread terminates, either through \fBpthread_exit\fP(3) or by cancellation. If several cleanup handlers are active at that point, they are called in LIFO order: the most recently installed handler is called first. -!pthread_cleanup_pop! removes the most recently installed cleanup -handler. If the |execute| argument is not 0, it also executes the -handler, by calling the |routine| function with arguments |arg|. If -the |execute| argument is 0, the handler is only removed but not +\fBpthread_cleanup_pop\fP removes the most recently installed cleanup +handler. If the \fIexecute\fP argument is not 0, it also executes the +handler, by calling the \fIroutine\fP function with arguments \fIarg\fP. If +the \fIexecute\fP argument is 0, the handler is only removed but not executed. -Matching pairs of !pthread_cleanup_push! and !pthread_cleanup_pop! +Matching pairs of \fBpthread_cleanup_push\fP and \fBpthread_cleanup_pop\fP must occur in the same function, at the same level of block nesting. -Actually, !pthread_cleanup_push! and !pthread_cleanup_pop! are macros, -and the expansion of !pthread_cleanup_push! introduces an open brace !{! -with the matching closing brace !}! being introduced by the expansion -of the matching !pthread_cleanup_pop!. - -!pthread_cleanup_push_defer_np! is a non-portable extension that -combines !pthread_cleanup_push! and !pthread_setcanceltype!(3). -It pushes a cleanup handler just as !pthread_cleanup_push! does, but +Actually, \fBpthread_cleanup_push\fP and \fBpthread_cleanup_pop\fP are macros, +and the expansion of \fBpthread_cleanup_push\fP introduces an open brace \fB{\fP +with the matching closing brace \fB}\fP being introduced by the expansion +of the matching \fBpthread_cleanup_pop\fP. + +\fBpthread_cleanup_push_defer_np\fP is a non-portable extension that +combines \fBpthread_cleanup_push\fP and \fBpthread_setcanceltype\fP(3). +It pushes a cleanup handler just as \fBpthread_cleanup_push\fP does, but also saves the current cancellation type and sets it to deferred cancellation. This ensures that the cleanup mechanism is effective even if the thread was initially in asynchronous cancellation mode. -!pthread_cleanup_pop_restore_np! pops a cleanup handler introduced by -!pthread_cleanup_push_defer_np!, and restores the cancellation type to -its value at the time !pthread_cleanup_push_defer_np! was called. +\fBpthread_cleanup_pop_restore_np\fP pops a cleanup handler introduced by +\fBpthread_cleanup_push_defer_np\fP, and restores the cancellation type to +its value at the time \fBpthread_cleanup_push_defer_np\fP was called. -!pthread_cleanup_push_defer_np! and !pthread_cleanup_pop_restore_np! +\fBpthread_cleanup_push_defer_np\fP and \fBpthread_cleanup_pop_restore_np\fP must occur in matching pairs, at the same level of block nesting. The following sequence @@ -113,14 +113,14 @@ Xavier Leroy .SH "SEE ALSO" -!pthread_exit!(3), -!pthread_cancel!(3), -!pthread_setcanceltype!(3). +\fBpthread_exit\fP(3), +\fBpthread_cancel\fP(3), +\fBpthread_setcanceltype\fP(3). .SH EXAMPLE -Here is how to lock a mutex |mut| in such a way that it will be -unlocked if the thread is canceled while |mut| is locked: +Here is how to lock a mutex \fImut\fP in such a way that it will be +unlocked if the thread is canceled while \fImut\fP is locked: .RS .ft 3 @@ -149,10 +149,10 @@ .fi Notice that the code above is safe only in deferred cancellation mode -(see !pthread_setcanceltype!(3)). In asynchronous cancellation mode, -a cancellation can occur between !pthread_cleanup_push! and -!pthread_mutex_lock!, or between !pthread_mutex_unlock! and -!pthread_cleanup_pop!, resulting in both cases in the thread trying to +(see \fBpthread_setcanceltype\fP(3)). In asynchronous cancellation mode, +a cancellation can occur between \fBpthread_cleanup_push\fP and +\fBpthread_mutex_lock\fP, or between \fBpthread_mutex_unlock\fP and +\fBpthread_cleanup_pop\fP, resulting in both cases in the thread trying to unlock a mutex not locked by the current thread. This is the main reason why asynchronous cancellation is difficult to use. @@ -177,7 +177,7 @@ The code above can be rewritten in a more compact and more efficient way, using the non-portable functions -!pthread_cleanup_push_defer_np! and !pthread_cleanup_pop_restore_np!: +\fBpthread_cleanup_push_defer_np\fP and \fBpthread_cleanup_pop_restore_np\fP: .RS .ft 3 --- a/linuxthreads/man/pthread_condattr_init.man +++ b/linuxthreads/man/pthread_condattr_init.man @@ -15,25 +15,25 @@ .SH DESCRIPTION Condition attributes can be specified at condition creation time, by passing a -condition attribute object as second argument to !pthread_cond_init!(3). -Passing !NULL! is equivalent to passing a condition attribute object with +condition attribute object as second argument to \fBpthread_cond_init\fP(3). +Passing \fBNULL\fP is equivalent to passing a condition attribute object with all attributes set to their default values. The LinuxThreads implementation supports no attributes for conditions. The functions on condition attributes are included only for compliance with the POSIX standard. -!pthread_condattr_init! initializes the condition attribute object -|attr| and fills it with default values for the attributes. -!pthread_condattr_destroy! destroys a condition attribute object, +\fBpthread_condattr_init\fP initializes the condition attribute object +\fIattr\fP and fills it with default values for the attributes. +\fBpthread_condattr_destroy\fP destroys a condition attribute object, which must not be reused until it is reinitialized. Both functions do nothing in the LinuxThreads implementation. .SH "RETURN VALUE" -!pthread_condattr_init! and !pthread_condattr_destroy! always return 0. +\fBpthread_condattr_init\fP and \fBpthread_condattr_destroy\fP always return 0. .SH AUTHOR Xavier Leroy .SH "SEE ALSO" -!pthread_cond_init!(3). +\fBpthread_cond_init\fP(3). --- a/linuxthreads/man/pthread_cond_init.man +++ b/linuxthreads/man/pthread_cond_init.man @@ -40,31 +40,31 @@ variable and another thread signals the condition just before the first thread actually waits on it. -!pthread_cond_init! initializes the condition variable |cond|, using the -condition attributes specified in |cond_attr|, or default attributes -if |cond_attr| is !NULL!. The LinuxThreads implementation supports no -attributes for conditions, hence the |cond_attr| parameter is actually +\fBpthread_cond_init\fP initializes the condition variable \fIcond\fP, using the +condition attributes specified in \fIcond_attr\fP, or default attributes +if \fIcond_attr\fP is \fBNULL\fP. The LinuxThreads implementation supports no +attributes for conditions, hence the \fIcond_attr\fP parameter is actually ignored. -Variables of type !pthread_cond_t! can also be initialized -statically, using the constant !PTHREAD_COND_INITIALIZER!. +Variables of type \fBpthread_cond_t\fP can also be initialized +statically, using the constant \fBPTHREAD_COND_INITIALIZER\fP. -!pthread_cond_signal! restarts one of the threads that are waiting on -the condition variable |cond|. If no threads are waiting on |cond|, -nothing happens. If several threads are waiting on |cond|, exactly one +\fBpthread_cond_signal\fP restarts one of the threads that are waiting on +the condition variable \fIcond\fP. If no threads are waiting on \fIcond\fP, +nothing happens. If several threads are waiting on \fIcond\fP, exactly one is restarted, but it is not specified which. -!pthread_cond_broadcast! restarts all the threads that are waiting on -the condition variable |cond|. Nothing happens if no threads are -waiting on |cond|. +\fBpthread_cond_broadcast\fP restarts all the threads that are waiting on +the condition variable \fIcond\fP. Nothing happens if no threads are +waiting on \fIcond\fP. -!pthread_cond_wait! atomically unlocks the |mutex| (as per -!pthread_unlock_mutex!) and waits for the condition variable |cond| to +\fBpthread_cond_wait\fP atomically unlocks the \fImutex\fP (as per +\fBpthread_unlock_mutex\fP) and waits for the condition variable \fIcond\fP to be signaled. The thread execution is suspended and does not consume -any CPU time until the condition variable is signaled. The |mutex| +any CPU time until the condition variable is signaled. The \fImutex\fP must be locked by the calling thread on entrance to -!pthread_cond_wait!. Before returning to the calling thread, -!pthread_cond_wait! re-acquires |mutex| (as per !pthread_lock_mutex!). +\fBpthread_cond_wait\fP. Before returning to the calling thread, +\fBpthread_cond_wait\fP re-acquires \fImutex\fP (as per \fBpthread_lock_mutex\fP). Unlocking the mutex and suspending on the condition variable is done atomically. Thus, if all threads always acquire the mutex before @@ -72,37 +72,37 @@ signaled (and thus ignored) between the time a thread locks the mutex and the time it waits on the condition variable. -!pthread_cond_timedwait! atomically unlocks |mutex| and waits on -|cond|, as !pthread_cond_wait! does, but it also bounds the duration -of the wait. If |cond| has not been signaled within the amount of time -specified by |abstime|, the mutex |mutex| is re-acquired and -!pthread_cond_timedwait! returns the error !ETIMEDOUT!. -The |abstime| parameter specifies an absolute time, with the same -origin as !time!(2) and !gettimeofday!(2): an |abstime| of 0 +\fBpthread_cond_timedwait\fP atomically unlocks \fImutex\fP and waits on +\fIcond\fP, as \fBpthread_cond_wait\fP does, but it also bounds the duration +of the wait. If \fIcond\fP has not been signaled within the amount of time +specified by \fIabstime\fP, the mutex \fImutex\fP is re-acquired and +\fBpthread_cond_timedwait\fP returns the error \fBETIMEDOUT\fP. +The \fIabstime\fP parameter specifies an absolute time, with the same +origin as \fBtime\fP(2) and \fBgettimeofday\fP(2): an \fIabstime\fP of 0 corresponds to 00:00:00 GMT, January 1, 1970. -!pthread_cond_destroy! destroys a condition variable, freeing the +\fBpthread_cond_destroy\fP destroys a condition variable, freeing the resources it might hold. No threads must be waiting on the condition -variable on entrance to !pthread_cond_destroy!. In the LinuxThreads +variable on entrance to \fBpthread_cond_destroy\fP. In the LinuxThreads implementation, no resources are associated with condition variables, -thus !pthread_cond_destroy! actually does nothing except checking that +thus \fBpthread_cond_destroy\fP actually does nothing except checking that the condition has no waiting threads. .SH CANCELLATION -!pthread_cond_wait! and !pthread_cond_timedwait! are cancellation +\fBpthread_cond_wait\fP and \fBpthread_cond_timedwait\fP are cancellation points. If a thread is cancelled while suspended in one of these functions, the thread immediately resumes execution, then locks again -the |mutex| argument to !pthread_cond_wait! and -!pthread_cond_timedwait!, and finally executes the cancellation. -Consequently, cleanup handlers are assured that |mutex| is locked when +the \fImutex\fP argument to \fBpthread_cond_wait\fP and +\fBpthread_cond_timedwait\fP, and finally executes the cancellation. +Consequently, cleanup handlers are assured that \fImutex\fP is locked when they are called. .SH "ASYNC-SIGNAL SAFETY" The condition functions are not async-signal safe, and should not be called from a signal handler. In particular, calling -!pthread_cond_signal! or !pthread_cond_broadcast! from a signal +\fBpthread_cond_signal\fP or \fBpthread_cond_broadcast\fP from a signal handler may deadlock the calling thread. .SH "RETURN VALUE" @@ -112,45 +112,45 @@ .SH ERRORS -!pthread_cond_init!, !pthread_cond_signal!, !pthread_cond_broadcast!, -and !pthread_cond_wait! never return an error code. +\fBpthread_cond_init\fP, \fBpthread_cond_signal\fP, \fBpthread_cond_broadcast\fP, +and \fBpthread_cond_wait\fP never return an error code. -The !pthread_cond_timedwait! function returns the following error codes +The \fBpthread_cond_timedwait\fP function returns the following error codes on error: .RS .TP -!ETIMEDOUT! +\fBETIMEDOUT\fP the condition variable was not signaled until the timeout specified by -|abstime| +\fIabstime\fP .TP -!EINTR! -!pthread_cond_timedwait! was interrupted by a signal +\fBEINTR\fP +\fBpthread_cond_timedwait\fP was interrupted by a signal .RE -The !pthread_cond_destroy! function returns the following error code +The \fBpthread_cond_destroy\fP function returns the following error code on error: .RS .TP -!EBUSY! -some threads are currently waiting on |cond|. +\fBEBUSY\fP +some threads are currently waiting on \fIcond\fP. .RE .SH AUTHOR Xavier Leroy .SH "SEE ALSO" -!pthread_condattr_init!(3), -!pthread_mutex_lock!(3), -!pthread_mutex_unlock!(3), -!gettimeofday!(2), -!nanosleep!(2). +\fBpthread_condattr_init\fP(3), +\fBpthread_mutex_lock\fP(3), +\fBpthread_mutex_unlock\fP(3), +\fBgettimeofday\fP(2), +\fBnanosleep\fP(2). .SH EXAMPLE -Consider two shared variables |x| and |y|, protected by the mutex |mut|, -and a condition variable |cond| that is to be signaled whenever |x| -becomes greater than |y|. +Consider two shared variables \fIx\fP and \fIy\fP, protected by the mutex \fImut\fP, +and a condition variable \fIcond\fP that is to be signaled whenever \fIx\fP +becomes greater than \fIy\fP. .RS .ft 3 @@ -164,7 +164,7 @@ .RE .fi -Waiting until |x| is greater than |y| is performed as follows: +Waiting until \fIx\fP is greater than \fIy\fP is performed as follows: .RS .ft 3 @@ -181,8 +181,8 @@ .RE .fi -Modifications on |x| and |y| that may cause |x| to become greater than -|y| should signal the condition if needed: +Modifications on \fIx\fP and \fIy\fP that may cause \fIx\fP to become greater than +\fIy\fP should signal the condition if needed: .RS .ft 3 @@ -199,11 +199,11 @@ If it can be proved that at most one waiting thread needs to be waken up (for instance, if there are only two threads communicating through -|x| and |y|), !pthread_cond_signal! can be used as a slightly more -efficient alternative to !pthread_cond_broadcast!. In doubt, use -!pthread_cond_broadcast!. +\fIx\fP and \fIy\fP), \fBpthread_cond_signal\fP can be used as a slightly more +efficient alternative to \fBpthread_cond_broadcast\fP. In doubt, use +\fBpthread_cond_broadcast\fP. -To wait for |x| to becomes greater than |y| with a timeout of 5 +To wait for \fIx\fP to becomes greater than \fIy\fP with a timeout of 5 seconds, do: .RS --- a/linuxthreads/man/pthread_create.man +++ b/linuxthreads/man/pthread_create.man @@ -9,38 +9,38 @@ int pthread_create(pthread_t * thread, pthread_attr_t * attr, void * (*start_routine)(void *), void * arg); .SH DESCRIPTION -!pthread_create! creates a new thread of control that executes +\fBpthread_create\fP creates a new thread of control that executes concurrently with the calling thread. The new thread applies the -function |start_routine| passing it |arg| as first argument. The new -thread terminates either explicitly, by calling !pthread_exit!(3), -or implicitly, by returning from the |start_routine| function. The -latter case is equivalent to calling !pthread_exit!(3) with the result -returned by |start_routine| as exit code. - -The |attr| argument specifies thread attributes to be applied to the -new thread. See !pthread_attr_init!(3) for a complete list of thread -attributes. The |attr| argument can also be !NULL!, in which case +function \fIstart_routine\fP passing it \fIarg\fP as first argument. The new +thread terminates either explicitly, by calling \fBpthread_exit\fP(3), +or implicitly, by returning from the \fIstart_routine\fP function. The +latter case is equivalent to calling \fBpthread_exit\fP(3) with the result +returned by \fIstart_routine\fP as exit code. + +The \fIattr\fP argument specifies thread attributes to be applied to the +new thread. See \fBpthread_attr_init\fP(3) for a complete list of thread +attributes. The \fIattr\fP argument can also be \fBNULL\fP, in which case default attributes are used: the created thread is joinable (not detached) and has default (non real-time) scheduling policy. .SH "RETURN VALUE" On success, the identifier of the newly created thread is stored in -the location pointed by the |thread| argument, and a 0 is returned. On +the location pointed by the \fIthread\fP argument, and a 0 is returned. On error, a non-zero error code is returned. .SH ERRORS .TP -!EAGAIN! +\fBEAGAIN\fP not enough system resources to create a process for the new thread. .TP -!EAGAIN! -more than !PTHREAD_THREADS_MAX! threads are already active. +\fBEAGAIN\fP +more than \fBPTHREAD_THREADS_MAX\fP threads are already active. .SH AUTHOR Xavier Leroy .SH "SEE ALSO" -!pthread_exit!(3), -!pthread_join!(3), -!pthread_detach!(3), -!pthread_attr_init!(3). +\fBpthread_exit\fP(3), +\fBpthread_join\fP(3), +\fBpthread_detach\fP(3), +\fBpthread_attr_init\fP(3). --- a/linuxthreads/man/pthread_detach.man +++ b/linuxthreads/man/pthread_detach.man @@ -9,36 +9,36 @@ int pthread_detach(pthread_t th); .SH DESCRIPTION -!pthread_detach! put the thread |th| in the detached state. This -guarantees that the memory resources consumed by |th| will be freed -immediately when |th| terminates. However, this prevents other threads -from synchronizing on the termination of |th| using !pthread_join!. +\fBpthread_detach\fP put the thread \fIth\fP in the detached state. This +guarantees that the memory resources consumed by \fIth\fP will be freed +immediately when \fIth\fP terminates. However, this prevents other threads +from synchronizing on the termination of \fIth\fP using \fBpthread_join\fP. A thread can be created initially in the detached state, using the -!detachstate! attribute to !pthread_create!(3). In contrast, -!pthread_detach! applies to threads created in the joinable state, and +\fBdetachstate\fP attribute to \fBpthread_create\fP(3). In contrast, +\fBpthread_detach\fP applies to threads created in the joinable state, and which need to be put in the detached state later. -After !pthread_detach! completes, subsequent attempts to perform -!pthread_join! on |th| will fail. If another thread is already joining -the thread |th| at the time !pthread_detach! is called, -!pthread_detach! does nothing and leaves |th| in the joinable state. +After \fBpthread_detach\fP completes, subsequent attempts to perform +\fBpthread_join\fP on \fIth\fP will fail. If another thread is already joining +the thread \fIth\fP at the time \fBpthread_detach\fP is called, +\fBpthread_detach\fP does nothing and leaves \fIth\fP in the joinable state. .SH "RETURN VALUE" On success, 0 is returned. On error, a non-zero error code is returned. .SH ERRORS .TP -!ESRCH! -No thread could be found corresponding to that specified by |th| +\fBESRCH\fP +No thread could be found corresponding to that specified by \fIth\fP .TP -!EINVAL! -the thread |th| is already in the detached state +\fBEINVAL\fP +the thread \fIth\fP is already in the detached state .SH AUTHOR Xavier Leroy .SH "SEE ALSO" -!pthread_create!(3), -!pthread_join!(3), -!pthread_attr_setdetachstate!(3). \ No newline at end of file +\fBpthread_create\fP(3), +\fBpthread_join\fP(3), +\fBpthread_attr_setdetachstate\fP(3). \ No newline at end of file --- a/linuxthreads/man/pthread_equal.man +++ b/linuxthreads/man/pthread_equal.man @@ -9,15 +9,15 @@ int pthread_equal(pthread_t thread1, pthread_t thread2); .SH DESCRIPTION -!pthread_equal! determines if two thread identifiers refer to the same +\fBpthread_equal\fP determines if two thread identifiers refer to the same thread. .SH "RETURN VALUE" -A non-zero value is returned if |thread1| and |thread2| refer to the +A non-zero value is returned if \fIthread1\fP and \fIthread2\fP refer to the same thread. Otherwise, 0 is returned. .SH AUTHOR Xavier Leroy .SH "SEE ALSO" -!pthread_self!(3). +\fBpthread_self\fP(3). --- a/linuxthreads/man/pthread_exit.man +++ b/linuxthreads/man/pthread_exit.man @@ -9,24 +9,24 @@ void pthread_exit(void *retval); .SH DESCRIPTION -!pthread_exit! terminates the execution of the calling thread. +\fBpthread_exit\fP terminates the execution of the calling thread. All cleanup handlers that have been set for the calling thread with -!pthread_cleanup_push!(3) are executed in reverse order (the most +\fBpthread_cleanup_push\fP(3) are executed in reverse order (the most recently pushed handler is executed first). Finalization functions for -thread-specific data are then called for all keys that have non-!NULL! +thread-specific data are then called for all keys that have non-\fBNULL\fP values associated with them in the calling thread (see -!pthread_key_create!(3)). Finally, execution of the calling thread is +\fBpthread_key_create\fP(3)). Finally, execution of the calling thread is stopped. -The |retval| argument is the return value of the thread. It can be -consulted from another thread using !pthread_join!(3). +The \fIretval\fP argument is the return value of the thread. It can be +consulted from another thread using \fBpthread_join\fP(3). .SH "RETURN VALUE" -The !pthread_exit! function never returns. +The \fBpthread_exit\fP function never returns. .SH AUTHOR Xavier Leroy .SH "SEE ALSO" -!pthread_create!(3), -!pthread_join!(3). +\fBpthread_create\fP(3), +\fBpthread_join\fP(3). --- a/linuxthreads/man/pthread_join.man +++ b/linuxthreads/man/pthread_join.man @@ -9,62 +9,62 @@ int pthread_join(pthread_t th, void **thread_return); .SH DESCRIPTION -!pthread_join! suspends the execution of the calling thread until the -thread identified by |th| terminates, either by calling !pthread_exit!(3) +\fBpthread_join\fP suspends the execution of the calling thread until the +thread identified by \fIth\fP terminates, either by calling \fBpthread_exit\fP(3) or by being cancelled. -If |thread_return| is not !NULL!, the return value of |th| is stored -in the location pointed to by |thread_return|. The return value of -|th| is either the argument it gave to !pthread_exit!(3), or -!PTHREAD_CANCELED! if |th| was cancelled. - -The joined thread !th! must be in the joinable state: it must not have -been detached using !pthread_detach!(3) or the -!PTHREAD_CREATE_DETACHED! attribute to !pthread_create!(3). +If \fIthread_return\fP is not \fBNULL\fP, the return value of \fIth\fP is stored +in the location pointed to by \fIthread_return\fP. The return value of +\fIth\fP is either the argument it gave to \fBpthread_exit\fP(3), or +\fBPTHREAD_CANCELED\fP if \fIth\fP was cancelled. + +The joined thread \fBth\fP must be in the joinable state: it must not have +been detached using \fBpthread_detach\fP(3) or the +\fBPTHREAD_CREATE_DETACHED\fP attribute to \fBpthread_create\fP(3). When a joinable thread terminates, its memory resources (thread descriptor and stack) are not deallocated until another thread -performs !pthread_join! on it. Therefore, !pthread_join! must be +performs \fBpthread_join\fP on it. Therefore, \fBpthread_join\fP must be called once for each joinable thread created to avoid memory leaks. At most one thread can wait for the termination of a given -thread. Calling !pthread_join! on a thread |th| on which another +thread. Calling \fBpthread_join\fP on a thread \fIth\fP on which another thread is already waiting for termination returns an error. .SH CANCELLATION -!pthread_join! is a cancellation point. If a thread is canceled while -suspended in !pthread_join!, the thread execution resumes immediately -and the cancellation is executed without waiting for the |th| thread -to terminate. If cancellation occurs during !pthread_join!, the |th| +\fBpthread_join\fP is a cancellation point. If a thread is canceled while +suspended in \fBpthread_join\fP, the thread execution resumes immediately +and the cancellation is executed without waiting for the \fIth\fP thread +to terminate. If cancellation occurs during \fBpthread_join\fP, the \fIth\fP thread remains not joined. .SH "RETURN VALUE" -On success, the return value of |th| is stored in the location pointed -to by |thread_return|, and 0 is returned. On error, a non-zero error +On success, the return value of \fIth\fP is stored in the location pointed +to by \fIthread_return\fP, and 0 is returned. On error, a non-zero error code is returned. .SH ERRORS .TP -!ESRCH! -No thread could be found corresponding to that specified by |th|. +\fBESRCH\fP +No thread could be found corresponding to that specified by \fIth\fP. .TP -!EINVAL! -The |th| thread has been detached. +\fBEINVAL\fP +The \fIth\fP thread has been detached. .TP -!EINVAL! -Another thread is already waiting on termination of |th|. +\fBEINVAL\fP +Another thread is already waiting on termination of \fIth\fP. .TP -!EDEADLK! -The |th| argument refers to the calling thread. +\fBEDEADLK\fP +The \fIth\fP argument refers to the calling thread. .SH AUTHOR Xavier Leroy .SH "SEE ALSO" -!pthread_exit!(3), -!pthread_detach!(3), -!pthread_create!(3), -!pthread_attr_setdetachstate!(3), -!pthread_cleanup_push!(3), -!pthread_key_create!(3). +\fBpthread_exit\fP(3), +\fBpthread_detach\fP(3), +\fBpthread_create\fP(3), +\fBpthread_attr_setdetachstate\fP(3), +\fBpthread_cleanup_push\fP(3), +\fBpthread_key_create\fP(3). --- a/linuxthreads/man/pthread_key_create.man +++ b/linuxthreads/man/pthread_key_create.man @@ -23,81 +23,81 @@ Each thread possesses a private memory block, the thread-specific data area, or TSD area for short. This area is indexed by TSD keys. The TSD -area associates values of type !void *! to TSD keys. TSD keys are +area associates values of type \fBvoid *\fP to TSD keys. TSD keys are common to all threads, but the value associated with a given TSD key can be different in each thread. -For concreteness, the TSD areas can be viewed as arrays of !void *! +For concreteness, the TSD areas can be viewed as arrays of \fBvoid *\fP pointers, TSD keys as integer indices into these arrays, and the value of a TSD key as the value of the corresponding array element in the calling thread. -When a thread is created, its TSD area initially associates !NULL! +When a thread is created, its TSD area initially associates \fBNULL\fP with all keys. -!pthread_key_create! allocates a new TSD key. The key is stored in the -location pointed to by |key|. There is a limit of !PTHREAD_KEYS_MAX! +\fBpthread_key_create\fP allocates a new TSD key. The key is stored in the +location pointed to by \fIkey\fP. There is a limit of \fBPTHREAD_KEYS_MAX\fP on the number of keys allocated at a given time. The value initially -associated with the returned key is !NULL! in all currently executing +associated with the returned key is \fBNULL\fP in all currently executing threads. -The |destr_function| argument, if not !NULL!, specifies a destructor +The \fIdestr_function\fP argument, if not \fBNULL\fP, specifies a destructor function associated with the key. When a thread terminates via -!pthread_exit! or by cancellation, |destr_function| is called with +\fBpthread_exit\fP or by cancellation, \fIdestr_function\fP is called with arguments the value associated with the key in that thread. The -|destr_function| is not called if that value is !NULL!. The order in +\fIdestr_function\fP is not called if that value is \fBNULL\fP. The order in which destructor functions are called at thread termination time is unspecified. -Before the destructor function is called, the !NULL! value is +Before the destructor function is called, the \fBNULL\fP value is associated with the key in the current thread. A destructor function -might, however, re-associate non-!NULL! values to that key or some +might, however, re-associate non-\fBNULL\fP values to that key or some other key. To deal with this, if after all the destructors have been -called for all non-!NULL! values, there are still some non-!NULL! +called for all non-\fBNULL\fP values, there are still some non-\fBNULL\fP values with associated destructors, then the process is repeated. The LinuxThreads implementation stops the process after -!PTHREAD_DESTRUCTOR_ITERATIONS! iterations, even if some non-!NULL! +\fBPTHREAD_DESTRUCTOR_ITERATIONS\fP iterations, even if some non-\fBNULL\fP values with associated descriptors remain. Other implementations may loop indefinitely. -!pthread_key_delete! deallocates a TSD key. It does not check whether -non-!NULL! values are associated with that key in the currently +\fBpthread_key_delete\fP deallocates a TSD key. It does not check whether +non-\fBNULL\fP values are associated with that key in the currently executing threads, nor call the destructor function associated with the key. -!pthread_setspecific! changes the value associated with |key| in the -calling thread, storing the given |pointer| instead. +\fBpthread_setspecific\fP changes the value associated with \fIkey\fP in the +calling thread, storing the given \fIpointer\fP instead. -!pthread_getspecific! returns the value currently associated with -|key| in the calling thread. +\fBpthread_getspecific\fP returns the value currently associated with +\fIkey\fP in the calling thread. .SH "RETURN VALUE" -!pthread_key_create!, !pthread_key_delete!, and !pthread_setspecific! +\fBpthread_key_create\fP, \fBpthread_key_delete\fP, and \fBpthread_setspecific\fP return 0 on success and a non-zero error code on failure. If -successful, !pthread_key_create! stores the newly allocated key in the -location pointed to by its |key| argument. +successful, \fBpthread_key_create\fP stores the newly allocated key in the +location pointed to by its \fIkey\fP argument. -!pthread_getspecific! returns the value associated with |key| on -success, and !NULL! on error. +\fBpthread_getspecific\fP returns the value associated with \fIkey\fP on +success, and \fBNULL\fP on error. .SH ERRORS -!pthread_key_create! returns the following error code on error: +\fBpthread_key_create\fP returns the following error code on error: .RS .TP -!EAGAIN! -!PTHREAD_KEYS_MAX! keys are already allocated +\fBEAGAIN\fP +\fBPTHREAD_KEYS_MAX\fP keys are already allocated .RE -!pthread_key_delete! and !pthread_setspecific! return the following +\fBpthread_key_delete\fP and \fBpthread_setspecific\fP return the following error code on error: .RS .TP -!EINVAL! -|key| is not a valid, allocated TSD key +\fBEINVAL\fP +\fIkey\fP is not a valid, allocated TSD key .RE -!pthread_getspecific! returns !NULL! if |key| is not a valid, +\fBpthread_getspecific\fP returns \fBNULL\fP if \fIkey\fP is not a valid, allocated TSD key. .SH AUTHOR --- a/linuxthreads/man/pthread_kill_other_threads_np.man +++ b/linuxthreads/man/pthread_kill_other_threads_np.man @@ -9,14 +9,14 @@ void pthread_kill_other_threads_np(void); .SH DESCRIPTION -!pthread_kill_other_threads_np! is a non-portable LinuxThreads extension. +\fBpthread_kill_other_threads_np\fP is a non-portable LinuxThreads extension. It causes all threads in the program to terminate immediately, except the calling thread which proceeds normally. It is intended to be -called just before a thread calls one of the !exec! functions, -e.g. !execve!(2). +called just before a thread calls one of the \fBexec\fP functions, +e.g. \fBexecve\fP(2). Termination of the other threads is not performed through -!pthread_cancel!(3) and completely bypasses the cancellation +\fBpthread_cancel\fP(3) and completely bypasses the cancellation mechanism. Hence, the current settings for cancellation state and cancellation type are ignored, and the cleanup handlers are not executed in the terminated threads. @@ -25,16 +25,16 @@ Xavier Leroy .SH "SEE ALSO" -!execve!(2), -!pthread_setcancelstate!(3), -!pthread_setcanceltype!(3), -!pthread_cancel!(3). +\fBexecve\fP(2), +\fBpthread_setcancelstate\fP(3), +\fBpthread_setcanceltype\fP(3), +\fBpthread_cancel\fP(3). .SH BUGS -According to POSIX 1003.1c, a successful !exec*! in one of the threads +According to POSIX 1003.1c, a successful \fBexec*\fP in one of the threads should terminate automatically all other threads in the program. This behavior is not yet implemented in LinuxThreads. -Calling !pthread_kill_other_threads_np! before !exec*! achieves much -of the same behavior, except that if !exec*! ultimately fails, then +Calling \fBpthread_kill_other_threads_np\fP before \fBexec*\fP achieves much +of the same behavior, except that if \fBexec*\fP ultimately fails, then all other threads are already killed. --- a/linuxthreads/man/pthread_mutexattr_init.man +++ b/linuxthreads/man/pthread_mutexattr_init.man @@ -21,64 +21,64 @@ .SH DESCRIPTION Mutex attributes can be specified at mutex creation time, by passing a -mutex attribute object as second argument to !pthread_mutex_init!(3). -Passing !NULL! is equivalent to passing a mutex attribute object with +mutex attribute object as second argument to \fBpthread_mutex_init\fP(3). +Passing \fBNULL\fP is equivalent to passing a mutex attribute object with all attributes set to their default values. -!pthread_mutexattr_init! initializes the mutex attribute object |attr| +\fBpthread_mutexattr_init\fP initializes the mutex attribute object \fIattr\fP and fills it with default values for the attributes. -!pthread_mutexattr_destroy! destroys a mutex attribute object, which -must not be reused until it is reinitialized. !pthread_mutexattr_destroy! +\fBpthread_mutexattr_destroy\fP destroys a mutex attribute object, which +must not be reused until it is reinitialized. \fBpthread_mutexattr_destroy\fP does nothing in the LinuxThreads implementation. LinuxThreads supports only one mutex attribute: the mutex kind, which -is either !PTHREAD_MUTEX_FAST_NP! for ``fast'' mutexes, -!PTHREAD_MUTEX_RECURSIVE_NP! for ``recursive'' mutexes, -or !PTHREAD_MUTEX_ERRORCHECK_NP! for ``error checking'' mutexes. -As the !NP! suffix indicates, this is a non-portable extension to the +is either \fBPTHREAD_MUTEX_FAST_NP\fP for ``fast'' mutexes, +\fBPTHREAD_MUTEX_RECURSIVE_NP\fP for ``recursive'' mutexes, +or \fBPTHREAD_MUTEX_ERRORCHECK_NP\fP for ``error checking'' mutexes. +As the \fBNP\fP suffix indicates, this is a non-portable extension to the POSIX standard and should not be employed in portable programs. The mutex kind determines what happens if a thread attempts to lock a -mutex it already owns with !pthread_mutex_lock!(3). If the mutex is of -the ``fast'' kind, !pthread_mutex_lock!(3) simply suspends the calling +mutex it already owns with \fBpthread_mutex_lock\fP(3). If the mutex is of +the ``fast'' kind, \fBpthread_mutex_lock\fP(3) simply suspends the calling thread forever. If the mutex is of the ``error checking'' kind, -!pthread_mutex_lock!(3) returns immediately with the error code -!EDEADLK!. If the mutex is of the ``recursive'' kind, the call to -!pthread_mutex_lock!(3) returns immediately with a success return +\fBpthread_mutex_lock\fP(3) returns immediately with the error code +\fBEDEADLK\fP. If the mutex is of the ``recursive'' kind, the call to +\fBpthread_mutex_lock\fP(3) returns immediately with a success return code. The number of times the thread owning the mutex has locked it is recorded in the mutex. The owning thread must call -!pthread_mutex_unlock!(3) the same number of times before the mutex +\fBpthread_mutex_unlock\fP(3) the same number of times before the mutex returns to the unlocked state. -The default mutex kind is ``fast'', that is, !PTHREAD_MUTEX_FAST_NP!. +The default mutex kind is ``fast'', that is, \fBPTHREAD_MUTEX_FAST_NP\fP. -!pthread_mutexattr_settype! sets the mutex kind attribute in |attr| -to the value specified by |kind|. +\fBpthread_mutexattr_settype\fP sets the mutex kind attribute in \fIattr\fP +to the value specified by \fIkind\fP. -!pthread_mutexattr_gettype! retrieves the current value of the -mutex kind attribute in |attr| and stores it in the location pointed -to by |kind|. +\fBpthread_mutexattr_gettype\fP retrieves the current value of the +mutex kind attribute in \fIattr\fP and stores it in the location pointed +to by \fIkind\fP. .SH "RETURN VALUE" -!pthread_mutexattr_init!, !pthread_mutexattr_destroy! and -!pthread_mutexattr_gettype! always return 0. +\fBpthread_mutexattr_init\fP, \fBpthread_mutexattr_destroy\fP and +\fBpthread_mutexattr_gettype\fP always return 0. -!pthread_mutexattr_settype! returns 0 on success and a non-zero +\fBpthread_mutexattr_settype\fP returns 0 on success and a non-zero error code on error. .SH ERRORS -On error, !pthread_mutexattr_settype! returns the following error code: +On error, \fBpthread_mutexattr_settype\fP returns the following error code: .TP -!EINVAL! -|kind| is neither !PTHREAD_MUTEX_FAST_NP! nor !PTHREAD_MUTEX_RECURSIVE_NP! -nor !PTHREAD_MUTEX_ERRORCHECK_NP! +\fBEINVAL\fP +\fIkind\fP is neither \fBPTHREAD_MUTEX_FAST_NP\fP nor \fBPTHREAD_MUTEX_RECURSIVE_NP\fP +nor \fBPTHREAD_MUTEX_ERRORCHECK_NP\fP .SH AUTHOR Xavier Leroy .SH "SEE ALSO" -!pthread_mutex_init!(3), -!pthread_mutex_lock!(3), -!pthread_mutex_unlock!(3). +\fBpthread_mutex_init\fP(3), +\fBpthread_mutex_lock\fP(3), +\fBpthread_mutex_unlock\fP(3). --- a/linuxthreads/man/pthread_mutexattr_setkind_np.man +++ b/linuxthreads/man/pthread_mutexattr_setkind_np.man @@ -14,26 +14,26 @@ .SH DESCRIPTION -These functions are deprecated, use !pthread_mutexattr_settype!(3) -and !pthread_mutexattr_gettype!(3) instead. +These functions are deprecated, use \fBpthread_mutexattr_settype\fP(3) +and \fBpthread_mutexattr_gettype\fP(3) instead. .SH "RETURN VALUE" -!pthread_mutexattr_getkind_np! always returns 0. +\fBpthread_mutexattr_getkind_np\fP always returns 0. -!pthread_mutexattr_setkind_np! returns 0 on success and a non-zero +\fBpthread_mutexattr_setkind_np\fP returns 0 on success and a non-zero error code on error. .SH ERRORS -On error, !pthread_mutexattr_setkind_np! returns the following error code: +On error, \fBpthread_mutexattr_setkind_np\fP returns the following error code: .TP -!EINVAL! -|kind| is neither !PTHREAD_MUTEX_FAST_NP! nor !PTHREAD_MUTEX_RECURSIVE_NP! -nor !PTHREAD_MUTEX_ERRORCHECK_NP! +\fBEINVAL\fP +\fIkind\fP is neither \fBPTHREAD_MUTEX_FAST_NP\fP nor \fBPTHREAD_MUTEX_RECURSIVE_NP\fP +nor \fBPTHREAD_MUTEX_ERRORCHECK_NP\fP .SH AUTHOR Xavier Leroy .SH "SEE ALSO" -!pthread_mutexattr_settype!(3), -!pthread_mutexattr_gettype!(3). +\fBpthread_mutexattr_settype\fP(3), +\fBpthread_mutexattr_gettype\fP(3). --- a/linuxthreads/man/pthread_mutex_init.man +++ b/linuxthreads/man/pthread_mutex_init.man @@ -38,75 +38,75 @@ that is already locked by another thread is suspended until the owning thread unlocks the mutex first. -!pthread_mutex_init! initializes the mutex object pointed to by -|mutex| according to the mutex attributes specified in |mutexattr|. -If |mutexattr| is !NULL!, default attributes are used instead. +\fBpthread_mutex_init\fP initializes the mutex object pointed to by +\fImutex\fP according to the mutex attributes specified in \fImutexattr\fP. +If \fImutexattr\fP is \fBNULL\fP, default attributes are used instead. The LinuxThreads implementation supports only one mutex attributes, the |mutex kind|, which is either ``fast'', ``recursive'', or ``error checking''. The kind of a mutex determines whether it can be locked again by a thread that already owns it. -The default kind is ``fast''. See !pthread_mutexattr_init!(3) for more +The default kind is ``fast''. See \fBpthread_mutexattr_init\fP(3) for more information on mutex attributes. -Variables of type !pthread_mutex_t! can also be initialized -statically, using the constants !PTHREAD_MUTEX_INITIALIZER! (for fast -mutexes), !PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP! (for recursive -mutexes), and !PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP! (for error checking +Variables of type \fBpthread_mutex_t\fP can also be initialized +statically, using the constants \fBPTHREAD_MUTEX_INITIALIZER\fP (for fast +mutexes), \fBPTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP\fP (for recursive +mutexes), and \fBPTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP\fP (for error checking mutexes). -!pthread_mutex_lock! locks the given mutex. If the mutex is currently +\fBpthread_mutex_lock\fP locks the given mutex. If the mutex is currently unlocked, it becomes locked and owned by the calling thread, and -!pthread_mutex_lock! returns immediately. If the mutex is already -locked by another thread, !pthread_mutex_lock! suspends the calling +\fBpthread_mutex_lock\fP returns immediately. If the mutex is already +locked by another thread, \fBpthread_mutex_lock\fP suspends the calling thread until the mutex is unlocked. If the mutex is already locked by the calling thread, the behavior of -!pthread_mutex_lock! depends on the kind of the mutex. If the mutex is +\fBpthread_mutex_lock\fP depends on the kind of the mutex. If the mutex is of the ``fast'' kind, the calling thread is suspended until the mutex is unlocked, thus effectively causing the calling thread to deadlock. If the mutex is of the ``error checking'' kind, -!pthread_mutex_lock! returns immediately with the error code !EDEADLK!. -If the mutex is of the ``recursive'' kind, !pthread_mutex_lock! +\fBpthread_mutex_lock\fP returns immediately with the error code \fBEDEADLK\fP. +If the mutex is of the ``recursive'' kind, \fBpthread_mutex_lock\fP succeeds and returns immediately, recording the number of times the calling thread has locked the mutex. An equal number of -!pthread_mutex_unlock! operations must be performed before the mutex +\fBpthread_mutex_unlock\fP operations must be performed before the mutex returns to the unlocked state. -!pthread_mutex_trylock! behaves identically to !pthread_mutex_lock!, +\fBpthread_mutex_trylock\fP behaves identically to \fBpthread_mutex_lock\fP, except that it does not block the calling thread if the mutex is already locked by another thread (or by the calling thread in the case -of a ``fast'' mutex). Instead, !pthread_mutex_trylock! returns -immediately with the error code !EBUSY!. +of a ``fast'' mutex). Instead, \fBpthread_mutex_trylock\fP returns +immediately with the error code \fBEBUSY\fP. -!pthread_mutex_unlock! unlocks the given mutex. The mutex is assumed +\fBpthread_mutex_unlock\fP unlocks the given mutex. The mutex is assumed to be locked and owned by the calling thread on entrance to -!pthread_mutex_unlock!. If the mutex is of the ``fast'' kind, -!pthread_mutex_unlock! always returns it to the unlocked state. If it +\fBpthread_mutex_unlock\fP. If the mutex is of the ``fast'' kind, +\fBpthread_mutex_unlock\fP always returns it to the unlocked state. If it is of the ``recursive'' kind, it decrements the locking count of the -mutex (number of !pthread_mutex_lock! operations performed on it by +mutex (number of \fBpthread_mutex_lock\fP operations performed on it by the calling thread), and only when this count reaches zero is the mutex actually unlocked. -On ``error checking'' mutexes, !pthread_mutex_unlock! actually checks +On ``error checking'' mutexes, \fBpthread_mutex_unlock\fP actually checks at run-time that the mutex is locked on entrance, and that it was -locked by the same thread that is now calling !pthread_mutex_unlock!. +locked by the same thread that is now calling \fBpthread_mutex_unlock\fP. If these conditions are not met, an error code is returned and the mutex remains unchanged. ``Fast'' and ``recursive'' mutexes perform no such checks, thus allowing a locked mutex to be unlocked by a thread other than its owner. This is non-portable behavior and must not be relied upon. -!pthread_mutex_destroy! destroys a mutex object, freeing the resources +\fBpthread_mutex_destroy\fP destroys a mutex object, freeing the resources it might hold. The mutex must be unlocked on entrance. In the LinuxThreads implementation, no resources are associated with mutex -objects, thus !pthread_mutex_destroy! actually does nothing except +objects, thus \fBpthread_mutex_destroy\fP actually does nothing except checking that the mutex is unlocked. .SH CANCELLATION None of the mutex functions is a cancellation point, not even -!pthread_mutex_lock!, in spite of the fact that it can suspend a +\fBpthread_mutex_lock\fP, in spite of the fact that it can suspend a thread for arbitrary durations. This way, the status of mutexes at cancellation points is predictable, allowing cancellation handlers to unlock precisely those mutexes that need to be unlocked before the @@ -117,58 +117,58 @@ The mutex functions are not async-signal safe. What this means is that they should not be called from a signal handler. In particular, -calling !pthread_mutex_lock! or !pthread_mutex_unlock! from a signal +calling \fBpthread_mutex_lock\fP or \fBpthread_mutex_unlock\fP from a signal handler may deadlock the calling thread. .SH "RETURN VALUE" -!pthread_mutex_init! always returns 0. The other mutex functions +\fBpthread_mutex_init\fP always returns 0. The other mutex functions return 0 on success and a non-zero error code on error. .SH ERRORS -The !pthread_mutex_lock! function returns the following error code +The \fBpthread_mutex_lock\fP function returns the following error code on error: .RS .TP -!EINVAL! +\fBEINVAL\fP the mutex has not been properly initialized. .TP -!EDEADLK! +\fBEDEADLK\fP the mutex is already locked by the calling thread (``error checking'' mutexes only). .RE -The !pthread_mutex_trylock! function returns the following error codes +The \fBpthread_mutex_trylock\fP function returns the following error codes on error: .RS .TP -!EBUSY! +\fBEBUSY\fP the mutex could not be acquired because it was currently locked. .TP -!EINVAL! +\fBEINVAL\fP the mutex has not been properly initialized. .RE -The !pthread_mutex_unlock! function returns the following error code +The \fBpthread_mutex_unlock\fP function returns the following error code on error: .RS .TP -!EINVAL! +\fBEINVAL\fP the mutex has not been properly initialized. .TP -!EPERM! +\fBEPERM\fP the calling thread does not own the mutex (``error checking'' mutexes only). .RE -The !pthread_mutex_destroy! function returns the following error code +The \fBpthread_mutex_destroy\fP function returns the following error code on error: .RS .TP -!EBUSY! +\fBEBUSY\fP the mutex is currently locked. .RE @@ -176,13 +176,13 @@ Xavier Leroy .SH "SEE ALSO" -!pthread_mutexattr_init!(3), -!pthread_mutexattr_setkind_np!(3), -!pthread_cancel!(3). +\fBpthread_mutexattr_init\fP(3), +\fBpthread_mutexattr_setkind_np\fP(3), +\fBpthread_cancel\fP(3). .SH EXAMPLE -A shared global variable |x| can be protected by a mutex as follows: +A shared global variable \fIx\fP can be protected by a mutex as follows: .RS .ft 3 @@ -195,8 +195,8 @@ .RE .fi -All accesses and modifications to |x| should be bracketed by calls to -!pthread_mutex_lock! and !pthread_mutex_unlock! as follows: +All accesses and modifications to \fIx\fP should be bracketed by calls to +\fBpthread_mutex_lock\fP and \fBpthread_mutex_unlock\fP as follows: .RS .ft 3 --- a/linuxthreads/man/pthread_once.man +++ b/linuxthreads/man/pthread_once.man @@ -12,19 +12,19 @@ .SH DESCRIPTION -The purpose of !pthread_once! is to ensure that a piece of -initialization code is executed at most once. The |once_control| +The purpose of \fBpthread_once\fP is to ensure that a piece of +initialization code is executed at most once. The \fIonce_control\fP argument points to a static or extern variable statically initialized -to !PTHREAD_ONCE_INIT!. +to \fBPTHREAD_ONCE_INIT\fP. -The first time !pthread_once! is called with a given |once_control| -argument, it calls |init_routine| with no argument and changes the -value of the |once_control| variable to record that initialization has -been performed. Subsequent calls to !pthread_once! with the same -!once_control! argument do nothing. +The first time \fBpthread_once\fP is called with a given \fIonce_control\fP +argument, it calls \fIinit_routine\fP with no argument and changes the +value of the \fIonce_control\fP variable to record that initialization has +been performed. Subsequent calls to \fBpthread_once\fP with the same +\fBonce_control\fP argument do nothing. .SH "RETURN VALUE" -!pthread_once! always returns 0. +\fBpthread_once\fP always returns 0. .SH ERRORS None. --- a/linuxthreads/man/pthread_self.man +++ b/linuxthreads/man/pthread_self.man @@ -9,15 +9,15 @@ pthread_t pthread_self(void); .SH DESCRIPTION -!pthread_self! return the thread identifier for the calling thread. +\fBpthread_self\fP return the thread identifier for the calling thread. .SH AUTHOR Xavier Leroy .SH "SEE ALSO" -!pthread_equal!(3), -!pthread_join!(3), -!pthread_detach!(3), -!pthread_setschedparam!(3), -!pthread_getschedparam!(3). +\fBpthread_equal\fP(3), +\fBpthread_join\fP(3), +\fBpthread_detach\fP(3), +\fBpthread_setschedparam\fP(3), +\fBpthread_getschedparam\fP(3). --- a/linuxthreads/man/pthread_setschedparam.man +++ b/linuxthreads/man/pthread_setschedparam.man @@ -14,66 +14,66 @@ .SH DESCRIPTION -!pthread_setschedparam! sets the scheduling parameters for the thread -|target_thread| as indicated by |policy| and |param|. |policy| can be -either !SCHED_OTHER! (regular, non-realtime scheduling), !SCHED_RR! -(realtime, round-robin) or !SCHED_FIFO! (realtime, first-in -first-out). |param| specifies the scheduling priority for the two -realtime policies. See !sched_setpolicy!(2) for more information on +\fBpthread_setschedparam\fP sets the scheduling parameters for the thread +\fItarget_thread\fP as indicated by \fIpolicy\fP and \fIparam\fP. \fIpolicy\fP can be +either \fBSCHED_OTHER\fP (regular, non-realtime scheduling), \fBSCHED_RR\fP +(realtime, round-robin) or \fBSCHED_FIFO\fP (realtime, first-in +first-out). \fIparam\fP specifies the scheduling priority for the two +realtime policies. See \fBsched_setpolicy\fP(2) for more information on scheduling policies. -The realtime scheduling policies !SCHED_RR! and !SCHED_FIFO! are +The realtime scheduling policies \fBSCHED_RR\fP and \fBSCHED_FIFO\fP are available only to processes with superuser privileges. -!pthread_getschedparam! retrieves the scheduling policy and scheduling -parameters for the thread |target_thread| and store them in the -locations pointed to by |policy| and |param|, respectively. +\fBpthread_getschedparam\fP retrieves the scheduling policy and scheduling +parameters for the thread \fItarget_thread\fP and store them in the +locations pointed to by \fIpolicy\fP and \fIparam\fP, respectively. .SH "RETURN VALUE" -!pthread_setschedparam! and !pthread_getschedparam! return 0 on +\fBpthread_setschedparam\fP and \fBpthread_getschedparam\fP return 0 on success and a non-zero error code on error. .SH ERRORS -On error, !pthread_setschedparam! returns the following error codes: +On error, \fBpthread_setschedparam\fP returns the following error codes: .RS .TP -!EINVAL! -|policy| is not one of !SCHED_OTHER!, !SCHED_RR!, !SCHED_FIFO! +\fBEINVAL\fP +\fIpolicy\fP is not one of \fBSCHED_OTHER\fP, \fBSCHED_RR\fP, \fBSCHED_FIFO\fP .TP -!EINVAL! -the priority value specified by |param| is not valid for the specified policy +\fBEINVAL\fP +the priority value specified by \fIparam\fP is not valid for the specified policy .TP -!EPERM! +\fBEPERM\fP the calling process does not have superuser permissions .TP -!ESRCH! -the |target_thread| is invalid or has already terminated +\fBESRCH\fP +the \fItarget_thread\fP is invalid or has already terminated .TP -!EFAULT! -|param| points outside the process memory space +\fBEFAULT\fP +\fIparam\fP points outside the process memory space .RE -On error, !pthread_getschedparam! returns the following error codes: +On error, \fBpthread_getschedparam\fP returns the following error codes: .RS .TP -!ESRCH! -the |target_thread| is invalid or has already terminated +\fBESRCH\fP +the \fItarget_thread\fP is invalid or has already terminated .TP -!EFAULT! -|policy| or |param| point outside the process memory space +\fBEFAULT\fP +\fIpolicy\fP or \fIparam\fP point outside the process memory space .RE .SH AUTHOR Xavier Leroy .SH "SEE ALSO" -!sched_setscheduler!(2), -!sched_getscheduler!(2), -!sched_getparam!(2), -!pthread_attr_setschedpolicy!(3), -!pthread_attr_setschedparam!(3). +\fBsched_setscheduler\fP(2), +\fBsched_getscheduler\fP(2), +\fBsched_getparam\fP(2), +\fBpthread_attr_setschedpolicy\fP(3), +\fBpthread_attr_setschedparam\fP(3). --- a/linuxthreads/man/pthread_sigmask.man +++ b/linuxthreads/man/pthread_sigmask.man @@ -19,36 +19,36 @@ .SH DESCRIPTION -!pthread_sigmask! changes the signal mask for the calling thread as -described by the |how| and |newmask| arguments. If |oldmask| is not -!NULL!, the previous signal mask is stored in the location pointed to -by |oldmask|. - -The meaning of the |how| and |newmask| arguments is the same as for -!sigprocmask!(2). If |how| is !SIG_SETMASK!, the signal mask is set to -|newmask|. If |how| is !SIG_BLOCK!, the signals specified to |newmask| -are added to the current signal mask. If |how| is !SIG_UNBLOCK!, the -signals specified to |newmask| are removed from the current signal +\fBpthread_sigmask\fP changes the signal mask for the calling thread as +described by the \fIhow\fP and \fInewmask\fP arguments. If \fIoldmask\fP is not +\fBNULL\fP, the previous signal mask is stored in the location pointed to +by \fIoldmask\fP. + +The meaning of the \fIhow\fP and \fInewmask\fP arguments is the same as for +\fBsigprocmask\fP(2). If \fIhow\fP is \fBSIG_SETMASK\fP, the signal mask is set to +\fInewmask\fP. If \fIhow\fP is \fBSIG_BLOCK\fP, the signals specified to \fInewmask\fP +are added to the current signal mask. If \fIhow\fP is \fBSIG_UNBLOCK\fP, the +signals specified to \fInewmask\fP are removed from the current signal mask. Recall that signal masks are set on a per-thread basis, but signal -actions and signal handlers, as set with !sigaction!(2), are shared +actions and signal handlers, as set with \fBsigaction\fP(2), are shared between all threads. -!pthread_kill! send signal number |signo| to the thread -|thread|. The signal is delivered and handled as described in -!kill!(2). - -!sigwait! suspends the calling thread until one of the signals -in |set| is delivered to the calling thread. It then stores the number -of the signal received in the location pointed to by |sig| and -returns. The signals in |set| must be blocked and not ignored on -entrance to !sigwait!. If the delivered signal has a signal handler -function attached, that function is |not| called. +\fBpthread_kill\fP send signal number \fIsigno\fP to the thread +\fIthread\fP. The signal is delivered and handled as described in +\fBkill\fP(2). + +\fBsigwait\fP suspends the calling thread until one of the signals +in \fIset\fP is delivered to the calling thread. It then stores the number +of the signal received in the location pointed to by \fIsig\fP and +returns. The signals in \fIset\fP must be blocked and not ignored on +entrance to \fBsigwait\fP. If the delivered signal has a signal handler +function attached, that function is \fInot\fP called. .SH CANCELLATION -!sigwait! is a cancellation point. +\fBsigwait\fP is a cancellation point. .SH "RETURN VALUE" @@ -56,50 +56,50 @@ .SH ERRORS -The !pthread_sigmask! function returns the following error codes +The \fBpthread_sigmask\fP function returns the following error codes on error: .RS .TP -!EINVAL! -|how| is not one of !SIG_SETMASK!, !SIG_BLOCK!, or !SIG_UNBLOCK! +\fBEINVAL\fP +\fIhow\fP is not one of \fBSIG_SETMASK\fP, \fBSIG_BLOCK\fP, or \fBSIG_UNBLOCK\fP .TP -!EFAULT! -|newmask| or |oldmask| point to invalid addresses +\fBEFAULT\fP +\fInewmask\fP or \fIoldmask\fP point to invalid addresses .RE -The !pthread_kill! function returns the following error codes +The \fBpthread_kill\fP function returns the following error codes on error: .RS .TP -!EINVAL! -|signo| is not a valid signal number +\fBEINVAL\fP +\fIsigno\fP is not a valid signal number .TP -!ESRCH! -the thread |thread| does not exist (e.g. it has already terminated) +\fBESRCH\fP +the thread \fIthread\fP does not exist (e.g. it has already terminated) .RE -The !sigwait! function never returns an error. +The \fBsigwait\fP function never returns an error. .SH AUTHOR Xavier Leroy .SH "SEE ALSO" -!sigprocmask!(2), -!kill!(2), -!sigaction!(2), -!sigsuspend!(2). +\fBsigprocmask\fP(2), +\fBkill\fP(2), +\fBsigaction\fP(2), +\fBsigsuspend\fP(2). .SH NOTES -For !sigwait! to work reliably, the signals being waited for must be +For \fBsigwait\fP to work reliably, the signals being waited for must be blocked in all threads, not only in the calling thread, since otherwise the POSIX semantics for signal delivery do not guarantee -that it's the thread doing the !sigwait! that will receive the signal. +that it's the thread doing the \fBsigwait\fP that will receive the signal. The best way to achieve this is block those signals before any threads are created, and never unblock them in the program other than by -calling !sigwait!. +calling \fBsigwait\fP. .SH BUGS @@ -112,11 +112,11 @@ In LinuxThreads, each thread is actually a kernel process with its own PID, so external signals are always directed to one particular thread. -If, for instance, another thread is blocked in !sigwait! on that +If, for instance, another thread is blocked in \fBsigwait\fP on that signal, it will not be restarted. -The LinuxThreads implementation of !sigwait! installs dummy signal -handlers for the signals in |set| for the duration of the wait. Since +The LinuxThreads implementation of \fBsigwait\fP installs dummy signal +handlers for the signals in \fIset\fP for the duration of the wait. Since signal handlers are shared between all threads, other threads must not attach their own signal handlers to these signals, or alternatively they should all block these signals (which is recommended anyway -- --- a/linuxthreads/man/sem_init.man +++ b/linuxthreads/man/sem_init.man @@ -26,98 +26,98 @@ .SH DESCRIPTION This manual page documents POSIX 1003.1b semaphores, not to be -confused with SystemV semaphores as described in !ipc!(5), !semctl!(2) -and !semop!(2). +confused with SystemV semaphores as described in \fBipc\fP(5), \fBsemctl\fP(2) +and \fBsemop\fP(2). Semaphores are counters for resources shared between threads. The basic operations on semaphores are: increment the counter atomically, and wait until the counter is non-null and decrement it atomically. -!sem_init! initializes the semaphore object pointed to by |sem|. The -count associated with the semaphore is set initially to |value|. The -|pshared| argument indicates whether the semaphore is local to the -current process (|pshared| is zero) or is to be shared between several -processes (|pshared| is not zero). LinuxThreads currently does not -support process-shared semaphores, thus !sem_init! always returns with -error !ENOSYS! if |pshared| is not zero. +\fBsem_init\fP initializes the semaphore object pointed to by \fIsem\fP. The +count associated with the semaphore is set initially to \fIvalue\fP. The +\fIpshared\fP argument indicates whether the semaphore is local to the +current process (\fIpshared\fP is zero) or is to be shared between several +processes (\fIpshared\fP is not zero). LinuxThreads currently does not +support process-shared semaphores, thus \fBsem_init\fP always returns with +error \fBENOSYS\fP if \fIpshared\fP is not zero. -!sem_wait! suspends the calling thread until the semaphore pointed to -by |sem| has non-zero count. It then atomically decreases the +\fBsem_wait\fP suspends the calling thread until the semaphore pointed to +by \fIsem\fP has non-zero count. It then atomically decreases the semaphore count. -!sem_trywait! is a non-blocking variant of !sem_wait!. If the -semaphore pointed to by |sem| has non-zero count, the count is -atomically decreased and !sem_trywait! immediately returns 0. -If the semaphore count is zero, !sem_trywait! immediately returns with -error !EAGAIN!. +\fBsem_trywait\fP is a non-blocking variant of \fBsem_wait\fP. If the +semaphore pointed to by \fIsem\fP has non-zero count, the count is +atomically decreased and \fBsem_trywait\fP immediately returns 0. +If the semaphore count is zero, \fBsem_trywait\fP immediately returns with +error \fBEAGAIN\fP. -!sem_post! atomically increases the count of the semaphore pointed to -by |sem|. This function never blocks and can safely be used in +\fBsem_post\fP atomically increases the count of the semaphore pointed to +by \fIsem\fP. This function never blocks and can safely be used in asynchronous signal handlers. -!sem_getvalue! stores in the location pointed to by |sval| the current -count of the semaphore |sem|. +\fBsem_getvalue\fP stores in the location pointed to by \fIsval\fP the current +count of the semaphore \fIsem\fP. -!sem_destroy! destroys a semaphore object, freeing the resources it +\fBsem_destroy\fP destroys a semaphore object, freeing the resources it might hold. No threads should be waiting on the semaphore at the time -!sem_destroy! is called. In the LinuxThreads implementation, no -resources are associated with semaphore objects, thus !sem_destroy! +\fBsem_destroy\fP is called. In the LinuxThreads implementation, no +resources are associated with semaphore objects, thus \fBsem_destroy\fP actually does nothing except checking that no thread is waiting on the semaphore. .SH CANCELLATION -!sem_wait! is a cancellation point. +\fBsem_wait\fP is a cancellation point. .SH "ASYNC-SIGNAL SAFETY" On processors supporting atomic compare-and-swap (Intel 486, Pentium -and later, Alpha, PowerPC, MIPS II, Motorola 68k), the !sem_post! +and later, Alpha, PowerPC, MIPS II, Motorola 68k), the \fBsem_post\fP function is async-signal safe and can therefore be called from signal handlers. This is the only thread synchronization function provided by POSIX threads that is async-signal safe. On the Intel 386 and the Sparc, the current LinuxThreads -implementation of !sem_post! is not async-signal safe by lack of the +implementation of \fBsem_post\fP is not async-signal safe by lack of the required atomic operations. .SH "RETURN VALUE" -The !sem_wait! and !sem_getvalue! functions always return 0. +The \fBsem_wait\fP and \fBsem_getvalue\fP functions always return 0. All other semaphore functions return 0 on success and -1 on error, in -addition to writing an error code in !errno!. +addition to writing an error code in \fBerrno\fP. .SH ERRORS -The !sem_init! function sets !errno! to the following codes on error: +The \fBsem_init\fP function sets \fBerrno\fP to the following codes on error: .RS .TP -!EINVAL! -|value| exceeds the maximal counter value !SEM_VALUE_MAX! +\fBEINVAL\fP +\fIvalue\fP exceeds the maximal counter value \fBSEM_VALUE_MAX\fP .TP -!ENOSYS! -|pshared| is not zero +\fBENOSYS\fP +\fIpshared\fP is not zero .RE -The !sem_trywait! function sets !errno! to the following error code on error: +The \fBsem_trywait\fP function sets \fBerrno\fP to the following error code on error: .RS .TP -!EAGAIN! +\fBEAGAIN\fP the semaphore count is currently 0 .RE -The !sem_post! function sets !errno! to the following error code on error: +The \fBsem_post\fP function sets \fBerrno\fP to the following error code on error: .RS .TP -!ERANGE! -after incrementation, the semaphore value would exceed !SEM_VALUE_MAX! +\fBERANGE\fP +after incrementation, the semaphore value would exceed \fBSEM_VALUE_MAX\fP (the semaphore count is left unchanged in this case) .RE -The !sem_destroy! function sets !errno! to the following error code on error: +The \fBsem_destroy\fP function sets \fBerrno\fP to the following error code on error: .RS .TP -!EBUSY! +\fBEBUSY\fP some threads are currently blocked waiting on the semaphore. .RE @@ -125,8 +125,8 @@ Xavier Leroy .SH "SEE ALSO" -!pthread_mutex_init!(3), -!pthread_cond_init!(3), -!pthread_cancel!(3), -!ipc!(5). +\fBpthread_mutex_init\fP(3), +\fBpthread_cond_init\fP(3), +\fBpthread_cancel\fP(3), +\fBipc\fP(5).