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)
.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
.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
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
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
.\" 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
--- /dev/null
+.\" 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 <fcntl.h>
+.P
+.BI "int fcntl(int " fd ", F_GETOWN);"
+.BI "int fcntl(int " fd ", F_SETOWN, int " arg );
+.P
+.B #define _GNU_SOURCE
+.B #include <fcntl.h>
+.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)
projects / thirdparty / man-pages.git / commitdiff
