1SIGNALFD(2)                Linux Programmer's Manual               SIGNALFD(2)
2
3
4

NAME

6       signalfd - create a file descriptor for accepting signals
7

SYNOPSIS

9       #include <sys/signalfd.h>
10
11       int signalfd(int fd, const sigset_t *mask, int flags);
12

DESCRIPTION

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

RETURN VALUE

153       On success, signalfd() returns a  signalfd  file  descriptor;  this  is
154       either  a  new  file descriptor (if fd was -1), or fd if fd was a valid
155       signalfd file descriptor.  On error, -1 is returned and errno is set to
156       indicate the error.
157

ERRORS

159       EBADF  The fd file descriptor is not a valid file descriptor.
160
161       EINVAL fd is not a valid signalfd file descriptor.
162
163       EINVAL flags  is  invalid;  or,  in  Linux  2.6.26 or earlier, flags is
164              nonzero.
165
166       EMFILE The per-process limit on the number of open file descriptors has
167              been reached.
168
169       ENFILE The system-wide limit on the total number of open files has been
170              reached.
171
172       ENODEV Could not mount (internal) anonymous inode device.
173
174       ENOMEM There was insufficient memory to  create  a  new  signalfd  file
175              descriptor.
176

VERSIONS

178       signalfd()  is available on Linux since kernel 2.6.22.  Working support
179       is provided in glibc since version 2.8.  The  signalfd4()  system  call
180       (see NOTES) is available on Linux since kernel 2.6.27.
181

CONFORMING TO

183       signalfd() and signalfd4() are Linux-specific.
184

NOTES

186       A process can create multiple signalfd file descriptors.  This makes it
187       possible to accept different signals  on  different  file  descriptors.
188       (This may be useful if monitoring the file descriptors using select(2),
189       poll(2), or epoll(7): the arrival of different signals will  make  dif‐
190       ferent  file  descriptors  ready.)   If a signal appears in the mask of
191       more than one of the file descriptors, then occurrences of that  signal
192       can be read (once) from any one of the file descriptors.
193
194       Attempts to include SIGKILL and SIGSTOP in mask are silently ignored.
195
196       The  signal  mask  employed by a signalfd file descriptor can be viewed
197       via the entry for the corresponding file descriptor  in  the  process's
198       /proc/[pid]/fdinfo directory.  See proc(5) for further details.
199
200   Limitations
201       The  signalfd  mechanism can't be used to receive signals that are syn‐
202       chronously generated, such as the  SIGSEGV  signal  that  results  from
203       accessing  an  invalid memory address or the SIGFPE signal that results
204       from an arithmetic error.  Such signals can be caught only  via  signal
205       handler.
206
207       As described above, in normal usage one blocks the signals that will be
208       accepted via signalfd().  If spawning a  child  process  to  execute  a
209       helper program (that does not need the signalfd file descriptor), then,
210       after the call to fork(2), you will normally want to unblock those sig‐
211       nals  before  calling execve(2), so that the helper program can see any
212       signals that it expects to see.  Be aware, however, that this won't  be
213       possible  in  the case of a helper program spawned behind the scenes by
214       any library function that the program may call.   In  such  cases,  one
215       must  fall  back to using a traditional signal handler that writes to a
216       file descriptor monitored by select(2), poll(2), or epoll(7),
217
218   C library/kernel differences
219       The underlying Linux  system  call  requires  an  additional  argument,
220       size_t  sizemask,  which  specifies the size of the mask argument.  The
221       glibc signalfd() wrapper function does not include this argument, since
222       it provides the required value for the underlying system call.
223
224       There  are  two  underlying Linux system calls: signalfd() and the more
225       recent signalfd4().  The former system call does not implement a  flags
226       argument.  The latter system call implements the flags values described
227       above.  Starting with glibc 2.9, the signalfd() wrapper  function  will
228       use signalfd4() where it is available.
229

BUGS

231       In kernels before 2.6.25, the ssi_ptr and ssi_int fields are not filled
232       in with the data accompanying a signal sent by sigqueue(3).
233

EXAMPLE

235       The program below accepts the signals SIGINT and SIGQUIT via a signalfd
236       file descriptor.  The program terminates after accepting a SIGQUIT sig‐
237       nal.  The following shell session demonstrates the use of the program:
238
239           $ ./signalfd_demo
240           ^C                   # Control-C generates SIGINT
241           Got SIGINT
242           ^C
243           Got SIGINT
244           ^\                    # Control-\ generates SIGQUIT
245           Got SIGQUIT
246           $
247
248   Program source
249
250       #include <sys/signalfd.h>
251       #include <signal.h>
252       #include <unistd.h>
253       #include <stdlib.h>
254       #include <stdio.h>
255
256       #define handle_error(msg) \
257           do { perror(msg); exit(EXIT_FAILURE); } while (0)
258
259       int
260       main(int argc, char *argv[])
261       {
262           sigset_t mask;
263           int sfd;
264           struct signalfd_siginfo fdsi;
265           ssize_t s;
266
267           sigemptyset(&mask);
268           sigaddset(&mask, SIGINT);
269           sigaddset(&mask, SIGQUIT);
270
271           /* Block signals so that they aren't handled
272              according to their default dispositions */
273
274           if (sigprocmask(SIG_BLOCK, &mask, NULL) == -1)
275               handle_error("sigprocmask");
276
277           sfd = signalfd(-1, &mask, 0);
278           if (sfd == -1)
279               handle_error("signalfd");
280
281           for (;;) {
282               s = read(sfd, &fdsi, sizeof(struct signalfd_siginfo));
283               if (s != sizeof(struct signalfd_siginfo))
284                   handle_error("read");
285
286               if (fdsi.ssi_signo == SIGINT) {
287                   printf("Got SIGINT\n");
288               } else if (fdsi.ssi_signo == SIGQUIT) {
289                   printf("Got SIGQUIT\n");
290                   exit(EXIT_SUCCESS);
291               } else {
292                   printf("Read unexpected signal\n");
293               }
294           }
295       }
296

SEE ALSO

298       eventfd(2), poll(2), read(2), select(2), sigaction(2),  sigprocmask(2),
299       sigwaitinfo(2),  timerfd_create(2), sigsetops(3), sigwait(3), epoll(7),
300       signal(7)
301

COLOPHON

303       This page is part of release 5.02 of the Linux  man-pages  project.   A
304       description  of  the project, information about reporting bugs, and the
305       latest    version    of    this    page,    can     be     found     at
306       https://www.kernel.org/doc/man-pages/.
307
308
309
310Linux                             2019-03-06                       SIGNALFD(2)
Impressum