illumos: manual page: signalfd.3c

SIGNALFD(3C) Standard C Library Functions SIGNALFD(3C)

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 desriptor.

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