Debian Codegraph @

upstream/debian-unstable/man2/signalfd.2

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