original/man2/signalfd.2

   1 .\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" starting from a version by Davide Libenzi <davidel@xmailserver.org>
   3 .\"
   4 .\" This program is free software; you can redistribute it and/or modify
   5 .\" it under the terms of the GNU General Public License as published by
   6 .\" the Free Software Foundation; either version 2 of the License, or
   7 .\" (at your option) any later version.
   8 .\"
   9 .\" This program is distributed in the hope that it will be useful,
  10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 .\" GNU General Public License for more details.
  13 .\"
  14 .\" You should have received a copy of the GNU General Public License
  15 .\" along with this program; if not, write to the Free Software
  16 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
  17 .\" MA  02111-1307  USA
  18 .\"
  19 .TH SIGNALFD 2 2009-01-13 Linux "Linux Programmer's Manual"
  20 .SH NAME
  21 signalfd \- create a file descriptor for accepting signals
  22 .SH SYNOPSIS
  23 .B #include <sys/signalfd.h>
  24 .sp
  25 .BI "int signalfd(int " fd ", const sigset_t *" mask ", int " flags );
  26 .SH DESCRIPTION
  27 .BR signalfd ()
  28 creates a file descriptor that can be used to accept signals
  29 targeted at the caller.
  30 This provides an alternative to the use of a signal handler or
  31 .BR sigwaitinfo (2),
  32 and has the advantage that the file descriptor may be monitored by
  33 .BR select (2),
  34 .BR poll (2),
  35 and
  36 .BR epoll (7).
  37
  38 The
  39 .I mask
  40 argument specifies the set of signals that the caller
  41 wishes to accept via the file descriptor.
  42 This argument is a signal set whose contents can be initialized
  43 using the macros described in
  44 .BR sigsetops (3).
  45 Normally, the set of signals to be received via the
  46 file descriptor should be blocked using
  47 .BR sigprocmask (2),
  48 to prevent the signals being handled according to their default
  49 dispositions.
  50 It is not possible to receive
  51 .B SIGKILL
  52 or
  53 .B SIGSTOP
  54 signals via a signalfd file descriptor;
  55 these signals are silently ignored if specified in
  56 .IR mask .
  57
  58 If the
  59 .I fd
  60 argument is \-1,
  61 then the call creates a new file descriptor and associates the
  62 signal set specified in
  63 .I mask
  64 with that descriptor.
  65 If
  66 .I fd
  67 is not \-1,
  68 then it must specify a valid existing signalfd file descriptor, and
  69 .I mask
  70 is used to replace the signal set associated with that descriptor.
  71
  72 Starting with Linux 2.6.27, the following values may be bitwise ORed in
  73 .IR flags
  74 to change the behaviour of
  75 .BR signalfd ():
  76 .TP 14
  77 .B SFD_NONBLOCK
  78 Set the
  79 .BR O_NONBLOCK
  80 file status flag on the new open file description.
  81 Using this flag saves extra calls to
  82 .BR fcntl (2)
  83 to achieve the same result.
  84 .TP
  85 .B SFD_CLOEXEC
  86 Set the close-on-exec
  87 .RB ( FD_CLOEXEC )
  88 flag on the new file descriptor.
  89 See the description of the
  90 .B O_CLOEXEC
  91 flag in
  92 .BR open (2)
  93 for reasons why this may be useful.
  94 .PP
  95 In Linux up to version 2.6.26, the
  96 .I flags
  97 argument is unused, and must be specified as zero.
  98
  99 .BR signalfd ()
 100 returns a file descriptor that supports the following operations:
 101 .TP
 102 .BR read (2)
 103 If one or more of the signals specified in
 104 .I mask
 105 is pending for the process, then the buffer supplied to
 106 .BR read (2)
 107 is used to return one or more
 108 .I signalfd_siginfo
 109 structures (see below) that describe the signals.
 110 The
 111 .BR read (2)
 112 returns information for as many signals as are pending and will
 113 fit in the supplied buffer.
 114 The buffer must be at least
 115 .I "sizeof(struct signalfd_siginfo)"
 116 bytes.
 117 The return value of the
 118 .BR read (2)
 119 is the total number of bytes read.
 120 .IP
 121 As a consequence of the
 122 .BR read (2),
 123 the signals are consumed,
 124 so that they are no longer pending for the process
 125 (i.e., will not be caught by signal handlers,
 126 and cannot be accepted using
 127 .BR sigwaitinfo (2)).
 128 .IP
 129 If none of the signals in
 130 .I mask
 131 is pending for the process, then the
 132 .BR read (2)
 133 either blocks until one of the signals in
 134 .I mask
 135 is generated for the process,
 136 or fails with the error
 137 .B EAGAIN
 138 if the file descriptor has been made nonblocking.
 139 .TP
 140 .BR poll "(2), " select "(2) (and similar)"
 141 The file descriptor is readable
 142 (the
 143 .BR select (2)
 144 .I readfds
 145 argument; the
 146 .BR poll (2)
 147 .B POLLIN
 148 flag)
 149 if one or more of the signals in
 150 .I mask
 151 is pending for the process.
 152 .IP
 153 The signalfd file descriptor also supports the other file-descriptor
 154 multiplexing APIs:
 155 .BR pselect (2),
 156 .BR ppoll (2),
 157 and
 158 .BR epoll (7).
 159 .TP
 160 .BR close (2)
 161 When the file descriptor is no longer required it should be closed.
 162 When all file descriptors associated with the same signalfd object
 163 have been closed, the resources for object are freed by the kernel.
 164 .SS The signalfd_siginfo structure
 165 The format of the
 166 .I signalfd_siginfo
 167 structure(s) returned by
 168 .BR read (2)s
 169 from a signalfd file descriptor is as follows:
 170 .in +4n
 171 .nf
 172
 173 struct signalfd_siginfo {
 174     uint32_t ssi_signo;   /* Signal number */
 175     int32_t  ssi_errno;   /* Error number (unused) */
 176     int32_t  ssi_code;    /* Signal code */
 177     uint32_t ssi_pid;     /* PID of sender */
 178     uint32_t ssi_uid;     /* Real UID of sender */
 179     int32_t  ssi_fd;      /* File descriptor (SIGIO) */
 180     uint32_t ssi_tid;     /* Kernel timer ID (POSIX timers)
 181     uint32_t ssi_band;    /* Band event (SIGIO) */
 182     uint32_t ssi_overrun; /* POSIX timer overrun count */
 183     uint32_t ssi_trapno;  /* Trap number that caused signal */
 184 .\" ssi_trapno is unused on most arches
 185     int32_t  ssi_status;  /* Exit status or signal (SIGCHLD) */
 186     int32_t  ssi_int;     /* Integer sent by sigqueue(2) */
 187     uint64_t ssi_ptr;     /* Pointer sent by sigqueue(2) */
 188     uint64_t ssi_utime;   /* User CPU time consumed (SIGCHLD) */
 189     uint64_t ssi_stime;   /* System CPU time consumed (SIGCHLD) */
 190     uint64_t ssi_addr;    /* Address that generated signal
 191                              (for hardware-generated signals) */
 192     uint8_t  pad[\fIX\fP];      /* Pad size to 128 bytes (allow for
 193                               additional fields in the future) */
 194 };
 195
 196 .fi
 197 .in
 198 Each of the fields in this structure
 199 is analogous to the similarly named field in the
 200 .I siginfo_t
 201 structure.
 202 The
 203 .I siginfo_t
 204 structure is described in
 205 .BR sigaction (2).
 206 Not all fields in the returned
 207 .I signalfd_siginfo
 208 structure will be valid for a specific signal;
 209 the set of valid fields can be determined from the value returned in the
 210 .I ssi_code
 211 field.
 212 This field is the analog of the
 213 .I siginfo_t
 214 .I si_code
 215 field; see
 216 .BR sigaction (2)
 217 for details.
 218 .SS fork(2) semantics
 219 After a
 220 .BR fork (2),
 221 the child inherits a copy of the signalfd file descriptor.
 222 A
 223 .BR read (2)
 224 from the file descriptor in the child will return information
 225 about signals queued to the child.
 226 .SS execve(2) semantics
 227 Just like any other file descriptor,
 228 a signalfd file descriptor remains open across an
 229 .BR execve (2),
 230 unless it has been marked for close-on-exec (see
 231 .BR fcntl (2)).
 232 Any signals that were available for reading before the
 233 .BR execve (2)
 234 remain available to the newly loaded program.
 235 (This is analogous to traditional signal semantics,
 236 where a blocked signal that is pending remains pending across an
 237 .BR execve (2).)
 238 .SS Thread semantics
 239 The semantics of signalfd file descriptors in a multithreaded program
 240 mirror the standard semantics for signals.
 241 In other words,
 242 when a thread reads from a signalfd file descriptor,
 243 it will read the signals that are directed to the thread
 244 itself and the signals that are directed to the process
 245 (i.e., the entire thread group).
 246 (A thread will not be able to read signals that are directed
 247 to other threads in the process.)
 248 .SH "RETURN VALUE"
 249 On success,
 250 .BR signalfd ()
 251 returns a signalfd file descriptor;
 252 this is either a new file descriptor (if
 253 .I fd
 254 was \-1), or
 255 .I fd
 256 if
 257 .I fd
 258 was a valid signalfd file descriptor.
 259 On error, \-1 is returned and
 260 .I errno
 261 is set to indicate the error.
 262 .SH ERRORS
 263 .TP
 264 .B EBADF
 265 The
 266 .I fd
 267 file descriptor is not a valid file descriptor.
 268 .TP
 269 .B EINVAL
 270 .I fd
 271 is not a valid signalfd file descriptor.
 272 .\" or, the
 273 .\" .I sizemask
 274 .\" argument is not equal to
 275 .\" .IR sizeof(sigset_t) ;
 276 .TP
 277 .B EINVAL
 278 .I flags
 279 is invalid;
 280 or, in Linux 2.6.26 or earlier,
 281 .I flags
 282 is nonzero.
 283 .TP
 284 .B EMFILE
 285 The per-process limit of open file descriptors has been reached.
 286 .TP
 287 .B ENFILE
 288 The system-wide limit on the total number of open files has been
 289 reached.
 290 .TP
 291 .B ENODEV
 292 Could not mount (internal) anonymous inode device.
 293 .TP
 294 .B ENOMEM
 295 There was insufficient memory to create a new signalfd file descriptor.
 296 .SH VERSIONS
 297 .BR signalfd ()
 298 is available on Linux since kernel 2.6.22.
 299 Working support is provided in glibc since version 2.8.
 300 .\" signalfd() is in glibc 2.7, but reportedly does not build
 301 The
 302 .BR signalfd4 ()
 303 system call (see NOTES) is available on Linux since kernel 2.6.27.
 304 .SH CONFORMING TO
 305 .BR signalfd ()
 306 and
 307 .BR signalfd4 ()
 308 are Linux-specific.
 309 .SH NOTES
 310 The underlying Linux system call requires an additional argument,
 311 .IR "size_t sizemask" ,
 312 which specifies the size of the
 313 .I mask
 314 argument.
 315 The glibc
 316 .BR signalfd ()
 317 wrapper function does not include this argument,
 318 since it provides the required value for the underlying system call.
 319
 320 A process can create multiple signalfd file descriptors.
 321 This makes it possible to accept different signals
 322 on different file descriptors.
 323 (This may be useful if monitoring the file descriptors using
 324 .BR select (2),
 325 .BR poll (2),
 326 or
 327 .BR epoll (7):
 328 the arrival of different signals will make different descriptors ready.)
 329 If a signal appears in the
 330 .I mask
 331 of more than one of the file descriptors, then occurrences
 332 of that signal can be read (once) from any one of the descriptors.
 333 .SS Underlying Linux system calls
 334 There are two underlying Linux system calls:
 335 .BR signalfd ()
 336 and the more recent
 337 .BR signalfd4 ().
 338 The former system call does not implement a
 339 .I flags
 340 argument.
 341 The latter system call implements the
 342 .I flags
 343 values described above.
 344 Starting with glibc 2.9, the
 345 .BR signalfd ()
 346 wrapper function will use
 347 .BR signalfd4 ()
 348 where it is available.
 349 .SH BUGS
 350 In kernels before 2.6.25, the
 351 .I ssi_ptr
 352 and
 353 .I ssi_int
 354 fields are not filled in with the data accompanying a signal sent by
 355 .BR sigqueue (2).
 356 .\" The fix also was put into 2.6.24.5
 357 .SH EXAMPLE
 358 The program below accepts the signals
 359 .B SIGINT
 360 and
 361 .B SIGQUIT
 362 via a signalfd file descriptor.
 363 The program terminates after accepting a
 364 .B SIGQUIT
 365 signal.
 366 The following shell session demonstrates the use of the program:
 367 .in +4n
 368 .nf
 369
 370 .RB "$" " ./signalfd_demo"
 371 .BR "^C" "                   # Control\-C generates SIGINT"
 372 Got SIGINT
 373 .B ^C
 374 Got SIGINT
 375 \fB^\\\fP                    # Control\-\\ generates SIGQUIT
 376 Got SIGQUIT
 377 $
 378 .fi
 379 .in
 380 .SS Program source
 381 \&
 382 .nf
 383 #include <sys/signalfd.h>
 384 #include <signal.h>
 385 #include <unistd.h>
 386 #include <stdlib.h>
 387 #include <stdio.h>
 388
 389 #define handle_error(msg) \\
 390     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 391
 392 int
 393 main(int argc, char *argv[])
 394 {
 395     sigset_t mask;
 396     int sfd;
 397     struct signalfd_siginfo fdsi;
 398     ssize_t s;
 399
 400     sigemptyset(&mask);
 401     sigaddset(&mask, SIGINT);
 402     sigaddset(&mask, SIGQUIT);
 403
 404     /* Block signals so that they aren\(aqt handled
 405        according to their default dispositions */
 406
 407     if (sigprocmask(SIG_BLOCK, &mask, NULL) == \-1)
 408         handle_error("sigprocmask");
 409
 410     sfd = signalfd(\-1, &mask, 0);
 411     if (sfd == \-1)
 412         handle_error("signalfd");
 413
 414     for (;;) {
 415         s = read(sfd, &fdsi, sizeof(struct signalfd_siginfo));
 416         if (s != sizeof(struct signalfd_siginfo))
 417             handle_error("read");
 418
 419         if (fdsi.ssi_signo == SIGINT) {
 420             printf("Got SIGINT\\n");
 421         } else if (fdsi.ssi_signo == SIGQUIT) {
 422             printf("Got SIGQUIT\\n");
 423             exit(EXIT_SUCCESS);
 424         } else {
 425             printf("Read unexpected signal\\n");
 426         }
 427     }
 428 }
 429 .fi
 430 .SH "SEE ALSO"
 431 .BR eventfd (2),
 432 .BR poll (2),
 433 .BR read (2),
 434 .BR select (2),
 435 .BR sigaction (2),
 436 .BR sigprocmask (2),
 437 .BR sigwaitinfo (2),
 438 .BR timerfd_create (2),
 439 .BR sigsetops (3),
 440 .BR sigwait (3),
 441 .BR epoll (7),
 442 .BR signal (7)