DESCRIPTION

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 sigwaitinfo(2), and has the advantage that the file descriptor may be monitored by select(2), poll(2), and epoll(7). The 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 sigsetops(3). Normally, the set of signals to be received via the file descriptor should be blocked using sigprocmask(2), to prevent the signals being handled according to their default dispositions. It is not possible to receive SIGKILL or SIGSTOP signals via a signalfd file descriptor; these signals are silently ignored if specified in mask.

If the fd argument is −1, then the call creates a new file descriptor and associates the signal set specified in mask with that descriptor. If fd is not −1, then it must specify a valid existing signalfd file descriptor, and mask is used to replace the signal set associated with that descriptor.

The flags argument is currently unused, and must be specified as zero. In the future, it may be used to request additional functionality.

signalfd() returns a file descriptor that supports the following operations:

RETURN VALUE

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

ERRORS

VERSIONS

signalfd() is available on Linux since kernel 2.6.22. Working support is provided in glibc since version 2.8.

CONFORMING TO

signalfd() is Linux-specific.

NOTES

The underlying Linux system call requires an additional argument, size_t sizemask, which specifies the size of the mask argument. The glibc signalfd() wrapper function does not include this argument, since it provides the required value for the underlying system call.

The flags argument is a glibc addition to the underlying system call.

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 select(2), poll(2), or epoll(7): the arrival of different signals will make different descriptors ready.) If a signal appears in the mask of more than one of the file descriptors, then occurrences of that signal can be read (once) from any one of the descriptors.

EXAMPLE

The program below accepts the signals SIGINT and SIGQUIT via a signalfd file descriptor. The program terminates after accepting a SIGQUIT signal. The following shell session demonstrates the use of the program:

#include <sys/signalfd.h>
#include <signal.h>
#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>

#define handle_error(msg) \
    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't 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(struct signalfd_siginfo));
        if (s != sizeof(struct signalfd_siginfo))
            handle_error("read");

        if (fdsi.signo == SIGINT) {
            printf("Got SIGINT\n");
        } else if (fdsi.signo == SIGQUIT) {
            printf("Got SIGQUIT\n");
            exit(EXIT_SUCCESS);
        } else {
            printf("Read unexpected signal\n");
        }
    }
}

SEE ALSO

eventfd(2), poll(2), read(2), select(2), sigaction(2), sigprocmask(2), sigwaitinfo(2), timerfd_create(2), sigsetops(3), epoll(7), signal(7)