Print this page
OS-5370 panic in signalfd (fix mancheck)
OS-5370 panic in signalfd
Reviewed by: Jerry Jelinek <jerry.jelinek@joyent.com>
Reviewed by: Robert Mustacchi <rm@joyent.com>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/signalfd.3c
+++ new/usr/src/man/man3c/signalfd.3c
1 1 .\"
2 2 .\" This file and its contents are supplied under the terms of the
3 3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 4 .\" You may only use this file in accordance with the terms of version
5 5 .\" 1.0 of the CDDL.
6 6 .\"
7 7 .\" A full copy of the text of the CDDL should have accompanied this
8 8 .\" source. A copy of the CDDL is also available via the Internet at
9 9 .\" http://www.illumos.org/license/CDDL.
10 10 .\"
11 -.\" Copyright 2015, Joyent, Inc.
11 +.\" Copyright 2016, Joyent, Inc.
12 12 .\"
13 -.Dd "April 9, 2016"
13 +.Dd "May 05, 2016"
14 14 .Dt SIGNALFD 3C
15 15 .Os
16 16 .Sh NAME
17 17 .Nm signalfd
18 18 .Nd create or modify a file descriptor for signal handling
19 19 .Sh SYNOPSIS
20 20 .In sys/signalfd.h
21 21 .
22 22 .Ft int
23 23 .Fo signalfd
24 24 .Fa "int fd"
25 25 .Fa "const sigset_t *mask"
26 26 .Fa "int flags"
27 27 .Fc
28 28 .
29 29 .Sh DESCRIPTION
30 30 The
31 31 .Fn signalfd
32 32 function returns a file descriptor that can be used
33 33 for synchronous consumption of signals. The file descriptor can be operated
34 34 upon via
35 35 .Xr read 2
36 36 and the facilities that notify of file descriptor activity (e.g.
37 37 .Xr poll 2 ,
38 38 .Xr port_get 3C ,
39 39 .Xr epoll_wait 3C
40 40 ). To dispose of the instance
41 41 .Xr close 2
42 42 should be called on the file descriptor.
43 43 .Pp
44 44 If the
45 45 .Va fd
46 46 argument is -1, a new signalfd file descriptor will be
47 47 returned, otherwise the
48 48 .Va fd
49 49 argument should be an existing signalfd file descriptor whose signal mask will
50 50 be updated.
51 51 .Pp
52 52 The
53 53 .Va mask
54 54 argument specifies the set of signals that are relevant to the file descriptor.
55 55 It may be manipulated with the standard signal set manipulation functions
56 56 documented in
57 57 .Xr sigsetops 3C .
58 58 Signals in the mask which cannot be caught (e.g.
59 59 .Fa SIGKILL )
60 60 are ignored.
61 61 .Pp
62 62 The
63 63 .Va flags
64 64 argument specifies additional parameters for the instance, and can have any of
65 65 the following values:
66 66 .Bl -tag -width Dv
67 67 .It Sy SFD_CLOEXEC
68 68 Instance will be closed upon an
69 69 .Xr exec 2 ;
70 70 see description for
71 71 .Fa O_CLOEXEC
72 72 in
73 73 .Xr open 2 .
74 74 .It Sy SFD_NONBLOCK
75 75 Instance will be set to be non-blocking. A
76 76 .Xr read 2
77 77 on a signalfd instance that has been initialized with
78 78 .Fa SFD_NONBLOCK ,
79 79 or made non-blocking in other ways, will return
80 80 .Er EAGAIN
81 81 in lieu of blocking if there are no signals from the
82 82 .Va mask
83 83 that are pending.
84 84 .El
85 85 .Pp
86 86 As with
87 87 .Xr sigwait 2 ,
88 88 reading a signal from the file descriptor will consume the signal. The signals
89 89 used with signalfd file descriptors are normally first blocked so that their
90 90 handler does not run when a signal arrives. If the signal is not blocked the
91 91 behavior matches that of
92 92 .Xr sigwait 2 ;
93 93 if a
94 94 .Xr read 2
95 95 is pending then the signal is consumed by the read, otherwise the signal is
96 96 consumed by the handler.
97 97 .Pp
98 98 The following operations can be performed upon a signalfd file descriptor:
99 99 .Bl -tag -width Dv
100 100 .It Sy read(2)
101 101 Reads and consumes one or more of the pending signals that match the file
102 102 descriptor's
103 103 .Va mask .
104 104 The read buffer must be large enough to hold one or more
105 105 .Vt signalfd_siginfo
106 106 structures, which is described below.
107 107 .Xr read 2
108 108 will block if there are no matching signals pending, or return
109 109 .Er EAGAIN
110 110 if the instance was created with
111 111 .Fa SFD_NONBLOCK .
112 112 After a
113 113 .Xr fork 2 ,
114 114 if the child reads from the descriptor it will only consume signals from itself.
115 115 .It Sy poll(2)
116 116 Provide notification when one of the signals from the
117 117 .Va mask
118 118 arrives.
119 119 .Fa POLLIN
120 120 and
121 121 .Fa POLLRDNORM
122 122 will be set.
123 123 .It Sy close(2)
124 124 Closes the desriptor.
125 125 .El
126 126 .Pp
127 127 The
128 128 .Vt signalfd_siginfo
129 129 structure returned from
130 130 .Xr read 2
131 131 is a fixed size 128 byte structure defined as follows:
132 132 .Bd -literal
133 133 typedef struct signalfd_siginfo {
134 134 uint32_t ssi_signo; /* signal from signal.h */
135 135 int32_t ssi_errno; /* error from errno.h */
136 136 int32_t ssi_code; /* signal code */
137 137 uint32_t ssi_pid; /* PID of sender */
138 138 uint32_t ssi_uid; /* real UID of sender */
139 139 int32_t ssi_fd; /* file descriptor (SIGIO) */
140 140 uint32_t ssi_tid; /* unused */
141 141 uint32_t ssi_band; /* band event (SIGIO) */
142 142 uint32_t ssi_overrun; /* unused */
|
↓ open down ↓ |
119 lines elided |
↑ open up ↑ |
143 143 uint32_t ssi_trapno; /* trap number that caused signal */
144 144 int32_t ssi_status; /* exit status or signal (SIGCHLD) */
145 145 int32_t ssi_int; /* unused */
146 146 uint64_t ssi_ptr; /* unused */
147 147 uint64_t ssi_utime; /* user CPU time consumed (SIGCHLD) */
148 148 uint64_t ssi_stime; /* system CPU time consumed (SIGCHLD) */
149 149 uint64_t ssi_addr; /* address that generated signal */
150 150 uint8_t ssi_pad[48]; /* pad size to 128 bytes */
151 151 } signalfd_siginfo_t;
152 152 .Ed
153 +.Sh NOTES
154 +File descriptor duplication during fork presents a challenge to the
155 +.Sy signalfd
156 +facility since signal data and events are dependent on the process from which
157 +they are queried. Its use with caching event systems such as
158 +.Xr epoll 5 ,
159 +.Sy /dev/poll ,
160 +or
161 +.Xr port_create 3C
162 +can result in undefined behavior if signalfd and polling descriptors are used
163 +together after being shared across a fork. Such restrictions do not apply if
164 +the child only calls
165 +.Xr close 2
166 +on the descriptors.
153 167 .Sh RETURN VALUES
154 168 Upon successful completion, a file descriptor associated with the instance
155 169 is returned. Otherwise, -1 is returned and errno is set to indicate the error.
156 170 When
157 171 .Va fd
158 172 is not -1 and there is no error, the value of
159 173 .Va fd
160 174 is returned.
161 175 .Sh ERRORS
162 176 The
163 177 .Fn signalfd function
164 178 will fail if:
165 179 .Bl -tag -width Er
166 180 .It Er EBADF
167 181 The
168 182 .Va fd
169 183 descriptor is invalid.
170 184 .It Er EFAULT
171 185 The
172 186 .Va mask
173 187 address is invalid.
174 188 .It Er EINVAL
175 189 The
176 190 .Va fd
177 191 descriptor is not a signalfd descriptor or the
178 192 .Va flags
179 193 are invalid.
|
↓ open down ↓ |
17 lines elided |
↑ open up ↑ |
180 194 .It Er EMFILE
181 195 There are currently
182 196 .Va OPEN_MAX
183 197 file descriptors open in the calling process.
184 198 .It Er ENODEV
185 199 Unable to allocate state for the file descriptor.
186 200 .El
187 201 .Sh SEE ALSO
188 202 .Xr poll 2 ,
189 203 .Xr sigwait 2 ,
204 +.Xr port_create 3C ,
190 205 .Xr sigsetops 3C ,
191 206 .Xr sigwaitinfo 3C ,
192 -.Xr signal.h 3HEAD
207 +.Xr signal.h 3HEAD ,
208 +.Xr epoll 5
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX