.\" 2014-07-08, David Herrmann <dh.herrmann@gmail.com>
.\" Document F_ADD_SEALS and F_GET_SEALS
.\"
-.TH FCNTL 2 2014-09-06 "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).
of the open file description,
instead of being released on any close of the file.
.PP
-Open file description locks always conflict with traditional record locks,
+Conflicting lock combinations
+(i.e., a read lock and a write lock or two write locks)
+where one lock is an open file description lock and the other
+is a traditional record lock conflict
even when they are acquired by the same process on the same file descriptor.
Open file description locks placed via the same open file description
.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
and the file descriptor open mode doesn't match with the
type of lock requested.
.TP
+.BR EBUSY
+.I cmd
+is
+.BR F_SETPIPE_SZ
+and the new pipe capacity specified in
+.I arg
+is smaller than the amount of buffer space currently
+used to store data in the pipe.
+.TP
.B EBUSY
.I cmd
is
includes
.BR F_SEAL_WRITE ,
and there exists a writable, shared mapping on the file referred to by
-.IR fd .
+.IR fd .
.TP
.B EDEADLK
It was detected that the specified
is outside your accessible address space.
.TP
.B EINTR
-For
-.BR F_SETLKW ,
-the command was interrupted by a signal; see
+.I cmd
+is
+.BR F_SETLKW
+or
+.BR F_OFD_SETLKW
+and the operation was interrupted by a signal; see
.BR signal (7).
-For
-.BR F_GETLK " and " F_SETLK ,
-the command was interrupted by a signal before the lock was checked or
+.TP
+.B EINTR
+.I cmd
+is
+.BR F_GETLK ,
+.BR F_SETLK ,
+.BR F_OFD_GETLK ,
+or
+.BR F_OFD_SETLK ,
+and the operation was interrupted by a signal before the lock was checked or
acquired.
Most likely when locking a remote file (e.g., locking over
NFS), but can sometimes happen locally.
.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 ,
projects / thirdparty / man-pages.git / blobdiff