1 SIGNALFD(3C) Standard C Library Functions SIGNALFD(3C)
2
3 NAME
4 signalfd - create or modify a file descriptor for signal handling
5
6 SYNOPSIS
7 #include <sys/signalfd.h>
8
9 int
10 signalfd(int fd, const sigset_t *mask, int flags);
11
12 DESCRIPTION
13 The signalfd() function returns a file descriptor that can be used for
14 synchronous consumption of signals. The file descriptor can be operated
15 upon via read(2) and the facilities that notify of file descriptor
16 activity (e.g. poll(2), port_get(3C), epoll_wait(3C) ). To dispose of
17 the instance close(2) should be called on the file descriptor.
18
19 If the fd argument is -1, a new signalfd file descriptor will be
20 returned, otherwise the fd argument should be an existing signalfd file
21 descriptor whose signal mask will be updated.
22
23 The mask argument specifies the set of signals that are relevant to the
24 file descriptor. It may be manipulated with the standard signal set
25 manipulation functions documented in sigsetops(3C). Signals in the mask
26 which cannot be caught (e.g. SIGKILL) are ignored.
27
28 The flags argument specifies additional parameters for the instance, and
29 can have any of the following values:
30
31 SFD_CLOEXEC Instance will be closed upon an exec(2); see description
32 for O_CLOEXEC in open(2).
33
34 SFD_NONBLOCK Instance will be set to be non-blocking. A read(2) on a
35 signalfd instance that has been initialized with
36 SFD_NONBLOCK, or made non-blocking in other ways, will
37 return EAGAIN in lieu of blocking if there are no signals
38 from the mask that are pending.
39
40 As with sigwait(2), reading a signal from the file descriptor will
41 consume the signal. The signals used with signalfd file descriptors are
42 normally first blocked so that their handler does not run when a signal
43 arrives. If the signal is not blocked the behavior matches that of
44 sigwait(2); if a read(2) is pending then the signal is consumed by the
45 read, otherwise the signal is consumed by the handler.
46
47 The following operations can be performed upon a signalfd file
48 descriptor:
49
50 read(2) Reads and consumes one or more of the pending signals that
51 match the file descriptor's mask. The read buffer must be
52 large enough to hold one or more signalfd_siginfo
53 structures, which is described below. read(2) will block
54 if there are no matching signals pending, or return EAGAIN
55 if the instance was created with SFD_NONBLOCK. After a
56 fork(2), if the child reads from the descriptor it will
57 only consume signals from itself.
58
59 poll(2) Provide notification when one of the signals from the mask
60 arrives. POLLIN and POLLRDNORM will be set.
61
62 close(2) Closes the desriptor.
63
64 The signalfd_siginfo structure returned from read(2) is a fixed size 128
65 byte structure defined as follows:
66
67 typedef struct signalfd_siginfo {
68 uint32_t ssi_signo; /* signal from signal.h */
69 int32_t ssi_errno; /* error from errno.h */
70 int32_t ssi_code; /* signal code */
71 uint32_t ssi_pid; /* PID of sender */
72 uint32_t ssi_uid; /* real UID of sender */
73 int32_t ssi_fd; /* file descriptor (SIGIO) */
74 uint32_t ssi_tid; /* unused */
75 uint32_t ssi_band; /* band event (SIGIO) */
76 uint32_t ssi_overrun; /* unused */
77 uint32_t ssi_trapno; /* trap number that caused signal */
78 int32_t ssi_status; /* exit status or signal (SIGCHLD) */
79 int32_t ssi_int; /* unused */
80 uint64_t ssi_ptr; /* unused */
81 uint64_t ssi_utime; /* user CPU time consumed (SIGCHLD) */
82 uint64_t ssi_stime; /* system CPU time consumed (SIGCHLD) */
83 uint64_t ssi_addr; /* address that generated signal */
84 uint8_t ssi_pad[48]; /* pad size to 128 bytes */
85 } signalfd_siginfo_t;
86
87 NOTES
88 File descriptor duplication during fork presents a challenge to the
89 signalfd facility since signal data and events are dependent on the
90 process from which they are queried. Its use with caching event systems
91 such as epoll(5), /dev/poll, or port_create(3C) can result in undefined
92 behavior if signalfd and polling descriptors are used together after
93 being shared across a fork. Such restrictions do not apply if the child
94 only calls close(2) on the descriptors.
95
96 RETURN VALUES
97 Upon successful completion, a file descriptor associated with the
98 instance is returned. Otherwise, -1 is returned and errno is set to
99 indicate the error. When fd is not -1 and there is no error, the value
100 of fd is returned.
101
102 ERRORS
103 The signalfd(function) will fail if:
104
105 EBADF The fd descriptor is invalid.
106
107 EFAULT The mask address is invalid.
108
109 EINVAL The fd descriptor is not a signalfd descriptor or the
110 flags are invalid.
111
112 EMFILE There are currently OPEN_MAX file descriptors open in
113 the calling process.
114
115 ENODEV Unable to allocate state for the file descriptor.
116
117 SEE ALSO
118 poll(2), sigwait(2), port_create(3C), sigsetops(3C), sigwaitinfo(3C),
119 signal.h(3HEAD), epoll(5)
120
121 illumos May 5, 2016 illumos