Tribblix: 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 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