usr/src/man/man2/fcntl.2

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
.\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright (c) 2013, OmniTI Computer Consulting, Inc. All rights reserved.
.\" Copyright 2015 Joyent, Inc.
.\" Copyright 2022 Oxide Computer Company
.\"
.TH FCNTL 2 "Feb 16, 2015"
.SH NAME
fcntl \- file control
.SH SYNOPSIS
.nf
#include <sys/types.h>
#include <unistd.h>
#include <fcntl.h>

\fBint\fR \fBfcntl\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIcmd\fR, \fB/*\fR \fIarg\fR */ ...);
.fi

.SH DESCRIPTION
The \fBfcntl()\fR function provides for control over open files. The
\fIfildes\fR argument is an open file descriptor.
.sp
.LP
The \fBfcntl()\fR function can take a third argument, \fIarg\fR, whose data
type, value, and use depend upon the value of \fIcmd\fR. The \fIcmd\fR argument
specifies the operation to be performed by \fBfcntl()\fR.
.sp
.LP
The values for \fIcmd\fR are defined in <\fBfcntl.h\fR> and include:
.sp
.ne 2
.na
\fB\fBF_DUPFD\fR\fR
.ad
.RS 15n
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,
\fIarg\fR, taken as an integer of type \fBint\fR. The new file descriptor
refers to the same open file description as the original file descriptor, and
shares any locks. The \fBFD_CLOEXEC\fR flag associated with the new file
descriptor is cleared to keep the file open across calls to one of the
\fBexec\fR(2) functions.
.RE

.sp
.ne 2
.na
\fB\fBF_DUP2FD\fR\fR
.ad
.RS 15n
Similar to \fBF_DUPFD\fR, but always returns \fIarg\fR. \fBF_DUP2FD\fR closes
\fIarg\fR if it is open and not equal to \fIfildes.\fR \fBF_DUP2FD\fR is
equivalent to \fBdup2\fR(\fIfildes\fR, \fIarg\fR).
.RE

.sp
.ne 2
.na
\fB\fBF_DUPFD_CLOEXEC\fR\fR
.ad
.RS 15n
Similar to \fBF_DUPFD\fR except that instead of clearing \fBFD_CLOEXEC\fR
it is explicitly set on the returned file descriptor.
.RE

.sp
.ne 2
.na
\fB\fBF_DUP2FD_CLOEXEC\fR\fR
.ad
.RS 15n
Similar to \fBF_DUP2FD\fR with two exceptions. The \fBFD_CLOEXEC\fR flag is
explicitly set on the returned file descriptor.  If \fIfiledes\fR equals
\fIarg\fR, the call will fail setting \fBerrno\fR to \fBEINVAL\fR.
.RE

.sp
.ne 2
.na
\fB\fBF_FREESP\fR\fR
.ad
.RS 15n
Free storage space associated with a section of the ordinary file \fIfildes\fR.
The section is specified by a variable of data type \fBstruct flock\fR pointed
to by \fIarg\fR. The data type \fBstruct flock\fR is defined in the
<\fBfcntl.h\fR> header (see \fBfcntl.h\fR(3HEAD)) and is described below. Note
that all file systems might not support all possible variations of
\fBF_FREESP\fR arguments. In particular, many file systems allow space to be
freed only at the end of a file.
.RE

.sp
.ne 2
.na
\fB\fBF_FREESP64\fR\fR
.ad
.RS 15n
Equivalent to \fBF_FREESP\fR, but takes a \fBstruct flock64\fR argument rather
than a \fBstruct flock\fR argument.
.RE

.sp
.ne 2
.na
\fB\fBF_ALLOCSP\fR\fR
.ad
.RS 15n
Allocate space for a section of the ordinary file \fIfildes\fR. The section is
specified by a variable of data type \fBstruct flock\fR pointed to by
\fIarg\fR. The data type \fBstruct flock\fR is defined in the <\fBfcntl.h\fR>
header (see \fBfcntl.h\fR(3HEAD) and is described below.
.RE

.sp
.ne 2
.na
\fB\fBF_ALLOCSP64\fR\fR
.ad
.RS 15n
Equivalent to \fBF_ALLOCSP\fR, but takes a \fBstruct flock64\fR argument rather
than a \fBstruct flock\fR argument.
.RE

.sp
.ne 2
.na
\fB\fBF_GETFD\fR\fR
.ad
.RS 15n
Get the file descriptor flags defined in <\fBfcntl.h\fR> that are associated
with the file descriptor \fIfildes\fR. File descriptor flags are associated
with a single file descriptor and do not affect other file descriptors that
refer to the same file.
.RE

.sp
.ne 2
.na
\fB\fBF_GETFL\fR\fR
.ad
.RS 15n
Get the file status flags and file access modes, defined in <\fBfcntl.h\fR>,
for the file descriptor specified by \fIfildes\fR. The file access modes can be
extracted from the return value using the mask \fBO_ACCMODE\fR, which is
defined in <\fBfcntl.h\fR>. File status flags and file access modes do not
affect other file descriptors that refer to the same file with different open
file descriptions.
.RE

.sp
.ne 2
.na
\fB\fBF_GETOWN\fR\fR
.ad
.RS 15n
If \fIfildes\fR refers to a socket, get the process or process group \fBID\fR
specified to receive \fBSIGURG\fR signals when out-of-band data is available.
Positive values indicate a process ID; negative values, other than \(mi1,
indicate a process group ID. If \fIfildes\fR does not refer to a socket, the
results are unspecified.
.RE

.sp
.ne 2
.na
\fB\fBF_GETXFL\fR\fR
.ad
.RS 15n
Get the file status flags, file access modes, and file creation and assignment
flags, defined in <\fBfcntl.h\fR>, for the file descriptor specified by
\fIfildes\fR. The file access modes can be extracted from the return value
using the mask \fBO_ACCMODE\fR, which is defined in <\fBfcntl.h\fR>. 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.
.RE

.sp
.ne 2
.na
\fB\fBF_SETFD\fR\fR
.ad
.RS 15n
Set the file descriptor flags defined in <\fBfcntl.h\fR>, that are associated
with \fIfildes\fR, to the third argument, \fIarg\fR, taken as type \fBint\fR.
If the \fBFD_CLOEXEC\fR flag in the third argument is 0, the file will remain
open across the \fBexec()\fR functions; otherwise the file will be closed upon
successful execution of one of the \fBexec()\fR functions.
.RE

.sp
.ne 2
.na
\fB\fBF_SETFL\fR\fR
.ad
.RS 15n
Set the file status flags, defined in <\fBfcntl.h\fR>, for the file descriptor
specified by \fIfildes\fR from the corresponding bits in the \fIarg\fR
argument, taken as type \fBint\fR. Bits corresponding to the file access mode
and file creation and assignment flags that are set in \fIarg\fR are ignored.
If any bits in \fIarg\fR other than those mentioned here are changed by the
application, the result is unspecified.
.RE

.sp
.ne 2
.na
\fB\fBF_SETOWN\fR\fR
.ad
.RS 15n
If \fIfildes\fR refers to a socket, set the process or process group \fBID\fR
specified to receive \fBSIGURG\fR signals when out-of-band data is available,
using the value of the third argument, \fIarg\fR, taken as type \fBint\fR.
Positive values indicate a process ID; negative values, other than \(mi1,
indicate a process group ID. If \fIfildes\fR does not refer to a socket, the
results are unspecified.
.RE

.sp
.LP
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.
.sp
.ne 2
.na
\fB\fBF_GETLK\fR\fR
.ad
.RS 14n
Get the first lock which blocks the POSIX lock description pointed to by the
third argument, \fIarg\fR, taken as a pointer to type \fBstruct flock\fR,
defined in <\fBfcntl.h\fR>. The information retrieved overwrites the
information passed to \fBfcntl()\fR in the structure \fBflock\fR. 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 \fBF_UNLCK\fR.
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,
\fB\(mi1\fR\& will be returned for the lock's pid value.
.RE

.sp
.ne 2
.na
\fB\fBF_GETLK64\fR\fR
.ad
.RS 14n
Equivalent to \fBF_GETLK\fR, but takes a \fBstruct flock64\fR argument rather
than a \fBstruct flock\fR argument.  See \fBlf64\fR(7).
.RE

.sp
.ne 2
.na
\fB\fBF_SETLK\fR\fR
.ad
.RS 14n
Set or clear a POSIX record lock according to the lock description pointed to
by the third argument, \fIarg\fR, taken as a pointer to type \fBstruct
flock\fR, defined in <\fBfcntl.h\fR>. \fBF_SETLK\fR is used to establish shared
(or read) locks (\fBF_RDLCK\fR) or exclusive (or write) locks (\fBF_WRLCK\fR),
as well as to remove either type of lock (\fBF_UNLCK\fR). \fBF_RDLCK\fR,
\fBF_WRLCK\fR and \fBF_UNLCK\fR are defined in <\fBfcntl.h\fR>. If a shared or
exclusive lock cannot be set, \fBfcntl()\fR will return immediately with a
return value of \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_SETLK64\fR\fR
.ad
.RS 14n
Equivalent to \fBF_SETLK\fR, but takes a \fBstruct flock64\fR argument rather
than a \fBstruct flock\fR argument. See \fBlf64\fR(7).
.RE

.sp
.ne 2
.na
\fB\fBF_SETLKW\fR\fR
.ad
.RS 14n
This command is the same as \fBF_SETLK\fR 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 \fBfcntl()\fR is
waiting for a region, \fBfcntl()\fR will be interrupted. Upon return from the
process' signal handler, \fBfcntl()\fR will return \fB\(mi1\fR with \fBerrno\fR
set to \fBEINTR\fR, and the lock operation will not be done.
.RE

.sp
.ne 2
.na
\fB\fBF_SETLKW64\fR\fR
.ad
.RS 14n
Equivalent to \fBF_SETLKW\fR, but takes a \fBstruct flock64\fR argument rather
than a \fBstruct flock\fR argument. See \fBlf64\fR(7).
.RE

.sp
.LP
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.
\fBnfs\fR(5)) which use the Network Lock Manager.
.sp
.ne 2
.na
\fB\fBF_OFD_GETLK\fR\fR
.ad
.RS 14n
Get the first lock which blocks the OFD lock description pointed to by the
third argument, \fIarg\fR, taken as a pointer to type \fBstruct flock\fR,
defined in <\fBfcntl.h\fR>. The information retrieved overwrites the
information passed to \fBfcntl()\fR in the structure \fBflock\fR. 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 \fBF_UNLCK\fR.
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,
\fB\(mi1\fR\& will be returned for the lock's pid value.
.RE

.sp
.ne 2
.na
\fB\fBF_OFD_GETLK64\fR\fR
.ad
.RS 14n
Equivalent to \fBF_OFD_GETLK\fR, but takes a \fBstruct flock64\fR argument
rather than a \fBstruct flock\fR argument. See \fBlf64\fR(7). This command
exists solely to allow the use of OFD locks with the transitional 64-bit file
interfaces.
.RE

.sp
.ne 2
.na
\fB\fBF_OFD_SETLK\fR\fR
.ad
.RS 14n
Set or clear a OFD record lock according to the lock description pointed to
by the third argument, \fIarg\fR, taken as a pointer to type \fBstruct
flock\fR, defined in <\fBfcntl.h\fR>. \fBF_OFD_SETLK\fR is used to establish
shared (or read) locks (\fBF_RDLCK\fR) or exclusive (or write) locks
(\fBF_WRLCK\fR), as well as to remove either type of lock (\fBF_UNLCK\fR).
\fBF_RDLCK\fR, \fBF_WRLCK\fR and \fBF_UNLCK\fR are defined in <\fBfcntl.h\fR>.
If a shared or exclusive lock cannot be set, \fBfcntl()\fR will return
immediately with a return value of \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_OFD_SETLK64\fR\fR
.ad
.RS 14n
Equivalent to \fBF_OFD_SETLK\fR, but takes a \fBstruct flock64\fR argument
rather than a \fBstruct flock\fR argument. See \fBlf64\fR(7). This command
exists solely to allow the use of OFD locks with the transitional 64-bit file
interfaces.
.RE

.sp
.ne 2
.na
\fB\fBF_OFD_SETLKW\fR\fR
.ad
.RS 14n
This command is the same as \fBF_OFD_SETLK\fR 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
\fBfcntl()\fR is waiting for a region, \fBfcntl()\fR will be interrupted. Upon
return from the process' signal handler, \fBfcntl()\fR will return \fB\(mi1\fR
with \fBerrno\fR set to \fBEINTR\fR, and the lock operation will not be done.
.RE

.sp
.ne 2
.na
\fB\fBF_OFD_SETLKW64\fR\fR
.ad
.RS 14n
Equivalent to \fBF_OFD_SETLKW\fR, but takes a \fBstruct flock64\fR argument
rather than a \fBstruct flock\fR argument. See \fBlf64\fR(7).  This command
exists solely to allow the use of OFD locks with the transitional 64-bit file
interfaces.
.RE

.sp
.LP
The following values for \fIcmd\fR 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.
.sp
.ne 2
.na
\fB\fBF_SHARE\fR\fR
.ad
.RS 13n
Sets a share reservation on a file with the specified access mode and
designates which types of access to deny.
.RE

.sp
.ne 2
.na
\fB\fBF_UNSHARE\fR\fR
.ad
.RS 13n
Remove an existing share reservation.
.RE

.SH 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 \fBF_SETLK\fR,
\fBF_SETLK64\fR, \fBF_SETLKW\fR, or \fBF_SETLKW64\fR commands to this system
call or by use of the \fBlockf\fR(3C) routine. There is no difference between
locks created via one mechanism or the other. Likewise, OFD-style locks are
created via the \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or
\fBF_OFD_SETLKW64\fR commands to this system call or by use of the
Linux/BSD-compatible \fBflock\fR(3C) routine. Note that this system call
supports the creation of range-specified OFD-style file locks, while
\fBflock\fR(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.
.sp
.LP
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 \fBfork\fR(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
\fBF_DUPFD\fR, \fBF_DUP2FD\fR, \fBF_DUPFD_CLOEXEC\fR, or \fBF_DUP2FD_CLOEXEC\fR
commands to the \fBfcntl\fR(2) system call, or those created via the
\fBdup\fR(2) system call, or those inherited by a child process created via
\fBfork\fR(2)) reference the same lock, but a file descriptor obtained via a
separate \fBopen\fR(2) call on the same file will reference a different lock.
A lock is removed only on the last \fBclose\fR(2) of the description, or when
the lock is explicitly unlocked.
.sp
.LP
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 \fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_OFD_GETLK\fR, or
\fBF_OFD_GETLK64\fR 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 \fBl_pid\fR field of a lock descriptor for any
such lock will always be set to \fB\(mi1\fR\&.
.sp
.LP
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.
.sp
.LP
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.
.sp
.LP
The \fBflock\fR structure contains at least the following elements:
.sp
.in +2
.nf
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 */
.fi
.in -2

.sp
.LP
The value of \fBl_whence\fR is \fBSEEK_SET\fR, \fBSEEK_CUR\fR, or
\fBSEEK_END\fR, to indicate that the relative offset \fBl_start\fR bytes will
be measured from the start of the file, current position or end of the file,
respectively. The value of \fBl_len\fR is the number of consecutive bytes to be
locked. The value of \fBl_len\fR may be negative (where the definition of
\fBoff_t\fR permits negative values of \fBl_len\fR). After a successful
\fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_OFD_GETLK\fR, or \fBF_OFD_GETLK64\fR
request, that is, one in which a lock was found, the value of \fBl_whence\fR
will be \fBSEEK_SET\fR.
.sp
.LP
The \fBl_pid\fR and \fBl_sysid\fR fields are used only with \fBF_GETLK\fR or
\fBF_GETLK64\fR to return the process \fBID\fR of the process holding a
POSIX-style blocking lock and to indicate which system is running that process,
or \fB\(mi1\fR\& if it is an OFD-style lock. These fields must both be
initialized to 0 prior to issuing a OFD-style locking command
(\fBF_OFD_GETLK\fR or \fBF_OFD_GETLK64\fR).
.sp
.LP
If \fBl_len\fR is positive, the area affected starts at \fBl_start\fR and ends
at \fBl_start\fR + \fBl_len \(mi 1\fR. If \fBl_len\fR is negative, the area
affected starts at \fBl_start\fR + \fBl_len\fR and ends at \fBl_start \(mi
1\fR. 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
\fBl_len\fR to 0. If such a lock also has \fBl_start\fR set to 0 and
\fBl_whence\fR is set to \fBSEEK_SET\fR, the whole file will be locked.
.sp
.LP
If a lock exists for which \fBl_len\fR is 0 and which includes the last byte of
the requested segment, and an unlock (\fBF_UNLCK\fR) request is made in which
\fBl_len\fR is non-zero and the offset of the last byte of the requested
segment is the maximum value for an object of type \fBoff_t\fR, then the
\fBF_UNLCK\fR request will be treated as a request to unlock from the start
of the requested segment with an \fBl_len\fR equal to 0. Otherwise, the request
will attempt to unlock only the requested segment.
.sp
.LP
There will be at most one type of lock set for each byte in the
file. Before a successful return from an \fBF_SETLK\fR, \fBF_SETLK64\fR,
\fBF_SETLKW\fR, or \fBF_SETLKW64\fR 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 \fBF_SETLK\fR,
\fBF_SETLK64\fR, \fBF_SETLKW\fR, or \fBF_SETLKW64\fR 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.
.sp
.LP
Similarly, before a successful return from an \fBF_OFD_SETLK\fR,
\fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR 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 \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or
\fBF_OFD_SETLKW64\fR 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.
.sp
.LP
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,
\fBfcntl()\fR will fail with an \fBEDEADLK\fR 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.

.SH 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 \fBDOS\fR or Windows emulators and \fBDOS based\fR \fBNFS\fR clients.
However, native UNIX versions of \fBDOS\fR or Windows applications may also
choose to use this form of access control.
.sp
.LP
A share reservation is described by an \fBfshare\fR structure defined in
<\fBsys/fcntl.h\fR>, which is included in <\fBfcntl.h\fR> as follows:
.sp
.in +2
.nf
typedef struct fshare {
        short   f_access;
        short   f_deny;
        int     f_id;
} fshare_t;
.fi
.in -2

.sp
.LP
A share reservation specifies the type of access, \fBf_access\fR, to be
requested on the open file descriptor. If access is granted, it further
specifies what type of access to deny other processes, \fBf_deny\fR. A single
process on the same file may hold multiple non-conflicting  reservations by
specifying an identifier, \fBf_id\fR, unique to the process, with each request.
.sp
.LP
An \fBF_UNSHARE\fR request releases the reservation with the specified
\fBf_id\fR. The \fBf_access\fR and \fBf_deny\fR fields are ignored.
.sp
.LP
Valid \fBf_access\fR values are:
.sp
.ne 2
.na
\fB\fBF_RDACC\fR\fR
.ad
.RS 11n
Set a file share reservation for read-only access.
.RE

.sp
.ne 2
.na
\fB\fBF_WRACC\fR\fR
.ad
.RS 11n
Set a file share reservation for write-only access.
.RE

.sp
.ne 2
.na
\fB\fBF_RWACC\fR\fR
.ad
.RS 11n
Set a file share reservation for read and write access.
.RE

.sp
.LP
Valid \fBf_deny\fR values are:
.sp
.ne 2
.na
\fB\fBF_COMPAT\fR\fR
.ad
.RS 12n
Set a file share reservation to compatibility mode.
.RE

.sp
.ne 2
.na
\fB\fBF_RDDNY\fR\fR
.ad
.RS 12n
Set a file share reservation to deny read access to other processes.
.RE

.sp
.ne 2
.na
\fB\fBF_WRDNY\fR\fR
.ad
.RS 12n
Set a file share reservation to deny write access to other processes.
.RE

.sp
.ne 2
.na
\fB\fBF_RWDNY\fR\fR
.ad
.RS 12n
Set a file share reservation to deny read and write access to other processes.
.RE

.sp
.ne 2
.na
\fB\fBF_NODNY\fR\fR
.ad
.RS 12n
Do not deny read or write access to any other process.
.RE

.SH RETURN VALUES
Upon successful completion, the value returned depends on \fIcmd\fR as follows:
.sp
.ne 2
.na
\fB\fBF_DUPFD\fR\fR
.ad
.RS 14n
A new file descriptor.
.RE

.sp
.ne 2
.na
\fB\fBF_FREESP\fR\fR
.ad
.RS 14n
Value of \fB0\fR.
.RE

.sp
.ne 2
.na
\fB\fBF_GETFD\fR\fR
.ad
.RS 14n
Value of flags defined in \fB<fcntl.h>\fR\&. The return value will not be
negative.
.RE

.sp
.ne 2
.na
\fB\fBF_GETFL\fR\fR
.ad
.RS 14n
Value of file status flags and access modes. The return value will not be
negative.
.RE

.sp
.ne 2
.na
\fB\fBF_GETLK\fR\fR
.ad
.RS 14n
Value other than \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_GETLK64\fR\fR
.ad
.RS 14n
Value other than \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_GETOWN\fR\fR
.ad
.RS 14n
Value of the socket owner process or process group; this will not be
\fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_GETXFL\fR\fR
.ad
.RS 14n
Value of file status flags, access modes, and creation and assignment flags.
The return value will not be negative.
.RE

.sp
.ne 2
.na
\fB\fBF_OFD_GETLK\fR\fR
.ad
.RS 14n
Value other then \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_OFD_GETLK64\fR\fR
.ad
.RS 14n
Value other then \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_OFD_SETLK\fR\fR
.ad
.RS 14n
Value other then \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_OFD_SETLK64\fR\fR
.ad
.RS 14n
Value other then \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_OFD_SETLKW\fR\fR
.ad
.RS 14n
Value other then \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_OFD_SETLKW64\fR\fR
.ad
.RS 14n
Value other then \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_SETFD\fR\fR
.ad
.RS 14n
Value other than \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_SETFL\fR\fR
.ad
.RS 14n
Value other than \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_SETLK\fR\fR
.ad
.RS 14n
Value other than \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_SETLK64\fR\fR
.ad
.RS 14n
Value other than \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_SETLKW\fR\fR
.ad
.RS 14n
Value other than \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_SETLKW64\fR\fR
.ad
.RS 14n
Value other than \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_SETOWN\fR\fR
.ad
.RS 14n
Value other than \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_SHARE\fR\fR
.ad
.RS 14n
Value other than \fB\(mi1\fR\&.
.RE

.sp
.ne 2
.na
\fB\fBF_UNSHARE\fR\fR
.ad
.RS 14n
Value other than \fB\(mi1\fR\&.
.RE

.sp
.LP
Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the
error.
.SH ERRORS
The \fBfcntl()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 13n
The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_OFD_SETLK\fR,
or \fBF_OFD_SETLK64\fR, the type of lock \fB(l_type)\fR is a shared
(\fBF_RDLCK\fR) or exclusive (\fBF_WRLCK\fR) 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.
.sp
The \fIcmd\fR argument is \fBF_FREESP\fR, the file exists, mandatory
file/record locking is set, and there are outstanding record locks on the file;
or the \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, or
\fBF_SETLKW64\fR, mandatory file/record locking is set, and the file is
currently being mapped to virtual memory using \fBmmap\fR(2).
.sp
The \fIcmd\fR argument is \fBF_SHARE\fR and \fBf_access\fR conflicts with an
existing \fBf_deny\fR share reservation.
.RE

.sp
.ne 2
.na
\fB\fBEBADF\fR\fR
.ad
.RS 13n
The \fIfildes\fR argument is not a valid open file descriptor; or the \fIcmd\fR
argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, \fBF_SETLKW64\fR,
\fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or
\fBF_OFD_SETLKW64\fR, the type of lock, \fBl_type\fR, is a shared lock
(\fBF_RDLCK\fR), and \fIfildes\fR is not a valid file descriptor open for
reading; or the type of lock \fBl_type\fR is an exclusive lock (\fBF_WRLCK\fR)
and \fIfildes\fR is not a valid file descriptor open for writing.
.sp
The \fIcmd\fR argument is \fBF_FREESP\fR and \fIfildes\fR is not a valid file
descriptor open for writing.
.sp
The \fIcmd\fR argument is \fBF_DUP2FD\fR, and \fIarg\fR is negative or is not
less than the current resource limit for \fBRLIMIT_NOFILE.\fR
.sp
The \fIcmd\fR argument is \fBF_SHARE,\fR the \fBf_access\fR share reservation
is for write access, and \fIfildes\fR is not a valid file descriptor open for
writing.
.sp
The \fIcmd\fR argument is \fBF_SHARE,\fR the \fBf_access\fR share reservation
is for read access, and \fIfildes\fR is not a valid file descriptor open for
reading.
.RE

.sp
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 13n
The \fIcmd\fR argument is \fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_SETLK\fR,
\fBF_SETLK64\fR, \fBF_SETLKW\fR, \fBF_SETLKW64\fR, \fBF_OFD_GETLK\fR,
\fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR,
\fBF_OFD_SETLKW64\fR, \fBF_SHARE\fR, \fBF_UNSHARE\fR, or \fBF_FREESP\fR and the
\fIarg\fR argument points to an illegal address.
.RE

.sp
.ne 2
.na
\fB\fBEINTR\fR\fR
.ad
.RS 13n
The \fIcmd\fR argument is \fBF_SETLKW\fR, \fBF_SETLKW64\fR, \fBF_OFD_SETLKW\fR,
or \fBF_OFD_SETLKW64\fR, and the function was interrupted by a signal.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 13n
The \fIcmd\fR argument is invalid or not supported by the file system; or the
\fIcmd\fR argument is \fBF_DUPFD\fR and \fIarg\fR is negative or greater than
or equal to \fBOPEN_MAX\fR; or the \fIcmd\fR argument is \fBF_GETLK\fR,
\fBF_GETLK64\fR, \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR,
\fBF_SETLKW64\fR, \fBF_OFD_GETLK\fR, \fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK\fR,
\fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR, and the data
pointed to by \fIarg\fR is not valid; or \fIfildes\fR refers to a file that
does not support locking.
.sp
The \fIcmd\fR argument is \fBF_UNSHARE\fR and a reservation with this
\fBf_id\fR for this process does not exist.
.sp
The \fIcmd\fR argument is \fBF_DUP2FD_CLOEXEC\fR and \fIfildes\fR is equal
to \fBarg\fR.
.RE

.sp
.ne 2
.na
\fB\fBEIO\fR\fR
.ad
.RS 13n
An I/O error occurred while reading from or writing to the file system.
.RE

.sp
.ne 2
.na
\fB\fBEMFILE\fR\fR
.ad
.RS 13n
The \fIcmd\fR argument is \fBF_DUPFD\fR and either \fBOPEN_MAX\fR file
descriptors are currently open in the calling process, or no file descriptors
greater than or equal to \fIarg\fR are available.
.RE

.sp
.ne 2
.na
\fB\fBENOLCK\fR\fR
.ad
.RS 13n
The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR,
\fBF_SETLKW64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR,
or \fBF_OFD_SETLKW64\fR, and satisfying the lock or unlock request would
result in the number of locked regions in the system exceeding a
system-imposed limit.
.RE

.sp
.ne 2
.na
\fB\fBENOLINK\fR\fR
.ad
.RS 13n
Either the \fIfildes\fR argument is on a remote machine and the link to that
machine is no longer active; or the \fIcmd\fR argument is \fBF_FREESP\fR, the
file is on a remote machine, and the link to that machine is no longer active.
.RE

.sp
.ne 2
.na
\fB\fBEOVERFLOW\fR\fR
.ad
.RS 13n
One of the values to be returned cannot be represented correctly.
.sp
The \fIcmd\fR argument is \fBF_GETLK\fR, \fBF_SETLK\fR, \fBF_SETLKW\fR,
\fBF_OFD_GETLK\fR, \fBF_OFD_SETLK\fR, or \fBF_OFD_SETLKW\fR, and
the smallest or, if \fBl_len\fR is non-zero, the largest, offset of any byte in
the requested segment cannot be represented correctly in an object of type
\fBoff_t\fR.
.sp
The \fIcmd\fR argument is \fBF_GETLK64\fR, \fBF_SETLK64\fR, \fBF_SETLKW64\fR,
\fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK64\fR, or \fBF_OFD_SETLKW64\fR,
and the smallest or, if \fBl_len\fR is non-zero, the largest, offset of any
byte in the requested segment cannot be represented correctly in an object of
type \fBoff64_t\fR.
.RE

.sp
.LP
The \fBfcntl()\fR function may fail if:
.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 11n
The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR,
\fBF_SETLKW64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR,
or \fBF_OFD_SETLKW64\fR and the file is currently being mapped to virtual memory
using \fBmmap\fR(2).
.RE

.sp
.ne 2
.na
\fB\fBEDEADLK\fR\fR
.ad
.RS 11n
The \fIcmd\fR argument is \fBF_SETLKW\fR or \fBF_SETLKW64\fR, 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.
.sp
The \fIcmd\fR argument is \fBF_FREESP,\fR mandatory record locking is enabled,
\fBO_NDELAY\fR and \fBO_NONBLOCK\fR are clear and a deadlock condition was
detected.
.RE

.sp
.ne 2
.na
\fB\fBEOPNOTSUPP\fR
.ad
.RS 11n
The \fIcmd\fR argument is \fBF_OFD_GETLK\fR, \fBF_OFD_GETLK64\fR,
\fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or
\fBF_OFD_SETLKW64\fR and the locking of files of the type indicated by the
\fIfildes\fR argument is not supported.
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard
_
MT-Level	Async-Signal Safe
.TE

.SH SEE ALSO
.BR chmod (2),
.BR close (2),
.BR creat (2),
.BR dup (2),
.BR exec (2),
.BR fork (2),
.BR mmap (2),
.BR open (2),
.BR pipe (2),
.BR read (2),
.BR sigaction (2),
.BR write (2),
.BR dup2 (3C),
.BR flock (3C),
.BR lockf (3C),
.BR fcntl.h (3HEAD),
.BR attributes (7),
.BR lf64 (7),
.BR standards (7),
.BR lockd (8)
.sp
.LP
\fIProgramming Interfaces Guide\fR
.SH NOTES
In the past, the variable \fBerrno\fR was set to \fBEACCES\fR rather than
\fBEAGAIN\fR when a section of a file is already locked by another process.
Therefore, portable application programs should expect and test for either
value.
.sp
.LP
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 \fBf_deny\fR value of \fBF_COMPAT\fR. For network
file systems, if \fBf_access\fR is \fBF_RDACC\fR, \fBf_deny\fR is mapped to
\fBF_RDDNY\fR. Otherwise, it is mapped to \fBF_RWDNY\fR.
.sp
.LP
To prevent possible file corruption, the system may reject \fBmmap()\fR
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 (\fBl_start\fR and \fBl_len\fR 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.
.sp
.LP
The process ID returned for locked files on network file systems might not be
meaningful.
.sp
.LP
If the file server crashes and has to be rebooted, the lock manager (see
\fBlockd\fR(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 \fBSIGLOST\fR signal.