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