1signal.h(3HEAD) Headers signal.h(3HEAD)
2
6 signal.h, signal - base signals
7
9 #include <signal.h>
10
13 A signal is an asynchronous notification of an event. A signal is said
14 to be generated for (or sent to) a process when the event associated
15 with that signal first occurs. Examples of such events include hardware
16 faults, timer expiration and terminal activity, as well as the invoca‐
17 tion of the kill(2) or sigsend(2) functions. In some circumstances, the
18 same event generates signals for multiple processes. A process may
19 request a detailed notification of the source of the signal and the
20 reason why it was generated. See siginfo.h(3HEAD).
21 Signals can be generated synchronously or asynchronously. Events
24 directly caused by the execution of code by a thread, such as a refer‐
25 ence to an unmapped, protected, or bad memory can generate SIGSEGV or
26 SIGBUS; a floating point exception can generate SIGFPE; and the execu‐
27 tion of an illegal instruction can generate SIGILL. Such events are
28 referred to as traps; signals generated by traps are said to be syn‐
29 chronously generated. Synchronously generated signals are initiated by
30 a specific thread and are delivered to and handled by that thread.
31 Signals may also be generated by calling kill(), sigqueue(), or
34 sigsend(). Events such as keyboard interrupts generate signals, such as
35 SIGINT, which are sent to the target process. Such events are referred
36 to as interrupts; signals generated by interrupts are said to be asyn‐
37 chronously generated. Asynchronously generated signals are not directed
38 to a particular thread but are handled by an arbitrary thread that
39 meets either of the following conditions:
40 o The thread is blocked in a call to sigwait(2) whose argument
42 includes the type of signal generated.
43 o The thread has a signal mask that does not include the type
45 of signal generated. See pthread_sigmask(3C). Each process
46 can specify a system action to be taken in response to each
47 signal sent to it, called the signal's disposition. All
48 threads in the process share the disposition. The set of
49 system signal actions for a process is initialized from that
50 of its parent. Once an action is installed for a specific
51 signal, it usually remains installed until another disposi‐
52 tion is explicitly requested by a call to either sigac‐
53 tion(), signal() or sigset(), or until the process execs().
54 See sigaction(2) and signal(3C). When a process execs, all
55 signals whose disposition has been set to catch the signal
56 will be set to SIG_DFL. Alternatively, a process may request
57 that the system automatically reset the disposition of a
58 signal to SIG_DFL after it has been caught. See sigac‐
59 tion(2) and signal(3C).
60 SIGNAL DELIVERY
62 A signal is said to be delivered to a process when a thread within the
63 process takes the appropriate action for the disposition of the sig‐
64 nal. Delivery of a signal can be blocked. There are two methods for
65 handling delivery of a signal in a multithreaded application. The first
66 method specifies a signal handler function to execute when the signal
67 is received by the process. See sigaction(2). The second method uses
68 sigwait(2) to create a thread to handle the receipt of the signal. The
69 sigaction() function can be used for both synchronously and asyn‐
70 chronously generated signals. The sigwait() function will work only for
71 asynchronously generated signals, as synchronously generated signals
72 are sent to the thread that caused the event. The sigwait() function is
73 the recommended for use with a multithreaded application.
74 SIGNAL MASK
76 Each thread has a signal mask that defines the set of signals cur‐
77 rently blocked from delivery to it. The signal mask of the main thread
78 is inherited from the signal mask of the thread that created it in the
79 parent process. The selection of the thread within the process that is
80 to take the appropriate action for the signal is based on the method of
81 signal generation and the signal masks of the threads in the receiving
82 process. Signals that are generated by action of a particular thread
83 such as hardware faults are delivered to the thread that caused the
84 signal. See pthread_sigmask(3C) or sigprocmask(2). See alarm(2) for
85 current semantics of delivery of SIGALRM. Signals that are directed to
86 a particular thread are delivered to the targeted thread. See
87 pthread_kill(3C). If the selected thread has blocked the signal, it
88 remains pending on the thread until it is unblocked. For all other
89 types of signal generation (for example, kill(2), sigsend(2), terminal
90 activity, and other external events not ascribable to a particular
91 thread) one of the threads that does not have the signal blocked is
92 selected to process the signal. If all the threads within the process
93 block the signal, it remains pending on the process until a thread in
94 the process unblocks it. If the action associated with a signal is set
95 to ignore the signal then both currently pending and subsequently gen‐
96 erated signals of this type are discarded immediately for this process.
97 The determination of which action is taken in response to a signal is
100 made at the time the signal is delivered to a thread within the
101 process, allowing for any changes since the time of generation. This
102 determination is independent of the means by which the signal was orig‐
103 inally generated.
104 The signals currently defined by <signal.h> are as follows:
107 Name Value Default Event
112 SIGHUP 1 Exit Hangup (see termio(7I))
113 SIGINT 2 Exit Interrupt (see termio(7I))
114 SIGQUIT 3 Core Quit (see termio(7I))
115 SIGILL 4 Core Illegal Instruction
116 SIGTRAP 5 Core Trace or Breakpoint Trap
117 SIGABRT 6 Core Abort
118 SIGEMT 7 Core Emulation Trap
119 SIGFPE 8 Core Arithmetic Exception
120 SIGKILL 9 Exit Killed
121 SIGBUS 10 Core Bus Error
122 SIGSEGV 11 Core Segmentation Fault
123 SIGSYS 12 Core Bad System Call
124 SIGPIPE 13 Exit Broken Pipe
125 SIGALRM 14 Exit Alarm Clock
126 SIGTERM 15 Exit Terminated
127 SIGUSR1 16 Exit User Signal 1
128 SIGUSR2 17 Exit User Signal 2
129 SIGCHLD 18 Ignore Child Status Changed
130 SIGPWR 19 Ignore Power Fail or Restart
131 SIGWINCH 20 Ignore Window Size Change
132 SIGURG 21 Ignore Urgent Socket Condition
134 SIGPOLL 22 Exit Pollable Event (see streamio(7I))
135 SIGSTOP 23 Stop Stopped (signal)
136 SIGTSTP 24 Stop Stopped (user) (see termio(7I))
137 SIGCONT 25 Ignore Continued
138 SIGTTIN 26 Stop Stopped (tty input) (see termio(7I))
139 SIGTTOU 27 Stop Stopped (tty output) (see termio(7I))
140 SIGVTALRM 28 Exit Virtual Timer Expired
141 SIGPROF 29 Exit Profiling Timer Expired
142 SIGXCPU 30 Core CPU time limit exceeded (see getr‐
143 limit(2))
144 SIGXFSZ 31 Core File size limit exceeded (see getr‐
145 limit(2))
146 SIGWAITING 32 Ignore Reserved
147 SIGLWP 33 Ignore Reserved
148 SIGFREEZE 34 Ignore Check point Freeze
149 SIGTHAW 35 Ignore Check point Thaw
150 SIGCANCEL 36 Ignore Reserved for threading support
151 SIGLOST 37 Exit Resource lost (for example, record-
152 lock lost)
153 SIGXRES 38 Ignore Resource control exceeded (see
154 setrctl(2))
155 SIGJVM1 39 Ignore Reserved for Java Virtual Machine 1
156 SIGJVM2 40 Ignore Reserved for Java Virtual Machine 2
157 SIGRTMIN * Exit First real time signal
158 (SIGRTMIN+1) * Exit Second real time signal
159 ...
160 (SIGRTMAX-1) * Exit Second-to-last real time signal
161 SIGRTMAX * Exit Last real time signal
162 The symbols SIGRTMIN through SIGRTMAX are evaluated dynamically to per‐
166 mit future configurability.
167 Applications should not use any of the signals marked "reserved" in the
170 above table for any purpose, to avoid interfering with their use by the
171 system.
172 SIGNAL DISPOSITION
174 A process using a signal(3C), sigset(3C) or sigaction(2) system call
175 can specify one of three dispositions for a signal: take the default
176 action for the signal, ignore the signal, or catch the signal.
177 Default Action: SIG_DFL
179 A disposition of SIG_DFL specifies the default action. The default
180 action for each signal is listed in the table above and is selected
181 from the following:
182 Exit When it gets the signal, the receiving process is to be ter‐
184 minated with all the consequences outlined in exit(2).
185 Core When it gets the signal, the receiving process is to be ter‐
188 minated with all the consequences outlined in exit(2). In
189 addition, a ``core image'' of the process is constructed in
190 the current working directory.
191 Stop When it gets the signal, the receiving process is to stop.
194 When a process is stopped, all the threads within the process
195 also stop executing.
196 Ignore When it gets the signal, the receiving process is to ignore
199 it. This is identical to setting the disposition to SIG_IGN.
200 Ignore Signal: SIG_IGN
203 A disposition of SIG_IGN specifies that the signal is to be ignored.
204 Setting a signal action to SIG_IGN for a signal that is pending causes
205 the pending signal to be discarded, whether or not it is blocked. Any
206 queued values pending are also discarded, and the resources used to
207 queue them are released and made available to queue other signals.
208 Catch Signal: function address
210 A disposition that is a function address specifies that, when it gets
211 the signal, the thread within the process that is selected to process
212 the signal will execute the signal handler at the specified address.
213 Normally, the signal handler is passed the signal number as its only
214 argument. If the disposition was set with the sigaction(2) function,
215 however, additional arguments can be requested. When the signal handler
216 returns, the receiving process resumes execution at the point it was
217 interrupted, unless the signal handler makes other arrangements. If an
218 invalid function address is specified, results are undefined.
219 If the disposition has been set with the sigset() or sigaction(), the
222 signal is automatically blocked in the thread while it is executing the
223 signal catcher. If a longjmp() is used to leave the signal catcher,
224 then the signal must be explicitly unblocked by the user. See
225 setjmp(3C), signal(3C) and sigprocmask(2).
226 If execution of the signal handler interrupts a blocked function call,
229 the handler is executed and the interrupted function call returns −1
230 to the calling process with errno set to EINTR. If the SA_RESTART flag
231 is set, however, certain function calls will be transparently
232 restarted.
233 Some signal-generating functions, such as high resolution timer expira‐
236 tion, asynchronous I/O completion, inter-process message arrival, and
237 the sigqueue(3C) function, support the specification of an application
238 defined value, either explicitly as a parameter to the function, or in
239 a sigevent structure parameter. The sigevent structure is defined by
240 <signal.h> and contains at least the following members:
241 Type Name Description
246 ──────────────────────────────────────────────────────────────────────────
247 int sigev_notify Notification type
248 int sigev_signo Signal number
249 ──────────────────────────────────────────────────────────────────────────
250 union sigval sigev_value Signal value
251 ──────────────────────────────────────────────────────────────────────────
252 void(*)(union sigval) sigev_notify_function Notification function
253 ──────────────────────────────────────────────────────────────────────────
254 (pthread_attr_t *) sigev_notify_attributes Notification attributes
255 The sigval union is defined by <signal.h>and contains at least the fol‐
259 lowing members:
260 Type Name Description
265 ────────────────────────────────────────────────────────────────
266 int sival_int Integer signal value
267 void * sival_ptr Pointer signal value
268 The sigev_notify member specifies the notification mechanism to use
272 when an asynchronous event occurs. The sigev_notify member may be
273 defined with the following values:
274 SIGEV_NONE No asynchronous notification is delivered when the
276 event of interest occurs.
277 SIGEV_SIGNAL A queued signal, with its value equal to sigev_signo,
280 is generated when the event of interest occurs.
281 SIGEV_THREAD The sigev_notify_function is called, with sigev_value
284 as its argument, to perform notification when the asyn‐
285 chronous event occurs. The function is executed in an
286 environment as if it were the start routine for a newly
287 created thread with thread attributes
288 sigev_notify_attributes. If sigev_notify_attributes is
289 NULL, the thread runs as a detached thread with default
290 attributes. Otherwise, the thread runs with the speci‐
291 fied attributes, but as a detached thread regardless.
292 The thread runs with all blockable signals blocked.
293 SIGEV_PORT An asynchronous notification is delivered to an event
296 port when the event of interest occurs. The
297 sigev_value.sival_ptr member points to a port_notify_t
298 structure defined in <port.h> (see port_associate(3C)).
299 The event port identifier as well as an application-
300 defined cookie are part of the port_notify_t structure.
301 The sigev_signo member contains the application-defined value to be
305 passed to the signal-catching function (for notification type
306 SIGEV_SIGNAL) at the time of the signal delivery as the si_value member
307 of the siginfo_t structure, or as the argument to the notification
308 function (for notification type SIGEV_THREAD) that is called when the
309 asynchronous event occurs. For notification type SIGEV_PORT,
310 sigev_value.sival_ptr points to a port_notify_t structure that speci‐
311 fies the port and an application-defined cookie.
312 The sigev_value member references the application defined value to be
315 passed to the signal-catching function at the time of the signal deliv‐
316 ery as the si_value member of the siginfo_t structure.
317 The sival_int member is used when the application defined value is of
320 type int, and the sival_ptr member is used when the application defined
321 value is a pointer.
322 When a signal is generated by sigqueue(3C) or any signal−generating
325 function which supports the specification of an application defined
326 value, the signal is marked pending and, if the SA_SIGINFO flag is set
327 for that signal, the signal is queued to the process along with the
328 application specified signal value. Multiple occurrences of signals so
329 generated are queued in FIFO order. If the SA_SIGINFO flag is not set
330 for that signal, later occurrences of that signal's generation, when a
331 signal is already queued, are silently discarded.
332
334 See attributes(5) for descriptions of the following attributes:
335 ┌─────────────────────────────┬─────────────────────────────┐
340 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
341 ├─────────────────────────────┼─────────────────────────────┤
342 │Interface Stability │Committed │
343 ├─────────────────────────────┼─────────────────────────────┤
344 │Standard │See standards(5). │
345 └─────────────────────────────┴─────────────────────────────┘
346
348 lockd(1M), Intro(2), alarm(2), exit(2), fcntl(2), getrlimit(2),
349 ioctl(2), kill(2), pause(2), setrctl(2), sigaction(2), sigaltstack(2),
350 sigprocmask(2), sigsend(2), sigsuspend(2), sigwait(2), port_asso‐
351 ciate(3C), pthread_create(3C), pthread_kill(3C), pthread_sigmask(3C),
352 setjmp(3C), siginfo.h(3HEAD), signal(3C), sigqueue(3C), sigsetops(3C),
353 ucontext.h(3HEAD), wait(3C), attributes(5), standards(5)
354
356 The dispositions of the SIGKILL and SIGSTOP signals cannot be altered
357 from their default values. The system generates an error if this is
358 attempted.
359 The SIGKILL, SIGSTOP, and SIGCANCEL signals cannot be blocked. The sys‐
362 tem silently enforces this restriction.
363 The SIGCANCEL signal cannot be directed to an individual thread using
366 pthread_kill(3C), but it can be sent to a process using kill(2),
367 sigsend(2), or sigqueue(3C).
368 Whenever a process receives a SIGSTOP, SIGTSTP, SIGTTIN, or SIGTTOU
371 signal, regardless of its disposition, any pending SIGCONT signal are
372 discarded.
373 Whenever a process receives a SIGCONT signal, regardless of its dispo‐
376 sition, any pending SIGSTOP, SIGTSTP, SIGTTIN, and SIGTTOU signals is
377 discarded. In addition, if the process was stopped, it is continued.
378 SIGPOLL is issued when a file descriptor corresponding to a STREAMS
381 file has a "selectable" event pending. See Intro(2). A process must
382 specifically request that this signal be sent using the I_SETSIG ioctl
383 call. Otherwise, the process will never receive SIGPOLL.
384 If the disposition of the SIGCHLD signal has been set with signal() or
387 sigset(), or with sigaction() and the SA_NOCLDSTOP flag has been speci‐
388 fied, it will only be sent to the calling process when its children
389 exit; otherwise, it will also be sent when the calling process's chil‐
390 dren are stopped or continued due to job control.
391 The name SIGCLD is also defined in this header and identifies the same
394 signal as SIGCHLD. SIGCLD is provided for backward compatibility, new
395 applications should use SIGCHLD.
396 The disposition of signals that are inherited as SIG_IGN should not be
399 changed.
400 Signals which are generated synchronously should not be masked. If such
403 a signal is blocked and delivered, the receiving process is killed.
404SunOS 5.11 5 Feb 2008 signal.h(3HEAD)