|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | STANDARDS | HISTORY | BUGS | SEE ALSO | COLOPHON |
|
|
|
F_GETSIG(2const) F_GETSIG(2const)
F_GETOWN, F_SETOWN, F_GETOWN_EX, F_SETOWN_EX, F_GETSIG, F_SETSIG -
managing signals
Standard C library (libc, -lc)
#include <fcntl.h>
int fcntl(int fd, F_GETOWN);
int fcntl(int fd, F_SETOWN, int arg);
#define _GNU_SOURCE
#include <fcntl.h>
int fcntl(int fd, F_GETOWN_EX, struct f_owner_ex *arg);
int fcntl(int fd, F_SETOWN_EX, const struct f_owner_ex *arg);
int fcntl(int fd, F_GETSIG);
int fcntl(int fd, F_SETSIG, int arg);
F_GETOWN, F_SETOWN, F_GETOWN_EX, F_SETOWN_EX, F_GETSIG, and
F_SETSIG are used to manage I/O availability signals:
F_GETOWN
Return (as the function result) the process ID or process
group ID currently receiving SIGIO and SIGURG signals for
events on file descriptor fd. Process IDs are returned as
positive values; process group IDs are returned as negative
values (but see BUGS below). arg is ignored.
F_SETOWN
Set the process ID or process group ID that will receive
SIGIO and SIGURG signals for events on the file descriptor
fd. The target process or process group ID is specified in
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, arg is specified as getpid(2)).
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 F_SETFL(2const) operation to set the
O_ASYNC file status flag on the file descriptor.
Subsequently, a SIGIO signal is sent whenever input or
output becomes possible on the file descriptor. The
fcntl() F_SETSIG operation can be used to obtain delivery
of a signal other than SIGIO.
Sending a signal to the owner process (group) specified by
F_SETOWN is subject to the same permissions checks as are
described for kill(2), where the sending process is the one
that employs F_SETOWN (but see BUGS below). If this
permission check fails, then the signal is silently
discarded. Note: The F_SETOWN operation records the
caller's credentials at the time of the fcntl() call, and
it is these saved credentials that are used for the
permission checks.
If the file descriptor fd refers to a socket, F_SETOWN also
selects the recipient of SIGURG signals that are delivered
when out-of-band data arrives on that socket. (SIGURG is
sent in any situation where select(2) would report the
socket as having an "exceptional condition".)
The following was true in Linux 2.6.x up to and including
Linux 2.6.11:
If a nonzero value is given to F_SETSIG in a
multithreaded process running with a threading
library that supports thread groups (e.g., NPTL),
then a positive value given to F_SETOWN has a
different meaning: 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 F_SETOWN
the result of gettid(2) instead of getpid(2) to get
sensible results when 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
gettid(2) or getpid(2) in this scenario.) Note,
however, that the statements in this paragraph do
not apply to the 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 F_SETOWN.
The above behavior was accidentally dropped in Linux
2.6.12, and won't be restored. From Linux 2.6.32 onward,
use F_SETOWN_EX to target SIGIO and SIGURG signals at a
particular thread.
F_GETOWN_EX
Return the current file descriptor owner settings as
defined by a previous F_SETOWN_EX operation. The
information is returned in the structure pointed to by arg,
which has the following form:
struct f_owner_ex {
int type;
pid_t pid;
};
The type field will have one of the values F_OWNER_TID,
F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive
integer representing a thread ID, process ID, or process
group ID. See F_SETOWN_EX for more details.
F_SETOWN_EX
This operation performs a similar task to 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 arg, which is a pointer
to a f_owner_ex structure. The type field has one of the
following values, which define how pid is interpreted:
F_OWNER_TID
Send the signal to the thread whose thread ID (the
value returned by a call to clone(2) or gettid(2))
is specified in pid.
F_OWNER_PID
Send the signal to the process whose ID is specified
in pid.
F_OWNER_PGRP
Send the signal to the process group whose ID is
specified in pid. (Note that, unlike with F_SETOWN,
a process group ID is specified as a positive value
here.)
F_GETSIG
Return (as the function result) the signal sent when input
or output becomes possible. A value of zero means SIGIO is
sent. Any other value (including SIGIO) is the signal sent
instead, and in this case additional info is available to
the signal handler if installed with SA_SIGINFO. arg is
ignored.
F_SETSIG
Set the signal sent when input or output becomes possible
to the value given in arg. A value of zero means to send
the default SIGIO signal. Any other value (including
SIGIO) is the signal to send instead, and in this case
additional info is available to the signal handler if
installed with SA_SIGINFO.
By using F_SETSIG with a nonzero value, and setting
SA_SIGINFO for the signal handler (see sigaction(2)), extra
information about I/O events is passed to the handler in a
siginfo_t structure. If the si_code field indicates the
source is SI_SIGIO, the 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 (select(2), poll(2),
read(2) with O_NONBLOCK set etc.) to determine which file
descriptors are available for I/O.
Note that the file descriptor provided in si_fd is the one
that was specified during the F_SETSIG operation. This can
lead to an unusual corner case. If the file descriptor is
duplicated (dup(2) or similar), and the original file
descriptor is closed, then I/O events will continue to be
generated, but the si_fd field will contain the number of
the now closed file descriptor.
By selecting a real time signal (value >= SIGRTMIN),
multiple I/O events may be queued using the same signal
numbers. (Queuing is dependent on available memory.)
Extra information is available if SA_SIGINFO is set for the
signal handler, as above.
Note that Linux imposes a limit on the number of real-time
signals that may be queued to a process (see getrlimit(2)
and signal(7)) and if this limit is reached, then the
kernel reverts to delivering SIGIO, and this signal is
delivered to the entire process rather than to a specific
thread.
Using these mechanisms, a program can implement fully asynchronous
I/O without using select(2) or poll(2) most of the time.
The use of O_ASYNC is specific to BSD and Linux. The only use of
F_GETOWN and F_SETOWN specified in POSIX.1 is in conjunction with
the use of the SIGURG signal on sockets. (POSIX does not specify
the SIGIO signal.) F_GETOWN_EX, F_SETOWN_EX, F_GETSIG, and
F_SETSIG are Linux-specific. POSIX has asynchronous I/O and the
aio_sigevent structure to achieve similar things; these are also
available in Linux as part of the GNU C Library (glibc).
See fcntl(2).
F_GETOWN
Value of file descriptor owner.
F_GETSIG
Value of signal sent when read or write becomes possible,
or zero for traditional SIGIO behavior.
F_SETOWN
F_GETOWN_EX
F_SETOWN_EX
F_SETSIG
Zero.
On error, -1 is returned, and errno is set to indicate the error.
See fcntl(2).
EINVAL op is F_SETSIG and arg is not an allowable signal number.
F_GETOWN
F_SETOWN
POSIX.1-2008.
F_GETOWN_EX
F_SETOWN_EX
F_GETSIG
F_SETSIG
Linux. (Define the _GNU_SOURCE macro to obtain these
definitions.)
F_GETOWN
F_SETOWN
POSIX.1-2001. (To get their definitions, define either
_XOPEN_SOURCE with the value 500 or greater, or
_POSIX_C_SOURCE with the value 200809L or greater.)
F_GETOWN_EX
F_GETOWN_EX
Linux 2.6.32.
F_GETSIG
F_GETSIG
Linux.
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 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; that is, the return value of fcntl()
will be -1, and errno will contain the (positive) process group
ID. The Linux-specific F_GETOWN_EX operation avoids this problem.
Since glibc 2.11, glibc makes the kernel F_GETOWN problem
invisible by implementing F_GETOWN using F_GETOWN_EX.
F_SETOWN
In Linux 2.4 and earlier, there is bug that can occur when an
unprivileged process uses F_SETOWN to specify the owner of a
socket file descriptor as a process (group) other than the caller.
In this case, fcntl() can return -1 with errno set to 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.
fcntl(2)
This page is part of the man-pages (Linux kernel and C library
user-space interface documentation) project. Information about
the project can be found at
⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report
for this manual page, see
⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩.
This page was obtained from the tarball man-pages-6.15.tar.gz
fetched from
⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on
2025-08-11. If you discover any rendering problems in this HTML
version of the page, or you believe there is a better or more up-
to-date source for the page, or you have corrections or
improvements to the information in this COLOPHON (which is not
part of the original manual page), send a mail to
man-pages@man7.org
Linux man-pages 6.15 2025-07-20 F_GETSIG(2const)
Pages that refer to this page: fcntl(2)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|