syscalls.2: SEE ALSO: add intro(2)

[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 Michael Kerrisk.
.\"
.\" %%%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.
.\"
.TH FCNTL 2 2014-01-21 "Linux" "Linux Programmer's Manual"
.SH NAME
fcntl \- manipulate file descriptor
.SH SYNOPSIS
.nf
.B #include <unistd.h>
.B #include <fcntl.h>
.sp
.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 .

.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.
.SS Duplicating a file descriptor
.TP
.BR F_DUPFD " (\fIint\fP)"
Find the lowest numbered available file descriptor
greater than or equal to
.I arg
and make it be a copy of
.IR fd .
This is different from
.BR dup2 (2),
which uses exactly the descriptor specified.
.IP
On success, the new 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 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 0, the file descriptor will remain open across an
.BR execve (2),
otherwise it will be closed.
.TP
.BR F_GETFD " (\fIvoid\fP)"
Read 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 .
.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.

The file status flags and their semantics are described in
.BR open (2).
.TP
.BR F_GETFL " (\fIvoid\fP)"
Get 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 locking
.BR F_GETLK ", " F_SETLK ", and " F_SETLKW
are used to acquire, release, and test for the existence of record
locks (also known as 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).
.in +4n
.nf
.sp
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
                        (F_GETLK only) */
    ...
};
.fi
.in
.P
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.

.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.

.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.

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.

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 .
.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.
If one or more incompatible locks would prevent
this lock being placed, then
.BR fcntl ()
returns details about one of these locks in the
.IR l_type ", " l_whence ", " l_start ", and " l_len
fields of
.I lock
and sets
.I l_pid
to be the PID of the process holding that lock.
.P
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.
.P
As well as being removed by an explicit
.BR F_UNLCK ,
record locks are automatically released when the process
terminates or if it closes
.I any
file descriptor referring to a file on which locks are held.
.\" (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 the locks on
a file like
.I /etc/passwd
or
.I /etc/mtab
when for some reason a library function decides to open, read
and close it.
.P
Record locks are not inherited by a child created via
.BR fork (2),
but are preserved across an
.BR execve (2).
.P
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.
.SS Mandatory locking
(Non-POSIX.)
The above record locks may be either advisory or mandatory,
and are advisory by default.

Advisory locks are not enforced and are useful only between
cooperating processes.

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
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