'\" 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.
+.\" 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
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" 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
.\"
-.TH FCNTL 2 2014-05-21 "Linux" "Linux Programmer's Manual"
+.TH FCNTL 2 2016-03-15 "Linux" "Linux Programmer's Manual"
.SH NAME
fcntl \- manipulate file descriptor
.SH SYNOPSIS
or
.I void
is specified if the argument is not required.
+
+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)"
.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
.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.
+
.BR F_SETLK ,
.BR F_SETLKW ,
and
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) */
+ (set by F_GETLK and F_OFD_GETLK) */
...
};
.fi
.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
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
+returns details about one of those locks in the
.IR l_type ", " l_whence ", " l_start ", and " l_len
fields of
-.I lock
-and sets
+.IR lock .
+If the conflicting lock is a traditional (process-associated) record lock,
+then the
.I l_pid
-to be the PID of the process holding that lock.
-Note that the information returned by
-.BR F_GETLK
+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.
.P
In order to place a read lock,
.I fd
must be open for writing.
To place both types of lock, open a file read-write.
-.P
+
+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.
+
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.
+record locks are automatically released when the process terminates.
.P
Record locks are not inherited by a child created via
.BR fork (2),
and
.BR write (2)
instead.
+
+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).
+
+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.
+
+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 (2)
+.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.)
+
+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.
+
+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
-(Non-POSIX.)
-The above record locks may be either advisory or mandatory,
-and are advisory by default.
+.IR Warning :
+the Linux implementation of mandatory locking is unreliable.
+See BUGS below.
+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.
+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)
If the
.B O_NONBLOCK
flag is not enabled, then
-system call is blocked until the lock is removed
+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
and
.BR chmod (2)).
-The Linux implementation of mandatory locking is unreliable.
-See BUGS below.
+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.
.SS Managing signals
.BR F_GETOWN ,
.BR F_SETOWN ,
.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)"
.PD 0
.TP 12
.B DN_ACCESS
-A file was accessed (read, pread, readv)
+A file was accessed
+.RB ( read (2),
+.BR pread (2),
+.BR readv (2),
+and similar)
.TP
.B DN_MODIFY
-A file was modified (write, pwrite, writev, truncate, ftruncate).
+A file was modified
+.RB ( write (2),
+.BR pwrite (2),
+.BR writev (2),
+.BR truncate (2),
+.BR ftruncate (2),
+and similar).
.TP
.B DN_CREATE
-A file was created (open, creat, mknod, mkdir, link, symlink, rename).
+A file was created
+.RB ( open (2),
+.BR creat (2),
+.BR mknod (2),
+.BR mkdir (2),
+.BR link (2),
+.BR symlink (2),
+.BR rename (2)
+into this directory).
.TP
.B DN_DELETE
-A file was unlinked (unlink, rename to another directory, rmdir).
+A file was unlinked
+.RB ( unlink (2),
+.BR rename (2)
+to another directory,
+.BR rmdir (2)).
.TP
.B DN_RENAME
-A file was renamed within this directory (rename).
+A file was renamed within this directory
+.RB ( rename (2)).
.TP
.B DN_ATTRIB
-The attributes of a file were changed (chown, chmod, utime[s]).
+The attributes of a file were changed
+.RB ( chown (2),
+.BR chmod (2),
+.BR utime (2),
+.BR utimensat (2),
+and similar).
.PD
.RE
.IP
.B F_SETSIG
command to
.BR fcntl ().
+(Note that
+.B SIGIO
+is one of the nonqueuing standard signals;
+switching to the use of a real-time signal means that
+multiple notifications can be queued to the process.)
In the latter case, the signal handler receives a
.I siginfo_t
structure as its second argument (if the handler was
the kernel may use a capacity larger than
.IR arg ,
if that is convenient for the implementation.
-The
-.B F_GETPIPE_SZ
-operation returns the actual size used.
+The actual capacity that is set is returned as the function result.
Attempting to set the pipe capacity smaller than the amount
of buffer space currently used to store data produces the error
.BR EBUSY .
.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 .
+.\"
+.SS File Sealing
+File seals limit the set of allowed operations on a given file.
+For each seal that is set on a file,
+a specific set of operations will fail with
+.B EPERM
+on this file from now on.
+The file is said to be sealed.
+The default set of seals depends on the type of the underlying
+file and filesystem.
+For an overview of file sealing, a discussion of its purpose,
+and some code examples, see
+.BR memfd_create (2).
+
+Currently, only the
+.I tmpfs
+filesystem supports sealing.
+On other filesystems, all
+.BR fcntl (2)
+operations that operate on seals will return
+.BR EINVAL .
+
+Seals are a property of an inode.
+Thus, all open file descriptors referring to the same inode share
+the same set of seals.
+Furthermore, seals can never be removed, only added.
+.TP
+.BR F_ADD_SEALS " (\fIint\fP; since Linux 3.17)"
+Add the seals given in the bit-mask argument
+.I arg
+to the set of seals of the inode referred to by the file descriptor
+.IR fd .
+Seals cannot be removed again.
+Once this call succeeds, the seals are enforced by the kernel immediately.
+If the current set of seals includes
+.BR F_SEAL_SEAL
+(see below), then this call will be rejected with
+.BR EPERM .
+Adding a seal that is already set is a no-op, in case
+.B F_SEAL_SEAL
+is not set already.
+In order to place a seal, the file descriptor
+.I fd
+must be writable.
+.TP
+.BR F_GET_SEALS " (\fIvoid\fP; since Linux 3.17)"
+Return (as the function result) the current set of seals
+of the inode referred to by
+.IR fd .
+If no seals are set, 0 is returned.
+If the file does not support sealing, \-1 is returned and
+.I errno
+is set to
+.BR EINVAL .
+.PP
+The following seals are available:
+.TP
+.BR F_SEAL_SEAL
+If this seal is set, any further call to
+.BR fcntl (2)
+with
+.B F_ADD_SEALS
+will fail with
+.BR EPERM .
+Therefore, this seal prevents any modifications to the set of seals itself.
+If the initial set of seals of a file includes
+.BR F_SEAL_SEAL ,
+then this effectively causes the set of seals to be constant and locked.
+.TP
+.BR F_SEAL_SHRINK
+If this seal is set, the file in question cannot be reduced in size.
+This affects
+.BR open (2)
+with the
+.B O_TRUNC
+flag as well as
+.BR truncate (2)
+and
+.BR ftruncate (2).
+Those calls will fail with
+.B EPERM
+if you try to shrink the file in question.
+Increasing the file size is still possible.
+.TP
+.BR F_SEAL_GROW
+If this seal is set, the size of the file in question cannot be increased.
+This affects
+.BR write (2)
+beyond the end of the file,
+.BR truncate (2),
+.BR ftruncate (2),
+and
+.BR fallocate (2).
+These calls will fail with
+.B EPERM
+if you use them to increase the file size.
+If you keep the size or shrink it, those calls still work as expected.
+.TP
+.BR F_SEAL_WRITE
+If this seal is set, you cannot modify the contents of the file.
+Note that shrinking or growing the size of the file is
+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 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
+.\" the effect of replacing the last hundred bytes by zeros.
+.\"
+Thus, this seal is normally used in combination with one of the other seals.
+This seal affects
+.BR write (2)
+and
+.BR fallocate (2)
+(only in combination with the
+.B FALLOC_FL_PUNCH_HOLE
+flag).
+Those calls will fail with
+.B EPERM
+if this seal is set.
+Furthermore, trying to create new shared, writable memory-mappings via
+.BR mmap (2)
+will also fail with
+.BR EPERM .
+
+Setting
+.B F_SEAL_WRITE
+via
+.BR fcntl (2)
+with
+.B F_ADD_SEALS
+will fail with
+.B EBUSY
+if any writable, shared mapping exists.
+Such mappings must be unmapped before you can add this seal.
+Furthermore, if there are any asynchronous I/O operations
+.RB ( io_submit (2))
+pending on the file,
+all outstanding writes will be discarded.
.SH RETURN VALUE
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
.B SIGIO
behavior.
.TP
-.B F_GETPIPE_SZ
+.BR F_GETPIPE_SZ ", " F_SETPIPE_SZ
The pipe capacity.
.TP
+.BR F_GET_SEALS
+A bit mask identifying the seals that have been set
+for the inode referred to by
+.IR fd .
+.TP
All other commands
Zero.
.PP
.TP
.B EBADF
.I fd
-is not an open file descriptor, or the command was
+is not an open file descriptor
+.TP
+.B EBADF
+.I cmd
+is
.B F_SETLK
or
.B F_SETLKW
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
+.BR F_ADD_SEALS ,
+.IR arg
+includes
+.BR F_SEAL_WRITE ,
+and there exists a writable, shared mapping on the file referred to by
+.IR fd .
+.TP
.B EDEADLK
It was detected that the specified
.B F_SETLKW
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.
.TP
.B EINVAL
-For
-.BR F_DUPFD ,
+The value specified in
+.I cmd
+is not recognized by this kernel.
+.TP
+.B EINVAL
+.I cmd
+is
+.BR F_ADD_SEALS
+and
.I arg
-is negative or is greater than the maximum allowable value.
-For
-.BR F_SETSIG ,
+includes an unrecognized sealing bit.
+.TP
+.BR EINVAL
+.I cmd
+is
+.BR F_ADD_SEALS
+or
+.BR F_GET_SEALS
+and the filesystem containing the inode referred to by
+.I fd
+does not support sealing.
+.TP
+.B EINVAL
+.I cmd
+is
+.BR F_DUPFD
+and
+.I arg
+is negative or is greater than the maximum allowable value
+(see the discussion of
+.BR RLIMIT_NOFILE
+in
+.BR getrlimit (2)).
+.TP
+.B EINVAL
+.I cmd
+is
+.BR F_SETSIG
+and
.I arg
is not an allowable signal number.
.TP
+.B EINVAL
+.I cmd
+is
+.BR F_OFD_SETLK ,
+.BR F_OFD_SETLKW ,
+or
+.BR F_OFD_GETLK ,
+and
+.I l_pid
+was not specified as zero.
+.TP
.B EMFILE
-For
-.BR F_DUPFD ,
-the process already has the maximum number of file descriptors open.
+.I cmd
+is
+.BR F_DUPFD
+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
protocol failed (e.g., locking over NFS).
.TP
+.B ENOTDIR
+.B F_NOTIFY
+was specified in
+.IR cmd ,
+but
+.IR fd
+does not refer to a directory.
+.TP
.B EPERM
Attempted to clear the
.B O_APPEND
flag on a file that has the append-only attribute set.
+.TP
+.B EPERM
+.I cmd
+was
+.BR F_ADD_SEALS ,
+but
+.I fd
+was not open for writing
+or the current set of seals on the file already includes
+.BR F_SEAL_SEAL .
.SH CONFORMING TO
SVr4, 4.3BSD, POSIX.1-2001.
Only the operations
and
.B F_SETOWN
are specified in POSIX.1-2001.
-(To get their definitions, define
-.BR _BSD_SOURCE ,
-or
+(To get their definitions, define either
+.\" .BR _BSD_SOURCE ,
+.\" or
.BR _XOPEN_SOURCE
-with the value 500 or greater, or define
+with the value 500 or greater, or
.BR _POSIX_C_SOURCE
with the value 200809L or greater.)
macro to obtain these definitions.)
.\" .PP
.\" SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions.
+
+.BR F_OFD_SETLK ,
+.BR F_OFD_SETLKW ,
+and
+.BR F_OFD_GETLK
+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.
+
+.BR F_ADD_SEALS
+and
+.BR F_GET_SEALS
+are Linux-specific.
+.\" FIXME . Once glibc adds support, add a note about FTM requirements
.SH NOTES
The errors returned by
.BR dup2 (2)
.I l_pid
alone is not going to be very useful if the process holding the lock
may live on a different machine.
+
+The original Linux
+.BR fcntl ()
+system call was not designed to handle large file offsets
+(in the
+.I flock
+structure).
+Consequently, an
+.BR fcntl64 ()
+system call was added in Linux 2.4.
+The newer system call employs a different structure for file locking,
+.IR flock64 ,
+and corresponding commands,
+.BR F_GETLK64 ,
+.BR F_SETLK64 ,
+and
+.BR F_SETLKW64 .
+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 locking and NFS
Before Linux 3.12, if an NFSv4 client
loses contact with the server for a period of time
which expresses the period in seconds.
The default value for this file is 90.)
.\"
-.\" Jeff Layton:
+.\" Jeff Layton:
.\" Note that this is not a firm timeout. The server runs a job
.\" periodically to clean out expired stateful objects, and it's likely
.\" that there is some time (maybe even up to another whole lease period)
This scenario potentially risks data corruption,
since another process might acquire a lock in the intervening period
and perform file I/O.
+
Since Linux 3.12,
.\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d
-if the client loses contact with the server,
+if an NFSv4 client loses contact with the server,
any I/O to the file by a process which "thinks" it holds
a lock will fail until that process closes and reopens the file.
A kernel parameter,
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 Deadlock detection
+The deadlock-detection algorithm employed by the kernel when dealing with
+.BR F_SETLKW
+requests can yield both
+false negatives (failures to detect deadlocks,
+leaving a set of deadlocked processes blocked indefinitely)
+and false positives
+.RB ( EDEADLK
+errors when there is no deadlock).
+For example,
+the kernel limits the lock depth of its dependency search to 10 steps,
+meaning that circular deadlock chains that exceed
+that size will not be detected.
+In addition, the kernel may falsely indicate a deadlock
+when two or more processes created using the
+.BR clone (2)
+.B CLONE_FILES
+flag place locks that appear (to the kernel) to conflict.
+.\"
.SS Mandatory locking
The Linux implementation of mandatory locking
is subject to race conditions which render it unreliable:
.\" Newsgroups: gmane.linux.file-systems
.\" Date: 2014-04-28 10:07:57 GMT
.\" http://thread.gmane.org/gmane.linux.file-systems/84481/focus=84518
+a
.BR write (2)
call that overlaps with a lock may modify data after the mandatory lock is
acquired;
.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