Tribblix: manual page: fcntl.2

FCNTL(2) System Calls FCNTL(2)

NAME

fcntl - file control

SYNOPSIS

#include <sys/types.h>
#include <unistd.h>
#include <fcntl.h>

int fcntl(int fildes, int cmd, /* arg */ ...);

DESCRIPTION

The fcntl() function provides for control over open files. The fildes
argument is an open file descriptor.

The fcntl() function can take a third argument, arg, whose data type,
value, and use depend upon the value of cmd. The cmd argument
specifies the operation to be performed by fcntl().

The values for cmd are defined in <fcntl.h> and include:

F_DUPFD
Return a new file descriptor which is the lowest
numbered available (that is, not already open) file
descriptor greater than or equal to the third
argument, arg, taken as an integer of type int. The
new file descriptor refers to the same open file
description as the original file descriptor, and
shares any locks. The FD_CLOEXEC or FD_CLOFORK flags
associated with the new file descriptor is cleared to
keep the file open across calls to one of the exec(2)
or fork(2) functions respectively.

F_DUP2FD
Similar to F_DUPFD, but always returns arg. F_DUP2FD
closes arg if it is open and not equal to fildes.
F_DUP2FD is equivalent to dup2(fildes, arg). The
FD_CLOEXEC and FD_CLOFORK flags are cleared on the new
descriptor, regardless of how they were set on the
original descriptor.

F_DUP3FD
Similar to F_DUP2FD; however, an additional argument
is used to set the resulting file descriptor flags,
rather than simply clearing them. The file descriptor
flags may be the bitwise-include-OR of FD_CLOEXEC and
FD_CLOFORK. This fourth argument is taken as type int.
Specifying an invalid flag in the fourth argument will
cause the function to fail and it will return EINVAL.

F_DUPFD_CLOEXEC
Similar to F_DUPFD except that the returned file
descriptor's flags are set explicitly to FD_CLOEXEC,
regardless of what the original file descriptor's
flags were.

F_DUPFD_CLOFORK
Similar to F_DUPFD except that the returned file
descriptor's flags are set explicitly to FD_CLOFORK,
regardless of what the original file descriptor's
flags were.

F_DUP2FD_CLOEXEC
Similar to F_DUP2FD with two exceptions. The
FD_CLOEXEC flag is explicitly set on the returned file
descriptor. If fildes equals arg, the call will fail
setting errno to EINVAL.

F_DUP2FD_CLOFORK
Similar to F_DUP2FD with two exceptions. The
FD_CLOFORK flag is explicitly set on the returned file
descriptor. If fildes equals arg, the call will fail
setting errno to EINVAL.

F_FREESP
Free storage space associated with a section of the
ordinary file fildes. The section is specified by a
variable of data type struct flock pointed to by arg.
The data type struct flock is defined in the <fcntl.h>
header (see fcntl.h(3HEAD)) and is described below.
Note that all file systems might not support all
possible variations of F_FREESP arguments. In
particular, many file systems allow space to be freed
only at the end of a file.

F_FREESP64
Equivalent to F_FREESP, but takes a struct flock64
argument rather than a struct flock argument.

F_ALLOCSP
Allocate space for a section of the ordinary file
fildes. The section is specified by a variable of data
type struct flock pointed to by arg. The data type
struct flock is defined in the <fcntl.h> header (see
fcntl.h(3HEAD) and is described below.

F_ALLOCSP64
Equivalent to F_ALLOCSP, but takes a struct flock64
argument rather than a struct flock argument.

F_GETFD
Get the file descriptor flags defined in <fcntl.h>
that are associated with the file descriptor fildes.
File descriptor flags are associated with a single
file descriptor and do not affect other file
descriptors that refer to the same file.

F_GETFL
Get the file status flags and file access modes,
defined in <fcntl.h>, for the file descriptor
specified by fildes. The file access modes can be
extracted from the return value using the mask
O_ACCMODE, which is defined in <fcntl.h>. File status
flags and file access modes do not affect other file
descriptors that refer to the same file with different
open file descriptions.

F_GETOWN
If fildes refers to a socket, get the process or
process group ID specified to receive SIGURG signals
when out-of-band data is available. Positive values
indicate a process ID; negative values, other than -1,
indicate a process group ID. If fildes does not refer
to a socket, the results are unspecified.

F_GETXFL
Get the file status flags, file access modes, and file
creation and assignment flags, defined in <fcntl.h>,
for the file descriptor specified by fildes. The file
access modes can be extracted from the return value
using the mask O_ACCMODE, which is defined in
<fcntl.h>. File status flags, file access modes, and
file creation and assignment flags do not affect other
file descriptors that refer to the same file with
different open file descriptions.

F_SETFD
Set the file descriptor flags defined in <fcntl.h>,
that are associated with fildes, to the third
argument, arg, taken as type int. There are two flags
that control the behavior of the file descriptor on
subsequent process activity. The FD_CLOEXEC flag, if
set, will cause the file descriptor to be closed upon
successful execution of one of the exec(2) functions.
The FD_CLOFORK flag, if set, will cause the file
descriptor to be closed upon successful execution of
one of the fork(2) functions.

F_SETFL
Set the file status flags, defined in <fcntl.h>, for
the file descriptor specified by fildes from the
corresponding bits in the arg argument, taken as type
int. Bits corresponding to the file access mode and
file creation and assignment flags that are set in arg
are ignored. If any bits in arg other than those
mentioned here are changed by the application, the
result is unspecified.

F_SETOWN
If fildes refers to a socket, set the process or
process group ID specified to receive SIGURG signals
when out-of-band data is available, using the value of
the third argument, arg, taken as type int. Positive
values indicate a process ID; negative values, other
than -1, indicate a process group ID. If fildes does
not refer to a socket, the results are unspecified.

The following commands are available for POSIX advisory or mandatory
record locking. POSIX record locking is supported for regular files,
and may be supported for other files. See the FILE LOCKING section of
this manual page for information about the types of file locks
available and their interaction.

F_GETLK
Get the first lock which blocks the POSIX lock
description pointed to by the third argument, arg,
taken as a pointer to type struct flock, defined in
<fcntl.h>. The information retrieved overwrites the
information passed to fcntl() in the structure flock.
If no lock is found that would prevent this lock from
being created, then the structure will be left
unchanged except for the lock type which will be set to
F_UNLCK. If multiple locks exist that would prevent
this lock from being created, which one is returned is
unspecified. If the blocking lock is an OFD-style lock,
-1 will be returned for the lock's pid value.

F_GETLK64
Equivalent to F_GETLK, but takes a struct flock64
argument rather than a struct flock argument. See
lf64(7).

F_SETLK
Set or clear a POSIX record lock according to the lock
description pointed to by the third argument, arg,
taken as a pointer to type struct flock, defined in
<fcntl.h>. F_SETLK is used to establish shared (or
read) locks (F_RDLCK) or exclusive (or write) locks
(F_WRLCK), as well as to remove either type of lock
(F_UNLCK). F_RDLCK, F_WRLCK and F_UNLCK are defined in
<fcntl.h>. If a shared or exclusive lock cannot be set,
fcntl() will return immediately with a return value of
-1.

F_SETLK64
Equivalent to F_SETLK, but takes a struct flock64
argument rather than a struct flock argument. See
lf64(7).

F_SETLKW
This command is the same as F_SETLK except that if a
shared or exclusive lock is blocked by other locks, the
process will wait until the request can be satisfied.
If a signal that is to be caught is received while
fcntl() is waiting for a region, fcntl() will be
interrupted. Upon return from the process' signal
handler, fcntl() will return -1 with errno set to
EINTR, and the lock operation will not be done.

F_SETLKW64
Equivalent to F_SETLKW, but takes a struct flock64
argument rather than a struct flock argument. See
lf64(7).

The following commands are available for OFD (open file description)
advisory record locking. OFD record locking is supported for regular
files, and may be supported for other files. See the FILE LOCKING
section of this manual page for information about the types of file
locks available and their interaction. OFD-style record locks are
currently limited to spanning the entire file and these locks are
currently not supported over remote file systems (e.g. nfs(5)) which
use the Network Lock Manager.

F_OFD_GETLK
Get the first lock which blocks the OFD lock
description pointed to by the third argument, arg,
taken as a pointer to type struct flock, defined in
<fcntl.h>. The information retrieved overwrites the
information passed to fcntl() in the structure flock.
If no lock is found that would prevent this lock from
being created, then the structure will be left
unchanged except for the lock type which will be set to
F_UNLCK. If multiple locks exist that would prevent
this lock from being created, which one is returned is
unspecified. If the blocking lock is an OFD-style lock,
-1 will be returned for the lock's pid value.

F_OFD_GETLK64
Equivalent to F_OFD_GETLK, but takes a struct flock64
argument rather than a struct flock argument. See
lf64(7). This command exists solely to allow the use of
OFD locks with the transitional 64-bit file interfaces.

F_OFD_SETLK
Set or clear a OFD record lock according to the lock
description pointed to by the third argument, arg,
taken as a pointer to type struct flock, defined in
<fcntl.h>. F_OFD_SETLK is used to establish shared (or
read) locks (F_RDLCK) or exclusive (or write) locks
(F_WRLCK), as well as to remove either type of lock
(F_UNLCK). F_RDLCK, F_WRLCK and F_UNLCK are defined in
<fcntl.h>. If a shared or exclusive lock cannot be
set, fcntl() will return immediately with a return
value of -1.

F_OFD_SETLK64
Equivalent to F_OFD_SETLK, but takes a struct flock64
argument rather than a struct flock argument. See
lf64(7). This command exists solely to allow the use of
OFD locks with the transitional 64-bit file interfaces.

F_OFD_SETLKW
This command is the same as F_OFD_SETLK except that if
a shared or exclusive lock is blocked by other locks,
the process will wait until the request can be
satisfied. If a signal that is to be caught is received
while fcntl() is waiting for a region, fcntl() will be
interrupted. Upon return from the process' signal
handler, fcntl() will return -1 with errno set to
EINTR, and the lock operation will not be done.

F_OFD_SETLKW64
Equivalent to F_OFD_SETLKW, but takes a struct flock64
argument rather than a struct flock argument. See
lf64(7). This command exists solely to allow the use
of OFD locks with the transitional 64-bit file
interfaces.

The following values for cmd are used for file share reservations. A
share reservation is placed on an entire file to allow cooperating
processes to control access to the file. See the SHARE RESERVATIONS
section of this manual page below for additional information.

F_SHARE
Sets a share reservation on a file with the specified
access mode and designates which types of access to
deny.

F_UNSHARE
Remove an existing share reservation.

FILE LOCKING

Two types of file locks are supported: POSIX-style and OFD-style.
OFD-style locks are associated with the open file description (not
descriptor) instead of with a process. Either type is advisory by
default, but POSIX-style locks can be mandatory if, and only if,
mandatory locking has been enabled on the file being locked. Each
type of lock may be created through two different interfaces. POSIX-
style locks are created via the F_SETLK, F_SETLK64, F_SETLKW, or
F_SETLKW64 commands to this system call or by use of the lockf(3C)
routine. There is no difference between locks created via one
mechanism or the other. Likewise, OFD-style locks are created via the
F_OFD_SETLK, F_OFD_SETLK64, F_OFD_SETLKW, or F_OFD_SETLKW64 commands
to this system call or by use of the Linux/BSD-compatible flock(3C)
routine. Note that this system call supports the creation of range-
specified OFD-style file locks, while flock(3C) does not. However,
the current implementation of OFD-style locking is limited to locking
the entire file. This limitation might be removed in the future.

The essential distinction between POSIX-style locks and OFD-style
locks lie in how ownership of a lock is scoped. POSIX locks are
scoped to a process. All POSIX locks associated with a file for a
given process are removed when any file descriptor for that file is
closed by that process or the process holding that file descriptor
terminates. POSIX-style locks are not inherited by a child process
created using fork(2). An OFD-style lock is scoped to the file
description for a file, not the process or open file descriptor. Thus
all file descriptors referring to the same description (i.e. those
created via the F_DUPFD, F_DUP2FD, F_DUP3FD, F_DUPFD_CLOEXEC,
F_DUP2FD_CLOEXEC, F_DUPFD_CLOFORK, or F_DUP2FD_CLOFORK commands to
the fcntl(2) system call, or those created via the dup(2) system
call, or those inherited by a child process created via fork(2))
reference the same lock, but a file descriptor obtained via a
separate open(2) call on the same file will reference a different
lock. A lock is removed only on the last close(2) of the
description, or when the lock is explicitly unlocked.

Locks of both styles are compatible. A file that has been locked with
one style of lock will be regarded as locked when creation of a lock
of either style is attempted, and information about the lock will be
provided via any of the F_GETLK, F_GETLK64, F_OFD_GETLK, or
F_OFD_GETLK64 commands to this system call if that lock would
conflict with an attempt to create the specified lock regardless of
whether the specified lock is of the same style as the conflicting
extant lock. Because ownership of OFD-style locks is scoped to the
open description rather than the calling process, the l_pid field of
a lock descriptor for any such lock will always be set to -1.

When a shared lock is set on a segment of a file, other callers
(regardless of whether in the same or different process and of
whether referenced via the same open file) will be able to set shared
locks on that segment or a portion of it. A POSIX-style shared lock
prevents any other process from setting an exclusive lock on any
portion of the protected area. A OFD-style shared lock prevents any
caller (even callers in the same process) from setting an exclusive
lock on any portion of the protected area, unless the caller makes
the request against a file descriptor referencing the same open file
against which the shared lock was created, in which case the lock
will be downgraded to a shared lock with respect to the specified
region. A request for a shared lock of either style will fail if the
file descriptor was not opened with read access.

A POSIX-style exclusive lock will prevent any other process from
setting a shared lock or an exclusive lock (of either style) on any
portion of the protected area. A request for an exclusive lock will
fail if the file descriptor was not opened with write access.

The flock structure contains at least the following elements:

short l_type; /* lock operation type */
short l_whence; /* lock base indicator */
off_t l_start; /* starting offset from base */
off_t l_len; /* lock length; l_len == 0 means
until end of file */
int l_sysid; /* system ID running process holding lock */
pid_t l_pid; /* process ID of process holding lock */

The value of l_whence is SEEK_SET, SEEK_CUR, or SEEK_END, to indicate
that the relative offset l_start bytes will be measured from the
start of the file, current position or end of the file, respectively.
The value of l_len is the number of consecutive bytes to be locked.
The value of l_len may be negative (where the definition of off_t
permits negative values of l_len). After a successful F_GETLK,
F_GETLK64, F_OFD_GETLK, or F_OFD_GETLK64 request, that is, one in
which a lock was found, the value of l_whence will be SEEK_SET.

The l_pid and l_sysid fields are used only with F_GETLK or F_GETLK64
to return the process ID of the process holding a POSIX-style
blocking lock and to indicate which system is running that process,
or -1 if it is an OFD-style lock. These fields must both be
initialized to 0 prior to issuing a OFD-style locking command
(F_OFD_GETLK or F_OFD_GETLK64).

If l_len is positive, the area affected starts at l_start and ends at
l_start + l_len - 1. If l_len is negative, the area affected starts
at l_start + l_len and ends at l_start - 1. Locks may start and
extend beyond the current end of a file, but must not be negative
relative to the beginning of the file. A lock will be set to extend
to the largest possible value of the file offset for that file by
setting l_len to 0. If such a lock also has l_start set to 0 and
l_whence is set to SEEK_SET, the whole file will be locked.

If a lock exists for which l_len is 0 and which includes the last
byte of the requested segment, and an unlock (F_UNLCK) request is
made in which l_len is non-zero and the offset of the last byte of
the requested segment is the maximum value for an object of type
off_t, then the F_UNLCK request will be treated as a request to
unlock from the start of the requested segment with an l_len equal to
0. Otherwise, the request will attempt to unlock only the requested
segment.

There will be at most one type of lock set for each byte in the file.
Before a successful return from an F_SETLK, F_SETLK64, F_SETLKW, or
F_SETLKW64 request when the calling process has previously existing
POSIX-style locks on bytes in the region specified by the request,
the previous POSIX-style lock type for each byte in the specified
region will be replaced by the new lock type. As specified above
under the descriptions of shared locks and exclusive locks, an
F_SETLK, F_SETLK64, F_SETLKW, or F_SETLKW64 request will
(respectively) fail or block when locks exist on bytes in the
specified region and the type of any of those locks conflicts with
the type specified in the request.

Similarly, before a successful return from an F_OFD_SETLK,
F_OFD_SETLK64, F_OFD_SETLKW, or F_OFD_SETLKW64 request when
previously-created OFD-style locks associated with the open file
apply to bytes in the region specified by the request, the previous
OFD-style lock type for each byte in the specified region will be
replaced by the new lock type. As specified above under the
descriptions of shared locks and exclusive locks, an F_OFD_SETLK,
F_OFD_SETLK64, F_OFD_SETLKW, or F_OFD_SETLKW64 request will
(respectively) fail or block when locks exist on bytes in the
specified region and the type of any of those locks conflicts with
the type specified in the request.

A potential for deadlock occurs if a process controlling a locked
region is put to sleep by attempting to lock another process' locked
region. If the system detects that sleeping until a locked region is
unlocked would cause a deadlock, fcntl() will fail with an EDEADLK
error. This deadlock detection and error value apply only to POSIX-
style locks. No deadlock detection is performed when attempting to
set an OFD-style lock.

SHARE RESERVATIONS

File share reservations are an advisory form of access control among
cooperating processes, on both local and remote machines. They are
most often used by DOS or Windows emulators and DOS based NFS
clients. However, native UNIX versions of DOS or Windows
applications may also choose to use this form of access control.

A share reservation is described by an fshare structure defined in
<sys/fcntl.h>, which is included in <fcntl.h> as follows:

typedef struct fshare {
short f_access;
short f_deny;
int f_id;
} fshare_t;

A share reservation specifies the type of access, f_access, to be
requested on the open file descriptor. If access is granted, it
further specifies what type of access to deny other processes,
f_deny. A single process on the same file may hold multiple non-
conflicting reservations by specifying an identifier, f_id, unique
to the process, with each request.

An F_UNSHARE request releases the reservation with the specified
f_id. The f_access and f_deny fields are ignored.

Valid f_access values are:

F_RDACC
Set a file share reservation for read-only access.

F_WRACC
Set a file share reservation for write-only access.

F_RWACC
Set a file share reservation for read and write access.

Valid f_deny values are:

F_COMPAT
Set a file share reservation to compatibility mode.

F_RDDNY
Set a file share reservation to deny read access to other
processes.

F_WRDNY
Set a file share reservation to deny write access to
other processes.

F_RWDNY
Set a file share reservation to deny read and write
access to other processes.

F_NODNY
Do not deny read or write access to any other process.

RETURN VALUES

Upon successful completion, the value returned depends on cmd as
follows:

F_DUPFD, F_DUP2FD, F_DUP3FD
A new file descriptor.

F_DUPFD_CLOEXEC, F_DUPFD_CLOFORK
A new file descriptor.

F_DUP2FD_CLOEXEC, F_DUP2FD_CLOFORK
A new file descriptor.

F_FREESP
Value of 0.

F_GETFD
Value of flags defined in <fcntl.h>. The return value
will not be negative.

F_GETFL
Value of file status flags and access modes. The return
value will not be negative.

F_GETLK
Value other than -1.

F_GETLK64
Value other than -1.

F_GETOWN
Value of the socket owner process or process group;
this will not be -1.

F_GETXFL
Value of file status flags, access modes, and creation
and assignment flags. The return value will not be
negative.

F_OFD_GETLK
Value other then -1.

F_OFD_GETLK64
Value other then -1.

F_OFD_SETLK
Value other then -1.

F_OFD_SETLK64
Value other then -1.

F_OFD_SETLKW
Value other then -1.

F_OFD_SETLKW64
Value other then -1.

F_SETFD
Value other than -1.

F_SETFL
Value other than -1.

F_SETLK
Value other than -1.

F_SETLK64
Value other than -1.

F_SETLKW
Value other than -1.

F_SETLKW64
Value other than -1.

F_SETOWN
Value other than -1.

F_SHARE
Value other than -1.

F_UNSHARE
Value other than -1.

Otherwise, -1 is returned and errno is set to indicate the error.

ERRORS

The fcntl() function will fail if:

EAGAIN
The cmd argument is F_SETLK, F_SETLK64, F_OFD_SETLK, or
F_OFD_SETLK64, the type of lock (l_type) is a shared
(F_RDLCK) or exclusive (F_WRLCK) lock, and the segment
of a file to be locked is already exclusive-locked by
another process or open file; or the type is an
exclusive lock and some portion of the segment of a file
to be locked is already shared-locked or exclusive-
locked by another process or open file.

The cmd argument is F_FREESP, the file exists, mandatory
file/record locking is set, and there are outstanding
record locks on the file; or the cmd argument is
F_SETLK, F_SETLK64, F_SETLKW, or F_SETLKW64, mandatory
file/record locking is set, and the file is currently
being mapped to virtual memory using mmap(2).

The cmd argument is F_SHARE and f_access conflicts with
an existing f_deny share reservation.

EBADF
The fildes argument is not a valid open file descriptor;
or the cmd argument is F_SETLK, F_SETLK64, F_SETLKW,
F_SETLKW64, F_OFD_SETLK, F_OFD_SETLK64, F_OFD_SETLKW, or
F_OFD_SETLKW64, the type of lock, l_type, is a shared
lock (F_RDLCK), and fildes is not a valid file
descriptor open for reading; or the type of lock l_type
is an exclusive lock (F_WRLCK) and fildes is not a valid
file descriptor open for writing.

The cmd argument is F_FREESP and fildes is not a valid
file descriptor open for writing.

The cmd argument is F_DUP2FD, F_DUP2FD_CLOEXEC,
F_DUP2FD_CLOFORK, or F_DUP3FD and arg is negative or is
not less than the current resource limit for
RLIMIT_NOFILE.

The cmd argument is F_SHARE, the f_access share
reservation is for write access, and fildes is not a
valid file descriptor open for writing.

The cmd argument is F_SHARE, the f_access share
reservation is for read access, and fildes is not a
valid file descriptor open for reading.

EFAULT
The cmd argument is F_GETLK, F_GETLK64, F_SETLK,
F_SETLK64, F_SETLKW, F_SETLKW64, F_OFD_GETLK,
F_OFD_GETLK64, F_OFD_SETLK, F_OFD_SETLK64, F_OFD_SETLKW,
F_OFD_SETLKW64, F_SHARE, F_UNSHARE, or F_FREESP and the
arg argument points to an illegal address.

EINTR
The cmd argument is F_SETLKW, F_SETLKW64, F_OFD_SETLKW,
or F_OFD_SETLKW64, and the function was interrupted by a
signal.

EINVAL
The cmd argument is invalid or not supported by the file
system; or the cmd argument is F_DUPFD and arg is
negative or greater than or equal to OPEN_MAX; or the
cmd argument is F_GETLK, F_GETLK64, F_SETLK, F_SETLK64,
F_SETLKW, F_SETLKW64, F_OFD_GETLK, F_OFD_GETLK64,
F_OFD_SETLK, F_OFD_SETLK64, F_OFD_SETLKW, or
F_OFD_SETLKW64, and the data pointed to by arg is not
valid; or fildes refers to a file that does not support
locking.

The cmd argument is F_UNSHARE and a reservation with
this f_id for this process does not exist.

The cmd argument is F_DUP2FD_CLOEXEC or F_DUP2FD_CLOFORK
and fildes is equal to arg.

The cmd argument is F_DUP3FD and the fourth flags
argument contains unknown values.

EIO
An I/O error occurred while reading from or writing to
the file system.

EMFILE
The cmd argument is F_DUPFD and either OPEN_MAX file
descriptors are currently open in the calling process,
or no file descriptors greater than or equal to arg are
available.

ENOLCK
The cmd argument is F_SETLK, F_SETLK64, F_SETLKW,
F_SETLKW64, F_OFD_SETLK, F_OFD_SETLK64, F_OFD_SETLKW, or
F_OFD_SETLKW64, and satisfying the lock or unlock
request would result in the number of locked regions in
the system exceeding a system-imposed limit.

ENOLINK
Either the fildes argument is on a remote machine and
the link to that machine is no longer active; or the cmd
argument is F_FREESP, the file is on a remote machine,
and the link to that machine is no longer active.

EOVERFLOW
One of the values to be returned cannot be represented
correctly.

The cmd argument is F_GETLK, F_SETLK, F_SETLKW,
F_OFD_GETLK, F_OFD_SETLK, or F_OFD_SETLKW, and the
smallest or, if l_len is non-zero, the largest, offset
of any byte in the requested segment cannot be
represented correctly in an object of type off_t.

The cmd argument is F_GETLK64, F_SETLK64, F_SETLKW64,
F_OFD_GETLK64, F_OFD_SETLK64, or F_OFD_SETLKW64, and the
smallest or, if l_len is non-zero, the largest, offset
of any byte in the requested segment cannot be
represented correctly in an object of type off64_t.

The fcntl() function may fail if:

EAGAIN
The cmd argument is F_SETLK, F_SETLK64, F_SETLKW,
F_SETLKW64, F_OFD_SETLK, F_OFD_SETLK64, F_OFD_SETLKW, or
F_OFD_SETLKW64 and the file is currently being mapped to
virtual memory using mmap(2).

EDEADLK
The cmd argument is F_SETLKW or F_SETLKW64, the lock is
blocked by some lock from another process and putting the
calling process to sleep, waiting for that lock to become
free would cause a deadlock.

The cmd argument is F_FREESP, mandatory record locking is
enabled, O_NDELAY and O_NONBLOCK are clear and a deadlock
condition was detected.

EOPNOTSUPP
The cmd argument is F_OFD_GETLK, F_OFD_GETLK64,
F_OFD_SETLK, F_OFD_SETLK64, F_OFD_SETLKW, or
F_OFD_SETLKW64 and the locking of files of the type
indicated by the fildes argument is not supported.

ATTRIBUTES

NOTES

In the past, the variable errno was set to EACCES rather than EAGAIN
when a section of a file is already locked by another process.
Therefore, portable application programs should expect and test for
either value.

Advisory locks allow cooperating processes to perform consistent
operations on files, but do not guarantee exclusive access. Files can
be accessed without advisory locks, but inconsistencies may result.
The network share locking protocol does not support the f_deny value
of F_COMPAT. For network file systems, if f_access is F_RDACC, f_deny
is mapped to F_RDDNY. Otherwise, it is mapped to F_RWDNY.

To prevent possible file corruption, the system may reject mmap()
requests for advisory locked files, or it may reject advisory locking
requests for mapped files. Applications that require a file be both
locked and mapped should lock the entire file (l_start and l_len both
set to 0). If a file is mapped, the system may reject an unlock
request, resulting in a lock that does not cover the entire file.

The process ID returned for locked files on network file systems
might not be meaningful.

If the file server crashes and has to be rebooted, the lock manager
(see lockd(8)) attempts to recover all locks that were associated
with that server. If a lock cannot be reclaimed, the process that
held the lock is issued a SIGLOST signal.

June 21, 2024 FCNTL(2)