diff options
Diffstat (limited to 'linuxthreads/man/pthread_sigmask.man')
| -rw-r--r-- | linuxthreads/man/pthread_sigmask.man | 123 |
1 files changed, 123 insertions, 0 deletions
diff --git a/linuxthreads/man/pthread_sigmask.man b/linuxthreads/man/pthread_sigmask.man new file mode 100644 index 0000000000..784161da2b --- /dev/null +++ b/linuxthreads/man/pthread_sigmask.man @@ -0,0 +1,123 @@ +.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). |