LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

fcntl.2: ffix 

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2017-08-13 22:40:20 +02:00
parent a12f0259f8
commit 778ac6277e
1 changed files with 62 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
man2/fcntl.2
View File

@ -69,7 +69,7 @@ fcntl \- manipulate file descriptor
.nf
.B #include <unistd.h>
.B #include <fcntl.h>
.sp
.PP
.BI "int fcntl(int " fd ", int " cmd ", ... /* " arg " */ );"
.fi
.SH DESCRIPTION
@ -78,7 +78,7 @@ 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
@ -92,7 +92,7 @@ and we identify the argument using the name
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
@ -193,7 +193,7 @@ Duplicated file descriptors
.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
@ -232,7 +232,7 @@ 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
@ -243,9 +243,9 @@ The third argument,
.IR lock ,
is a pointer to a structure that has at least the following fields
(in unspecified order).
.PP
.in +4n
.nf
.sp
.EX
struct flock {
...
short l_type; /* Type of lock: F_RDLCK,
@ -258,15 +258,15 @@ struct flock {
(set by F_GETLK and F_OFD_GETLK) */
...
};
.fi
.EE
.in
.P
.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:
@ -286,7 +286,7 @@ 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
@ -301,7 +301,7 @@ 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
@ -314,7 +314,7 @@ covers bytes
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
@ -386,7 +386,7 @@ in the
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 ()
@ -411,7 +411,7 @@ 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
@ -434,7 +434,7 @@ 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.
@ -452,7 +452,7 @@ should be avoided; use
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:
@ -490,7 +490,7 @@ and available since Linux 3.15.
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,
@ -514,7 +514,7 @@ Conflicting lock combinations
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
@ -527,7 +527,7 @@ 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
@ -546,7 +546,7 @@ 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
@ -620,12 +620,12 @@ 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.,
@ -645,7 +645,7 @@ If the
.B O_NONBLOCK
flag is enabled, then the system call fails with the error
.BR EAGAIN .
.PP
To make use of mandatory locks, mandatory locking must be enabled
both on the filesystem that contains the file to be locked,
and on the file itself.
@ -662,7 +662,7 @@ permission bit (see
.BR chmod (1)
and
.BR chmod (2)).
.PP
Mandatory locking is not specified by POSIX.
Some other systems also support mandatory locking,
although the details of how to enable it vary across systems.
@ -705,7 +705,7 @@ Most commonly, the calling process specifies itself as the owner
.I arg
is specified as
.BR getpid (2)).
.IP
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
@ -723,7 +723,7 @@ The
.B F_SETSIG
command can be used to obtain delivery of a signal other than
.BR SIGIO .
.IP
Sending a signal to the owner process (group) specified by
.B F_SETOWN
is subject to the same permissions checks as are described for
@ -740,7 +740,7 @@ operation records the caller's credentials at the time of the
.BR fcntl ()
call,
and it is these saved credentials that are used for the permission checks.
.IP
If the file descriptor
.I fd
refers to a socket,
@ -764,7 +764,7 @@ would report the socket as having an "exceptional condition".)
.\" .I fd
.\" refers to a terminal device, then SIGIO
.\" signals are sent to the foreground process group of the terminal.
.IP
The following was true in 2.6.x kernels up to and including
kernel 2.6.11:
.RS
@ -827,16 +827,16 @@ operation.
The information is returned in the structure pointed to by
.IR arg ,
which has the following form:
.nf
.IP
.in +4n
.EX
struct f_owner_ex {
int type;
pid_t pid;
};
.EE
.in
.fi
.IP
The
.I type
field will have one of the values
@ -929,7 +929,7 @@ is available to the signal handler if installed with
.\" See the description of
.\" .B F_SETOWN
.\" for more details.
.IP
By using
.B F_SETSIG
with a nonzero value, and setting
@ -957,7 +957,7 @@ should use the usual mechanisms
with
.B O_NONBLOCK
set etc.) to determine which file descriptors are available for I/O.
.IP
Note that the file descriptor provided in
.I si_fd
is the one that was specified during the
@ -970,7 +970,7 @@ 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.
.IP
By selecting a real time signal (value >=
.BR SIGRTMIN ),
multiple I/O events may be queued using the same signal numbers.
@ -979,7 +979,7 @@ Extra information is available
if
.B SA_SIGINFO
is set for the signal handler, as above.
.IP
Note that Linux imposes a limit on the
number of real-time signals that may be queued to a
process (see
@ -1124,12 +1124,12 @@ command specifying
.I arg
as
.BR F_RDLCK .
.PP
If the lease holder fails to downgrade or remove the lease within
the number of seconds specified in
.IR /proc/sys/fs/lease-break-time ,
then the kernel forcibly removes or downgrades the lease holder's lease.
.PP
Once a lease break has been initiated,
.B F_GETLEASE
returns the target lease type (either
@ -1139,11 +1139,11 @@ or
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.
.PP
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.
.PP
If the lease breaker's blocked
.BR open (2)
or
@ -1164,7 +1164,7 @@ flag when calling
then the call immediately fails with the error
.BR EWOULDBLOCK ,
but the other steps still occur as described above.
.PP
The default signal used to notify the lease holder is
.BR SIGIO ,
but this can be changed using the
@ -1253,7 +1253,7 @@ and similar).
feature test macro must be defined before including
.I any
header files.)
.IP
Directory notifications are normally "one-shot", and the application
must reregister to receive further notifications.
Alternatively, if
@ -1261,7 +1261,7 @@ Alternatively, if
is included in
.IR arg ,
then notification will remain in effect until explicitly removed.
.IP
.\" The following does seem a poor API-design choice...
A series of
.B F_NOTIFY
@ -1273,7 +1273,7 @@ To disable notification of all events, make an
call specifying
.I arg
as 0.
.IP
Notification occurs via delivery of a signal.
The default signal is
.BR SIGIO ,
@ -1296,12 +1296,12 @@ and the
field of this structure contains the file descriptor which
generated the notification (useful when establishing notification
on multiple directories).
.IP
Especially when using
.BR DN_MULTISHOT ,
a real time signal should be used for notification,
so that multiple notifications can be queued.
.IP
.B NOTE:
New applications should use the
.I inotify
@ -1332,7 +1332,7 @@ yield the error
a privileged process
.RB ( CAP_SYS_RESOURCE )
can override the limit.
.IP
When allocating the buffer for the pipe,
the kernel may use a capacity larger than
.IR arg ,
@ -1341,7 +1341,7 @@ if that is convenient for the implementation.
the allocation is the next higher power-of-two page-size multiple
of the requested size.)
The actual capacity (in bytes) that is set is returned as the function result.
.IP
Attempting to set the pipe capacity smaller than the amount
of buffer space currently used to store data produces the error
.BR EBUSY .
@ -1362,7 +1362,7 @@ file and filesystem.
For an overview of file sealing, a discussion of its purpose,
and some code examples, see
.BR memfd_create (2).
.PP
Currently,
file seals can be applied only to a file descriptor returned by
.BR memfd_create (2)
@ -1373,7 +1373,7 @@ On other filesystems, all
.BR fcntl ()
operations that operate on seals will return
.BR EINVAL .
.PP
Seals are a property of an inode.
Thus, all open file descriptors referring to the same inode share
the same set of seals.
@ -1477,7 +1477,7 @@ Furthermore, trying to create new shared, writable memory-mappings via
.BR mmap (2)
will also fail with
.BR EPERM .
.IP
Using the
.B F_ADD_SEALS
operation to set the
@ -1707,7 +1707,7 @@ Only the operations
and
.BR F_SETLKW
are specified in POSIX.1-2001.
.PP
.BR F_GETOWN
and
.B F_SETOWN
@ -1719,7 +1719,7 @@ are specified in POSIX.1-2001.
with the value 500 or greater, or
.BR _POSIX_C_SOURCE
with the value 200809L or greater.)
.PP
.B F_DUPFD_CLOEXEC
is specified in POSIX.1-2008.
(To get this definition, define
@ -1727,7 +1727,7 @@ is specified in POSIX.1-2008.
with the value 200809L or greater, or
.B _XOPEN_SOURCE
with the value 700 or greater.)
.PP
.BR F_GETOWN_EX ,
.BR F_SETOWN_EX ,
.BR F_SETPIPE_SZ ,
@ -1744,7 +1744,7 @@ are Linux-specific.
macro to obtain these definitions.)
.\" .PP
.\" SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions.
.PP
.BR F_OFD_SETLK ,
.BR F_OFD_SETLKW ,
and
@ -1753,7 +1753,7 @@ are Linux-specific (and one must define
.BR _GNU_SOURCE
to obtain their definitions),
but work is being done to have them included in the next version of POSIX.1.
.PP
.BR F_ADD_SEALS
and
.BR F_GET_SEALS
@ -1786,14 +1786,14 @@ However, these details can be ignored by applications using glibc, whose
.BR fcntl ()
wrapper function transparently employs the more recent system call
where it is available.
.\"
.SS Record locks
Since kernel 2.0, there is no interaction between the types of lock
placed by
.BR flock (2)
and
.BR fcntl ().
.PP
Several systems have more fields in
.I "struct flock"
such as, for example,
@ -1805,7 +1805,7 @@ Clearly,
.I l_pid
alone is not going to be very useful if the process holding the lock
may live on a different machine.
.PP
The original Linux
.BR fcntl ()
system call was not designed to handle large file offsets
@ -1854,7 +1854,7 @@ The default value for this file is 90.)
This scenario potentially risks data corruption,
since another process might acquire a lock in the intervening period
and perform file I/O.
.PP
Since Linux 3.12,
.\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d
if an NFSv4 client loses contact with the server,
@ -1975,7 +1975,7 @@ It is therefore inadvisable to rely on mandatory locking.
.BR capabilities (7),
.BR feature_test_macros (7),
.BR lslocks (8)
.PP
.IR locks.txt ,
.IR mandatory-locking.txt ,
and