1SIGACTION(2)                  System Calls Manual                 SIGACTION(2)
2
3
4

NAME

6       sigaction - software signal facilities
7

SYNOPSIS

9       #include <signal.h>
10
11       struct sigaction {
12            int     (*sa_handler)();
13            sigset_t sa_mask;
14            int   sa_flags;
15       };
16
17       sigaction(sig, act, oact)
18       int sig;
19       struct sigaction *act;
20       struct sigaction *oact;
21

DESCRIPTION

23       The system defines a set of signals that may be delivered to a process.
24       Signal delivery resembles the occurrence of a hardware  interrupt:  the
25       signal  is blocked from further occurrence, the current process context
26       is saved, and a new one is built.  A process may specify a  handler  to
27       which a signal is delivered, or specify that a signal is to be ignored.
28       A process may also specify that a default action is to be taken by  the
29       system  when  a  signal occurs.  A signal may also be blocked, in which
30       case its delivery is postponed until it is unblocked.  The action to be
31       taken  on  delivery  is  determined at the time of delivery.  Normally,
32       signal handlers execute on the current stack of the process.  This  may
33       be changed, on a per-handler basis, so that signals are taken on a spe‐
34       cial signal stack.
35
36       Signal routines execute with the signal that  caused  their  invocation
37       blocked, but other signals may yet occur.  A global signal mask defines
38       the set of signals currently blocked from delivery to a  process.   The
39       signal  mask for a process is initialized from that of its parent (nor‐
40       mally empty).  It may be changed with a sigprocmask(2) call, or when  a
41       signal is delivered to the process.
42
43       When  a signal condition arises for a process, the signal is added to a
44       set of signals pending for the process.  If the signal is not currently
45       blocked  by  the  process then it is delivered to the process.  Signals
46       may be delivered any time a process enters the operating system  (e.g.,
47       during a system call, page fault or trap, or clock interrupt).  If mul‐
48       tiple signals are ready to be delivered at the same time,  any  signals
49       that  could be caused by traps are delivered first.  Additional signals
50       may be processed at the same time, with each appearing to interrupt the
51       handlers for the previous signals before their first instructions.  The
52       set of pending signals is returned by the sigpending(2) function.  When
53       a  caught  signal  is  delivered,  the  current state of the process is
54       saved, a new signal mask is calculated (as described  below),  and  the
55       signal handler is invoked.  The call to the handler is arranged so that
56       if the signal handling routine returns normally the process will resume
57       execution  in  the  context  from before the signal's delivery.  If the
58       process wishes to resume in a different context, then it  must  arrange
59       to restore the previous context itself.
60
61       When  a signal is delivered to a process a new signal mask is installed
62       for the duration of the process' signal handler (or until a sigprocmask
63       call  is made).  This mask is formed by taking the union of the current
64       signal mask set, the signal to be delivered, and the signal mask  asso‐
65       ciated with the handler to be invoked.
66
67       Sigaction assigns an action for a specific signal.  If act is non-zero,
68       it specifies an action (SIG_DFL, SIG_IGN, or  a  handler  routine)  and
69       mask  to be used when delivering the specified signal.  If oact is non-
70       zero, the previous handling information for the signal is  returned  to
71       the user.
72
73       Once  a signal handler is installed, it remains installed until another
74       sigaction call is made, or an execve(2) is  performed.   A  signal-spe‐
75       cific  default  action  may  be reset by setting sa_handler to SIG_DFL.
76       The defaults are process  termination,  possibly  with  core  dump;  no
77       action;  stopping the process; or continuing the process.  See the sig‐
78       nal list below for each signal's  default  action.   If  sa_handler  is
79       SIG_DFL,  the  default  action for the signal is to discard the signal,
80       and if a signal is pending, the pending signal is discarded even if the
81       signal  is masked.  If sa_handler is set to SIG_IGN current and pending
82       instances of the signal are ignored and discarded.
83
84       Options may be specified by setting sa_flags.  If the SA_NOCLDSTOP  bit
85       is  set when installing a catching function for the SIGCHLD signal, the
86       SIGCHLD signal will be generated only when a child process  exits,  not
87       when  a  child process stops.  Further, if the SA_ONSTACK bit is set in
88       sa_flags, the system will deliver the signal to the process on a signal
89       stack, specified with sigstack(2).
90
91       If  a  signal  is caught during the system calls listed below, the call
92       may be forced to terminate with the error EINTR, the  call  may  return
93       with  a  data  transfer  shorter  than  requested,  or  the call may be
94       restarted.  Restart of  pending  calls  is  requested  by  setting  the
95       SA_RESTART bit in sa_flags.  The affected system calls include open(2),
96       read(2), write(2), sendto(2), recvfrom(2), sendmsg(2) and recvmsg(2) on
97       a  communications channel or a slow device (such as a terminal, but not
98       a regular file) and during a wait(2) or ioctl(2).  However, calls  that
99       have  already committed are not restarted, but instead return a partial
100       success (for example, a short read count).
101
102       After a fork(2) or vfork(2) all signals, the signal  mask,  the  signal
103       stack, and the restart/interrupt flags are inherited by the child.
104
105       Execve(2)  reinstates  the  default  action  for all signals which were
106       caught and resets all signals to be caught on the user stack.   Ignored
107       signals  remain ignored; the signal mask remains the same; signals that
108       restart pending system calls continue to do so.
109
110       The following is a list of all signals with names  as  in  the  include
111       file <signal.h>:
112
113            NAME       Action      Description
114            SIGHUP     terminate   terminal line hangup
115            SIGINT     terminate   interrupt program
116            SIGQUIT    core        quit program
117            SIGILL     core        illegal instruction
118            SIGTRAP    core        trace trap
119            SIGIOT     core        abort(2) call (same as SIGABRT)
120            SIGEMT     core        emulate instruction executed
121            SIGFPE     core        floating-point exception
122            SIGKILL    terminate   kill program
123            SIGBUS     core        bus error
124            SIGSEGV    core        segmentation violation
125            SIGSYS     core        system call given invalid argument
126            SIGPIPE    terminate   write on a pipe with no reader
127            SIGALRM    terminate   real-time timer expired
128            SIGTERM    terminate   software termination signal
129            SIGURG     discard     urgent condition present on socket
130            SIGSTOP    stop        stop (cannot be caught or ignored)
131            SIGTSTP    stop        stop generated from keyboard
132            SIGCONT    discard     continue after stop
133            SIGCHLD    discard     child status has changed
134            SIGTTIN    stop        background read attempted on control termi‐
135            nal
136            SIGTTOU    stop        background write attemped to control termi‐
137            nal
138            SIGIO      discard     I/O   is  possible  on  a  descriptor  (see
139            fcntl(2))
140            SIGXCPU    terminate   cpu time limit exceeded (see setrlimit(2))
141            SIGXFSZ    terminate   file size limit exceeded (see setrlimit(2))
142            SIGVTALRM  terminate   virtual time alarm (see setitimer(2))
143            SIGPROF    terminate   profiling timer alarm (see setitimer(2))
144            SIGWINCH   discard     Window size change
145            SIGINFO    discard     status request from keyboard
146            SIGUSR1    terminate   User defined signal 1
147            SIGUSR2    terminate   User defined signal 2
148

NOTE

150       The mask specified in act is not allowed to block SIGKILL  or  SIGSTOP.
151       This is done silently by the system.
152

RETURN VALUES

154       A  0  value indicated that the call succeeded.  A -1 return value indi‐
155       cates an error occurred and errno is set to indicated the reason.
156

EXAMPLE

158       The handler routine can be declared:
159
160       int handler(sig, code, scp)
161       int sig, code;
162       struct sigcontext *scp;
163
164       Here sig is the signal number, into which the hardware faults and traps
165       are  mapped.  Code is a parameter that is either a constant or the code
166       provided by the hardware.  Scp is a pointer to the sigcontext structure
167       (defined  in  <signal.h>,  used  to restore the context from before the
168       signal.
169

ERRORS

171       Sigaction will fail and no new signal handler will be installed if  one
172       of the following occurs:
173
174       EFAULT              Either  act  or oact points to memory that is not a
175                           valid part of the process address space.
176
177       EINVAL              Sig is not a valid signal number.
178
179       EINVAL              An attempt is made to ignore or  supply  a  handler
180                           for SIGKILL or SIGSTOP.
181

STANDARDS

183       The  sigaction  function is defined by IEEE Std1003.1-1988 (``POSIX'').
184       The SA_ONSTACK and SA_RESTART flags are Berkeley extensions, as are the
185       signals,  SIGTRAP,  SIGEMT,  SIGBUS,  SIGSYS,  SIGURG,  SIGIO, SIGXCPU,
186       SIGXFSZ, SIGVTALRM, SIGPROF, SIGWINCH, and SIGINFO.  Those signals  are
187       available on most BSD-derived systems.
188

BUGS

190       The  networking related syscalls are not properly restarted in 2.11BSD.
191       The SIGINFO signal is not implemented in 2.11BSD.
192

SEE ALSO

194       kill(1),  fcntl(2),  ptrace(2),  kill(2),  setitimer(2),  setrlimit(2),
195       sigaction(2),   sigprocmask(2),   sigsuspend(2),  sigblock(2),  sigset‐
196       mask(2),  sigpause(2),  sigstack(2),  sigvec(2),  setjmp(3),  siginter‐
197       rupt(3), sigsetops(3), tty(4)
198
199
200
2014.4 Berkeley Distribution      September 3, 1997                  SIGACTION(2)
Impressum