diff options
Diffstat (limited to 'linuxthreads/man')
22 files changed, 2095 insertions, 0 deletions
diff --git a/linuxthreads/man/Makefile b/linuxthreads/man/Makefile new file mode 100644 index 0000000000..4875c3d765 --- /dev/null +++ b/linuxthreads/man/Makefile @@ -0,0 +1,31 @@ +SOURCES=pthread_atfork.man pthread_attr_init.man pthread_cancel.man \ + pthread_cleanup_push.man pthread_cond_init.man \ + pthread_condattr_init.man pthread_create.man pthread_detach.man \ + pthread_equal.man pthread_exit.man pthread_join.man \ + pthread_key_create.man pthread_mutex_init.man \ + pthread_mutexattr_init.man pthread_once.man pthread_self.man \ + pthread_setschedparam.man pthread_sigmask.man sem_init.man \ + pthread_kill_other_threads_np.man + +MANPAGES=$(SOURCES:.man=.3thr) + +PREPRO=perl troffprepro + +MANDIR=/usr/man/man3 + +all: $(MANPAGES) + +.SUFFIXES: .man .3thr + +.man.3thr: + $(PREPRO) $*.man $*.3thr + +$(MANPAGES): troffprepro + +clean: + rm -f *.3thr + rm -f *~ + +install: + install *.3thr $(MANDIR) + @echo "*** Remember to run /usr/sbin/makewhatis `dirname $(MANDIR)` at some point" diff --git a/linuxthreads/man/pthread_atfork.man b/linuxthreads/man/pthread_atfork.man new file mode 100644 index 0000000000..4d06a56f8b --- /dev/null +++ b/linuxthreads/man/pthread_atfork.man @@ -0,0 +1,58 @@ +.TH PTHREAD_ATFORK 3 LinuxThreads + +.SH NAME +pthread_atfork \- register handlers to be called at fork(2) time + +.SH SYNOPSIS +#include <pthread.h> + +int pthread_atfork(void (*prepare)(void), void (*parent)(void), void (*child)(void)); + +.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| +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. + +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 +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 +(first added, first called). + +To understand the purpose of !pthread_atfork!, recall that !fork!(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. Thus, if a mutex is locked by a thread +other than the thread calling !fork!, that mutex will remain locked +forever in the child process, possibly blocking the execution of the +child process. To avoid this, install handlers with !pthread_atfork! +as follows: the |prepare| handler locks the global mutexes (in locking +order), and the |parent| and |child| handlers unlock them (in +reverse order). Alternatively, |prepare| and |parent| can be set to +!NULL! and |child| to a function that calls !pthread_mutex_init! on +the global mutexes. + +.SH "RETURN VALUE" + +!pthread_atfork! returns 0 on success and a non-zero error code on error. + +.SH ERRORS +.TP +!ENOMEM! +insufficient memory available to register the handlers. + +.SH AUTHOR +Xavier Leroy <Xavier.Leroy@inria.fr> + +.SH "SEE ALSO" +!fork!(2), +!pthread_mutex_lock!(3), +!pthread_mutex_unlock!(3). diff --git a/linuxthreads/man/pthread_attr_init.man b/linuxthreads/man/pthread_attr_init.man new file mode 100644 index 0000000000..bd5a169242 --- /dev/null +++ b/linuxthreads/man/pthread_attr_init.man @@ -0,0 +1,221 @@ +.TH PTHREAD_ATTR_INIT 3 LinuxThreads + +.XREF pthread_attr_destroy +.XREF pthread_attr_setdetachstate +.XREF pthread_attr_getdetachstate +.XREF pthread_attr_setschedparam +.XREF pthread_attr_getschedparam +.XREF pthread_attr_setschedpolicy +.XREF pthread_attr_getschedpolicy +.XREF pthread_attr_setinheritsched +.XREF pthread_attr_getinheritsched +.XREF pthread_attr_setscope +.XREF pthread_attr_getscope + +.SH NAME +pthread_attr_init, pthread_attr_destroy, pthread_attr_setdetachstate, pthread_attr_getdetachstate, pthread_attr_setschedparam, pthread_attr_getschedparam, pthread_attr_setschedpolicy, pthread_attr_getschedpolicy, pthread_attr_setinheritsched, pthread_attr_getinheritsched, pthread_attr_setscope, pthread_attr_getscope \- thread creation attributes + +.SH SYNOPSIS +#include <pthread.h> + +int pthread_attr_init(pthread_attr_t *attr); + +int pthread_attr_destroy(pthread_attr_t *attr); + +int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate); + +int pthread_attr_getdetachstate(const pthread_attr_t *attr, int *detachstate); + +int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy); + +int pthread_attr_getschedpolicy(const pthread_attr_t *attr, int *policy); + +int pthread_attr_setschedparam(pthread_attr_t *attr, const struct sched_param *param); + +int pthread_attr_getschedparam(const pthread_attr_t *attr, struct sched_param *param); + +int pthread_attr_setinheritsched(pthread_attr_t *attr, int inherit); + +int pthread_attr_getinheritsched(const pthread_attr_t *attr, int *inherit); + +int pthread_attr_setscope(pthread_attr_t *attr, int scope); + +int pthread_attr_getscope(const pthread_attr_t *attr, int *scope); + +.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 +passing a thread attribute object with all attributes set to their +default values. + +!pthread_attr_init! initializes the thread attribute object |attr| 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|. + +!pthread_attr_destroy! destroys a thread attribute object, which +must not be reused until it is reinitialized. !pthread_attr_destroy! +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 +previously created. + +The following thread attributes are supported: + +.SS detachstate + +Control whether the thread is created in the joinable state (value +!PTHREAD_CREATE_JOINABLE!) or in the detached state +(!PTHREAD_CREATE_DETACHED!). + +Default value: !PTHREAD_CREATE_JOINABLE!. + +In the joinable state, another thread can synchronize on the thread +termination and recover its termination code using !pthread_join!(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. + +In the detached state, the thread resources are immediately freed when +it terminates, but !pthread_join!(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). + +.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. + +Default value: !SCHED_OTHER!. + +The realtime scheduling policies !SCHED_RR! and !SCHED_FIFO! are +available only to processes with superuser privileges. + +The scheduling policy of a thread can be changed after creation with +!pthread_setschedparam!(3). + +.SS schedparam + +Contain the scheduling parameters (essentially, the scheduling +priority) for the thread. See !sched_setparam!(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!. + +The scheduling priority of a thread can be changed after creation with +!pthread_setschedparam!(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!). + +Default value: !PTHREAD_EXPLICIT_SCHED!. + +.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 +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 +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. + +Default value: !PTHREAD_SCOPE_SYSTEM!. + +.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 +by their second argument. + +.SH ERRORS + +The !pthread_attr_setdetachstate! 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!. +.RE + +The !pthread_attr_setschedparam! 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!). +.RE + +The !pthread_attr_setschedpolicy! 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!. + +.TP +!ENOTSUP! +|policy| is !SCHED_FIFO! or !SCHED_RR!, and the effective user of the +calling process is not super-user. +.RE + +The !pthread_attr_setinheritsched! 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!. +.RE + +The !pthread_attr_setscope! 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!. + +.TP +!ENOTSUP! +the specified |scope| is !PTHREAD_SCOPE_PROCESS! (not supported). +.RE + +.SH AUTHOR +Xavier Leroy <Xavier.Leroy@inria.fr> + +.SH "SEE ALSO" +!pthread_create!(3), +!pthread_join!(3), +!pthread_detach!(3), +!pthread_setschedparam!(3). diff --git a/linuxthreads/man/pthread_cancel.man b/linuxthreads/man/pthread_cancel.man new file mode 100644 index 0000000000..202d5c9b26 --- /dev/null +++ b/linuxthreads/man/pthread_cancel.man @@ -0,0 +1,155 @@ +.TH PTHREAD_CANCEL 3 LinuxThreads + +.XREF pthread_setcancelstate +.XREF pthread_setcanceltype +.XREF pthread_testcancel + +.SH NAME +pthread_cancel, pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel \- thread cancellation + +.SH SYNOPSIS +#include <pthread.h> + +int pthread_cancel(pthread_t thread); + +int pthread_setcancelstate(int state, int *oldstate); + +int pthread_setcanceltype(int type, int *oldtype); + +void pthread_testcancel(void); + +.SH DESCRIPTION + +Cancellation is the mechanism by which a thread can terminate the +execution of another thread. More precisely, a thread can send a +cancellation request to another thread. Depending on its settings, the +target thread can then either ignore the request, honor it +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: +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. + +!pthread_cancel! sends a cancellation request to the thread denoted +by the |thread| argument. + +!pthread_setcancelstate! 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|, +and can thus be restored later by another call to +!pthread_setcancelstate!. + +!pthread_setcanceltype! 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 +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|, +and can thus be restored later by another call to +!pthread_setcanceltype!. + +Threads are always created by !pthread_create!(3) with cancellation +enabled and deferred. That is, the initial cancellation state is +!PTHREAD_CANCEL_ENABLE! and the initial type is +!PTHREAD_CANCEL_DEFERRED!. + +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) +.br +!pthread_cond_wait!(3) +.br +!pthread_cond_timedwait!(3) +.br +!pthread_testcancel!(3) +.br +!sem_wait!(3) +.br +!sigwait!(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 +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 +on error. + +.SH ERRORS +!pthread_cancel! returns the following error code on error: +.RS +.TP +!ESRCH! +no thread could be found corresponding to that specified by the |thread| ID. +.RE + +!pthread_setcancelstate! returns the following error code on error: +.RS +.TP +!EINVAL! +the |state| argument is not !PTHREAD_CANCEL_ENABLE! nor +!PTHREAD_CANCEL_DISABLE! +.RE + +!pthread_setcanceltype! returns the following error code on error: +.RS +.TP +!EINVAL! +the |type| argument is not !PTHREAD_CANCEL_DEFERRED! nor +!PTHREAD_CANCEL_ASYNCHRONOUS! +.RE + +.SH AUTHOR +Xavier Leroy <Xavier.Leroy@inria.fr> + +.SH "SEE ALSO" +!pthread_exit!(3), +!pthread_cleanup_push!(3), +!pthread_cleanup_pop!(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), +etc.) and library functions that may call these system calls (e.g. +!fprintf!(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 +achieved as follows: + +.RS +.ft 3 +.nf +.sp +pthread_testcancel(); +retcode = read(fd, buffer, length); +pthread_testcancel(); +.ft +.LP +.RE +.fi diff --git a/linuxthreads/man/pthread_cleanup_push.man b/linuxthreads/man/pthread_cleanup_push.man new file mode 100644 index 0000000000..1591431c9c --- /dev/null +++ b/linuxthreads/man/pthread_cleanup_push.man @@ -0,0 +1,194 @@ +.TH PTHREAD_CLEANUP 3 LinuxThreads + +.XREF pthread_cleanup_pop +.XREF pthread_cleanup_push_defer_np +.XREF pthread_cleanup_pop_restore_np + +.SH NAME +pthread_cleanup_push, pthread_cleanup_pop, pthread_cleanup_push_defer_np, pthread_cleanup_pop_restore_np \- install and remove cleanup handlers + +.SH SYNOPSIS +#include <pthread.h> + +void pthread_cleanup_push(void (*routine) (void *), void *arg); + +void pthread_cleanup_pop(int execute); + +void pthread_cleanup_push_defer_np(void (*routine) (void *), void *arg); + +void pthread_cleanup_pop_restore_np(int execute); + +.SH DESCRIPTION + +Cleanup handlers are functions that get called when a thread +terminates, either by calling !pthread_exit!(3) or because of +cancellation. Cleanup handlers are installed and removed following a +stack-like discipline. + +The purpose of cleanup handlers is to free the resources that a thread +may hold at the time it terminates. In particular, if a thread +exits or is cancelled while it owns a locked mutex, the mutex will +remain locked forever and prevent other threads from executing +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. + +!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) +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 +executed. + +Matching pairs of !pthread_cleanup_push! and !pthread_cleanup_pop! +must occur in the same function, at the same level of block nesting. +Actually, !pthread_c |