From: Alejandro Colomar Date: Sat, 19 Jul 2025 21:58:10 +0000 (+0200) Subject: man/man2/fcntl.2, man/man2const/F_GETSIG.2const: Split F_{G,S}ETOWN*, F_{G,S}ETSIG... X-Git-Tag: man-pages-6.15~2^2~4 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2a02d055833d603a6ef82754ced7db95f52270a1;p=thirdparty%2Fman-pages.git man/man2/fcntl.2, man/man2const/F_GETSIG.2const: Split F_{G,S}ETOWN*, F_{G,S}ETSIG from fcntl(2) Signed-off-by: Alejandro Colomar --- diff --git a/man/man2/fcntl.2 b/man/man2/fcntl.2 index a98c14f5a..b81f92c0b 100644 --- a/man/man2/fcntl.2 +++ b/man/man2/fcntl.2 @@ -526,360 +526,18 @@ Linux does not define this signal, and does not provide any asynchronous notification of lost locks. .\" .SS Managing signals -.BR F_GETOWN , -.BR F_SETOWN , -.BR F_GETOWN_EX , -.BR F_SETOWN_EX , -.BR F_GETSIG , -and -.B F_SETSIG -are used to manage I/O availability signals: -.TP -.BR F_GETOWN \~(\f[I]void\f[]) -Return (as the function result) -the process ID or process group ID currently receiving -.B SIGIO -and -.B SIGURG -signals for events on file descriptor -.IR fd . -Process IDs are returned as positive values; -process group IDs are returned as negative values (but see BUGS below). -.I arg -is ignored. -.TP -.BR F_SETOWN \~(\f[I]int\f[]) -Set the process ID or process group ID that will receive -.B SIGIO -and -.B SIGURG -signals for events on the file descriptor -.IR fd . -The target process or process group ID is specified in -.IR arg . -A process ID is specified as a positive value; -a process group ID is specified as a negative value. -Most commonly, the calling process specifies itself as the owner -(that is, -.I arg -is specified as -.BR getpid (2)). -.IP -As well as setting the file descriptor owner, -one must also enable generation of signals on the file descriptor. -This is done by using the -.BR F_SETFL (2const) -operation to set the -.B O_ASYNC -file status flag on the file descriptor. -Subsequently, a -.B SIGIO -signal is sent whenever input or output becomes possible -on the file descriptor. -The -.BR fcntl () -.B F_SETSIG -operation can be used to obtain delivery of a signal other than -.BR SIGIO . -.IP -Sending a signal to the owner process (group) specified by -.B F_SETOWN -is subject to the same permissions checks as are described for -.BR kill (2), -where the sending process is the one that employs -.B F_SETOWN -(but see BUGS below). -If this permission check fails, then the signal is -silently discarded. -.IR Note : -The -.B F_SETOWN -operation records the caller's credentials at the time of the -.BR fcntl () -call, -and it is these saved credentials that are used for the permission checks. -.IP -If the file descriptor -.I fd -refers to a socket, -.B F_SETOWN -also selects -the recipient of -.B SIGURG -signals that are delivered when out-of-band -data arrives on that socket. -.RB ( SIGURG -is sent in any situation where -.BR select (2) -would report the socket as having an "exceptional condition".) -.\" The following appears to be rubbish. It doesn't seem to -.\" be true according to the kernel source, and I can write -.\" a program that gets a terminal-generated SIGIO even though -.\" it is not the foreground process group of the terminal. -.\" -- MTK, 8 Apr 05 -.\" -.\" If the file descriptor -.\" .I fd -.\" refers to a terminal device, then SIGIO -.\" signals are sent to the foreground process group of the terminal. -.IP -The following was true in Linux 2.6.x up to and including Linux 2.6.11: -.RS -.IP -If a nonzero value is given to -.B F_SETSIG -in a multithreaded process running with a threading library -that supports thread groups (e.g., NPTL), -then a positive value given to -.B F_SETOWN -has a different meaning: -.\" The relevant place in the (2.6) kernel source is the -.\" 'switch' in fs/fcntl.c::send_sigio_to_task() -- MTK, Apr 2005 -instead of being a process ID identifying a whole process, -it is a thread ID identifying a specific thread within a process. -Consequently, it may be necessary to pass -.B F_SETOWN -the result of -.BR gettid (2) -instead of -.BR getpid (2) -to get sensible results when -.B F_SETSIG -is used. -(In current Linux threading implementations, -a main thread's thread ID is the same as its process ID. -This means that a single-threaded program can equally use -.BR gettid (2) -or -.BR getpid (2) -in this scenario.) -Note, however, that the statements in this paragraph do not apply -to the -.B SIGURG -signal generated for out-of-band data on a socket: -this signal is always sent to either a process or a process group, -depending on the value given to -.BR F_SETOWN . -.\" send_sigurg()/send_sigurg_to_task() bypasses -.\" kill_fasync()/send_sigio()/send_sigio_to_task() -.\" to directly call send_group_sig_info() -.\" -- MTK, Apr 2005 (kernel 2.6.11) -.RE -.IP -The above behavior was accidentally dropped in Linux 2.6.12, -and won't be restored. -From Linux 2.6.32 onward, use -.B F_SETOWN_EX -to target -.B SIGIO -and -.B SIGURG -signals at a particular thread. -.TP -.BR F_GETOWN_EX "\~(\f[I]struct\~f_owner_ex\~*\f[]; since Linux 2.6.32)" -Return the current file descriptor owner settings -as defined by a previous -.B F_SETOWN_EX -operation. -The information is returned in the structure pointed to by -.IR arg , -which has the following form: -.IP -.in +4n -.EX -struct f_owner_ex { - int type; - pid_t pid; -}; -.EE -.in -.IP -The -.I type -field will have one of the values -.BR F_OWNER_TID , -.BR F_OWNER_PID , -or -.BR F_OWNER_PGRP . -The -.I pid -field is a positive integer representing a thread ID, process ID, -or process group ID. -See -.B F_SETOWN_EX -for more details. -.TP -.BR F_SETOWN_EX "\~(\f[I]struct\~f_owner_ex\~*\f[]; since Linux 2.6.32)" -This operation performs a similar task to -.BR F_SETOWN . -It allows the caller to direct I/O availability signals -to a specific thread, process, or process group. -The caller specifies the target of signals via -.IR arg , -which is a pointer to a -.I f_owner_ex -structure. -The -.I type -field has one of the following values, which define how -.I pid -is interpreted: -.RS -.TP -.B F_OWNER_TID -Send the signal to the thread whose thread ID -(the value returned by a call to -.BR clone (2) -or -.BR gettid (2)) -is specified in -.IR pid . -.TP -.B F_OWNER_PID -Send the signal to the process whose ID -is specified in -.IR pid . -.TP -.B F_OWNER_PGRP -Send the signal to the process group whose ID -is specified in -.IR pid . -(Note that, unlike with -.BR F_SETOWN , -a process group ID is specified as a positive value here.) -.RE -.TP -.BR F_GETSIG \~(\f[I]void\f[]) -Return (as the function result) -the signal sent when input or output becomes possible. -A value of zero means -.B SIGIO -is sent. -Any other value (including -.BR SIGIO ) -is the -signal sent instead, and in this case additional info is available to -the signal handler if installed with -.BR SA_SIGINFO . -.I arg -is ignored. .TP -.BR F_SETSIG \~(\f[I]int\f[]) -Set the signal sent when input or output becomes possible -to the value given in -.IR arg . -A value of zero means to send the default -.B SIGIO -signal. -Any other value (including -.BR SIGIO ) -is the signal to send instead, and in this case additional info -is available to the signal handler if installed with -.BR SA_SIGINFO . -.\" -.\" The following was true only up until Linux 2.6.11: -.\" -.\" Additionally, passing a nonzero value to -.\" .B F_SETSIG -.\" changes the signal recipient from a whole process to a specific thread -.\" within a process. -.\" See the description of -.\" .B F_SETOWN -.\" for more details. -.IP -By using -.B F_SETSIG -with a nonzero value, and setting -.B SA_SIGINFO -for the -signal handler (see -.BR sigaction (2)), -extra information about I/O events is passed to -the handler in a -.I siginfo_t -structure. -If the -.I si_code -field indicates the source is -.BR SI_SIGIO , -the -.I si_fd -field gives the file descriptor associated with the event. -Otherwise, -there is no indication which file descriptors are pending, and you -should use the usual mechanisms -.RB ( select (2), -.BR poll (2), -.BR read (2) -with -.B O_NONBLOCK -set etc.) to determine which file descriptors are available for I/O. -.IP -Note that the file descriptor provided in -.I si_fd -is the one that was specified during the -.B F_SETSIG -operation. -This can lead to an unusual corner case. -If the file descriptor is duplicated -.RB ( dup (2) -or similar), and the original file descriptor is closed, -then I/O events will continue to be generated, but the -.I si_fd -field will contain the number of the now closed file descriptor. -.IP -By selecting a real time signal (value >= -.BR SIGRTMIN ), -multiple I/O events may be queued using the same signal numbers. -(Queuing is dependent on available memory.) -Extra information is available -if -.B SA_SIGINFO -is set for the signal handler, as above. -.IP -Note that Linux imposes a limit on the -number of real-time signals that may be queued to a -process (see -.BR getrlimit (2) -and -.BR signal (7)) -and if this limit is reached, then the kernel reverts to -delivering -.BR SIGIO , -and this signal is delivered to the entire -process rather than to a specific thread. -.\" See fs/fcntl.c::send_sigio_to_task() (2.4/2.6) sources -- MTK, Apr 05 -.P -Using these mechanisms, a program can implement fully asynchronous I/O -without using -.BR select (2) -or -.BR poll (2) -most of the time. -.P -The use of -.B O_ASYNC -is specific to BSD and Linux. -The only use of -.B F_GETOWN -and -.B F_SETOWN -specified in POSIX.1 is in conjunction with the use of the -.B SIGURG -signal on sockets. -(POSIX does not specify the -.B SIGIO -signal.) -.BR F_GETOWN_EX , -.BR F_SETOWN_EX , -.BR F_GETSIG , -and -.B F_SETSIG -are Linux-specific. -POSIX has asynchronous I/O and the -.I aio_sigevent -structure to achieve similar things; these are also available -in Linux as part of the GNU C Library (glibc). +.BR F_GETOWN (2const) +.TQ +.BR F_SETOWN (2const) +.TQ +.BR F_GETOWN_EX (2const) +.TQ +.BR F_SETOWN_EX (2const) +.TQ +.BR F_GETSIG (2const) +.TQ +.BR F_SETSIG (2const) .SS Leases .TP .BR F_SETLEASE (2const) @@ -908,19 +566,7 @@ in Linux as part of the GNU C Library (glibc). .TQ .BR F_SET_FILE_RW_HINT (2const) .SH RETURN VALUE -For a successful call, the return value depends on the operation: -.TP -.B F_GETOWN -Value of file descriptor owner. -.TP -.B F_GETSIG -Value of signal sent when read or write becomes possible, or zero -for traditional -.B SIGIO -behavior. -.TP -All other operations -Zero. +For a successful call, the return value depends on the operation. .P On error, \-1 is returned, and .I errno @@ -986,14 +632,6 @@ is not recognized by this kernel. .B EINVAL .I op is -.B F_SETSIG -and -.I arg -is not an allowable signal number. -.TP -.B EINVAL -.I op -is .BR F_OFD_SETLK , .BR F_OFD_SETLKW , or @@ -1013,16 +651,6 @@ and but Linux doesn't support them. .SH STANDARDS POSIX.1-2008. -.P -.BR F_GETOWN_EX , -.BR F_SETOWN_EX , -.BR F_GETSIG , -and -.BR F_SETSIG , -are Linux-specific. -(Define the -.B _GNU_SOURCE -macro to obtain these definitions.) .\" .P .\" SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions. .P @@ -1043,18 +671,6 @@ Only the operations and .B F_SETLKW are specified in POSIX.1-2001. -.P -.B F_GETOWN -and -.B F_SETOWN -are specified in POSIX.1-2001. -(To get their definitions, define either -.\" .BR _BSD_SOURCE , -.\" or -.B _XOPEN_SOURCE -with the value 500 or greater, or -.B _POSIX_C_SOURCE -with the value 200809L or greater.) .SH NOTES .SS File locking The original Linux @@ -1163,50 +779,6 @@ Because of the attendant risk of data corruption, .\" commit f6de7a39c181dfb8a2c534661a53c73afb3081cd this parameter defaults to 0 (disabled). .SH BUGS -.SS F_GETOWN -A limitation of the Linux system call conventions on some -architectures (notably i386) means that if a (negative) -process group ID to be returned by -.B F_GETOWN -falls in the range \-1 to \-4095, then the return value is wrongly -interpreted by glibc as an error in the system call; -.\" glibc source: sysdeps/unix/sysv/linux/i386/sysdep.h -that is, the return value of -.BR fcntl () -will be \-1, and -.I errno -will contain the (positive) process group ID. -The Linux-specific -.B F_GETOWN_EX -operation avoids this problem. -.\" mtk, Dec 04: some limited testing on alpha and ia64 seems to -.\" indicate that ANY negative PGID value will cause F_GETOWN -.\" to misinterpret the return as an error. Some other architectures -.\" seem to have the same range check as i386. -Since glibc 2.11, glibc makes the kernel -.B F_GETOWN -problem invisible by implementing -.B F_GETOWN -using -.BR F_GETOWN_EX . -.SS F_SETOWN -In Linux 2.4 and earlier, there is bug that can occur -when an unprivileged process uses -.B F_SETOWN -to specify the owner -of a socket file descriptor -as a process (group) other than the caller. -In this case, -.BR fcntl () -can return \-1 with -.I errno -set to -.BR EPERM , -even when the owner process (group) is one that the caller -has permission to send signals to. -Despite this error return, the file descriptor owner is set, -and signals will be sent to the owner. -.\" .SS Deadlock detection The deadlock-detection algorithm employed by the kernel when dealing with .B F_SETLKW diff --git a/man/man2const/F_GETSIG.2const b/man/man2const/F_GETSIG.2const new file mode 100644 index 000000000..c12507c31 --- /dev/null +++ b/man/man2const/F_GETSIG.2const @@ -0,0 +1,496 @@ +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH F_GETSIG 2const (date) "Linux man-pages (unreleased)" +.SH NAME +F_GETOWN, +F_SETOWN, +F_GETOWN_EX, +F_SETOWN_EX, +F_GETSIG, +F_SETSIG +\- +managing signals +.SH LIBRARY +Standard C library +.RI ( libc ,\~ \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fcntl(int " fd ", F_GETOWN);" +.BI "int fcntl(int " fd ", F_SETOWN, int " arg ); +.P +.B #define _GNU_SOURCE +.B #include +.P +.BI "int fcntl(int " fd ", F_GETOWN_EX, struct f_owner_ex *" arg ); +.BI "int fcntl(int " fd ", F_SETOWN_EX, const struct f_owner_ex *" arg ); +.BI "int fcntl(int " fd ", F_GETSIG);" +.BI "int fcntl(int " fd ", F_SETSIG, int " arg ); +.fi +.SH DESCRIPTION +.BR F_GETOWN , +.BR F_SETOWN , +.BR F_GETOWN_EX , +.BR F_SETOWN_EX , +.BR F_GETSIG , +and +.B F_SETSIG +are used to manage I/O availability signals: +.TP +.BR F_GETOWN \~(\f[I]void\f[]) +Return (as the function result) +the process ID or process group ID currently receiving +.B SIGIO +and +.B SIGURG +signals for events on file descriptor +.IR fd . +Process IDs are returned as positive values; +process group IDs are returned as negative values (but see BUGS below). +.I arg +is ignored. +.TP +.BR F_SETOWN \~(\f[I]int\f[]) +Set the process ID or process group ID that will receive +.B SIGIO +and +.B SIGURG +signals for events on the file descriptor +.IR fd . +The target process or process group ID is specified in +.IR arg . +A process ID is specified as a positive value; +a process group ID is specified as a negative value. +Most commonly, the calling process specifies itself as the owner +(that is, +.I arg +is specified as +.BR getpid (2)). +.IP +As well as setting the file descriptor owner, +one must also enable generation of signals on the file descriptor. +This is done by using the +.BR F_SETFL (2const) +operation to set the +.B O_ASYNC +file status flag on the file descriptor. +Subsequently, a +.B SIGIO +signal is sent whenever input or output becomes possible +on the file descriptor. +The +.BR fcntl () +.B F_SETSIG +operation can be used to obtain delivery of a signal other than +.BR SIGIO . +.IP +Sending a signal to the owner process (group) specified by +.B F_SETOWN +is subject to the same permissions checks as are described for +.BR kill (2), +where the sending process is the one that employs +.B F_SETOWN +(but see BUGS below). +If this permission check fails, then the signal is +silently discarded. +.IR Note : +The +.B F_SETOWN +operation records the caller's credentials at the time of the +.BR fcntl () +call, +and it is these saved credentials that are used for the permission checks. +.IP +If the file descriptor +.I fd +refers to a socket, +.B F_SETOWN +also selects +the recipient of +.B SIGURG +signals that are delivered when out-of-band +data arrives on that socket. +.RB ( SIGURG +is sent in any situation where +.BR select (2) +would report the socket as having an "exceptional condition".) +.\" The following appears to be rubbish. It doesn't seem to +.\" be true according to the kernel source, and I can write +.\" a program that gets a terminal-generated SIGIO even though +.\" it is not the foreground process group of the terminal. +.\" -- MTK, 8 Apr 05 +.\" +.\" If the file descriptor +.\" .I fd +.\" refers to a terminal device, then SIGIO +.\" signals are sent to the foreground process group of the terminal. +.IP +The following was true in Linux 2.6.x up to and including Linux 2.6.11: +.RS +.IP +If a nonzero value is given to +.B F_SETSIG +in a multithreaded process running with a threading library +that supports thread groups (e.g., NPTL), +then a positive value given to +.B F_SETOWN +has a different meaning: +.\" The relevant place in the (2.6) kernel source is the +.\" 'switch' in fs/fcntl.c::send_sigio_to_task() -- MTK, Apr 2005 +instead of being a process ID identifying a whole process, +it is a thread ID identifying a specific thread within a process. +Consequently, it may be necessary to pass +.B F_SETOWN +the result of +.BR gettid (2) +instead of +.BR getpid (2) +to get sensible results when +.B F_SETSIG +is used. +(In current Linux threading implementations, +a main thread's thread ID is the same as its process ID. +This means that a single-threaded program can equally use +.BR gettid (2) +or +.BR getpid (2) +in this scenario.) +Note, however, that the statements in this paragraph do not apply +to the +.B SIGURG +signal generated for out-of-band data on a socket: +this signal is always sent to either a process or a process group, +depending on the value given to +.BR F_SETOWN . +.\" send_sigurg()/send_sigurg_to_task() bypasses +.\" kill_fasync()/send_sigio()/send_sigio_to_task() +.\" to directly call send_group_sig_info() +.\" -- MTK, Apr 2005 (kernel 2.6.11) +.RE +.IP +The above behavior was accidentally dropped in Linux 2.6.12, +and won't be restored. +From Linux 2.6.32 onward, use +.B F_SETOWN_EX +to target +.B SIGIO +and +.B SIGURG +signals at a particular thread. +.TP +.BR F_GETOWN_EX "\~(\f[I]struct\~f_owner_ex\~*\f[]; since Linux 2.6.32)" +Return the current file descriptor owner settings +as defined by a previous +.B F_SETOWN_EX +operation. +The information is returned in the structure pointed to by +.IR arg , +which has the following form: +.IP +.in +4n +.EX +struct f_owner_ex { + int type; + pid_t pid; +}; +.EE +.in +.IP +The +.I type +field will have one of the values +.BR F_OWNER_TID , +.BR F_OWNER_PID , +or +.BR F_OWNER_PGRP . +The +.I pid +field is a positive integer representing a thread ID, process ID, +or process group ID. +See +.B F_SETOWN_EX +for more details. +.TP +.BR F_SETOWN_EX "\~(\f[I]struct\~f_owner_ex\~*\f[]; since Linux 2.6.32)" +This operation performs a similar task to +.BR F_SETOWN . +It allows the caller to direct I/O availability signals +to a specific thread, process, or process group. +The caller specifies the target of signals via +.IR arg , +which is a pointer to a +.I f_owner_ex +structure. +The +.I type +field has one of the following values, which define how +.I pid +is interpreted: +.RS +.TP +.B F_OWNER_TID +Send the signal to the thread whose thread ID +(the value returned by a call to +.BR clone (2) +or +.BR gettid (2)) +is specified in +.IR pid . +.TP +.B F_OWNER_PID +Send the signal to the process whose ID +is specified in +.IR pid . +.TP +.B F_OWNER_PGRP +Send the signal to the process group whose ID +is specified in +.IR pid . +(Note that, unlike with +.BR F_SETOWN , +a process group ID is specified as a positive value here.) +.RE +.TP +.BR F_GETSIG \~(\f[I]void\f[]) +Return (as the function result) +the signal sent when input or output becomes possible. +A value of zero means +.B SIGIO +is sent. +Any other value (including +.BR SIGIO ) +is the +signal sent instead, and in this case additional info is available to +the signal handler if installed with +.BR SA_SIGINFO . +.I arg +is ignored. +.TP +.BR F_SETSIG \~(\f[I]int\f[]) +Set the signal sent when input or output becomes possible +to the value given in +.IR arg . +A value of zero means to send the default +.B SIGIO +signal. +Any other value (including +.BR SIGIO ) +is the signal to send instead, and in this case additional info +is available to the signal handler if installed with +.BR SA_SIGINFO . +.\" +.\" The following was true only up until Linux 2.6.11: +.\" +.\" Additionally, passing a nonzero value to +.\" .B F_SETSIG +.\" changes the signal recipient from a whole process to a specific thread +.\" within a process. +.\" See the description of +.\" .B F_SETOWN +.\" for more details. +.IP +By using +.B F_SETSIG +with a nonzero value, and setting +.B SA_SIGINFO +for the +signal handler (see +.BR sigaction (2)), +extra information about I/O events is passed to +the handler in a +.I siginfo_t +structure. +If the +.I si_code +field indicates the source is +.BR SI_SIGIO , +the +.I si_fd +field gives the file descriptor associated with the event. +Otherwise, +there is no indication which file descriptors are pending, and you +should use the usual mechanisms +.RB ( select (2), +.BR poll (2), +.BR read (2) +with +.B O_NONBLOCK +set etc.) to determine which file descriptors are available for I/O. +.IP +Note that the file descriptor provided in +.I si_fd +is the one that was specified during the +.B F_SETSIG +operation. +This can lead to an unusual corner case. +If the file descriptor is duplicated +.RB ( dup (2) +or similar), and the original file descriptor is closed, +then I/O events will continue to be generated, but the +.I si_fd +field will contain the number of the now closed file descriptor. +.IP +By selecting a real time signal (value >= +.BR SIGRTMIN ), +multiple I/O events may be queued using the same signal numbers. +(Queuing is dependent on available memory.) +Extra information is available +if +.B SA_SIGINFO +is set for the signal handler, as above. +.IP +Note that Linux imposes a limit on the +number of real-time signals that may be queued to a +process (see +.BR getrlimit (2) +and +.BR signal (7)) +and if this limit is reached, then the kernel reverts to +delivering +.BR SIGIO , +and this signal is delivered to the entire +process rather than to a specific thread. +.\" See fs/fcntl.c::send_sigio_to_task() (2.4/2.6) sources -- MTK, Apr 05 +.P +Using these mechanisms, a program can implement fully asynchronous I/O +without using +.BR select (2) +or +.BR poll (2) +most of the time. +.P +The use of +.B O_ASYNC +is specific to BSD and Linux. +The only use of +.B F_GETOWN +and +.B F_SETOWN +specified in POSIX.1 is in conjunction with the use of the +.B SIGURG +signal on sockets. +(POSIX does not specify the +.B SIGIO +signal.) +.BR F_GETOWN_EX , +.BR F_SETOWN_EX , +.BR F_GETSIG , +and +.B F_SETSIG +are Linux-specific. +POSIX has asynchronous I/O and the +.I aio_sigevent +structure to achieve similar things; these are also available +in Linux as part of the GNU C Library (glibc). +.SH RETURN VALUE +See +.BR fcntl (2). +.TP +.B F_GETOWN +Value of file descriptor owner. +.TP +.B F_GETSIG +Value of signal sent when read or write becomes possible, or zero +for traditional +.B SIGIO +behavior. +.TP +.B F_SETOWN +.TQ +.B F_GETOWN_EX +.TQ +.B F_SETOWN_EX +.TQ +.B F_SETSIG +Zero. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +See +.BR fcntl (2). +.TP +.B EINVAL +.I op +is +.B F_SETSIG +and +.I arg +is not an allowable signal number. +.SH STANDARDS +POSIX.1-2008. +.P +.BR F_GETOWN_EX , +.BR F_SETOWN_EX , +.BR F_GETSIG , +and +.BR F_SETSIG , +are Linux-specific. +(Define the +.B _GNU_SOURCE +macro to obtain these definitions.) +.\" .P +.\" SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions. +.SH HISTORY +.B F_GETOWN +and +.B F_SETOWN +are specified in POSIX.1-2001. +(To get their definitions, define either +.\" .BR _BSD_SOURCE , +.\" or +.B _XOPEN_SOURCE +with the value 500 or greater, or +.B _POSIX_C_SOURCE +with the value 200809L or greater.) +.SH BUGS +.SS F_GETOWN +A limitation of the Linux system call conventions on some +architectures (notably i386) means that if a (negative) +process group ID to be returned by +.B F_GETOWN +falls in the range \-1 to \-4095, then the return value is wrongly +interpreted by glibc as an error in the system call; +.\" glibc source: sysdeps/unix/sysv/linux/i386/sysdep.h +that is, the return value of +.BR fcntl () +will be \-1, and +.I errno +will contain the (positive) process group ID. +The Linux-specific +.B F_GETOWN_EX +operation avoids this problem. +.\" mtk, Dec 04: some limited testing on alpha and ia64 seems to +.\" indicate that ANY negative PGID value will cause F_GETOWN +.\" to misinterpret the return as an error. Some other architectures +.\" seem to have the same range check as i386. +Since glibc 2.11, glibc makes the kernel +.B F_GETOWN +problem invisible by implementing +.B F_GETOWN +using +.BR F_GETOWN_EX . +.SS F_SETOWN +In Linux 2.4 and earlier, there is bug that can occur +when an unprivileged process uses +.B F_SETOWN +to specify the owner +of a socket file descriptor +as a process (group) other than the caller. +In this case, +.BR fcntl () +can return \-1 with +.I errno +set to +.BR EPERM , +even when the owner process (group) is one that the caller +has permission to send signals to. +Despite this error return, the file descriptor owner is set, +and signals will be sent to the owner. +.\" +.SH SEE ALSO +.BR fcntl (2)