Debian Codegraph @

upstream/debian-unstable/man2/F_GETSIG.2const

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH F_GETSIG 2const 2025-12-31 "Linux man-pages 6.18"
6 .SH NAME
7 F_GETOWN,
8 F_SETOWN,
9 F_GETOWN_EX,
10 F_SETOWN_EX,
11 F_GETSIG,
12 F_SETSIG
13 \-
14 managing signals
15 .SH LIBRARY
16 Standard C library
17 .RI ( libc ,\~ \-lc )
18 .SH SYNOPSIS
19 .nf
20 .B #include <fcntl.h>
21 .P
22 .BI "int fcntl(int " fd ", F_GETOWN);"
23 .BI "int fcntl(int " fd ", F_SETOWN, int " arg );
24 .P
25 .B #define _GNU_SOURCE
26 .B #include <fcntl.h>
27 .P
28 .BI "int fcntl(int " fd ", F_GETOWN_EX, struct f_owner_ex *" arg );
29 .BI "int fcntl(int " fd ", F_SETOWN_EX, const struct f_owner_ex *" arg );
30 .BI "int fcntl(int " fd ", F_GETSIG);"
31 .BI "int fcntl(int " fd ", F_SETSIG, int " arg );
32 .fi
33 .SH DESCRIPTION
34 .BR F_GETOWN ,
35 .BR F_SETOWN ,
36 .BR F_GETOWN_EX ,
37 .BR F_SETOWN_EX ,
38 .BR F_GETSIG ,
39 and
40 .B F_SETSIG
41 are used to manage I/O availability signals:
42 .TP
43 .B F_GETOWN
44 Return (as the function result)
45 the process ID or process group ID currently receiving
46 .B SIGIO
47 and
48 .B SIGURG
49 signals for events on file descriptor
50 .IR fd .
51 Process IDs are returned as positive values;
52 process group IDs are returned as negative values (but see BUGS below).
53 .I arg
54 is ignored.
55 .TP
56 .B F_SETOWN
57 Set the process ID or process group ID that will receive
58 .B SIGIO
59 and
60 .B SIGURG
61 signals for events on the file descriptor
62 .IR fd .
63 The target process or process group ID is specified in
64 .IR arg .
65 A process ID is specified as a positive value;
66 a process group ID is specified as a negative value.
67 Most commonly, the calling process specifies itself as the owner
68 (that is,
69 .I arg
70 is specified as
71 .BR getpid (2)).
72 .IP
73 As well as setting the file descriptor owner,
74 one must also enable generation of signals on the file descriptor.
75 This is done by using the
76 .BR F_SETFL (2const)
77 operation to set the
78 .B O_ASYNC
79 file status flag on the file descriptor.
80 Subsequently, a
81 .B SIGIO
82 signal is sent whenever input or output becomes possible
83 on the file descriptor.
84 The
85 .BR fcntl ()
86 .B F_SETSIG
87 operation can be used to obtain delivery of a signal other than
88 .BR SIGIO .
89 .IP
90 Sending a signal to the owner process (group) specified by
91 .B F_SETOWN
92 is subject to the same permissions checks as are described for
93 .BR kill (2),
94 where the sending process is the one that employs
95 .B F_SETOWN
96 (but see BUGS below).
97 If this permission check fails, then the signal is
98 silently discarded.
99 .IR Note :
100 The
101 .B F_SETOWN
102 operation records the caller's credentials at the time of the
103 .BR fcntl ()
104 call,
105 and it is these saved credentials that are used for the permission checks.
106 .IP
107 If the file descriptor
108 .I fd
109 refers to a socket,
110 .B F_SETOWN
111 also selects
112 the recipient of
113 .B SIGURG
114 signals that are delivered when out-of-band
115 data arrives on that socket.
116 .RB ( SIGURG
117 is sent in any situation where
118 .BR select (2)
119 would report the socket as having an "exceptional condition".)
120 .\" The following appears to be rubbish. It doesn't seem to
121 .\" be true according to the kernel source, and I can write
122 .\" a program that gets a terminal-generated SIGIO even though
123 .\" it is not the foreground process group of the terminal.
124 .\" -- MTK, 8 Apr 05
125 .\"
126 .\" If the file descriptor
127 .\" .I fd
128 .\" refers to a terminal device, then SIGIO
129 .\" signals are sent to the foreground process group of the terminal.
130 .IP
131 The following was true in Linux 2.6.x up to and including Linux 2.6.11:
132 .RS
133 .IP
134 If a nonzero value is given to
135 .B F_SETSIG
136 in a multithreaded process running with a threading library
137 that supports thread groups (e.g., NPTL),
138 then a positive value given to
139 .B F_SETOWN
140 has a different meaning:
141 .\" The relevant place in the (2.6) kernel source is the
142 .\" 'switch' in fs/fcntl.c::send_sigio_to_task() -- MTK, Apr 2005
143 instead of being a process ID identifying a whole process,
144 it is a thread ID identifying a specific thread within a process.
145 Consequently, it may be necessary to pass
146 .B F_SETOWN
147 the result of
148 .BR gettid (2)
149 instead of
150 .BR getpid (2)
151 to get sensible results when
152 .B F_SETSIG
153 is used.
154 (In current Linux threading implementations,
155 a main thread's thread ID is the same as its process ID.
156 This means that a single-threaded program can equally use
157 .BR gettid (2)
158 or
159 .BR getpid (2)
160 in this scenario.)
161 Note, however, that the statements in this paragraph do not apply
162 to the
163 .B SIGURG
164 signal generated for out-of-band data on a socket:
165 this signal is always sent to either a process or a process group,
166 depending on the value given to
167 .BR F_SETOWN .
168 .\" send_sigurg()/send_sigurg_to_task() bypasses
169 .\" kill_fasync()/send_sigio()/send_sigio_to_task()
170 .\" to directly call send_group_sig_info()
171 .\" -- MTK, Apr 2005 (kernel 2.6.11)
172 .RE
173 .IP
174 The above behavior was accidentally dropped in Linux 2.6.12,
175 and won't be restored.
176 From Linux 2.6.32 onward, use
177 .B F_SETOWN_EX
178 to target
179 .B SIGIO
180 and
181 .B SIGURG
182 signals at a particular thread.
183 .TP
184 .B F_GETOWN_EX
185 Return the current file descriptor owner settings
186 as defined by a previous
187 .B F_SETOWN_EX
188 operation.
189 The information is returned in the structure pointed to by
190 .IR arg ,
191 which has the following form:
192 .IP
193 .in +4n
194 .EX
195 struct f_owner_ex {
196 int type;
197 pid_t pid;
198 };
199 .EE
200 .in
201 .IP
202 The
203 .I type
204 field will have one of the values
205 .BR F_OWNER_TID ,
206 .BR F_OWNER_PID ,
207 or
208 .BR F_OWNER_PGRP .
209 The
210 .I pid
211 field is a positive integer representing a thread ID, process ID,
212 or process group ID.
213 See
214 .B F_SETOWN_EX
215 for more details.
216 .TP
217 .B F_SETOWN_EX
218 This operation performs a similar task to
219 .BR F_SETOWN .
220 It allows the caller to direct I/O availability signals
221 to a specific thread, process, or process group.
222 The caller specifies the target of signals via
223 .IR arg ,
224 which is a pointer to a
225 .I f_owner_ex
226 structure.
227 The
228 .I type
229 field has one of the following values, which define how
230 .I pid
231 is interpreted:
232 .RS
233 .TP
234 .B F_OWNER_TID
235 Send the signal to the thread whose thread ID
236 (the value returned by a call to
237 .BR clone (2)
238 or
239 .BR gettid (2))
240 is specified in
241 .IR pid .
242 .TP
243 .B F_OWNER_PID
244 Send the signal to the process whose ID
245 is specified in
246 .IR pid .
247 .TP
248 .B F_OWNER_PGRP
249 Send the signal to the process group whose ID
250 is specified in
251 .IR pid .
252 (Note that, unlike with
253 .BR F_SETOWN ,
254 a process group ID is specified as a positive value here.)
255 .RE
256 .TP
257 .B F_GETSIG
258 Return (as the function result)
259 the signal sent when input or output becomes possible.
260 A value of zero means
261 .B SIGIO
262 is sent.
263 Any other value (including
264 .BR SIGIO )
265 is the
266 signal sent instead, and in this case additional info is available to
267 the signal handler if installed with
268 .BR SA_SIGINFO .
269 .I arg
270 is ignored.
271 .TP
272 .B F_SETSIG
273 Set the signal sent when input or output becomes possible
274 to the value given in
275 .IR arg .
276 A value of zero means to send the default
277 .B SIGIO
278 signal.
279 Any other value (including
280 .BR SIGIO )
281 is the signal to send instead, and in this case additional info
282 is available to the signal handler if installed with
283 .BR SA_SIGINFO .
284 .\"
285 .\" The following was true only up until Linux 2.6.11:
286 .\"
287 .\" Additionally, passing a nonzero value to
288 .\" .B F_SETSIG
289 .\" changes the signal recipient from a whole process to a specific thread
290 .\" within a process.
291 .\" See the description of
292 .\" .B F_SETOWN
293 .\" for more details.
294 .IP
295 By using
296 .B F_SETSIG
297 with a nonzero value, and setting
298 .B SA_SIGINFO
299 for the
300 signal handler (see
301 .BR sigaction (2)),
302 extra information about I/O events is passed to
303 the handler in a
304 .I siginfo_t
305 structure.
306 If the
307 .I si_code
308 field indicates the source is
309 .BR SI_SIGIO ,
310 the
311 .I si_fd
312 field gives the file descriptor associated with the event.
313 Otherwise,
314 there is no indication which file descriptors are pending, and you
315 should use the usual mechanisms
316 .RB ( select (2),
317 .BR poll (2),
318 .BR read (2)
319 with
320 .B O_NONBLOCK
321 set etc.) to determine which file descriptors are available for I/O.
322 .IP
323 Note that the file descriptor provided in
324 .I si_fd
325 is the one that was specified during the
326 .B F_SETSIG
327 operation.
328 This can lead to an unusual corner case.
329 If the file descriptor is duplicated
330 .RB ( dup (2)
331 or similar), and the original file descriptor is closed,
332 then I/O events will continue to be generated, but the
333 .I si_fd
334 field will contain the number of the now closed file descriptor.
335 .IP
336 By selecting a real time signal (value >=
337 .BR SIGRTMIN ),
338 multiple I/O events may be queued using the same signal numbers.
339 (Queuing is dependent on available memory.)
340 Extra information is available
341 if
342 .B SA_SIGINFO
343 is set for the signal handler, as above.
344 .IP
345 Note that Linux imposes a limit on the
346 number of real-time signals that may be queued to a
347 process (see
348 .BR getrlimit (2)
349 and
350 .BR signal (7))
351 and if this limit is reached, then the kernel reverts to
352 delivering
353 .BR SIGIO ,
354 and this signal is delivered to the entire
355 process rather than to a specific thread.
356 .\" See fs/fcntl.c::send_sigio_to_task() (2.4/2.6) sources -- MTK, Apr 05
357 .P
358 Using these mechanisms, a program can implement fully asynchronous I/O
359 without using
360 .BR select (2)
361 or
362 .BR poll (2)
363 most of the time.
364 .P
365 The use of
366 .B O_ASYNC
367 is specific to BSD and Linux.
368 The only use of
369 .B F_GETOWN
370 and
371 .B F_SETOWN
372 specified in POSIX.1 is in conjunction with the use of the
373 .B SIGURG
374 signal on sockets.
375 (POSIX does not specify the
376 .B SIGIO
377 signal.)
378 .BR F_GETOWN_EX ,
379 .BR F_SETOWN_EX ,
380 .BR F_GETSIG ,
381 and
382 .B F_SETSIG
383 are Linux-specific.
384 POSIX has asynchronous I/O and the
385 .I aio_sigevent
386 structure to achieve similar things;
387 these are also available in Linux
388 as part of the GNU C Library (glibc).
389 .SH RETURN VALUE
390 See
391 .BR fcntl (2).
392 .TP
393 .B F_GETOWN
394 Value of file descriptor owner.
395 .TP
396 .B F_GETSIG
397 Value of signal sent when read or write becomes possible, or zero
398 for traditional
399 .B SIGIO
400 behavior.
401 .TP
402 .B F_SETOWN
403 .TQ
404 .B F_GETOWN_EX
405 .TQ
406 .B F_SETOWN_EX
407 .TQ
408 .B F_SETSIG
409 Zero.
410 .P
411 On error, \-1 is returned, and
412 .I errno
413 is set to indicate the error.
414 .SH ERRORS
415 See
416 .BR fcntl (2).
417 .TP
418 .B EINVAL
419 .I op
420 is
421 .B F_SETSIG
422 and
423 .I arg
424 is not an allowable signal number.
425 .SH STANDARDS
426 .TP
427 .B F_GETOWN
428 .TQ
429 .B F_SETOWN
430 .TQ
431 .B F_GETOWN_EX
432 .TQ
433 .B F_SETOWN_EX
434 POSIX.1-2024.
435 .TP
436 .B F_GETSIG
437 .TQ
438 .B F_SETSIG
439 Linux.
440 (Define the
441 .B _GNU_SOURCE
442 macro to obtain these definitions.)
443 .\" .P
444 .\" SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions.
445 .SH HISTORY
446 .TP
447 .B F_GETOWN
448 .TQ
449 .B F_SETOWN
450 POSIX.1-2001.
451 (To get their definitions, define either
452 .\" .BR _BSD_SOURCE ,
453 .\" or
454 .B _XOPEN_SOURCE
455 with the value 500 or greater, or
456 .B _POSIX_C_SOURCE
457 with the value 200809L or greater.)
458 .TP
459 .B F_GETOWN_EX
460 .TQ
461 .B F_SETOWN_EX
462 POSIX.1-2024.
463 Linux 2.6.32.
464 .TP
465 .B F_GETSIG
466 .TQ
467 .B F_SETSIG
468 Linux.
469 .SH BUGS
470 .SS F_GETOWN
471 A limitation of the Linux system call conventions on some
472 architectures (notably i386) means that if a (negative)
473 process group ID to be returned by
474 .B F_GETOWN
475 falls in the range \-1 to \-4095, then the return value is wrongly
476 interpreted by glibc as an error in the system call;
477 .\" glibc source: sysdeps/unix/sysv/linux/i386/sysdep.h
478 that is, the return value of
479 .BR fcntl ()
480 will be \-1, and
481 .I errno
482 will contain the (positive) process group ID.
483 The Linux-specific
484 .B F_GETOWN_EX
485 operation avoids this problem.
486 .\" mtk, Dec 04: some limited testing on alpha and ia64 seems to
487 .\" indicate that ANY negative PGID value will cause F_GETOWN
488 .\" to misinterpret the return as an error. Some other architectures
489 .\" seem to have the same range check as i386.
490 Since glibc 2.11, glibc makes the kernel
491 .B F_GETOWN
492 problem invisible by implementing
493 .B F_GETOWN
494 using
495 .BR F_GETOWN_EX .
496 .SS F_SETOWN
497 In Linux 2.4 and earlier, there is bug that can occur
498 when an unprivileged process uses
499 .B F_SETOWN
500 to specify the owner
501 of a socket file descriptor
502 as a process (group) other than the caller.
503 In this case,
504 .BR fcntl ()
505 can return \-1 with
506 .I errno
507 set to
508 .BR EPERM ,
509 even when the owner process (group) is one that the caller
510 has permission to send signals to.
511 Despite this error return, the file descriptor owner is set,
512 and signals will be sent to the owner.
513 .\"
514 .SH SEE ALSO
515 .BR fcntl (2)