NAME

signalfd — create or modify a file descriptor for signal handling

SYNOPSIS

#include <sys/signalfd.h>

int
signalfd(int fd, const sigset_t *mask, int flags);

DESCRIPTION

The signalfd() function returns a file descriptor that can be used for synchronous consumption of signals. The file descriptor can be operated upon via read(2) and the facilities that notify of file descriptor activity (e.g. poll(2), port_get(3C), epoll_wait(3C) ). To dispose of the instance close(2) should be called on the file descriptor.

If the fd argument is -1, a new signalfd file descriptor will be returned, otherwise the fd argument should be an existing signalfd file descriptor whose signal mask will be updated.

The mask argument specifies the set of signals that are relevant to the file descriptor. It may be manipulated with the standard signal set manipulation functions documented in sigsetops(3C). Signals in the mask which cannot be caught (e.g. SIGKILL) are ignored.

The flags argument specifies additional parameters for the instance, and can have any of the following values:

SFD_CLOEXEC: Instance will be closed upon an exec(2); see description for O_CLOEXEC in open(2).
SFD_NONBLOCK: Instance will be set to be non-blocking. A read(2) on a signalfd instance that has been initialized with SFD_NONBLOCK, or made non-blocking in other ways, will return EAGAIN in lieu of blocking if there are no signals from the mask that are pending.

As with sigwait(2), reading a signal from the file descriptor will consume the signal. The signals used with signalfd file descriptors are normally first blocked so that their handler does not run when a signal arrives. If the signal is not blocked the behavior matches that of sigwait(2); if a read(2) is pending then the signal is consumed by the read, otherwise the signal is consumed by the handler.

The following operations can be performed upon a signalfd file descriptor:

read(2): Reads and consumes one or more of the pending signals that match the file descriptor's mask. The read buffer must be large enough to hold one or more signalfd_siginfo structures, which is described below. read(2) will block if there are no matching signals pending, or return EAGAIN if the instance was created with SFD_NONBLOCK. After a fork(2), if the child reads from the descriptor it will only consume signals from itself.
poll(2): Provide notification when one of the signals from the mask arrives. POLLIN and POLLRDNORM will be set.
close(2): Closes the descriptor.

The signalfd_siginfo structure returned from read(2) is a fixed size 128 byte structure defined as follows:

typedef struct signalfd_siginfo {
        uint32_t ssi_signo;     /* signal from signal.h */
        int32_t  ssi_errno;     /* error from errno.h */
        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;       /* unused */
        uint32_t ssi_band;      /* band event (SIGIO) */
        uint32_t ssi_overrun;   /* unused */
        uint32_t ssi_trapno;    /* trap number that caused signal */
        int32_t  ssi_status;    /* exit status or signal (SIGCHLD) */
        int32_t  ssi_int;       /* unused */
        uint64_t ssi_ptr;       /* unused */
        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 */
        uint8_t  ssi_pad[48];   /* pad size to 128 bytes */
} signalfd_siginfo_t;

NOTES

File descriptor duplication during fork presents a challenge to the signalfd facility since signal data and events are dependent on the process from which they are queried. Its use with caching event systems such as epoll(7), /dev/poll, or port_create(3C) can result in undefined behavior if signalfd and polling descriptors are used together after being shared across a fork. Such restrictions do not apply if the child only calls close(2) on the descriptors.

RETURN VALUES

Upon successful completion, a file descriptor associated with the instance is returned. Otherwise, -1 is returned and errno is set to indicate the error. When fd is not -1 and there is no error, the value of fd is returned.

ERRORS

The signalfd(function) will fail if:

EBADF: The fd descriptor is invalid.
EFAULT: The mask address is invalid.
EINVAL: The fd descriptor is not a signalfd descriptor or the flags are invalid.
EMFILE: There are currently OPEN_MAX file descriptors open in the calling process.
ENODEV: Unable to allocate state for the file descriptor.