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

NAME

6       signalfd - create a file descriptor for accepting signals
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/signalfd.h>
13
14       int signalfd(int fd, const sigset_t *mask, int flags);
15

DESCRIPTION

17       signalfd() creates a file descriptor that can be used to accept signals
18       targeted at the caller.  This provides an alternative to the use  of  a
19       signal  handler  or sigwaitinfo(2), and has the advantage that the file
20       descriptor may be monitored by select(2), poll(2), and epoll(7).
21
22       The mask argument specifies the set of signals that the  caller  wishes
23       to accept via the file descriptor.  This argument is a signal set whose
24       contents can be initialized using the macros described in sigsetops(3).
25       Normally,  the  set  of  signals to be received via the file descriptor
26       should be blocked using sigprocmask(2), to prevent  the  signals  being
27       handled according to their default dispositions.  It is not possible to
28       receive SIGKILL or SIGSTOP signals  via  a  signalfd  file  descriptor;
29       these signals are silently ignored if specified in mask.
30
31       If  the  fd argument is -1, then the call creates a new file descriptor
32       and associates the signal set specified in mask with that file descrip‐
33       tor.   If  fd is not -1, then it must specify a valid existing signalfd
34       file descriptor, and mask is used to replace the signal set  associated
35       with that file descriptor.
36
37       Starting with Linux 2.6.27, the following values may be bitwise ORed in
38       flags to change the behavior of signalfd():
39
40       SFD_NONBLOCK  Set the O_NONBLOCK file status flag on the open file  de‐
41                     scription  (see  open(2)) referred to by the new file de‐
42                     scriptor.  Using this flag saves extra calls to  fcntl(2)
43                     to achieve the same result.
44
45       SFD_CLOEXEC   Set  the  close-on-exec (FD_CLOEXEC) flag on the new file
46                     descriptor.  See the description of the O_CLOEXEC flag in
47                     open(2) for reasons why this may be useful.
48
49       Up to Linux 2.6.26, the flags argument is unused, and must be specified
50       as zero.
51
52       signalfd() returns a file descriptor that supports the following opera‐
53       tions:
54
55       read(2)
56              If  one  or more of the signals specified in mask is pending for
57              the process, then the buffer supplied to read(2) is used to  re‐
58              turn  one  or  more signalfd_siginfo structures (see below) that
59              describe the signals.  The read(2) returns  information  for  as
60              many signals as are pending and will fit in the supplied buffer.
61              The buffer must  be  at  least  sizeof(struct  signalfd_siginfo)
62              bytes.   The  return value of the read(2) is the total number of
63              bytes read.
64
65              As a consequence of the read(2), the signals  are  consumed,  so
66              that  they are no longer pending for the process (i.e., will not
67              be caught by signal handlers, and cannot be accepted using  sig‐
68              waitinfo(2)).
69
70              If  none of the signals in mask is pending for the process, then
71              the read(2) either blocks until one of the signals  in  mask  is
72              generated for the process, or fails with the error EAGAIN if the
73              file descriptor has been made nonblocking.
74
75       poll(2), select(2) (and similar)
76              The file descriptor is readable (the select(2) readfds argument;
77              the  poll(2)  POLLIN flag) if one or more of the signals in mask
78              is pending for the process.
79
80              The signalfd file descriptor also supports  the  other  file-de‐
81              scriptor multiplexing APIs: pselect(2), ppoll(2), and epoll(7).
82
83       close(2)
84              When  the  file  descriptor  is  no longer required it should be
85              closed.  When all file descriptors associated with the same sig‐
86              nalfd  object  have  been  closed,  the resources for object are
87              freed by the kernel.
88
89   The signalfd_siginfo structure
90       The format of the signalfd_siginfo structure(s)  returned  by  read(2)s
91       from a signalfd file descriptor is as follows:
92
93           struct signalfd_siginfo {
94               uint32_t ssi_signo;    /* Signal number */
95               int32_t  ssi_errno;    /* Error number (unused) */
96               int32_t  ssi_code;     /* Signal code */
97               uint32_t ssi_pid;      /* PID of sender */
98               uint32_t ssi_uid;      /* Real UID of sender */
99               int32_t  ssi_fd;       /* File descriptor (SIGIO) */
100               uint32_t ssi_tid;      /* Kernel timer ID (POSIX timers)
101               uint32_t ssi_band;     /* Band event (SIGIO) */
102               uint32_t ssi_overrun;  /* POSIX timer overrun count */
103               uint32_t ssi_trapno;   /* Trap number that caused signal */
104               int32_t  ssi_status;   /* Exit status or signal (SIGCHLD) */
105               int32_t  ssi_int;      /* Integer sent by sigqueue(3) */
106               uint64_t ssi_ptr;      /* Pointer sent by sigqueue(3) */
107               uint64_t ssi_utime;    /* User CPU time consumed (SIGCHLD) */
108               uint64_t ssi_stime;    /* System CPU time consumed
109                                         (SIGCHLD) */
110               uint64_t ssi_addr;     /* Address that generated signal
111                                         (for hardware-generated signals) */
112               uint16_t ssi_addr_lsb; /* Least significant bit of address
113                                         (SIGBUS; since Linux 2.6.37) */
114               uint8_t  pad[X];       /* Pad size to 128 bytes (allow for
115                                         additional fields in the future) */
116           };
117
118       Each  of  the  fields  in  this structure is analogous to the similarly
119       named field in the siginfo_t structure.  The siginfo_t structure is de‐
120       scribed  in sigaction(2).  Not all fields in the returned signalfd_sig‐
121       info structure will be valid for a specific signal; the  set  of  valid
122       fields can be determined from the value returned in the ssi_code field.
123       This field is the analog of the siginfo_t  si_code  field;  see  sigac‐
124       tion(2) for details.
125
126   fork(2) semantics
127       After  a  fork(2),  the  child inherits a copy of the signalfd file de‐
128       scriptor.  A read(2) from the file descriptor in the child will  return
129       information about signals queued to the child.
130
131   Semantics of file descriptor passing
132       As with other file descriptors, signalfd file descriptors can be passed
133       to another process via a UNIX domain socket (see unix(7)).  In the  re‐
134       ceiving  process,  a read(2) from the received file descriptor will re‐
135       turn information about signals queued to that process.
136
137   execve(2) semantics
138       Just like any other file descriptor, a signalfd file descriptor remains
139       open  across  an execve(2), unless it has been marked for close-on-exec
140       (see fcntl(2)).  Any signals that were available for reading before the
141       execve(2) remain available to the newly loaded program.  (This is anal‐
142       ogous to traditional signal semantics, where a blocked signal  that  is
143       pending remains pending across an execve(2).)
144
145   Thread semantics
146       The  semantics  of signalfd file descriptors in a multithreaded program
147       mirror the standard semantics for signals.   In  other  words,  when  a
148       thread  reads from a signalfd file descriptor, it will read the signals
149       that are directed to the thread itself and the  signals  that  are  di‐
150       rected  to the process (i.e., the entire thread group).  (A thread will
151       not be able to read signals that are directed to other threads  in  the
152       process.)
153
154   epoll(7) semantics
155       If  a  process adds (via epoll_ctl(2)) a signalfd file descriptor to an
156       epoll(7) instance, then epoll_wait(2) returns events only  for  signals
157       sent  to that process.  In particular, if the process then uses fork(2)
158       to create a child process, then the child will be able to read(2)  sig‐
159       nals  that  are  sent  to  it  using  the signalfd file descriptor, but
160       epoll_wait(2) will not indicate that the signalfd  file  descriptor  is
161       ready.   In  this  scenario,  a  possible  workaround is that after the
162       fork(2), the child process can close the signalfd file descriptor  that
163       it  inherited  from the parent process and then create another signalfd
164       file descriptor and add it to the epoll instance.   Alternatively,  the
165       parent  and  the  child  could delay creating their (separate) signalfd
166       file descriptors and adding them to the epoll instance until after  the
167       call to fork(2).
168

RETURN VALUE

170       On  success, signalfd() returns a signalfd file descriptor; this is ei‐
171       ther a new file descriptor (if fd was -1), or fd if fd was a valid sig‐
172       nalfd  file  descriptor.   On error, -1 is returned and errno is set to
173       indicate the error.
174

ERRORS

176       EBADF  The fd file descriptor is not a valid file descriptor.
177
178       EINVAL fd is not a valid signalfd file descriptor.
179
180       EINVAL flags is invalid; or, in Linux 2.6.26 or earlier, flags is  non‐
181              zero.
182
183       EMFILE The per-process limit on the number of open file descriptors has
184              been reached.
185
186       ENFILE The system-wide limit on the total number of open files has been
187              reached.
188
189       ENODEV Could not mount (internal) anonymous inode device.
190
191       ENOMEM There  was insufficient memory to create a new signalfd file de‐
192              scriptor.
193

VERSIONS

195   C library/kernel differences
196       The underlying Linux  system  call  requires  an  additional  argument,
197       size_t  sizemask,  which  specifies the size of the mask argument.  The
198       glibc signalfd() wrapper function does not include this argument, since
199       it provides the required value for the underlying system call.
200
201       There  are  two  underlying Linux system calls: signalfd() and the more
202       recent signalfd4().  The former system call does not implement a  flags
203       argument.  The latter system call implements the flags values described
204       above.  Starting with glibc 2.9, the signalfd() wrapper  function  will
205       use signalfd4() where it is available.
206

STANDARDS

208       Linux.
209

HISTORY

211       signalfd()
212              Linux 2.6.22, glibc 2.8.
213
214       signalfd4()
215              Linux 2.6.27.
216

NOTES

218       A process can create multiple signalfd file descriptors.  This makes it
219       possible to accept different signals  on  different  file  descriptors.
220       (This may be useful if monitoring the file descriptors using select(2),
221       poll(2), or epoll(7): the arrival of different signals will  make  dif‐
222       ferent  file  descriptors  ready.)   If a signal appears in the mask of
223       more than one of the file descriptors, then occurrences of that  signal
224       can be read (once) from any one of the file descriptors.
225
226       Attempts to include SIGKILL and SIGSTOP in mask are silently ignored.
227
228       The  signal  mask  employed by a signalfd file descriptor can be viewed
229       via the entry for the corresponding file descriptor  in  the  process's
230       /proc/pid/fdinfo directory.  See proc(5) for further details.
231
232   Limitations
233       The  signalfd  mechanism can't be used to receive signals that are syn‐
234       chronously generated, such as the SIGSEGV signal that results from  ac‐
235       cessing  an  invalid  memory  address or the SIGFPE signal that results
236       from an arithmetic error.  Such signals can be caught only  via  signal
237       handler.
238
239       As described above, in normal usage one blocks the signals that will be
240       accepted via signalfd().  If spawning a  child  process  to  execute  a
241       helper program (that does not need the signalfd file descriptor), then,
242       after the call to fork(2), you will normally want to unblock those sig‐
243       nals  before  calling execve(2), so that the helper program can see any
244       signals that it expects to see.  Be aware, however, that this won't  be
245       possible  in  the case of a helper program spawned behind the scenes by
246       any library function that the program may call.   In  such  cases,  one
247       must  fall  back to using a traditional signal handler that writes to a
248       file descriptor monitored by select(2), poll(2), or epoll(7).
249

BUGS

251       Before Linux 2.6.25, the ssi_ptr and ssi_int fields are not  filled  in
252       with the data accompanying a signal sent by sigqueue(3).
253

EXAMPLES

255       The program below accepts the signals SIGINT and SIGQUIT via a signalfd
256       file descriptor.  The program terminates after accepting a SIGQUIT sig‐
257       nal.  The following shell session demonstrates the use of the program:
258
259           $ ./signalfd_demo
260           ^C                   # Control-C generates SIGINT
261           Got SIGINT
262           ^C
263           Got SIGINT
264           ^\                    # Control-\ generates SIGQUIT
265           Got SIGQUIT
266           $
267
268   Program source
269
270       #include <err.h>
271       #include <signal.h>
272       #include <stdio.h>
273       #include <stdlib.h>
274       #include <sys/signalfd.h>
275       #include <unistd.h>
276
277       int
278       main(void)
279       {
280           int                      sfd;
281           ssize_t                  s;
282           sigset_t                 mask;
283           struct signalfd_siginfo  fdsi;
284
285           sigemptyset(&mask);
286           sigaddset(&mask, SIGINT);
287           sigaddset(&mask, SIGQUIT);
288
289           /* Block signals so that they aren't handled
290              according to their default dispositions. */
291
292           if (sigprocmask(SIG_BLOCK, &mask, NULL) == -1)
293               err(EXIT_FAILURE, "sigprocmask");
294
295           sfd = signalfd(-1, &mask, 0);
296           if (sfd == -1)
297               err(EXIT_FAILURE, "signalfd");
298
299           for (;;) {
300               s = read(sfd, &fdsi, sizeof(fdsi));
301               if (s != sizeof(fdsi))
302                   err(EXIT_FAILURE, "read");
303
304               if (fdsi.ssi_signo == SIGINT) {
305                   printf("Got SIGINT\n");
306               } else if (fdsi.ssi_signo == SIGQUIT) {
307                   printf("Got SIGQUIT\n");
308                   exit(EXIT_SUCCESS);
309               } else {
310                   printf("Read unexpected signal\n");
311               }
312           }
313       }
314

SEE ALSO

316       eventfd(2),  poll(2), read(2), select(2), sigaction(2), sigprocmask(2),
317       sigwaitinfo(2), timerfd_create(2), sigsetops(3), sigwait(3),  epoll(7),
318       signal(7)
319
320
321
322Linux man-pages 6.04              2023-03-30                       signalfd(2)
Impressum