From 00161f1ba6f1c2a4168c305886e6ff7e3a93f5ea Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Thu, 15 Sep 2005 11:47:39 +0000 Subject: [PATCH] Split sigpending(), sigprocmask(), and sigsuspend() out into separate new pages. Other minor changes NOTES: described SA_NODER / sa_mask bug which was present in all kernels up to and including 2.6.13. See http://marc.theaimsgroup.com/?l=linux-kernel&m=112360948603171&w=2 and http://marc.theaimsgroup.com/?l=linux-kernel&m=112362164911432&w=2 List: linux-kernel Subject: Signal handling possibly wrong From: Bodo Stroesser Date: 2005-08-09 17:44:06 --- man2/sigaction.2 | 126 ++++++++++++++++------------------------------- 1 file changed, 42 insertions(+), 84 deletions(-) diff --git a/man2/sigaction.2 b/man2/sigaction.2 index 63b775d68..3de0ad1b9 100644 --- a/man2/sigaction.2 +++ b/man2/sigaction.2 @@ -1,5 +1,6 @@ '\" t .\" Copyright (c) 1994,1995 Mike Battersby +.\" and 2004, 2005 Michael Kerrisk .\" based on work by faith@cs.unc.edu .\" .\" Permission is granted to make and distribute verbatim copies of this @@ -36,23 +37,17 @@ .\" Updated discussion for POSIX.1-2001 and SIGCHLD and sa_flags. .\" Formatting fixes .\" 2004-12-09, mtk, added SI_TKILL + other minor changes +.\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend() +.\" out of this page into separate pages. .\" -.TH SIGACTION 2 2004-11-11 "Linux 2.6.9" "Linux Programmer's Manual" +.TH SIGACTION 2 2005-09-15 "Linux 2.6.14" "Linux Programmer's Manual" .SH NAME -sigaction, sigprocmask, sigpending, sigsuspend \- -POSIX signal handling API +sigaction \- examine and change a signal action .SH SYNOPSIS .B #include -.sp 2 +.sp .BI "int sigaction(int " signum ", const struct sigaction *" act , .BI "struct sigaction *" oldact ); -.sp -.BI "int sigprocmask(int " how ", const sigset_t *" set , -.BI "sigset_t *" oldset ); -.sp -.BI "int sigpending(sigset_t *" set ); -.sp -.BI "int sigsuspend(const sigset_t *" mask ); .SH DESCRIPTION The .BR sigaction () @@ -114,8 +109,15 @@ for the default action, to ignore this signal, or a pointer to a signal handling function. This function receives the signal number as its only argument. .PP +If +.B SA_SIGINFO +is specified in +.IR sa_flags , +then .I sa_sigaction -also specifies the action to be associated with +(instead of +.IR sa_handler ) +specifies the signal-handling function for .IR signum . This function receives the signal number as its first argument, a pointer to a @@ -355,80 +357,21 @@ POLL_PRI:high priority input available POLL_HUP:device disconnected .TE -.PP -The -.BR sigprocmask () -call is used to change the list of currently blocked signals. The -behaviour of the call is dependent on the value of -.IR how , -as follows. -.RS -.TP -.B SIG_BLOCK -The set of blocked signals is the union of the current set and the -.I set -argument. -.TP -.B SIG_UNBLOCK -The signals in -.I set -are removed from the current set of blocked signals. It is legal to -attempt to unblock a signal which is not blocked. -.TP -.B SIG_SETMASK -The set of blocked signals is set to the argument -.IR set . -.RE -.PP -If -.I oldset -is non\-null, the previous value of the signal mask is stored in -.IR oldset . -.PP -The -.BR sigpending () -call allows the examination of pending signals (ones which have been -raised while blocked). The signal mask of pending signals is stored -in -.IR set . -.PP -The -.BR sigsuspend () -call temporarily replaces the signal mask for the process with that -given by -.I mask -and then suspends the process until a signal is received. - .SH "RETURN VALUE" -.BR sigaction (), -.BR sigprocmask (), -and -.BR sigpending () -return 0 on success and \-1 on error. -.BR sigsuspend () -always returns \-1, normally with the error -.BR EINTR . - +.BR sigaction () +returns 0 on success and \-1 on error. .SH ERRORS .TP .B EFAULT -.IR act ", " oldact ", " set ", " oldset -or -.I mask -point to memory which is not a valid part of the process address space. -.TP -.B EINTR -System call was interrupted. +.IR act " or " oldact +points to memory which is not a valid part of the process address space. .TP .B EINVAL An invalid signal was specified. This will also be generated if an attempt is made to change the action for .BR SIGKILL " or " SIGSTOP ", " -which cannot be caught. +which cannot be caught or ignored. .SH NOTES -It is not possible to block -.BR SIGKILL " or " SIGSTOP -with the sigprocmask call. Attempts to do so will be silently ignored. .PP According to POSIX, the behaviour of a process is undefined after it ignores a @@ -493,24 +436,37 @@ allowed the receipt of any signal, not just the one we are installing (effectively overriding any .I sa_mask settings). -.PP -.\" FIXME What "library" is being referred to in the following sentence? -The -.BR SA_RESETHAND " and " SA_NODEFER -names for SVr4 compatibility are present only in library versions 3.0.9 -and greater. +.\".PP +.\"The +.\".BR SA_RESETHAND " and " SA_NODEFER +.\"names for SVr4 compatibility are present only in library versions 3.0.9 +.\"and greater. .PP .BR sigaction () can be called with a null second argument to query the current signal handler. It can also be used to check whether a given signal is valid for the current machine by calling it with null second and third arguments. .PP +It is not possible to block +.BR SIGKILL " or " SIGSTOP +(by specifying them in +.IR sa_mask ). +Attempts to do so are silently ignored. +.PP See .BR sigsetops (3) for details on manipulating signal sets. +.SH BUGS +In kernels up to and including 2.6.13, specifying +.B SA_NODEFER +in +.I sa_flags +preventing not only the delivered signal from being masked during +execution of the handler, but also the signals specified in +.IR sa_mask . +This bug is was fixed in kernel 2.6.14. .SH "CONFORMING TO" POSIX, SVr4. SVr4 does not document the EINTR condition. - .SH UNDOCUMENTED Before the introduction of .B SA_SIGINFO @@ -521,14 +477,16 @@ with second argument of type .IR "struct sigcontext". See the relevant kernel sources for details. This use is obsolete now. - .SH "SEE ALSO" .BR kill (1), .BR kill (2), .BR pause (2), .BR sigaltstack (2), .BR signal (2), +.BR sigpending (2), +.BR sigprocmask (2), .BR sigqueue (2), +.BR sigsuspend (2), .BR sigvec (2), .BR wait (2), .BR killpg (3),