diff options
Diffstat (limited to 'linuxthreads/man')
23 files changed, 0 insertions, 2128 deletions
diff --git a/linuxthreads/man/Makefile b/linuxthreads/man/Makefile deleted file mode 100644 index 4afd2ee15d..0000000000 --- a/linuxthreads/man/Makefile +++ /dev/null @@ -1,31 +0,0 @@ -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 pthread_mutexattr_setkind_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 deleted file mode 100644 index b682bed3ac..0000000000 --- a/linuxthreads/man/pthread_atfork.man +++ /dev/null @@ -1,53 +0,0 @@ -.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. The mutexes are not usable after the -!fork! and must be initialized with |pthread_mutex_init| 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. - -.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 deleted file mode 100644 index bd5a169242..0000000000 --- a/linuxthreads/man/pthread_attr_init.man +++ /dev/null @@ -1,221 +0,0 @@ -.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 deleted file mode 100644 index 202d5c9b26..0000000000 --- a/linuxthreads/man/pthread_cancel.man +++ /dev/null @@ -1,155 +0,0 @@ -.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 deleted file mode 100644 index 1591431c9c..0000000000 --- a/linuxthreads/man/pthread_cleanup_push.man +++ /dev/null @@ -1,194 +0,0 @@ -.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_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 -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. - -!pthread_cleanup_push_defer_np! and !pthread_cleanup_pop_restore_np! -must occur in matching pairs, at the same level of block nesting. - -The following sequence - -.RS -.ft 3 -.nf -.sp -pthread_cleanup_push_defer_np(routine, arg); -... -pthread_cleanup_pop_defer_np(execute); -.ft -.LP -.RE -.fi - -is functionally equivalent to (but more compact and more efficient than) - -.RS -.ft 3 -.nf -.sp -{ int oldtype; - pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype); - pthread_cleanup_push(routine, arg); - ... - pthread_cleanup_pop(execute); - pthread_setcanceltype(oldtype, NULL); -} -.ft -.LP -.RE -.fi - -.SH "RETURN VALUE" - -None. - -.SH ERRORS - -None. - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!pthread_exit!(3), -!pthread_cancel!(3), -!pthread_setcanceltype!(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: - -.RS -.ft 3 -.nf -.sp -pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut); -pthread_mutex_lock(&mut); -/* do some work */ -pthread_mutex_unlock(&mut); -pthread_cleanup_pop(0); -.ft -.LP -.RE -.fi - -Equivalently, the last two lines can be replaced by - -.RS -.ft 3 -.nf -.sp -pthread_cleanup_pop(1); -.ft -.LP -.RE -.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 -unlock a mutex not locked by the current thread. This is the main -reason why asynchronous cancellation is difficult to use. - -If the code above must also work in asynchronous cancellation mode, -then it must switch to deferred mode for locking and unlocking the -mutex: - -.RS -.ft 3 -.nf -.sp -pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype); -pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut); -pthread_mutex_lock(&mut); -/* do some work */ -pthread_cleanup_pop(1); -pthread_setcanceltype(oldtype, NULL); -.ft -.LP -.RE -.fi - -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!: - -.RS -.ft 3 -.nf -.sp -pthread_cleanup_push_restore_np(pthread_mutex_unlock, (void *) &mut); -pthread_mutex_lock(&mut); -/* do some work */ -pthread_cleanup_pop_restore_np(1); -.ft -.LP -.RE -.fi - diff --git a/linuxthreads/man/pthread_cond_init.man b/linuxthreads/man/pthread_cond_init.man deleted file mode 100644 index 4913062fd2..0000000000 --- a/linuxthreads/man/pthread_cond_init.man +++ /dev/null @@ -1,234 +0,0 @@ -.TH PTHREAD_COND 3 LinuxThreads - -.XREF pthread_cond_signal -.XREF pthread_cond_broadcast -.XREF pthread_cond_wait -.XREF pthread_cond_timedwait -.XREF pthread_cond_destroy - -.SH NAME -pthread_cond_init, pthread_cond_destroy, pthread_cond_signal, pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait \- operations on conditions - -.SH SYNOPSIS -#include <pthread.h> - -pthread_cond_t cond = PTHREAD_COND_INITIALIZER; - -int pthread_cond_init(pthread_cond_t *cond, pthread_condattr_t *cond_attr); - -int pthread_cond_signal(pthread_cond_t *cond); - -int pthread_cond_broadcast(pthread_cond_t *cond); - -int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex); - -int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime); - -int pthread_cond_destroy(pthread_cond_t *cond); - -.SH DESCRIPTION - -A condition (short for ``condition variable'') is a synchronization -device that allows threads to suspend execution and relinquish the -processors until some predicate on shared data is satisfied. The basic -operations on conditions are: signal the condition (when the -predicate becomes true), and wait for the condition, suspending the -thread execution until another thread signals the condition. - -A condition variable must always be associated with a mutex, to avoid -the race condition where a thread prepares to wait on a condition -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 -ignored. - -Variables of type !pthread_cond_t! can also be initialized -statically, using the constant !PTHREAD_COND_INITIALIZER!. - -!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 -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|. - -!pthread_cond_wait! atomically unlocks the |mutex| (as per -!pthread_unlock_mutex!) and waits for the condition variable |cond| to -be signaled. The thread execution is suspended and does not consume -any CPU time until the condition variable is signaled. The |mutex| -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!). - -Unlocking the mutex and suspending on the condition variable is done -atomically. Thus, if all threads always acquire the mutex before -signaling the condition, this guarantees that the condition cannot be -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 -corresponds to 00:00:00 GMT, January 1, 1970. - -!pthread_cond_destroy! 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 -implementation, no resources are associated with condition variables, -thus !pthread_cond_destroy! actually does nothing except checking that -the condition has no waiting threads. - -.SH CANCELLATION - -!pthread_cond_wait! and !pthread_cond_timedwait! 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 -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 -handler may deadlock the calling thread. - -.SH "RETURN VALUE" - -All condition variable functions return 0 on success and a non-zero -error code on error. - -.SH ERRORS - -!pthread_cond_init!, !pthread_cond_signal!, !pthread_cond_broadcast!, -and !pthread_cond_wait! never return an error code. - -The !pthread_cond_timedwait! function returns the following error codes -on error: -.RS -.TP -!ETIMEDOUT! -the condition variable was not signaled until the timeout specified by -|abstime| - -.TP -!EINTR! -!pthread_cond_timedwait! was interrupted by a signal -.RE - -The !pthread_cond_destroy! function returns the following error code -on error: -.RS -.TP -!EBUSY! -some threads are currently waiting on |cond|. -.RE - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!pthread_condattr_init!(3), -!pthread_mutex_lock!(3), -!pthread_mutex_unlock!(3), -!gettimeofday!(2), -!nanosleep!(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|. - -.RS -.ft 3 -.nf -.sp -int x,y; -pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER; -pthread_cond_t cond = PTHREAD_COND_INITIALIZER; -.ft -.LP -.RE -.fi - -Waiting until |x| is greater than |y| is performed as follows: - -.RS -.ft 3 -.nf -.sp -pthread_mutex_lock(&mut); -while (x <= y) { - pthread_cond_wait(&cond, &mut); -} -/* operate on x and y */ -pthread_mutex_unlock(&mut); -.ft -.LP -.RE -.fi - -Modifications on |x| and |y| that may cause |x| to become greater than -|y| should signal the condition if needed: - -.RS -.ft 3 -.nf -.sp -pthread_mutex_lock(&mut); -/* modify x and y */ -if (x > y) pthread_cond_broadcast(&cond); -pthread_mutex_unlock(&mut); -.ft -.LP -.RE -.fi - -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!. - -To wait for |x| to becomes greater than |y| with a timeout of 5 -seconds, do: - -.RS -.ft 3 -.nf -.sp -struct timeval now; -struct timespec timeout; -int retcode; - -pthread_mutex_lock(&mut); -gettimeofday(&now); -timeout.tv_sec = now.tv_sec + 5; -timeout.tv_nsec = now.tv_usec * 1000; -retcode = 0; -while (x <= y && retcode != ETIMEDOUT) { - retcode = pthread_cond_timedwait(&cond, &mut, &timeout); -} -if (retcode == ETIMEDOUT) { - /* timeout occurred */ -} else { - /* operate on x and y */ -} -pthread_mutex_unlock(&mut); -.ft -.LP -.RE -.fi diff --git a/linuxthreads/man/pthread_condattr_init.man b/linuxthreads/man/pthread_condattr_init.man deleted file mode 100644 index f491cbedbe..0000000000 --- a/linuxthreads/man/pthread_condattr_init.man +++ /dev/null @@ -1,39 +0,0 @@ -.TH PTHREAD_CONDATTR 3 LinuxThreads - -.XREF pthread_condattr_destroy - -.SH NAME -pthread_condattr_init, pthread_condattr_destroy \- condition creation attributes - -.SH SYNOPSIS -#include <pthread.h> - -int pthread_condattr_init(pthread_condattr_t *attr); - -int pthread_condattr_destroy(pthread_condattr_t *attr); - -.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 -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, -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. - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!pthread_cond_init!(3). diff --git a/linuxthreads/man/pthread_create.man b/linuxthreads/man/pthread_create.man deleted file mode 100644 index a94004767a..0000000000 --- a/linuxthreads/man/pthread_create.man +++ /dev/null @@ -1,46 +0,0 @@ -.TH PTHREAD_CREATE 3 LinuxThreads - -.SH NAME -pthread_create \- create a new thread - -.SH SYNOPSIS -#include <pthread.h> - -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 -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 -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 -error, a non-zero error code is returned. - -.SH ERRORS -.TP -!EAGAIN! -not enough system resources to create a process for the new thread. -.TP -!EAGAIN! -more than !PTHREAD_THREADS_MAX! threads are already active. - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!pthread_exit!(3), -!pthread_join!(3), -!pthread_detach!(3), -!pthread_attr_init!(3). diff --git a/linuxthreads/man/pthread_detach.man b/linuxthreads/man/pthread_detach.man deleted file mode 100644 index 7b43f45faa..0000000000 --- a/linuxthreads/man/pthread_detach.man +++ /dev/null @@ -1,44 +0,0 @@ -.TH PTHREAD_DETACH 3 LinuxThreads - -.SH NAME -pthread_detach \- put a running thread in the detached state - -.SH SYNOPSIS -#include <pthread.h> - -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!. - -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 -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. - -.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| -.TP -!EINVAL! -the thread |th| is already in the detached state - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!pthread_create!(3), -!pthread_join!(3), -!pthread_attr_setdetachstate!(3). \ No newline at end of file diff --git a/linuxthreads/man/pthread_equal.man b/linuxthreads/man/pthread_equal.man deleted file mode 100644 index 1a0396515a..0000000000 --- a/linuxthreads/man/pthread_equal.man +++ /dev/null @@ -1,23 +0,0 @@ -.TH PTHREAD_EQUAL 3 LinuxThreads - -.SH NAME -pthread_equal \- compare two thread identifiers - -.SH SYNOPSIS -#include <pthread.h> - -int pthread_equal(pthread_t thread1, pthread_t thread2); - -.SH DESCRIPTION -!pthread_equal! 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 -same thread. Otherwise, 0 is returned. - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!pthread_self!(3). diff --git a/linuxthreads/man/pthread_exit.man b/linuxthreads/man/pthread_exit.man deleted file mode 100644 index 54751e9d05..0000000000 --- a/linuxthreads/man/pthread_exit.man +++ /dev/null @@ -1,32 +0,0 @@ -.TH PTHREAD_EXIT 3 LinuxThreads - -.SH NAME -pthread_exit \- terminate the calling thread - -.SH SYNOPSIS -#include <pthread.h> - -void pthread_exit(void *retval); - -.SH DESCRIPTION -!pthread_exit! 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 -recently pushed handler is executed first). Finalization functions for -thread-specific data are then called for all keys that have non-!NULL! -values associated with them in the calling thread (see -!pthread_key_create!(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). - -.SH "RETURN VALUE" -The !pthread_exit! function never returns. - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!pthread_create!(3), -!pthread_join!(3). diff --git a/linuxthreads/man/pthread_join.man b/linuxthreads/man/pthread_join.man deleted file mode 100644 index d587093841..0000000000 --- a/linuxthreads/man/pthread_join.man +++ /dev/null @@ -1,70 +0,0 @@ -.TH PTHREAD_JOIN 3 LinuxThreads - -.SH NAME -pthread_join \- wait for termination of another thread - -.SH SYNOPSIS -#include <pthread.h> - -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) -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). - -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 -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 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| -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 -code is returned. - -.SH ERRORS -.TP -!ESRCH! -No thread could be found corresponding to that specified by |th|. -.TP -!EINVAL! -The |th| thread has been detached. -.TP -!EINVAL! -Another thread is already waiting on termination of |th|. -.TP -!EDEADLK! -The |th| argument refers to the calling thread. - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!pthread_exit!(3), -!pthread_detach!(3), -!pthread_create!(3), -!pthread_attr_setdetachstate!(3), -!pthread_cleanup_push!(3), -!pthread_key_create!(3). diff --git a/linuxthreads/man/pthread_key_create.man b/linuxthreads/man/pthread_key_create.man deleted file mode 100644 index 6823e304c9..0000000000 --- a/linuxthreads/man/pthread_key_create.man +++ /dev/null @@ -1,151 +0,0 @@ -.TH PTHREAD_SPECIFIC 3 LinuxThreads - -.SH NAME -pthread_key_create, pthread_key_delete, pthread_setspecific, pthread_getspecific \- management of thread-specific data - -.SH SYNOPSIS -#include <pthread.h> - -int pthread_key_create(pthread_key_t *key, void (*destr_function) (void *)); - -int pthread_key_delete(pthread_key_t key); - -int pthread_setspecific(pthread_key_t key, const void *pointer); - -void * pthread_getspecific(pthread_key_t key); - -.SH DESCRIPTION - -Programs often need global or static variables that have different -values in different threads. Since threads share one memory space, -this cannot be achieved with regular variables. Thread-specific data -is the POSIX threads answer to this need. - -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 -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 *! -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! -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! -on the number of keys allocated at a given time. The value initially -associated with the returned key is !NULL! in all currently executing -threads. - -The |destr_function| argument, if not !NULL!, specifies a destructor -function associated with the key. When a thread terminates via -!pthread_exit! or by cancellation, |destr_function| 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 -which destructor functions are called at thread termination time is -unspecified. - -Before the destructor function is called, the !NULL! 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 -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! -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! -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 -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. - -!pthread_getspecific! returns the value currently associated with -|key| in the calling thread. - -.SH "RETURN VALUE" - -!pthread_key_create!, !pthread_key_delete!, and !pthread_setspecific! -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. - -!pthread_getspecific! returns the value associated with |key| on -success, and !NULL! on error. - -.SH ERRORS -!pthread_key_create! returns the following error code on error: -.RS -.TP -!EAGAIN! -!PTHREAD_KEYS_MAX! keys are already allocated -.RE - -!pthread_key_delete! and !pthread_setspecific! return the following -error code on error: -.RS -.TP -!EINVAL! -|key| is not a valid, allocated TSD key -.RE - -!pthread_getspecific! returns !NULL! if |key| is not a valid, -allocated TSD key. - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -pthread_create(3), pthread_exit(3), pthread_testcancel(3). - -.SH EXAMPLE - -The following code fragment allocates a thread-specific array of 100 -characters, with automatic reclaimation at thread exit: - -.RS -.ft 3 -.nf -.sp -/* Key for the thread-specific buffer */ -static pthread_key_t buffer_key; - -/* Once-only initialisation of the key */ -static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT; - -/* Allocate the thread-specific buffer */ -void buffer_alloc(void) -{ - pthread_once(&buffer_key_once, buffer_key_alloc); - pthread_setspecific(buffer_key, malloc(100)); -} - -/* Return the thread-specific buffer */ -char * get_buffer(void) -{ - return (char *) pthread_getspecific(buffer_key); -} - -/* Allocate the key */ -static void buffer_key_alloc() -{ - pthread_key_create(&buffer_key, buffer_destroy); -} - -/* Free the thread-specific buffer */ -static void buffer_destroy(void * buf) -{ - free(buf); -} -.ft -.LP -.RE -.fi diff --git a/linuxthreads/man/pthread_kill_other_threads_np.man b/linuxthreads/man/pthread_kill_other_threads_np.man deleted file mode 100644 index 0de42d52d5..0000000000 --- a/linuxthreads/man/pthread_kill_other_threads_np.man +++ /dev/null @@ -1,40 +0,0 @@ -.TH PTHREAD_KILL_OTHER_THREADS_NP 3 LinuxThreads - -.SH NAME -pthread_kill_other_threads_np \- terminate all threads in program except calling thread - -.SH SYNOPSIS -#include <pthread.h> - -void pthread_kill_other_threads_np(void); - -.SH DESCRIPTION -!pthread_kill_other_threads_np! 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). - -Termination of the other threads is not performed through -!pthread_cancel!(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. - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!execve!(2), -!pthread_setcancelstate!(3), -!pthread_setcanceltype!(3), -!pthread_cancel!(3). - -.SH BUGS - -According to POSIX 1003.1c, a successful !exec*! 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 -all other threads are already killed. diff --git a/linuxthreads/man/pthread_mutex_init.man b/linuxthreads/man/pthread_mutex_init.man deleted file mode 100644 index 643b007aec..0000000000 --- a/linuxthreads/man/pthread_mutex_init.man +++ /dev/null @@ -1,213 +0,0 @@ -.TH PTHREAD_MUTEX 3 LinuxThreads - -.XREF pthread_mutex_lock -.XREF pthread_mutex_unlock -.XREF pthread_mutex_trylock -.XREF pthread_mutex_destroy - -.SH NAME -pthread_mutex_init, pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock, pthread_mutex_destroy \- operations on mutexes - -.SH SYNOPSIS -#include <pthread.h> - -pthread_mutex_t fastmutex = PTHREAD_MUTEX_INITIALIZER; - -pthread_mutex_t recmutex = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP; - -pthread_mutex_t errchkmutex = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP; - -int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *mutexattr); - -int pthread_mutex_lock(pthread_mutex_t *mutex); - -int pthread_mutex_trylock(pthread_mutex_t *mutex); - -int pthread_mutex_unlock(pthread_mutex_t *mutex); - -int pthread_mutex_destroy(pthread_mutex_t *mutex); - -.SH DESCRIPTION -A mutex is a MUTual EXclusion device, and is useful for protecting -shared data structures from concurrent modifications, and implementing -critical sections and monitors. - -A mutex has two possible states: unlocked (not owned by any thread), -and locked (owned by one thread). A mutex can never be owned by two -different threads simultaneously. A thread attempting to lock a mutex -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. - -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 -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 -mutexes). - -!pthread_mutex_lock! 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 -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 -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! -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 -returns to the unlocked state. - -!pthread_mutex_trylock! behaves identically to !pthread_mutex_lock!, -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!. - -!pthread_mutex_unlock! 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 -is of the ``recursive'' kind, it decrements the locking count of the -mutex (number of !pthread_mutex_lock! 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 -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!. -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 -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 -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 -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 -thread stops executing. Consequently, threads using deferred -cancellation should never hold a mutex for extended periods of time. - -.SH "ASYNC-SIGNAL SAFETY" - -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 -handler may deadlock the calling thread. - -.SH "RETURN VALUE" - -!pthread_mutex_init! 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 -on error: -.RS -.TP -!EINVAL! -the mutex has not been properly initialized. - -.TP -!EDEADLK! -the mutex is already locked by the calling thread -(``error checking'' mutexes only). -.RE - -The !pthread_mutex_trylock! function returns the following error codes -on error: -.RS -.TP -!EBUSY! -the mutex could not be acquired because it was currently locked. - -.TP -!EINVAL! -the mutex has not been properly initialized. -.RE - -The !pthread_mutex_unlock! function returns the following error code -on error: -.RS -.TP -!EINVAL! -the mutex has not been properly initialized. - -.TP -!EPERM! -the calling thread does not own the mutex (``error checking'' mutexes only). -.RE - -The !pthread_mutex_destroy! function returns the following error code -on error: -.RS -.TP -!EBUSY! -the mutex is currently locked. -.RE - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!pthread_mutexattr_init!(3), -!pthread_mutexattr_setkind_np!(3), -!pthread_cancel!(3). - -.SH EXAMPLE - -A shared global variable |x| can be protected by a mutex as follows: - -.RS -.ft 3 -.nf -.sp -int x; -pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER; -.ft -.LP -.RE -.fi - -All accesses and modifications to |x| should be bracketed by calls to -!pthread_mutex_lock! and !pthread_mutex_unlock! as follows: - -.RS -.ft 3 -.nf -.sp -pthread_mutex_lock(&mut); -/* operate on x */ -pthread_mutex_unlock(&mut); -.ft -.LP -.RE -.fi - - diff --git a/linuxthreads/man/pthread_mutexattr_init.man b/linuxthreads/man/pthread_mutexattr_init.man deleted file mode 100644 index b838948904..0000000000 --- a/linuxthreads/man/pthread_mutexattr_init.man +++ /dev/null @@ -1,84 +0,0 @@ -.TH PTHREAD_MUTEXATTR 3 LinuxThreads - -.XREF pthread_mutexattr_destroy -.XREF pthread_mutexattr_settype -.XREF pthread_mutexattr_gettype - -.SH NAME -pthread_mutexattr_init, pthread_mutexattr_destroy, pthread_mutexattr_settype, pthread_mutexattr_gettype \- mutex creation attributes - -.SH SYNOPSIS -#include <pthread.h> - -int pthread_mutexattr_init(pthread_mutexattr_t *attr); - -int pthread_mutexattr_destroy(pthread_mutexattr_t *attr); - -int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int kind); - -int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *kind); - -.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 -all attributes set to their default values. - -!pthread_mutexattr_init! initializes the mutex attribute object |attr| -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! -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 -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 -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 -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 -returns to the unlocked state. - -The default mutex kind is ``fast'', that is, !PTHREAD_MUTEX_FAST_NP!. - -!pthread_mutexattr_settype! sets the mutex kind attribute in |attr| -to the value specified by |kind|. - -!pthread_mutexattr_gettype! retrieves the current value of the -mutex kind attribute in |attr| and stores it in the location pointed -to by |kind|. - -.SH "RETURN VALUE" -!pthread_mutexattr_init!, !pthread_mutexattr_destroy! and -!pthread_mutexattr_gettype! always return 0. - -!pthread_mutexattr_settype! returns 0 on success and a non-zero -error code on error. - -.SH ERRORS - -On error, !pthread_mutexattr_settype! returns the following error code: -.TP -!EINVAL! -|kind| is neither !PTHREAD_MUTEX_FAST_NP! nor !PTHREAD_MUTEX_RECURSIVE_NP! -nor !PTHREAD_MUTEX_ERRORCHECK_NP! - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!pthread_mutex_init!(3), -!pthread_mutex_lock!(3), -!pthread_mutex_unlock!(3). diff --git a/linuxthreads/man/pthread_mutexattr_setkind_np.man b/linuxthreads/man/pthread_mutexattr_setkind_np.man deleted file mode 100644 index e10f47d0e5..0000000000 --- a/linuxthreads/man/pthread_mutexattr_setkind_np.man +++ /dev/null @@ -1,39 +0,0 @@ -.TH PTHREAD_MUTEXATTR_SETKIND_NP 3 LinuxThreads - -.XREF pthread_mutexattr_getkind_np - -.SH NAME -pthread_mutexattr_setkind_np, pthread_mutexattr_getkind_np \- deprecated mutex creation attributes - -.SH SYNOPSIS -#include <pthread.h> - -int pthread_mutexattr_setkind_np(pthread_mutexattr_t *attr, int kind); - -int pthread_mutexattr_getkind_np(const pthread_mutexattr_t *attr, int *kind); - -.SH DESCRIPTION - -These functions are deprecated, use !pthread_mutexattr_settype!(3) -and !pthread_mutexattr_gettype!(3) instead. - -.SH "RETURN VALUE" -!pthread_mutexattr_getkind_np! always returns 0. - -!pthread_mutexattr_setkind_np! 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: -.TP -!EINVAL! -|kind| is neither !PTHREAD_MUTEX_FAST_NP! nor !PTHREAD_MUTEX_RECURSIVE_NP! -nor !PTHREAD_MUTEX_ERRORCHECK_NP! - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!pthread_mutexattr_settype!(3), -!pthread_mutexattr_gettype!(3). diff --git a/linuxthreads/man/pthread_once.man b/linuxthreads/man/pthread_once.man deleted file mode 100644 index e9d117b656..0000000000 --- a/linuxthreads/man/pthread_once.man +++ /dev/null @@ -1,34 +0,0 @@ -.TH PTHREAD_ONCE 3 LinuxThreads - -.SH NAME -pthread_once \- once-only initialization - -.SH SYNOPSIS -#include <pthread.h> - -pthread_once_t once_control = PTHREAD_ONCE_INIT; - -int pthread_once(pthread_once_t *once_control, void (*init_routine) (void)); - -.SH DESCRIPTION - -The purpose of !pthread_once! is to ensure that a piece of -initialization code is executed at most once. The |once_control| -argument points to a static or extern variable statically initialized -to !PTHREAD_ONCE_INIT!. - -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. - -.SH "RETURN VALUE" -!pthread_once! always returns 0. - -.SH ERRORS -None. - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - diff --git a/linuxthreads/man/pthread_self.man b/linuxthreads/man/pthread_self.man deleted file mode 100644 index 3aa4a0021e..0000000000 --- a/linuxthreads/man/pthread_self.man +++ /dev/null @@ -1,23 +0,0 @@ -.TH PTHREAD_SELF 3 LinuxThreads - -.SH NAME -pthread_self \- return identifier of current thread - -.SH SYNOPSIS -#include <pthread.h> - -pthread_t pthread_self(void); - -.SH DESCRIPTION -!pthread_self! return the thread identifier for the calling thread. - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!pthread_equal!(3), -!pthread_join!(3), -!pthread_detach!(3), -!pthread_setschedparam!(3), -!pthread_getschedparam!(3). - diff --git a/linuxthreads/man/pthread_setschedparam.man b/linuxthreads/man/pthread_setschedparam.man deleted file mode 100644 index 3992927837..0000000000 --- a/linuxthreads/man/pthread_setschedparam.man +++ /dev/null @@ -1,79 +0,0 @@ -.TH PTHREAD_SETSCHEDPARAM 3 LinuxThreads - -.XREF pthread_getschedparam - -.SH NAME -pthread_setschedparam, pthread_getschedparam \- control thread scheduling parameters - -.SH SYNOPSIS -#include <pthread.h> - -int pthread_setschedparam(pthread_t target_thread, int policy, const struct sched_param *param); - -int pthread_getschedparam(pthread_t target_thread, int *policy, struct sched_param *param); - -.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 -scheduling policies. - -The realtime scheduling policies !SCHED_RR! and !SCHED_FIFO! 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. - -.SH "RETURN VALUE" -!pthread_setschedparam! and !pthread_getschedparam! return 0 on -success and a non-zero error code on error. - -.SH ERRORS -On error, !pthread_setschedparam! returns the following error codes: -.RS -.TP -!EINVAL! -|policy| is not one of !SCHED_OTHER!, !SCHED_RR!, !SCHED_FIFO! - -.TP -!EINVAL! -the priority value specified by |param| is not valid for the specified policy - -.TP -!EPERM! -the calling process does not have superuser permissions - -.TP -!ESRCH! -the |target_thread| is invalid or has already terminated - -.TP -!EFAULT! -|param| points outside the process memory space -.RE - -On error, !pthread_getschedparam! returns the following error codes: -.RS -.TP -!ESRCH! -the |target_thread| is invalid or has already terminated - -.TP -!EFAULT! -|policy| or |param| point outside the process memory space -.RE - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!sched_setscheduler!(2), -!sched_getscheduler!(2), -!sched_getparam!(2), -!pthread_attr_setschedpolicy!(3), -!pthread_attr_setschedparam!(3). diff --git a/linuxthreads/man/pthread_sigmask.man b/linuxthreads/man/pthread_sigmask.man deleted file mode 100644 index 784161da2b..0000000000 --- a/linuxthreads/man/pthread_sigmask.man +++ /dev/null @@ -1,123 +0,0 @@ -.TH PTHREAD_SIGNAL 3 LinuxThreads - -.XREF pthread_kill -.XREF sigwait - -.SH NAME -pthread_sigmask, pthread_kill, sigwait \- handling of signals in threads - -.SH SYNOPSIS -#include <pthread.h> -.br -#include <signal.h> - -int pthread_sigmask(int how, const sigset_t *newmask, sigset_t *oldmask); - -int pthread_kill(pthread_t thread, int signo); - -int sigwait(const sigset_t *set, int *sig); - -.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 -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 -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. - -.SH CANCELLATION - -!sigwait! is a cancellation point. - -.SH "RETURN VALUE" - -On success, 0 is returned. On failure, a non-zero error code is returned. - -.SH ERRORS - -The !pthread_sigmask! function returns the following error codes -on error: -.RS -.TP -!EINVAL! -|how| is not one of !SIG_SETMASK!, !SIG_BLOCK!, or !SIG_UNBLOCK! - -.TP -!EFAULT! -|newmask| or |oldmask| point to invalid addresses -.RE - -The !pthread_kill! function returns the following error codes -on error: -.RS -.TP -!EINVAL! -|signo| is not a valid signal number - -.TP -!ESRCH! -the thread |thread| does not exist (e.g. it has already terminated) -.RE - -The !sigwait! function never returns an error. - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!sigprocmask!(2), -!kill!(2), -!sigaction!(2), -!sigsuspend!(2). - -.SH NOTES - -For !sigwait! 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. -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!. - -.SH BUGS - -Signal handling in LinuxThreads departs significantly from the POSIX -standard. According to the standard, ``asynchronous'' (external) -signals are addressed to the whole process (the collection of all -threads), which then delivers them to one particular thread. The -thread that actually receives the signal is any thread that does -not currently block the signal. - -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 -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 -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 -- -see the Notes section). diff --git a/linuxthreads/man/sem_init.man b/linuxthreads/man/sem_init.man deleted file mode 100644 index e3a1a63e36..0000000000 --- a/linuxthreads/man/sem_init.man +++ /dev/null @@ -1,132 +0,0 @@ -.TH SEMAPHORES 3 LinuxThreads - -.XREF sem_wait -.XREF sem_trywait -.XREF sem_post -.XREF sem_getvalue -.XREF sem_destroy - -.SH NAME -sem_init, sem_wait, sem_trywait, sem_post, sem_getvalue, sem_destroy \- operations on semaphores - -.SH SYNOPSIS -#include <semaphore.h> - -int sem_init(sem_t *sem, int pshared, unsigned int value); - -int sem_wait(sem_t * sem); - -int sem_trywait(sem_t * sem); - -int sem_post(sem_t * sem); - -int sem_getvalue(sem_t * sem, int * sval); - -int sem_destroy(sem_t * sem); - -.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). - -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. - -!sem_wait! suspends the calling thread until the semaphore pointed to -by |sem| 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!. - -!sem_post! atomically increases the count of the semaphore pointed to -by |sem|. 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|. - -!sem_destroy! 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! -actually does nothing except checking that no thread is waiting on the -semaphore. - -.SH CANCELLATION - -!sem_wait! 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! -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 -required atomic operations. - -.SH "RETURN VALUE" - -The !sem_wait! and !sem_getvalue! 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!. - -.SH ERRORS - -The !sem_init! function sets !errno! to the following codes on error: -.RS -.TP -!EINVAL! -|value| exceeds the maximal counter value !SEM_VALUE_MAX! -.TP -!ENOSYS! -|pshared| is not zero -.RE - -The !sem_trywait! function sets !errno! to the following error code on error: -.RS -.TP -!EAGAIN! -the semaphore count is currently 0 -.RE - -The !sem_post! function sets !errno! to the following error code on error: -.RS -.TP -!ERANGE! -after incrementation, the semaphore value would exceed !SEM_VALUE_MAX! -(the semaphore count is left unchanged in this case) -.RE - -The !sem_destroy! function sets !errno! to the following error code on error: -.RS -.TP -!EBUSY! -some threads are currently blocked waiting on the semaphore. -.RE - -.SH AUTHOR -Xavier Leroy <Xavier.Leroy@inria.fr> - -.SH "SEE ALSO" -!pthread_mutex_init!(3), -!pthread_cond_init!(3), -!pthread_cancel!(3), -!ipc!(5). - diff --git a/linuxthreads/man/troffprepro b/linuxthreads/man/troffprepro deleted file mode 100755 index ba564fefbe..0000000000 --- a/linuxthreads/man/troffprepro +++ /dev/null @@ -1,68 +0,0 @@ -#!/usr/local/bin/perl - -$insynopsis = 0; - -open(INPUT, $ARGV[0]) || die("cannot open $ARGV[0]"); -open(OUTPUT, "> $ARGV[1]") || die("cannot create $ARGV[1]"); - -select(OUTPUT); - -line: -while(<INPUT>) { - if (/^\.XREF (.*)$/) { - $xref = $1; - $_ = $ARGV[1]; - m/^.*\.(([1-8]).*)$/; - $suffix = $1; - $extension = $2; - open(XREF, "> $xref.$suffix"); - print XREF ".so man$extension/$ARGV[1]\n"; - close(XREF); - next line; - } - if (/^\.SH/) { - $insynopsis = /SYNOPSIS/; - print $_; - next; - } - if ($insynopsis) { - if (/^#/) { - print ".B ", $_; - } - elsif (/^[a-z]/) { - chop; -# if (m/^([a-zA-Z][a-zA-Z0-9_]*\s+[a-zA-Z][a-zA-Z0-9_]*)\(/) { -# print ".B \"", $1, "\"\n"; -# $_ = '(' . $'; -# } -# s/([a-zA-Z][a-zA-Z0-9_]*)(\s*[,()=])/" \1 "\2/g; - s/([ *])([a-zA-Z][a-zA-Z0-9_]*)(\s*[,)=])/\1" \2 "\3/g; - print ".BI \"", $_, "\"\n"; - } - else { - print $_; - } - next; - } - chop; - s/!([^!]+)!\|([^|]+)\|([^\s]*)\s*/\n.BI "\1" "\2\3"\n/g; - s/([!|])([^!|]+)\1([^\s]*)\s*/do subst($1,$2,$3)/eg; - s/^\n+//; - s/\n+$//; - s/\n\n+/\n/g; - print $_, "\n"; -} - -close(INPUT); -close(OUTPUT); - -sub subst { - local ($a, $b, $c) = @_; - if ($c) { - "\n" . ($a eq "!" ? ".BR " : ".IR ") . "\"$b\" $c\n" - } else { - "\n" . ($a eq "!" ? ".B " : ".I ") . "\"$b\"\n" - } -} - - |