| .\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" starting from a version by Davide Libenzi <davidel@xmailserver.org> |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_SW_3_PARA) |
| .\" This program is free software; you can redistribute it and/or modify |
| .\" it under the terms of the GNU General Public License as published by |
| .\" the Free Software Foundation; either version 2 of the License, or |
| .\" (at your option) any later version. |
| .\" |
| .\" This program is distributed in the hope that it will be useful, |
| .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| .\" GNU General Public License for more details. |
| .\" |
| .\" You should have received a copy of the GNU General Public |
| .\" License along with this manual; if not, see |
| .\" <http://www.gnu.org/licenses/>. |
| .\" %%%LICENSE_END |
| .\" |
| .TH SIGNALFD 2 2021-03-22 Linux "Linux Programmer's Manual" |
| .SH NAME |
| signalfd \- create a file descriptor for accepting signals |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/signalfd.h> |
| .PP |
| .BI "int signalfd(int " fd ", const sigset_t *" mask ", int " flags ); |
| .fi |
| .SH DESCRIPTION |
| .BR signalfd () |
| creates a file descriptor that can be used to accept signals |
| targeted at the caller. |
| This provides an alternative to the use of a signal handler or |
| .BR sigwaitinfo (2), |
| and has the advantage that the file descriptor may be monitored by |
| .BR select (2), |
| .BR poll (2), |
| and |
| .BR epoll (7). |
| .PP |
| The |
| .I mask |
| argument specifies the set of signals that the caller |
| wishes to accept via the file descriptor. |
| This argument is a signal set whose contents can be initialized |
| using the macros described in |
| .BR sigsetops (3). |
| Normally, the set of signals to be received via the |
| file descriptor should be blocked using |
| .BR sigprocmask (2), |
| to prevent the signals being handled according to their default |
| dispositions. |
| It is not possible to receive |
| .B SIGKILL |
| or |
| .B SIGSTOP |
| signals via a signalfd file descriptor; |
| these signals are silently ignored if specified in |
| .IR mask . |
| .PP |
| If the |
| .I fd |
| argument is \-1, |
| then the call creates a new file descriptor and associates the |
| signal set specified in |
| .I mask |
| with that file descriptor. |
| If |
| .I fd |
| is not \-1, |
| then it must specify a valid existing signalfd file descriptor, and |
| .I mask |
| is used to replace the signal set associated with that file descriptor. |
| .PP |
| Starting with Linux 2.6.27, the following values may be bitwise ORed in |
| .IR flags |
| to change the behavior of |
| .BR signalfd (): |
| .TP 14 |
| .B SFD_NONBLOCK |
| Set the |
| .BR O_NONBLOCK |
| file status flag on the open file description (see |
| .BR open (2)) |
| referred to by the new file descriptor. |
| Using this flag saves extra calls to |
| .BR fcntl (2) |
| to achieve the same result. |
| .TP |
| .B SFD_CLOEXEC |
| Set the close-on-exec |
| .RB ( FD_CLOEXEC ) |
| flag on the new file descriptor. |
| See the description of the |
| .B O_CLOEXEC |
| flag in |
| .BR open (2) |
| for reasons why this may be useful. |
| .PP |
| In Linux up to version 2.6.26, the |
| .I flags |
| argument is unused, and must be specified as zero. |
| .PP |
| .BR signalfd () |
| returns a file descriptor that supports the following operations: |
| .TP |
| .BR read (2) |
| If one or more of the signals specified in |
| .I mask |
| is pending for the process, then the buffer supplied to |
| .BR read (2) |
| is used to return one or more |
| .I signalfd_siginfo |
| structures (see below) that describe the signals. |
| The |
| .BR read (2) |
| returns information for as many signals as are pending and will |
| fit in the supplied buffer. |
| The buffer must be at least |
| .I "sizeof(struct signalfd_siginfo)" |
| bytes. |
| The return value of the |
| .BR read (2) |
| is the total number of bytes read. |
| .IP |
| As a consequence of the |
| .BR read (2), |
| the signals are consumed, |
| so that they are no longer pending for the process |
| (i.e., will not be caught by signal handlers, |
| and cannot be accepted using |
| .BR sigwaitinfo (2)). |
| .IP |
| If none of the signals in |
| .I mask |
| is pending for the process, then the |
| .BR read (2) |
| either blocks until one of the signals in |
| .I mask |
| is generated for the process, |
| or fails with the error |
| .B EAGAIN |
| if the file descriptor has been made nonblocking. |
| .TP |
| .BR poll "(2), " select "(2) (and similar)" |
| The file descriptor is readable |
| (the |
| .BR select (2) |
| .I readfds |
| argument; the |
| .BR poll (2) |
| .B POLLIN |
| flag) |
| if one or more of the signals in |
| .I mask |
| is pending for the process. |
| .IP |
| The signalfd file descriptor also supports the other file-descriptor |
| multiplexing APIs: |
| .BR pselect (2), |
| .BR ppoll (2), |
| and |
| .BR epoll (7). |
| .TP |
| .BR close (2) |
| When the file descriptor is no longer required it should be closed. |
| When all file descriptors associated with the same signalfd object |
| have been closed, the resources for object are freed by the kernel. |
| .SS The signalfd_siginfo structure |
| The format of the |
| .I signalfd_siginfo |
| structure(s) returned by |
| .BR read (2)s |
| from a signalfd file descriptor is as follows: |
| .PP |
| .in +4n |
| .EX |
| struct signalfd_siginfo { |
| uint32_t ssi_signo; /* Signal number */ |
| int32_t ssi_errno; /* Error number (unused) */ |
| int32_t ssi_code; /* Signal code */ |
| uint32_t ssi_pid; /* PID of sender */ |
| uint32_t ssi_uid; /* Real UID of sender */ |
| int32_t ssi_fd; /* File descriptor (SIGIO) */ |
| uint32_t ssi_tid; /* Kernel timer ID (POSIX timers) |
| uint32_t ssi_band; /* Band event (SIGIO) */ |
| uint32_t ssi_overrun; /* POSIX timer overrun count */ |
| uint32_t ssi_trapno; /* Trap number that caused signal */ |
| .\" ssi_trapno is unused on most arches |
| int32_t ssi_status; /* Exit status or signal (SIGCHLD) */ |
| int32_t ssi_int; /* Integer sent by sigqueue(3) */ |
| uint64_t ssi_ptr; /* Pointer sent by sigqueue(3) */ |
| uint64_t ssi_utime; /* User CPU time consumed (SIGCHLD) */ |
| uint64_t ssi_stime; /* System CPU time consumed |
| (SIGCHLD) */ |
| uint64_t ssi_addr; /* Address that generated signal |
| (for hardware\-generated signals) */ |
| uint16_t ssi_addr_lsb; /* Least significant bit of address |
| (SIGBUS; since Linux 2.6.37) |
| .\" ssi_addr_lsb: commit b8aeec34175fc8fe8b0d40efea4846dfc1ba663e |
| uint8_t pad[\fIX\fP]; /* Pad size to 128 bytes (allow for |
| additional fields in the future) */ |
| }; |
| .EE |
| .in |
| .PP |
| Each of the fields in this structure |
| is analogous to the similarly named field in the |
| .I siginfo_t |
| structure. |
| The |
| .I siginfo_t |
| structure is described in |
| .BR sigaction (2). |
| Not all fields in the returned |
| .I signalfd_siginfo |
| structure will be valid for a specific signal; |
| the set of valid fields can be determined from the value returned in the |
| .I ssi_code |
| field. |
| This field is the analog of the |
| .I siginfo_t |
| .I si_code |
| field; see |
| .BR sigaction (2) |
| for details. |
| .SS fork(2) semantics |
| After a |
| .BR fork (2), |
| the child inherits a copy of the signalfd file descriptor. |
| A |
| .BR read (2) |
| from the file descriptor in the child will return information |
| about signals queued to the child. |
| .SS Semantics of file descriptor passing |
| As with other file descriptors, |
| signalfd file descriptors can be passed to another process |
| via a UNIX domain socket (see |
| .BR unix (7)). |
| In the receiving process, a |
| .BR read (2) |
| from the received file descriptor will return information |
| about signals queued to that process. |
| .SS execve(2) semantics |
| Just like any other file descriptor, |
| a signalfd file descriptor remains open across an |
| .BR execve (2), |
| unless it has been marked for close-on-exec (see |
| .BR fcntl (2)). |
| Any signals that were available for reading before the |
| .BR execve (2) |
| remain available to the newly loaded program. |
| (This is analogous to traditional signal semantics, |
| where a blocked signal that is pending remains pending across an |
| .BR execve (2).) |
| .SS Thread semantics |
| The semantics of signalfd file descriptors in a multithreaded program |
| mirror the standard semantics for signals. |
| In other words, |
| when a thread reads from a signalfd file descriptor, |
| it will read the signals that are directed to the thread |
| itself and the signals that are directed to the process |
| (i.e., the entire thread group). |
| (A thread will not be able to read signals that are directed |
| to other threads in the process.) |
| .\" |
| .SS epoll(7) semantics |
| If a process adds (via |
| .BR epoll_ctl (2)) |
| a signalfd file descriptor to an |
| .BR epoll (7) |
| instance, then |
| .BR epoll_wait (2) |
| returns events only for signals sent to that process. |
| In particular, if the process then uses |
| .BR fork (2) |
| to create a child process, then the child will be able to |
| .BR read (2) |
| signals that are sent to it using the signalfd file descriptor, but |
| .BR epoll_wait (2) |
| will |
| .B not |
| indicate that the signalfd file descriptor is ready. |
| In this scenario, a possible workaround is that after the |
| .BR fork (2), |
| the child process can close the signalfd file descriptor that it inherited |
| from the parent process and then create another signalfd file descriptor |
| and add it to the epoll instance. |
| Alternatively, the parent and the child could delay creating their |
| (separate) signalfd file descriptors and adding them to the |
| epoll instance until after the call to |
| .BR fork (2). |
| .SH RETURN VALUE |
| On success, |
| .BR signalfd () |
| returns a signalfd file descriptor; |
| this is either a new file descriptor (if |
| .I fd |
| was \-1), or |
| .I fd |
| if |
| .I fd |
| was a valid signalfd file descriptor. |
| On error, \-1 is returned and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EBADF |
| The |
| .I fd |
| file descriptor is not a valid file descriptor. |
| .TP |
| .B EINVAL |
| .I fd |
| is not a valid signalfd file descriptor. |
| .\" or, the |
| .\" .I sizemask |
| .\" argument is not equal to |
| .\" .IR sizeof(sigset_t) ; |
| .TP |
| .B EINVAL |
| .I flags |
| is invalid; |
| or, in Linux 2.6.26 or earlier, |
| .I flags |
| is nonzero. |
| .TP |
| .B EMFILE |
| The per-process limit on the number of open file descriptors has been reached. |
| .TP |
| .B ENFILE |
| The system-wide limit on the total number of open files has been |
| reached. |
| .TP |
| .B ENODEV |
| Could not mount (internal) anonymous inode device. |
| .TP |
| .B ENOMEM |
| There was insufficient memory to create a new signalfd file descriptor. |
| .SH VERSIONS |
| .BR signalfd () |
| is available on Linux since kernel 2.6.22. |
| Working support is provided in glibc since version 2.8. |
| .\" signalfd() is in glibc 2.7, but reportedly does not build |
| The |
| .BR signalfd4 () |
| system call (see NOTES) is available on Linux since kernel 2.6.27. |
| .SH CONFORMING TO |
| .BR signalfd () |
| and |
| .BR signalfd4 () |
| are Linux-specific. |
| .SH NOTES |
| A process can create multiple signalfd file descriptors. |
| This makes it possible to accept different signals |
| on different file descriptors. |
| (This may be useful if monitoring the file descriptors using |
| .BR select (2), |
| .BR poll (2), |
| or |
| .BR epoll (7): |
| the arrival of different signals will make different file descriptors ready.) |
| If a signal appears in the |
| .I mask |
| of more than one of the file descriptors, then occurrences |
| of that signal can be read (once) from any one of the file descriptors. |
| .PP |
| Attempts to include |
| .B SIGKILL |
| and |
| .B SIGSTOP |
| in |
| .I mask |
| are silently ignored. |
| .PP |
| The signal mask employed by a signalfd file descriptor can be viewed |
| via the entry for the corresponding file descriptor in the process's |
| .IR /proc/[pid]/fdinfo |
| directory. |
| See |
| .BR proc (5) |
| for further details. |
| .\" |
| .SS Limitations |
| The signalfd mechanism can't be used to receive signals that |
| are synchronously generated, such as the |
| .BR SIGSEGV |
| signal that results from accessing an invalid memory address |
| or the |
| .BR SIGFPE |
| signal that results from an arithmetic error. |
| Such signals can be caught only via signal handler. |
| .PP |
| As described above, |
| in normal usage one blocks the signals that will be accepted via |
| .BR signalfd (). |
| If spawning a child process to execute a helper program |
| (that does not need the signalfd file descriptor), |
| then, after the call to |
| .BR fork (2), |
| you will normally want to unblock those signals before calling |
| .BR execve (2), |
| so that the helper program can see any signals that it expects to see. |
| Be aware, however, |
| that this won't be possible in the case of a helper program spawned |
| behind the scenes by any library function that the program may call. |
| In such cases, one must fall back to using a traditional signal |
| handler that writes to a file descriptor monitored by |
| .BR select (2), |
| .BR poll (2), |
| or |
| .BR epoll (7). |
| .\" |
| .SS C library/kernel differences |
| The underlying Linux system call requires an additional argument, |
| .IR "size_t sizemask" , |
| which specifies the size of the |
| .I mask |
| argument. |
| The glibc |
| .BR signalfd () |
| wrapper function does not include this argument, |
| since it provides the required value for the underlying system call. |
| .PP |
| There are two underlying Linux system calls: |
| .BR signalfd () |
| and the more recent |
| .BR signalfd4 (). |
| The former system call does not implement a |
| .I flags |
| argument. |
| The latter system call implements the |
| .I flags |
| values described above. |
| Starting with glibc 2.9, the |
| .BR signalfd () |
| wrapper function will use |
| .BR signalfd4 () |
| where it is available. |
| .SH BUGS |
| In kernels before 2.6.25, the |
| .I ssi_ptr |
| and |
| .I ssi_int |
| fields are not filled in with the data accompanying a signal sent by |
| .BR sigqueue (3). |
| .\" The fix also was put into 2.6.24.5 |
| .SH EXAMPLES |
| The program below accepts the signals |
| .B SIGINT |
| and |
| .B SIGQUIT |
| via a signalfd file descriptor. |
| The program terminates after accepting a |
| .B SIGQUIT |
| signal. |
| The following shell session demonstrates the use of the program: |
| .PP |
| .in +4n |
| .EX |
| .RB "$" " ./signalfd_demo" |
| .BR "\(haC" " # Control\-C generates SIGINT" |
| Got SIGINT |
| .B \(haC |
| Got SIGINT |
| \fB\(ha\e\fP # Control\-\e generates SIGQUIT |
| Got SIGQUIT |
| $ |
| .EE |
| .in |
| .SS Program source |
| \& |
| .EX |
| #include <sys/signalfd.h> |
| #include <signal.h> |
| #include <unistd.h> |
| #include <stdlib.h> |
| #include <stdio.h> |
| |
| #define handle_error(msg) \e |
| do { perror(msg); exit(EXIT_FAILURE); } while (0) |
| |
| int |
| main(int argc, char *argv[]) |
| { |
| sigset_t mask; |
| int sfd; |
| struct signalfd_siginfo fdsi; |
| ssize_t s; |
| |
| sigemptyset(&mask); |
| sigaddset(&mask, SIGINT); |
| sigaddset(&mask, SIGQUIT); |
| |
| /* Block signals so that they aren\(aqt handled |
| according to their default dispositions. */ |
| |
| if (sigprocmask(SIG_BLOCK, &mask, NULL) == \-1) |
| handle_error("sigprocmask"); |
| |
| sfd = signalfd(\-1, &mask, 0); |
| if (sfd == \-1) |
| handle_error("signalfd"); |
| |
| for (;;) { |
| s = read(sfd, &fdsi, sizeof(fdsi)); |
| if (s != sizeof(fdsi)) |
| handle_error("read"); |
| |
| if (fdsi.ssi_signo == SIGINT) { |
| printf("Got SIGINT\en"); |
| } else if (fdsi.ssi_signo == SIGQUIT) { |
| printf("Got SIGQUIT\en"); |
| exit(EXIT_SUCCESS); |
| } else { |
| printf("Read unexpected signal\en"); |
| } |
| } |
| } |
| .EE |
| .SH SEE ALSO |
| .BR eventfd (2), |
| .BR poll (2), |
| .BR read (2), |
| .BR select (2), |
| .BR sigaction (2), |
| .BR sigprocmask (2), |
| .BR sigwaitinfo (2), |
| .BR timerfd_create (2), |
| .BR sigsetops (3), |
| .BR sigwait (3), |
| .BR epoll (7), |
| .BR signal (7) |