.\" 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
.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
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)
+.BR open (2).
The principal difference between the two lock types
is that whereas traditional record locks
of the open file description,
instead of being released on any close of the file.
.PP
-Open file description locks always conflict with traditional record locks,
+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
.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.
is not recognized by this kernel.
.TP
.B EINVAL
-For
-.BR F_DUPFD ,
+.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
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.)
.BR F_OFD_SETLKW ,
and
.BR F_OFD_GETLK
-are Linux-specific,
+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.
-.\" FIXME Presumably, glibc will require _GNU_SOURCE
+
+.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)
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)
.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