.\" 2014-07-08, David Herrmann <dh.herrmann@gmail.com>
.\" Document F_ADD_SEALS and F_GET_SEALS
.\"
-.TH FCNTL 2 2015-02-21 "Linux" "Linux Programmer's Manual"
+.TH FCNTL 2 2016-03-15 "Linux" "Linux Programmer's Manual"
.SH NAME
fcntl \- manipulate file descriptor
.SH SYNOPSIS
.IR fd .
This is different from
.BR dup2 (2),
-which uses exactly the descriptor specified.
+which uses exactly the file descriptor specified.
.IP
-On success, the new descriptor is returned.
+On success, the new file descriptor is returned.
.IP
See
.BR dup (2)
As for
.BR F_DUPFD ,
but additionally set the
-close-on-exec flag for the duplicate descriptor.
+close-on-exec flag for the duplicate file descriptor.
Specifying this flag permits a program to avoid an additional
.BR fcntl ()
.B F_SETFD
in most respects identical to the traditional record locks described above.
This lock type is Linux-specific,
and available since Linux 3.15.
+(There is a proposal with the Austin Group
+.\" FIXME . Review progress into POSIX
+.\" http://austingroupbugs.net/view.php?id=768
+to include this lock type in the next revision of POSIX.1.)
For an explanation of open file descriptions, see
.BR open (2).
.B SIGIO
and
.B SIGURG
-signals for events on file descriptor
-.IR fd
-to the ID given in
+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.
is specified as
.BR getpid (2)).
-.\" From glibc.info:
-If you set the
-.B O_ASYNC
-status flag on a file descriptor by using the
+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 fcntl ()
.B F_SETFL
-command of
-.BR fcntl (),
-a
+command 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 that file descriptor.
+on the file descriptor.
+The
+.BR fcntl ()
.B F_SETSIG
-can be used to obtain delivery of a signal other than
+command can be used to obtain delivery of a signal other than
.BR SIGIO .
-If this permission check fails, then the signal is
-silently discarded.
Sending a signal to the owner process (group) specified by
.B F_SETOWN
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.
If the file descriptor
.I fd
.B SIGURG
signals at a particular thread.
.TP
-.BR F_GETOWN_EX " (struct f_owner_ex *) (since Linux 2.6.32)"
+.BR F_GETOWN_EX " (\fIstruct f_owner_ex *\fP) (since Linux 2.6.32)"
Return the current file descriptor owner settings
as defined by a previous
.BR F_SETOWN_EX
.B F_SETOWN_EX
for more details.
.TP
-.BR F_SETOWN_EX " (struct f_owner_ex *) (since Linux 2.6.32)"
+.BR F_SETOWN_EX " (\fIstruct f_owner_ex *\fP) (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
.B O_NONBLOCK
set etc.) to determine which file descriptors are available for I/O.
+Note that the file descriptor provided in
+.I si_fd
+is the one that was specified during the
+.BR 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.
+
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).
+(Queuing is dependent on available memory.)
Extra information is available
if
.B SA_SIGINFO
or released using any of these descriptors.
Furthermore, the lease is released by either an explicit
.B F_UNLCK
-operation on any of these duplicate descriptors, or when all
-such descriptors have been closed.
+operation on any of these duplicate file descriptors, or when all
+such file descriptors have been closed.
.P
Leases may be taken out only on regular files.
An unprivileged process may take out a lease only on a file whose
.I siginfo_t
structure as its second argument, and the
.I si_fd
-field of this argument will hold the descriptor of the leased file
+field of this argument will hold the file descriptor of the leased file
that has been accessed by another process.
-(This is useful if the caller holds leases against multiple files).
+(This is useful if the caller holds leases against multiple files.)
.SS File and directory change notification (dnotify)
.TP
.BR F_NOTIFY " (\fIint\fP)"
still possible and allowed.
.\" One or more other seals are typically used with F_SEAL_WRITE
.\" because, given a file with the F_SEAL_WRITE seal set, then,
-.\" while it would no longer be possinle to (say) write zeros into
+.\" while it would no longer be possible to (say) write zeros into
.\" the last 100 bytes of a file, it would still be possible
.\" to (say) shrink the file by 100 bytes using ftruncate(), and
.\" then increase the file size by 100 bytes, which would have
For a successful call, the return value depends on the operation:
.TP 0.9i
.B F_DUPFD
-The new descriptor.
+The new file descriptor.
.TP
.B F_GETFD
Value of file descriptor flags.
Type of lease held on file descriptor.
.TP
.B F_GETOWN
-Value of descriptor owner.
+Value of file descriptor owner.
.TP
.B F_GETSIG
Value of signal sent when read or write becomes possible, or zero
.I cmd
is
.BR F_DUPFD
-and the process already has the maximum number of file descriptors open.
+and the per-process limit on the number of open file descriptors
+has been reached.
.TP
.B ENOLCK
Too many segment locks open, lock table is full, or a remote locking
.B F_SETOWN
are specified in POSIX.1-2001.
(To get their definitions, define either
-.BR _BSD_SOURCE ,
-or
+.\" .BR _BSD_SOURCE ,
+.\" or
.BR _XOPEN_SOURCE
with the value 500 or greater, or
.BR _POSIX_C_SOURCE
.BR F_ADD_SEALS
and
.BR F_GET_SEALS
-are Lnux-specific.
+are Linux-specific.
.\" FIXME . Once glibc adds support, add a note about FTM requirements
.SH NOTES
The errors returned by
.BR socket (2),
.BR lockf (3),
.BR capabilities (7),
-.BR feature_test_macros (7)
+.BR feature_test_macros (7),
+.BR lslocks (8)
.IR locks.txt ,
.IR mandatory-locking.txt ,