]>
Commit | Line | Data |
---|---|---|
5b0bafdd MK |
1 | .\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" starting from a version by Davide Libenzi <davidel@xmailserver.org> | |
3 | .\" | |
f0008367 | 4 | .\" %%%LICENSE_START(GPLv2+_SW_3_PARA) |
5b0bafdd MK |
5 | .\" This program is free software; you can redistribute it and/or modify |
6 | .\" it under the terms of the GNU General Public License as published by | |
7 | .\" the Free Software Foundation; either version 2 of the License, or | |
8 | .\" (at your option) any later version. | |
9 | .\" | |
10 | .\" This program is distributed in the hope that it will be useful, | |
11 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
12 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
13 | .\" GNU General Public License for more details. | |
14 | .\" | |
68fa4398 MK |
15 | .\" You should have received a copy of the GNU General Public |
16 | .\" License along with this manual; if not, see | |
17 | .\" <http://www.gnu.org/licenses/>. | |
8ff7380d | 18 | .\" %%%LICENSE_END |
5b0bafdd | 19 | .\" |
867c9b34 | 20 | .TH SIGNALFD 2 2019-10-10 Linux "Linux Programmer's Manual" |
5b0bafdd MK |
21 | .SH NAME |
22 | signalfd \- create a file descriptor for accepting signals | |
23 | .SH SYNOPSIS | |
24 | .B #include <sys/signalfd.h> | |
cc560d77 | 25 | .PP |
5b0bafdd MK |
26 | .BI "int signalfd(int " fd ", const sigset_t *" mask ", int " flags ); |
27 | .SH DESCRIPTION | |
28 | .BR signalfd () | |
29 | creates a file descriptor that can be used to accept signals | |
30 | targeted at the caller. | |
31 | This provides an alternative to the use of a signal handler or | |
32 | .BR sigwaitinfo (2), | |
33 | and has the advantage that the file descriptor may be monitored by | |
34 | .BR select (2), | |
35 | .BR poll (2), | |
36 | and | |
37 | .BR epoll (7). | |
cc560d77 | 38 | .PP |
5b0bafdd MK |
39 | The |
40 | .I mask | |
41 | argument specifies the set of signals that the caller | |
42 | wishes to accept via the file descriptor. | |
43 | This argument is a signal set whose contents can be initialized | |
44 | using the macros described in | |
45 | .BR sigsetops (3). | |
46 | Normally, the set of signals to be received via the | |
47 | file descriptor should be blocked using | |
48 | .BR sigprocmask (2), | |
49 | to prevent the signals being handled according to their default | |
50 | dispositions. | |
51 | It is not possible to receive | |
52 | .B SIGKILL | |
53 | or | |
54 | .B SIGSTOP | |
55 | signals via a signalfd file descriptor; | |
56 | these signals are silently ignored if specified in | |
57 | .IR mask . | |
cc560d77 | 58 | .PP |
5b0bafdd MK |
59 | If the |
60 | .I fd | |
61 | argument is \-1, | |
62 | then the call creates a new file descriptor and associates the | |
63 | signal set specified in | |
64 | .I mask | |
d9cb0d7d | 65 | with that file descriptor. |
5b0bafdd MK |
66 | If |
67 | .I fd | |
68 | is not \-1, | |
69 | then it must specify a valid existing signalfd file descriptor, and | |
70 | .I mask | |
d9cb0d7d | 71 | is used to replace the signal set associated with that file descriptor. |
cc560d77 | 72 | .PP |
89d9a56f MK |
73 | Starting with Linux 2.6.27, the following values may be bitwise ORed in |
74 | .IR flags | |
a1fa36af | 75 | to change the behavior of |
89d9a56f MK |
76 | .BR signalfd (): |
77 | .TP 14 | |
78 | .B SFD_NONBLOCK | |
79 | Set the | |
80 | .BR O_NONBLOCK | |
7f11e32c MK |
81 | file status flag on the open file description (see |
82 | .BR open (2)) | |
83 | referred to by the new file descriptor. | |
89d9a56f MK |
84 | Using this flag saves extra calls to |
85 | .BR fcntl (2) | |
86 | to achieve the same result. | |
87 | .TP | |
88 | .B SFD_CLOEXEC | |
89 | Set the close-on-exec | |
90 | .RB ( FD_CLOEXEC ) | |
91 | flag on the new file descriptor. | |
c5571b61 | 92 | See the description of the |
89d9a56f MK |
93 | .B O_CLOEXEC |
94 | flag in | |
95 | .BR open (2) | |
96 | for reasons why this may be useful. | |
97 | .PP | |
98 | In Linux up to version 2.6.26, the | |
5b0bafdd | 99 | .I flags |
89d9a56f | 100 | argument is unused, and must be specified as zero. |
cc560d77 | 101 | .PP |
5b0bafdd MK |
102 | .BR signalfd () |
103 | returns a file descriptor that supports the following operations: | |
104 | .TP | |
105 | .BR read (2) | |
106 | If one or more of the signals specified in | |
107 | .I mask | |
108 | is pending for the process, then the buffer supplied to | |
109 | .BR read (2) | |
110 | is used to return one or more | |
111 | .I signalfd_siginfo | |
112 | structures (see below) that describe the signals. | |
113 | The | |
114 | .BR read (2) | |
115 | returns information for as many signals as are pending and will | |
116 | fit in the supplied buffer. | |
117 | The buffer must be at least | |
118 | .I "sizeof(struct signalfd_siginfo)" | |
119 | bytes. | |
120 | The return value of the | |
121 | .BR read (2) | |
122 | is the total number of bytes read. | |
123 | .IP | |
124 | As a consequence of the | |
125 | .BR read (2), | |
126 | the signals are consumed, | |
127 | so that they are no longer pending for the process | |
128 | (i.e., will not be caught by signal handlers, | |
129 | and cannot be accepted using | |
130 | .BR sigwaitinfo (2)). | |
131 | .IP | |
132 | If none of the signals in | |
133 | .I mask | |
134 | is pending for the process, then the | |
135 | .BR read (2) | |
136 | either blocks until one of the signals in | |
137 | .I mask | |
138 | is generated for the process, | |
139 | or fails with the error | |
140 | .B EAGAIN | |
ff40dbb3 | 141 | if the file descriptor has been made nonblocking. |
5b0bafdd MK |
142 | .TP |
143 | .BR poll "(2), " select "(2) (and similar)" | |
144 | The file descriptor is readable | |
145 | (the | |
146 | .BR select (2) | |
147 | .I readfds | |
148 | argument; the | |
149 | .BR poll (2) | |
150 | .B POLLIN | |
151 | flag) | |
152 | if one or more of the signals in | |
153 | .I mask | |
154 | is pending for the process. | |
155 | .IP | |
156 | The signalfd file descriptor also supports the other file-descriptor | |
157 | multiplexing APIs: | |
158 | .BR pselect (2), | |
159 | .BR ppoll (2), | |
160 | and | |
161 | .BR epoll (7). | |
162 | .TP | |
163 | .BR close (2) | |
164 | When the file descriptor is no longer required it should be closed. | |
165 | When all file descriptors associated with the same signalfd object | |
166 | have been closed, the resources for object are freed by the kernel. | |
167 | .SS The signalfd_siginfo structure | |
168 | The format of the | |
169 | .I signalfd_siginfo | |
170 | structure(s) returned by | |
171 | .BR read (2)s | |
172 | from a signalfd file descriptor is as follows: | |
cc560d77 | 173 | .PP |
5b0bafdd | 174 | .in +4n |
cc560d77 | 175 | .EX |
f7e9afe8 | 176 | struct signalfd_siginfo { |
17be9ac5 MK |
177 | uint32_t ssi_signo; /* Signal number */ |
178 | int32_t ssi_errno; /* Error number (unused) */ | |
179 | int32_t ssi_code; /* Signal code */ | |
180 | uint32_t ssi_pid; /* PID of sender */ | |
181 | uint32_t ssi_uid; /* Real UID of sender */ | |
182 | int32_t ssi_fd; /* File descriptor (SIGIO) */ | |
183 | uint32_t ssi_tid; /* Kernel timer ID (POSIX timers) | |
184 | uint32_t ssi_band; /* Band event (SIGIO) */ | |
185 | uint32_t ssi_overrun; /* POSIX timer overrun count */ | |
186 | uint32_t ssi_trapno; /* Trap number that caused signal */ | |
d0fe4db7 | 187 | .\" ssi_trapno is unused on most arches |
17be9ac5 MK |
188 | int32_t ssi_status; /* Exit status or signal (SIGCHLD) */ |
189 | int32_t ssi_int; /* Integer sent by sigqueue(3) */ | |
190 | uint64_t ssi_ptr; /* Pointer sent by sigqueue(3) */ | |
191 | uint64_t ssi_utime; /* User CPU time consumed (SIGCHLD) */ | |
192 | uint64_t ssi_stime; /* System CPU time consumed | |
193 | (SIGCHLD) */ | |
194 | uint64_t ssi_addr; /* Address that generated signal | |
195 | (for hardware-generated signals) */ | |
5fe5d581 MK |
196 | uint16_t ssi_addr_lsb; /* Least significant bit of address |
197 | (SIGBUS; since Linux 2.6.37) | |
198 | .\" ssi_addr_lsb: commit b8aeec34175fc8fe8b0d40efea4846dfc1ba663e | |
17be9ac5 | 199 | uint8_t pad[\fIX\fP]; /* Pad size to 128 bytes (allow for |
275714d8 | 200 | additional fields in the future) */ |
5b0bafdd | 201 | }; |
cc560d77 | 202 | .EE |
5b0bafdd | 203 | .in |
c7885256 | 204 | .PP |
5b0bafdd MK |
205 | Each of the fields in this structure |
206 | is analogous to the similarly named field in the | |
207 | .I siginfo_t | |
208 | structure. | |
209 | The | |
210 | .I siginfo_t | |
211 | structure is described in | |
212 | .BR sigaction (2). | |
213 | Not all fields in the returned | |
214 | .I signalfd_siginfo | |
215 | structure will be valid for a specific signal; | |
216 | the set of valid fields can be determined from the value returned in the | |
217 | .I ssi_code | |
218 | field. | |
219 | This field is the analog of the | |
220 | .I siginfo_t | |
221 | .I si_code | |
222 | field; see | |
223 | .BR sigaction (2) | |
224 | for details. | |
225 | .SS fork(2) semantics | |
226 | After a | |
227 | .BR fork (2), | |
228 | the child inherits a copy of the signalfd file descriptor. | |
98895092 MK |
229 | A |
230 | .BR read (2) | |
231 | from the file descriptor in the child will return information | |
232 | about signals queued to the child. | |
3f816312 MK |
233 | .SS Semantics of file descriptor passing |
234 | As with other file descriptors, | |
235 | signalfd file descriptors can be passed to another process | |
236 | via a UNIX domain socket (see | |
237 | .BR unix (7)). | |
238 | In the receiving process, a | |
239 | .BR read (2) | |
240 | from the received file descriptor will return information | |
241 | about signals queued to that process. | |
5b0bafdd MK |
242 | .SS execve(2) semantics |
243 | Just like any other file descriptor, | |
244 | a signalfd file descriptor remains open across an | |
245 | .BR execve (2), | |
246 | unless it has been marked for close-on-exec (see | |
247 | .BR fcntl (2)). | |
248 | Any signals that were available for reading before the | |
249 | .BR execve (2) | |
250 | remain available to the newly loaded program. | |
251 | (This is analogous to traditional signal semantics, | |
252 | where a blocked signal that is pending remains pending across an | |
253 | .BR execve (2).) | |
5b0bafdd MK |
254 | .SS Thread semantics |
255 | The semantics of signalfd file descriptors in a multithreaded program | |
256 | mirror the standard semantics for signals. | |
257 | In other words, | |
258 | when a thread reads from a signalfd file descriptor, | |
259 | it will read the signals that are directed to the thread | |
260 | itself and the signals that are directed to the process | |
261 | (i.e., the entire thread group). | |
262 | (A thread will not be able to read signals that are directed | |
263 | to other threads in the process.) | |
b892d64f | 264 | .\" |
e95f6bf4 | 265 | .SS epoll(7) semantics |
b892d64f MK |
266 | If a process adds (via |
267 | .BR epoll_ctl (2)) | |
268 | a signalfd file descriptor to an | |
269 | .BR epoll (7) | |
270 | instance, then | |
271 | .BR epoll_wait (2) | |
272 | returns events only for signals sent to that process. | |
273 | In particular, if the process then uses | |
274 | .BR fork () | |
275 | to create a child process, then the child will be able to | |
276 | .BR read (2) | |
277 | signals that are sent to it using the signalfd file descriptor, but | |
278 | .BR epoll_wait (2) | |
279 | will | |
280 | .B not | |
281 | indicate that the signalfd file descriptor is ready. | |
282 | In this scenario, a possible workaround is that after the | |
283 | .BR fork (2), | |
284 | the child process can close the signalfd file descriptor that it inherited | |
285 | from the parent process and then create another signalfd file descriptor | |
286 | and add it to the epoll instance. | |
287 | Alternatively, the parent and the child could delay creating their | |
288 | (separate) signalfd file descriptors and adding them to the | |
289 | epoll instance until after the call to | |
290 | .BR fork (2). | |
47297adb | 291 | .SH RETURN VALUE |
5b0bafdd MK |
292 | On success, |
293 | .BR signalfd () | |
294 | returns a signalfd file descriptor; | |
295 | this is either a new file descriptor (if | |
296 | .I fd | |
297 | was \-1), or | |
298 | .I fd | |
299 | if | |
300 | .I fd | |
301 | was a valid signalfd file descriptor. | |
302 | On error, \-1 is returned and | |
303 | .I errno | |
304 | is set to indicate the error. | |
305 | .SH ERRORS | |
306 | .TP | |
307 | .B EBADF | |
308 | The | |
309 | .I fd | |
310 | file descriptor is not a valid file descriptor. | |
311 | .TP | |
312 | .B EINVAL | |
313 | .I fd | |
89d9a56f | 314 | is not a valid signalfd file descriptor. |
5b0bafdd MK |
315 | .\" or, the |
316 | .\" .I sizemask | |
317 | .\" argument is not equal to | |
318 | .\" .IR sizeof(sigset_t) ; | |
319 | .TP | |
89d9a56f MK |
320 | .B EINVAL |
321 | .I flags | |
322 | is invalid; | |
323 | or, in Linux 2.6.26 or earlier, | |
324 | .I flags | |
c7094399 | 325 | is nonzero. |
89d9a56f | 326 | .TP |
5b0bafdd | 327 | .B EMFILE |
26c32fab | 328 | The per-process limit on the number of open file descriptors has been reached. |
5b0bafdd MK |
329 | .TP |
330 | .B ENFILE | |
331 | The system-wide limit on the total number of open files has been | |
332 | reached. | |
333 | .TP | |
334 | .B ENODEV | |
335 | Could not mount (internal) anonymous inode device. | |
336 | .TP | |
337 | .B ENOMEM | |
338 | There was insufficient memory to create a new signalfd file descriptor. | |
339 | .SH VERSIONS | |
340 | .BR signalfd () | |
341 | is available on Linux since kernel 2.6.22. | |
342 | Working support is provided in glibc since version 2.8. | |
343 | .\" signalfd() is in glibc 2.7, but reportedly does not build | |
89d9a56f MK |
344 | The |
345 | .BR signalfd4 () | |
346 | system call (see NOTES) is available on Linux since kernel 2.6.27. | |
5b0bafdd MK |
347 | .SH CONFORMING TO |
348 | .BR signalfd () | |
1fadf79b MK |
349 | and |
350 | .BR signalfd4 () | |
351 | are Linux-specific. | |
5b0bafdd | 352 | .SH NOTES |
5b0bafdd MK |
353 | A process can create multiple signalfd file descriptors. |
354 | This makes it possible to accept different signals | |
355 | on different file descriptors. | |
356 | (This may be useful if monitoring the file descriptors using | |
357 | .BR select (2), | |
358 | .BR poll (2), | |
359 | or | |
360 | .BR epoll (7): | |
d9cb0d7d | 361 | the arrival of different signals will make different file descriptors ready.) |
5b0bafdd MK |
362 | If a signal appears in the |
363 | .I mask | |
364 | of more than one of the file descriptors, then occurrences | |
d9cb0d7d | 365 | of that signal can be read (once) from any one of the file descriptors. |
cc560d77 | 366 | .PP |
07a5f3db MK |
367 | Attempts to include |
368 | .B SIGKILL | |
369 | and | |
370 | .B SIGSTOP | |
371 | in | |
372 | .I mask | |
373 | are silently ignored. | |
cc560d77 | 374 | .PP |
13dd2598 MK |
375 | The signal mask employed by a signalfd file descriptor can be viewed |
376 | via the entry for the corresponding file descriptor in the process's | |
377 | .IR /proc/[pid]/fdinfo | |
378 | directory. | |
379 | See | |
380 | .BR proc (5) | |
381 | for further details. | |
4a96f7b5 MK |
382 | .\" |
383 | .SS Limitations | |
b435e1e1 MK |
384 | The signalfd mechanism can't be used to receive signals that |
385 | are synchronously generated, such as the | |
386 | .BR SIGSEGV | |
387 | signal that results from accessing an invalid memory address | |
388 | or the | |
389 | .BR SIGFPE | |
390 | signal that results from an arithmetic error. | |
391 | Such signals can be caught only via signal handler. | |
cc560d77 | 392 | .PP |
76e55b8a MK |
393 | As described above, |
394 | in normal usage one blocks the signals that will be accepted via | |
395 | .BR signalfd (). | |
396 | If spawning a child process to execute a helper program | |
397 | (that does not need the signalfd file descriptor), | |
398 | then, after the call to | |
399 | .BR fork (2), | |
400 | you will normally want to unblock those signals before calling | |
401 | .BR execve (2), | |
402 | so that the helper program can see any signals that it expects to see. | |
403 | Be aware, however, | |
404 | that this won't be possible in the case of a helper program spawned | |
405 | behind the scenes by any library function that the program may call. | |
406 | In such cases, one must fall back to using a traditional signal | |
407 | handler that writes to a file descriptor monitored by | |
408 | .BR select (2), | |
409 | .BR poll (2), | |
410 | or | |
362310a7 | 411 | .BR epoll (7). |
13dd2598 | 412 | .\" |
0722a578 | 413 | .SS C library/kernel differences |
68f611bd MK |
414 | The underlying Linux system call requires an additional argument, |
415 | .IR "size_t sizemask" , | |
416 | which specifies the size of the | |
417 | .I mask | |
418 | argument. | |
419 | The glibc | |
420 | .BR signalfd () | |
421 | wrapper function does not include this argument, | |
422 | since it provides the required value for the underlying system call. | |
cc560d77 | 423 | .PP |
89d9a56f MK |
424 | There are two underlying Linux system calls: |
425 | .BR signalfd () | |
426 | and the more recent | |
427 | .BR signalfd4 (). | |
428 | The former system call does not implement a | |
429 | .I flags | |
430 | argument. | |
431 | The latter system call implements the | |
432 | .I flags | |
433 | values described above. | |
434 | Starting with glibc 2.9, the | |
435 | .BR signalfd () | |
436 | wrapper function will use | |
437 | .BR signalfd4 () | |
438 | where it is available. | |
dbe108ed | 439 | .SH BUGS |
25c8faf5 | 440 | In kernels before 2.6.25, the |
dbe108ed MK |
441 | .I ssi_ptr |
442 | and | |
443 | .I ssi_int | |
444 | fields are not filled in with the data accompanying a signal sent by | |
485ab701 | 445 | .BR sigqueue (3). |
cd56f36f | 446 | .\" The fix also was put into 2.6.24.5 |
5b0bafdd MK |
447 | .SH EXAMPLE |
448 | The program below accepts the signals | |
449 | .B SIGINT | |
450 | and | |
451 | .B SIGQUIT | |
452 | via a signalfd file descriptor. | |
453 | The program terminates after accepting a | |
454 | .B SIGQUIT | |
455 | signal. | |
456 | The following shell session demonstrates the use of the program: | |
cc560d77 | 457 | .PP |
5b0bafdd | 458 | .in +4n |
cc560d77 | 459 | .EX |
b43a3b30 MK |
460 | .RB "$" " ./signalfd_demo" |
461 | .BR "^C" " # Control\-C generates SIGINT" | |
5b0bafdd | 462 | Got SIGINT |
b43a3b30 | 463 | .B ^C |
5b0bafdd | 464 | Got SIGINT |
d1a71985 | 465 | \fB^\e\fP # Control\-\e generates SIGQUIT |
5b0bafdd MK |
466 | Got SIGQUIT |
467 | $ | |
cc560d77 | 468 | .EE |
1c32ee47 | 469 | .in |
9c330504 | 470 | .SS Program source |
d84d0300 | 471 | \& |
cc560d77 | 472 | .EX |
5b0bafdd MK |
473 | #include <sys/signalfd.h> |
474 | #include <signal.h> | |
475 | #include <unistd.h> | |
476 | #include <stdlib.h> | |
477 | #include <stdio.h> | |
478 | ||
d1a71985 | 479 | #define handle_error(msg) \e |
5b0bafdd MK |
480 | do { perror(msg); exit(EXIT_FAILURE); } while (0) |
481 | ||
482 | int | |
483 | main(int argc, char *argv[]) | |
484 | { | |
485 | sigset_t mask; | |
486 | int sfd; | |
487 | struct signalfd_siginfo fdsi; | |
488 | ssize_t s; | |
489 | ||
490 | sigemptyset(&mask); | |
491 | sigaddset(&mask, SIGINT); | |
492 | sigaddset(&mask, SIGQUIT); | |
493 | ||
f81fb444 | 494 | /* Block signals so that they aren\(aqt handled |
5b0bafdd MK |
495 | according to their default dispositions */ |
496 | ||
497 | if (sigprocmask(SIG_BLOCK, &mask, NULL) == \-1) | |
498 | handle_error("sigprocmask"); | |
499 | ||
500 | sfd = signalfd(\-1, &mask, 0); | |
501 | if (sfd == \-1) | |
502 | handle_error("signalfd"); | |
503 | ||
504 | for (;;) { | |
505 | s = read(sfd, &fdsi, sizeof(struct signalfd_siginfo)); | |
506 | if (s != sizeof(struct signalfd_siginfo)) | |
507 | handle_error("read"); | |
508 | ||
d372f252 | 509 | if (fdsi.ssi_signo == SIGINT) { |
d1a71985 | 510 | printf("Got SIGINT\en"); |
d372f252 | 511 | } else if (fdsi.ssi_signo == SIGQUIT) { |
d1a71985 | 512 | printf("Got SIGQUIT\en"); |
5b0bafdd MK |
513 | exit(EXIT_SUCCESS); |
514 | } else { | |
d1a71985 | 515 | printf("Read unexpected signal\en"); |
5b0bafdd MK |
516 | } |
517 | } | |
518 | } | |
cc560d77 | 519 | .EE |
47297adb | 520 | .SH SEE ALSO |
5b0bafdd MK |
521 | .BR eventfd (2), |
522 | .BR poll (2), | |
523 | .BR read (2), | |
524 | .BR select (2), | |
525 | .BR sigaction (2), | |
526 | .BR sigprocmask (2), | |
527 | .BR sigwaitinfo (2), | |
528 | .BR timerfd_create (2), | |
529 | .BR sigsetops (3), | |
7c85aa6b | 530 | .BR sigwait (3), |
5b0bafdd MK |
531 | .BR epoll (7), |
532 | .BR signal (7) |