.\" Copyright, the authors of the Linux man-pages project
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH F_GETSIG 2const 2025-07-20 "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
.B F_GETOWN
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
.B F_SETOWN
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
.B F_GETOWN_EX
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
.B F_SETOWN_EX
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
.B F_GETSIG
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
.B F_SETSIG
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
.TP
.B F_GETOWN
.TQ
.B F_SETOWN
POSIX.1-2008.
.TP
.B F_GETOWN_EX
.TQ
.B F_SETOWN_EX
.TQ
.B F_GETSIG
.TQ
.B F_SETSIG
Linux.
(Define the
.B _GNU_SOURCE
macro to obtain these definitions.)
.\" .P
.\" SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions.
.SH HISTORY
.TP
.B F_GETOWN
.TQ
.B F_SETOWN
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.)
.TP
.B F_GETOWN_EX
.TQ
.B F_GETOWN_EX
Linux 2.6.32.
.TP
.B F_GETSIG
.TQ
.B F_GETSIG
Linux.
.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)