user_namespaces.7: Minor rewordings of recently added text

[thirdparty/man-pages.git] / man2 / fcntl.2

'\" t
.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson;
.\" and Copyright (C) 1998 Jamie Lokier;
.\" and Copyright (C) 2002-2010, 2014 Michael Kerrisk;
.\" and Copyright (C) 2014 Jeff Layton
.\" and Copyright (C) 2014 David Herrmann
.\" and Copyright (C) 2017 Jens Axboe
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
.\" Modified 1995-09-26 by Andries Brouwer <aeb@cwi.nl>
.\" and again on 960413 and 980804 and 981223.
.\" Modified 1998-12-11 by Jamie Lokier <jamie@imbolc.ucc.ie>
.\" Applied correction by Christian Ehrhardt - aeb, 990712
.\" Modified 2002-04-23 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"	Added note on F_SETFL and O_DIRECT
.\"	Complete rewrite + expansion of material on file locking
.\"	Incorporated description of F_NOTIFY, drawing on
.\"		Stephen Rothwell's notes in Documentation/dnotify.txt.
.\"	Added description of F_SETLEASE and F_GETLEASE
.\" Corrected and polished, aeb, 020527.
.\" Modified 2004-03-03 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"     Modified description of file leases: fixed some errors of detail
.\"     Replaced the term "lease contestant" by "lease breaker"
.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
.\"     Added notes on capability requirements
.\" Modified 2004-12-08, added O_NOATIME after note from Martin Pool
.\" 2004-12-10, mtk, noted F_GETOWN bug after suggestion from aeb.
.\" 2005-04-08 Jamie Lokier <jamie@shareable.org>, mtk
.\"	Described behavior of F_SETOWN/F_SETSIG in
.\"	multithreaded processes, and generally cleaned
.\"	up the discussion of F_SETOWN.
.\" 2005-05-20, Johannes Nicolai <johannes.nicolai@hpi.uni-potsdam.de>,
.\"	mtk: Noted F_SETOWN bug for socket file descriptor in Linux 2.4
.\"	and earlier.  Added text on permissions required to send signal.
.\" 2009-09-30, Michael Kerrisk
.\"     Note obsolete F_SETOWN behavior with threads.
.\"     Document F_SETOWN_EX and F_GETOWN_EX
.\" 2010-06-17, Michael Kerrisk
.\"	Document F_SETPIPE_SZ and F_GETPIPE_SZ.
.\" 2014-07-08, David Herrmann <dh.herrmann@gmail.com>
.\"     Document F_ADD_SEALS and F_GET_SEALS
.\" 2017-06-26, Jens Axboe <axboe@kernel.dk>
.\"     Document F_{GET,SET}_RW_HINT and F_{GET,SET}_FILE_RW_HINT
.\"
.TH FCNTL 2 2019-03-06 "Linux" "Linux Programmer's Manual"
.SH NAME
fcntl \- manipulate file descriptor
.SH SYNOPSIS
.nf
.B #include <unistd.h>
.B #include <fcntl.h>
.PP
.BI "int fcntl(int " fd ", int " cmd ", ... /* " arg " */ );"
.fi
.SH DESCRIPTION
.BR fcntl ()
performs one of the operations described below on the open file descriptor
.IR fd .
The operation is determined by
.IR cmd .
.PP
.BR fcntl ()
can take an optional third argument.
Whether or not this argument is required is determined by
.IR cmd .
The required argument type is indicated in parentheses after each
.I cmd
name (in most cases, the required type is
.IR int ,
and we identify the argument using the name
.IR arg ),
or
.I void
is specified if the argument is not required.
.PP
Certain of the operations below are supported only since a particular
Linux kernel version.
The preferred method of checking whether the host kernel supports
a particular operation is to invoke
.BR fcntl ()
with the desired
.IR cmd
value and then test whether the call failed with
.BR EINVAL ,
indicating that the kernel does not recognize this value.
.SS Duplicating a file descriptor
.TP
.BR F_DUPFD " (\fIint\fP)"
Duplicate the file descriptor
.IR fd
using the lowest-numbered available file descriptor greater than or equal to
.IR arg .
This is different from
.BR dup2 (2),
which uses exactly the file descriptor specified.
.IP
On success, the new file descriptor is returned.
.IP
See
.BR dup (2)
for further details.
.TP
.BR F_DUPFD_CLOEXEC " (\fIint\fP; since Linux 2.6.24)"
As for
.BR F_DUPFD ,
but additionally set the
close-on-exec flag for the duplicate file descriptor.
Specifying this flag permits a program to avoid an additional
.BR fcntl ()
.B F_SETFD
operation to set the
.B FD_CLOEXEC
flag.
For an explanation of why this flag is useful,
see the description of
.B O_CLOEXEC
in
.BR open (2).
.SS File descriptor flags
The following commands manipulate the flags associated with
a file descriptor.
Currently, only one such flag is defined:
.BR FD_CLOEXEC ,
the close-on-exec flag.
If the
.B FD_CLOEXEC
bit is set,
the file descriptor will automatically be closed during a successful
.BR execve (2).
(If the
.BR execve (2)
fails, the file descriptor is left open.)
If the
.B FD_CLOEXEC
bit is not set, the file descriptor will remain open across an
.BR execve (2).
.TP
.BR F_GETFD " (\fIvoid\fP)"
Return (as the function result) the file descriptor flags;
.I arg
is ignored.
.TP
.BR F_SETFD " (\fIint\fP)"
Set the file descriptor flags to the value specified by
.IR arg .
.PP
In multithreaded programs, using
.BR fcntl ()
.B F_SETFD
to set the close-on-exec flag at the same time as another thread performs a
.BR fork (2)
plus
.BR execve (2)
is vulnerable to a race condition that may unintentionally leak
the file descriptor to the program executed in the child process.
See the discussion of the
.BR O_CLOEXEC
flag in
.BR open (2)
for details and a remedy to the problem.
.SS File status flags
Each open file description has certain associated status flags,
initialized by
.BR open (2)
.\" or
.\" .BR creat (2),
and possibly modified by
.BR fcntl ().
Duplicated file descriptors
(made with
.BR dup (2),
.BR fcntl (F_DUPFD),
.BR fork (2),
etc.) refer to the same open file description, and thus
share the same file status flags.
.PP
The file status flags and their semantics are described in
.BR open (2).
.TP
.BR F_GETFL " (\fIvoid\fP)"
Return (as the function result)
the file access mode and the file status flags;
.I arg
is ignored.
.TP
.BR F_SETFL " (\fIint\fP)"
Set the file status flags to the value specified by
.IR arg .
File access mode
.RB ( O_RDONLY ", " O_WRONLY ", " O_RDWR )
and file creation flags
(i.e.,
.BR O_CREAT ", " O_EXCL ", " O_NOCTTY ", " O_TRUNC )
in
.I arg
are ignored.
On Linux, this command can change only the
.BR O_APPEND ,
.BR O_ASYNC ,
.BR O_DIRECT ,
.BR O_NOATIME ,
and
.B O_NONBLOCK
flags.
It is not possible to change the
.BR O_DSYNC
and
.BR O_SYNC
flags; see BUGS, below.
.SS Advisory record locking
Linux implements traditional ("process-associated") UNIX record locks,
as standardized by POSIX.
For a Linux-specific alternative with better semantics,
see the discussion of open file description locks below.
.PP
.BR F_SETLK ,
.BR F_SETLKW ,
and
.BR F_GETLK
are used to acquire, release, and test for the existence of record
locks (also known as byte-range, file-segment, or file-region locks).
The third argument,
.IR lock ,
is a pointer to a structure that has at least the following fields
(in unspecified order).
.PP
.in +4n
.EX
struct flock {
    ...
    short l_type;    /* Type of lock: F_RDLCK,
                        F_WRLCK, F_UNLCK */
    short l_whence;  /* How to interpret l_start:
                        SEEK_SET, SEEK_CUR, SEEK_END */
    off_t l_start;   /* Starting offset for lock */
    off_t l_len;     /* Number of bytes to lock */
    pid_t l_pid;     /* PID of process blocking our lock
                        (set by F_GETLK and F_OFD_GETLK) */
    ...
};
.EE
.in
.PP
The
.IR l_whence ", " l_start ", and " l_len
fields of this structure specify the range of bytes we wish to lock.
Bytes past the end of the file may be locked,
but not bytes before the start of the file.
.PP
.I l_start
is the starting offset for the lock, and is interpreted
relative to either:
the start of the file (if
.I l_whence
is
.BR SEEK_SET );
the current file offset (if
.I l_whence
is
.BR SEEK_CUR );
or the end of the file (if
.I l_whence
is
.BR SEEK_END ).
In the final two cases,
.I l_start
can be a negative number provided the
offset does not lie before the start of the file.
.PP
.I l_len
specifies the number of bytes to be locked.
If
.I l_len
is positive, then the range to be locked covers bytes
.I l_start
up to and including
.IR l_start + l_len \-1.
Specifying 0 for
.I l_len
has the special meaning: lock all bytes starting at the
location specified by
.IR l_whence " and " l_start
through to the end of file, no matter how large the file grows.
.PP
POSIX.1-2001 allows (but does not require)
an implementation to support a negative
.I l_len
value; if
.I l_len
is negative, the interval described by
.I lock
covers bytes
.IR l_start + l_len
up to and including
.IR l_start \-1.
This is supported by Linux since kernel versions 2.4.21 and 2.5.49.
.PP
The
.I l_type
field can be used to place a read
.RB ( F_RDLCK )
or a write
.RB ( F_WRLCK )
lock on a file.
Any number of processes may hold a read lock (shared lock)
on a file region, but only one process may hold a write lock
(exclusive lock).
An exclusive lock excludes all other locks,
both shared and exclusive.
A single process can hold only one type of lock on a file region;
if a new lock is applied to an already-locked region,
then the existing lock is converted to the new lock type.
(Such conversions may involve splitting, shrinking, or coalescing with
an existing lock if the byte range specified by the new lock does not
precisely coincide with the range of the existing lock.)
.TP
.BR F_SETLK " (\fIstruct flock *\fP)"
Acquire a lock (when
.I l_type
is
.B F_RDLCK
or
.BR F_WRLCK )
or release a lock (when
.I l_type
is
.BR F_UNLCK )
on the bytes specified by the
.IR l_whence ", " l_start ", and " l_len
fields of
.IR lock .
If a conflicting lock is held by another process,
this call returns \-1 and sets
.I errno
to
.B EACCES
or
.BR EAGAIN .
(The error returned in this case differs across implementations,
so POSIX requires a portable application to check for both errors.)
.TP
.BR F_SETLKW " (\fIstruct flock *\fP)"
As for
.BR F_SETLK ,
but if a conflicting lock is held on the file, then wait for that
lock to be released.
If a signal is caught while waiting, then the call is interrupted
and (after the signal handler has returned)
returns immediately (with return value \-1 and
.I errno
set to
.BR EINTR ;
see
.BR signal (7)).
.TP
.BR F_GETLK " (\fIstruct flock *\fP)"
On input to this call,
.I lock
describes a lock we would like to place on the file.
If the lock could be placed,
.BR fcntl ()
does not actually place it, but returns
.B F_UNLCK
in the
.I l_type
field of
.I lock
and leaves the other fields of the structure unchanged.
.IP
If one or more incompatible locks would prevent
this lock being placed, then
.BR fcntl ()
returns details about one of those locks in the
.IR l_type ", " l_whence ", " l_start ", and " l_len
fields of
.IR lock .
If the conflicting lock is a traditional (process-associated) record lock,
then the
.I l_pid
field is set to the PID of the process holding that lock.
If the conflicting lock is an open file description lock, then
.I l_pid
is set to \-1.
Note that the returned information
may already be out of date by the time the caller inspects it.
.PP
In order to place a read lock,
.I fd
must be open for reading.
In order to place a write lock,
.I fd
must be open for writing.
To place both types of lock, open a file read-write.
.PP
When placing locks with
.BR F_SETLKW ,
the kernel detects
.IR deadlocks ,
whereby two or more processes have their
lock requests mutually blocked by locks held by the other processes.
For example, suppose process A holds a write lock on byte 100 of a file,
and process B holds a write lock on byte 200.
If each process then attempts to lock the byte already
locked by the other process using
.BR F_SETLKW ,
then, without deadlock detection,
both processes would remain blocked indefinitely.
When the kernel detects such deadlocks,
it causes one of the blocking lock requests to immediately fail with the error
.BR EDEADLK ;
an application that encounters such an error should release
some of its locks to allow other applications to proceed before
attempting regain the locks that it requires.
Circular deadlocks involving more than two processes are also detected.
Note, however, that there are limitations to the kernel's
deadlock-detection algorithm; see BUGS.
.PP
As well as being removed by an explicit
.BR F_UNLCK ,
record locks are automatically released when the process terminates.
.PP
Record locks are not inherited by a child created via
.BR fork (2),
but are preserved across an
.BR execve (2).
.PP
Because of the buffering performed by the
.BR stdio (3)
library, the use of record locking with routines in that package
should be avoided; use
.BR read (2)
and
.BR write (2)
instead.
.PP
The record locks described above are associated with the process
(unlike the open file description locks described below).
This has some unfortunate consequences:
.IP * 3
If a process closes
.I any
file descriptor referring to a file,
then all of the process's locks on that file are released,
regardless of the file descriptor(s) on which the locks were obtained.
.\" (Additional file descriptors referring to the same file
.\" may have been obtained by calls to
.\" .BR open "(2), " dup "(2), " dup2 "(2), or " fcntl ().)
This is bad: it means that a process can lose its locks on
a file such as
.I /etc/passwd
or
.I /etc/mtab
when for some reason a library function decides to open, read,
and close the same file.
.IP *
The threads in a process share locks.
In other words,
a multithreaded program can't use record locking to ensure
that threads don't simultaneously access the same region of a file.
.PP
Open file description locks solve both of these problems.
.SS Open file description locks (non-POSIX)
Open file description locks are advisory byte-range locks whose operation is
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).
.PP
The principal difference between the two lock types
is that whereas traditional record locks
are associated with a process,
open file description locks are associated with the
open file description on which they are acquired,
much like locks acquired with
.BR flock (2).
Consequently (and unlike traditional advisory record locks),
open file description locks are inherited across
.BR fork (2)
(and
.BR clone (2)
with
.BR CLONE_FILES ),
and are only automatically released on the last close
of the open file description,
instead of being released on any close of the file.
.PP
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.
.PP
Open file description locks placed via the same open file description
(i.e., via the same file descriptor,
or via a duplicate of the file descriptor created by
.BR fork (2),
.BR dup (2),
.BR fcntl ()
.BR F_DUPFD ,
and so on) are always compatible:
if a new lock is placed on an already locked region,
then the existing lock is converted to the new lock type.
(Such conversions may result in splitting, shrinking, or coalescing with
an existing lock as discussed above.)
.PP
On the other hand, open file description locks may conflict with
each other when they are acquired via different open file descriptions.
Thus, the threads in a multithreaded program can use
open file description locks to synchronize access to a file region
by having each thread perform its own
.BR open (2)
on the file and applying locks via the resulting file descriptor.
.PP
As with traditional advisory locks, the third argument to
.BR fcntl (),
.IR lock ,
is a pointer to an
.IR flock
structure.
By contrast with traditional record locks, the
.I l_pid
field of that structure must be set to zero
when using the commands described below.
.PP
The commands for working with open file description locks are analogous
to those used with traditional locks:
.TP
.BR F_OFD_SETLK " (\fIstruct flock *\fP)"
Acquire an open file description lock (when
.I l_type
is
.B F_RDLCK
or
.BR F_WRLCK )
or release an open file description lock (when
.I l_type
is
.BR F_UNLCK )
on the bytes specified by the
.IR l_whence ", " l_start ", and " l_len
fields of
.IR lock .
If a conflicting lock is held by another process,
this call returns \-1 and sets
.I errno
to
.BR EAGAIN .
.TP
.BR F_OFD_SETLKW " (\fIstruct flock *\fP)"
As for
.BR F_OFD_SETLK ,
but if a conflicting lock is held on the file, then wait for that lock to be
released.
If a signal is caught while waiting, then the call is interrupted
and (after the signal handler has returned) returns immediately
(with return value \-1 and
.I errno
set to
.BR EINTR ;
see
.BR signal (7)).
.TP
.BR F_OFD_GETLK " (\fIstruct flock *\fP)"
On input to this call,
.I lock
describes an open file description lock we would like to place on the file.
If the lock could be placed,
.BR fcntl ()
does not actually place it, but returns
.B F_UNLCK
in the
.I l_type
field of
.I lock
and leaves the other fields of the structure unchanged.
If one or more incompatible locks would prevent this lock being placed,
then details about one of these locks are returned via
.IR lock ,
as described above for
.BR F_GETLK .
.PP
In the current implementation,
.\" commit 57b65325fe34ec4c917bc4e555144b4a94d9e1f7
no deadlock detection is performed for open file description locks.
(This contrasts with process-associated record locks,
for which the kernel does perform deadlock detection.)
.\"
.SS Mandatory locking
.IR Warning :
the Linux implementation of mandatory locking is unreliable.
See BUGS below.
Because of these bugs,
and the fact that the feature is believed to be little used,
since Linux 4.5, mandatory locking has been made an optional feature,
governed by a configuration option
.RB ( CONFIG_MANDATORY_FILE_LOCKING ).
This is an initial step toward removing this feature completely.
.PP
By default, both traditional (process-associated) and open file description
record locks are advisory.
Advisory locks are not enforced and are useful only between
cooperating processes.
.PP
Both lock types can also be mandatory.
Mandatory locks are enforced for all processes.
If a process tries to perform an incompatible access (e.g.,
.BR read (2)
or
.BR write (2))
on a file region that has an incompatible mandatory lock,
then the result depends upon whether the
.B O_NONBLOCK
flag is enabled for its open file description.
If the
.B O_NONBLOCK
flag is not enabled, then
the system call is blocked until the lock is removed
or converted to a mode that is compatible with the access.
If the
.B O_NONBLOCK
flag is enabled, then the system call fails with the error