'\" t
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\"
.\" 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.
.\"
.\" 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>
.\" 2010-06-17, Michael Kerrisk
.\" Document F_SETPIPE_SZ and F_GETPIPE_SZ.
.\"
-.TH FCNTL 2 2010-11-21 "Linux" "Linux Programmer's Manual"
+.TH FCNTL 2 2014-05-21 "Linux" "Linux Programmer's Manual"
.SH NAME
fcntl \- manipulate file descriptor
.SH SYNOPSIS
The required argument type is indicated in parentheses after each
.I cmd
name (in most cases, the required type is
-.IR long ,
+.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"
+.SS Duplicating a file descriptor
.TP
-.BR F_DUPFD " (\fIlong\fP)"
+.BR F_DUPFD " (\fIint\fP)"
Find the lowest numbered available file descriptor
greater than or equal to
.I arg
.BR dup (2)
for further details.
.TP
-.BR F_DUPFD_CLOEXEC " (\fIlong\fP; since Linux 2.6.24)"
+.BR F_DUPFD_CLOEXEC " (\fIint\fP; since Linux 2.6.24)"
As for
.BR F_DUPFD ,
but additionally set the
.B O_CLOEXEC
in
.BR open (2).
-.SS "File descriptor flags"
+.SS File descriptor flags
The following commands manipulate the flags associated with
a file descriptor.
Currently, only one such flag is defined:
.I arg
is ignored.
.TP
-.BR F_SETFD " (\fIlong\fP)"
+.BR F_SETFD " (\fIint\fP)"
Set the file descriptor flags to the value specified by
.IR arg .
-.SS "File status flags"
+.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)
.BR open (2).
.TP
.BR F_GETFL " (\fIvoid\fP)"
-Read the file status flags;
+Get the file access mode and the file status flags;
.I arg
is ignored.
.TP
-.BR F_SETFL " (\fIlong\fP)"
+.BR F_SETFL " (\fIint\fP)"
Set the file status flags to the value specified by
.IR arg .
File access mode
in
.I arg
are ignored.
-On Linux this command can only change the
+On Linux this command can change only the
.BR O_APPEND ,
.BR O_ASYNC ,
.BR O_DIRECT ,
and
.B O_NONBLOCK
flags.
-.\" FIXME . According to POSIX.1-2001, O_SYNC should also be modifiable
-.\" via fcntl(2), but currently Linux does not permit this
-.\" See http://bugzilla.kernel.org/show_bug.cgi?id=5994
-.SS "Advisory locking"
-.BR F_GETLK ", " F_SETLK " and " F_SETLKW
+It is not possible to change the
+.BR O_DSYNC
+and
+.BR O_SYNC
+flags; see BUGS, below.
+.SS Advisory locking
+.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 file-segment or file-region locks).
The third argument,
is positive, then the range to be locked covers bytes
.I l_start
up to and including
-.IR l_start + l_len \- 1 .
+.IR l_start + l_len \-1.
Specifying 0 for
.I l_len
has the special meaning: lock all bytes starting at the
and sets
.I l_pid
to be the PID of the process holding that lock.
+Note that the information returned by
+.BR F_GETLK
+may already be out of date by the time the caller inspects it.
.P
In order to place a read lock,
.I fd
and
.BR write (2)
instead.
-.SS "Mandatory locking"
+.SS Mandatory locking
(Non-POSIX.)
The above record locks may be either advisory or mandatory,
and are advisory by default.
.BR EAGAIN .
To make use of mandatory locks, mandatory locking must be enabled
-both on the file system that contains the file to be locked,
+both on the filesystem that contains the file to be locked,
and on the file itself.
-Mandatory locking is enabled on a file system
+Mandatory locking is enabled on a filesystem
using the "\-o mand" option to
.BR mount (8),
or the
The Linux implementation of mandatory locking is unreliable.
See BUGS below.
-.SS "Managing signals"
+.SS Managing signals
.BR F_GETOWN ,
.BR F_SETOWN ,
.BR F_GETOWN_EX ,
.I arg
is ignored.
.TP
-.BR F_SETOWN " (\fIlong\fP)"
+.BR F_SETOWN " (\fIint\fP)"
Set the process ID or process group ID that will receive
.B SIGIO
and
.I arg
is ignored.
.TP
-.BR F_SETSIG " (\fIlong\fP)"
+.BR F_SETSIG " (\fIint\fP)"
Set the signal sent when input or output becomes possible
to the value given in
.IR arg .
most of the time.
.PP
The use of
-.BR O_ASYNC ,
-.BR F_GETOWN ,
-.B F_SETOWN
+.BR O_ASYNC
is specific to BSD and Linux.
+The only use of
+.BR F_GETOWN
+and
+.B F_SETOWN
+specified in POSIX.1 is in conjunction with the use of the
+.B SIGURG
+signal on sockets.
+(POSIX does not specify the
+.BR SIGIO
+signal.)
.BR F_GETOWN_EX ,
.BR F_SETOWN_EX ,
.BR F_GETSIG ,
.BR truncate (2)
the file referred to by that file descriptor.
.TP
-.BR F_SETLEASE " (\fIlong\fP)"
+.BR F_SETLEASE " (\fIint\fP)"
Set or remove a file lease according to which of the following
values is specified in the integer
.IR arg :
the file is opened for writing or is truncated.
.\" The following became true in kernel 2.6.10:
.\" See the man-pages-2.09 Changelog for further info.
-A read lease can only be placed on a file descriptor that
+A read lease can be placed only on a file descriptor that
is opened read-only.
.TP
.B F_WRLCK
operation on any of these duplicate descriptors, or when all
such descriptors have been closed.
.P
-Leases may only be taken out on regular files.
-An unprivileged process may only take out a lease on a file whose
-UID (owner) matches the file system UID of the process.
+Leases may be taken out only on regular files.
+An unprivileged process may take out a lease only on a file whose
+UID (owner) matches the filesystem UID of the process.
A process with the
.B CAP_LEASE
capability may take out leases on arbitrary files.
If the lease holder fails to downgrade or remove the lease within
the number of seconds specified in
-.I /proc/sys/fs/lease-break-time
+.IR /proc/sys/fs/lease-break-time ,
then the kernel forcibly removes or downgrades the lease holder's lease.
+Once a lease break has been initiated,
+.B F_GETLEASE
+returns the target lease type (either
+.B F_RDLCK
+or
+.BR F_UNLCK ,
+depending on what would be compatible with the lease breaker)
+until the lease holder voluntarily downgrades or removes the lease or
+the kernel forcibly does so after the lease break timer expires.
+
Once the lease has been voluntarily or forcibly removed or downgraded,
and assuming the lease breaker has not unblocked its system call,
the kernel permits the lease breaker's system call to proceed.
field of this argument will hold the descriptor of the leased file
that has been accessed by another process.
(This is useful if the caller holds leases against multiple files).
-.SS "File and directory change notification (dnotify)"
+.SS File and directory change notification (dnotify)
.TP
-.BR F_NOTIFY " (\fIlong\fP)"
+.BR F_NOTIFY " (\fIint\fP)"
(Linux 2.4 onward)
Provide notification when the directory referred to by
.I fd
.I inotify
interface (available since kernel 2.6.13),
which provides a much superior interface for obtaining notifications of
-file system events.
+filesystem events.
See
.BR inotify (7).
-.SS "Changing the capacity of a pipe"
+.SS Changing the capacity of a pipe
.TP
-.BR F_SETPIPE_SZ " (\fIlong\fP; since Linux 2.6.35)"
+.BR F_SETPIPE_SZ " (\fIint\fP; since Linux 2.6.35)"
Change the capacity of the pipe referred to by
.I fd
to be at least
bytes.
An unprivileged process can adjust the pipe capacity to any value
between the system page size and the limit defined in
-.IR /proc/sys/fs/pipe-size-max
+.IR /proc/sys/fs/pipe-max-size
(see
.BR proc (5)).
Attempts to set the pipe capacity below the page size are silently
rounded up to the page size.
Attempts by an unprivileged process to set the pipe capacity above the limit in
-.IR /proc/sys/fs/pipe-size-max
+.IR /proc/sys/fs/pipe-max-size
yield the error
.BR EPERM ;
a privileged process
.BR F_GETPIPE_SZ " (\fIvoid\fP; since Linux 2.6.35)"
Return (as the function result) the capacity of the pipe referred to by
.IR fd .
-.SH "RETURN VALUE"
+.SH RETURN VALUE
For a successful call, the return value depends on the operation:
.TP 0.9i
.B F_DUPFD
Attempted to clear the
.B O_APPEND
flag on a file that has the append-only attribute set.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
SVr4, 4.3BSD, POSIX.1-2001.
Only the operations
.BR F_DUPFD ,
.BR F_GETFL ,
.BR F_SETFL ,
.BR F_GETLK ,
-.BR F_SETLK
+.BR F_SETLK ,
and
-.BR F_SETLKW ,
+.BR F_SETLKW
are specified in POSIX.1-2001.
.BR F_GETOWN
.B F_SETOWN
are specified in POSIX.1-2001.
(To get their definitions, define
-.BR BSD_SOURCE ,
+.BR _BSD_SOURCE ,
or
.BR _XOPEN_SOURCE
with the value 500 or greater, or define
.\" .PP
.\" SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions.
.SH NOTES
+The errors returned by
+.BR dup2 (2)
+are different from those returned by
+.BR F_DUPFD .
+.\"
+.SS File locking
The original Linux
.BR fcntl ()
system call was not designed to handle large file offsets
wrapper function transparently employs the more recent system call
where it is available.
-The errors returned by
-.BR dup2 (2)
-are different from those returned by
-.BR F_DUPFD .
-
Since kernel 2.0, there is no interaction between the types of lock
placed by
.BR flock (2)
alone is not going to be very useful if the process holding the lock
may live on a different machine.
.SH BUGS
+.SS F_SETFL
+It is not possible to use
+.BR F_SETFL
+to change the state of the
+.BR O_DSYNC
+and
+.BR O_SYNC
+flags.
+.\" FIXME . According to POSIX.1-2001, O_SYNC should also be modifiable
+.\" via fcntl(2), but currently Linux does not permit this
+.\" See http://bugzilla.kernel.org/show_bug.cgi?id=5994
+Attempts to change the state of these flags are silently ignored.
+.SS 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
.B F_GETOWN
using
.BR F_GETOWN_EX .
-
+.SS F_SETOWN
In Linux 2.4 and earlier, there is bug that can occur
when an unprivileged process uses
.B F_SETOWN
has permission to send signals to.
Despite this error return, the file descriptor owner is set,
and signals will be sent to the owner.
-
+.SS Mandatory locking
The implementation of mandatory locking in all known versions of Linux
is subject to race conditions which render it unreliable:
.\" http://marc.info/?l=linux-kernel&m=119013491707153&w=2
Similar races exist between mandatory locks and
.BR mmap (2).
It is therefore inadvisable to rely on mandatory locking.
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR dup2 (2),
.BR flock (2),
.BR open (2),
.BR lockf (3),
.BR capabilities (7),
.BR feature_test_macros (7)
-.P
-See also
+
.IR locks.txt ,
.IR mandatory-locking.txt ,
and
.I dnotify.txt
-in the kernel source directory
-.IR Documentation/filesystems/ .
-(On older kernels, these files are directly under the
+in the Linux kernel source directory
+.IR Documentation/filesystems/
+(on older kernels, these files are directly under the
.I Documentation/
directory, and
.I mandatory-locking.txt
is called
-.IR mandatory.txt .)
+.IR mandatory.txt )
+.SH COLOPHON
+This page is part of release 3.68 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
