.\"
.\" 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
.\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 2024 Oxide Computer Company
.\"
.TH FCNTL.H 3HEAD "June 21, 2024"
.SH NAME
fcntl.h, fcntl \- file control options
.SH SYNOPSIS
.nf
#include <fcntl.h>
.fi

.SH DESCRIPTION
The \fB<fcntl.h>\fR header defines the following requests and arguments for use
by the functions \fBfcntl\fR(2), \fBopen\fR(2), and \fBopenat\fR(2).
.sp
.LP
Values for \fIcmd\fR used by \fBfcntl()\fR (the following values are unique):
.sp
.ne 2
.na
\fB\fBF_DUPFD\fR\fR
.ad
.RS 15n
Duplicate file descriptor. File descriptor flags cleared on duplicate.
.RE

.sp
.ne 2
.na
\fB\fBF_DUP2FD\fR\fR
.ad
.RS 15n
Similar to \fBF_DUPFD\fR, but always returns \fIarg\fR.  File descriptor flags
cleared on duplicate.
.RE

.sp
.ne 2
.na
\fB\fBF_DUP3FD\fR\fR
.ad
.RS 15n
Similar to \fBF_DUP2FD\fR, but takes a fourth \fBint\fR argument which specifies
the file descriptor flags (\fBFD_CLOEXEC\fR and \fBFD_CLOFORK\fR).
.RE

.sp
.ne 2
.na
\fB\fBF_DUPFD_CLOEXEC\fR\fR
.ad
.RS 15n
Similar to \fBF_DUPFD\fR, but the \fBFD_CLOEXEC\fR flag is set on the returned
descriptor.
.RE

.sp
.ne 2
.na
\fB\fBF_DUPFD_CLOFORK\fR\fR
.ad
.RS 15n
Similar to \fBF_DUPFD\fR, but the \fBFD_CLOFORK\fR flag is set on the returned
descriptor.
.RE

.sp
.ne 2
.na
\fB\fBF_DUP2FD_CLOEXEC\fR\fR
.ad
.RS 15n
Similar to \fBF_DUP2FD\fR, but the \fBFD_CLOEXEC\fR flag is set on the returned
descriptor.
.RE

.sp
.ne 2
.na
\fB\fBF_DUP2FD_CLOFORK\fR\fR
.ad
.RS 15n
Similar to \fBF_DUP2FD\fR, but the \fBFD_CLOFORK\fR flag is set on the returned
descriptor.
.RE

.sp
.ne 2
.na
\fB\fBF_GETFD\fR\fR
.ad
.RS 15n
Get file descriptor flags.
.RE

.sp
.ne 2
.na
\fB\fBF_SETFD\fR\fR
.ad
.RS 15n
Set file descriptor flags.
.RE

.sp
.ne 2
.na
\fB\fBF_GETFL\fR\fR
.ad
.RS 15n
Get file status flags.
.RE

.sp
.ne 2
.na
\fB\fBF_SETFL\fR\fR
.ad
.RS 15n
Set file status flags.
.RE

.sp
.ne 2
.na
\fB\fBF_GETOWN\fR\fR
.ad
.RS 15n
Get process or process group \fBID\fR to receive \fBSIGURG\fR signals.
.RE

.sp
.ne 2
.na
\fB\fBF_SETOWN\fR\fR
.ad
.RS 15n
Set process or process group \fBID\fR to receive \fBSIGURG\fR signals.
.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.
.RE

.sp
.ne 2
.na
\fB\fBF_ALLOCSP\fR\fR
.ad
.RS 15n
Allocate space for a section of the ordinary file \fIfildes\fR.
.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_GETLK\fR\fR
.ad
.RS 15n
Get record locking information.
.RE

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

.sp
.ne 2
.na
\fB\fBF_SETLK\fR\fR
.ad
.RS 15n
Set record locking information.
.RE

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

.sp
.ne 2
.na
\fB\fBF_SETLKW\fR\fR
.ad
.RS 15n
Set record locking information; wait if blocked.
.RE

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

.sp
.ne 2
.na
\fB\fBF_SHARE\fR\fR
.ad
.RS 15n
Set share reservation.
.RE

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

.sp
.LP
File descriptor flags used for \fBfcntl()\fR:
.sp
.ne 2
.na
\fB\fBFD_CLOEXEC\fR\fR
.ad
.RS 14n
Close the file descriptor upon execution of an \fBexec\fR function (see
\fBexec\fR(2)).
.RE

.sp
.ne 2
.na
\fB\fBFD_CLOFORK\fR\fR
.ad
.RS 14n
Close the file descriptor in any child process created with the \fBfork\fR(2)
family functions.
.RE

.sp
.LP
Values for \fBl_type\fR used for record locking with \fBfcntl()\fR (the
following values are unique):
.sp
.ne 2
.na
\fB\fBF_RDLCK\fR\fR
.ad
.RS 11n
Shared or read lock.
.RE

.sp
.ne 2
.na
\fB\fBF_UNLCK\fR\fR
.ad
.RS 11n
Unlock.
.RE

.sp
.ne 2
.na
\fB\fBF_WRLCK\fR\fR
.ad
.RS 11n
Exclusive or write lock.
.RE

.sp
.LP
Values for \fBf_access\fR used for share reservations with \fBfcntl()\fR (the
following values are unique):
.sp
.ne 2
.na
\fB\fBF_RDACC\fR\fR
.ad
.RS 11n
Read-only share reservation.
.RE

.sp
.ne 2
.na
\fB\fBF_WRACC\fR\fR
.ad
.RS 11n
Write-only share reservation.
.RE

.sp
.ne 2
.na
\fB\fBF_RWACC\fR\fR
.ad
.RS 11n
Read and write share reservation.
.RE

.sp
.LP
Values for \fBf_deny\fR used for share reservations with \fBfcntl()\fR (the
following values are unique):
.sp
.ne 2
.na
\fB\fBF_COMPAT\fR\fR
.ad
.RS 12n
Compatibility mode share reservation.
.RE

.sp
.ne 2
.na
\fB\fBF_RDDNY\fR\fR
.ad
.RS 12n
Deny other read access share reservations.
.RE

.sp
.ne 2
.na
\fB\fBF_WRDNY\fR\fR
.ad
.RS 12n
Deny other write access share reservations.
.RE

.sp
.ne 2
.na
\fB\fBF_RWDNY\fR\fR
.ad
.RS 12n
Deny other read or write access share reservations.
.RE

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

.sp
.LP
File creation and assignment flags are used in the \fIoflag\fR argument by
\fBopen()\fR and \fBopenat()\fR. All of these values are bitwise distinct:
.sp
.ne 2
.na
\fB\fBO_CREAT\fR\fR
.ad
.RS 12n
Create file if it does not exist.
.RE

.sp
.ne 2
.na
.B O_DIRECTORY
.ad
.RS 12n
Fail unless the path is a directory.
.RE

.sp
.ne 2
.na
\fB\fBO_EXCL\fR\fR
.ad
.RS 12n
Exclusive use flag.
.RE

.sp
.ne 2
.na
\fB\fBO_NOCTTY\fR\fR
.ad
.RS 12n
Do not assign controlling tty.
.RE

.sp
.ne 2
.na
\fB\fBO_TRUNC\fR\fR
.ad
.RS 12n
Truncate flag.
.RE

.sp
.ne 2
.na
\fB\fBO_XATTR\fR\fR
.ad
.RS 12n
When opening a file, this flag affects the way in which relative paths are
resolved by \fBopen()\fR and \fBopenat()\fR.  With this flag set, the
\fIpath\fR argument is resolved as an extended attribute reference on either
the current working directory (if open) or of the file referenced by the file
descriptor argument of \fBopenat()\fR.
.RE

.sp
.LP
File status flags used for \fBfcntl()\fR, \fBopen()\fR, and \fBopen()\fR:
.sp
.ne 2
.na
\fB\fBO_APPEND\fR\fR
.ad
.RS 14n
Set append mode.
.RE

.sp
.ne 2
.na
.B O_CLOEXEC
.ad
.RS 12n
The file should be closed on any calls to \fBexec\fR(2).
.RE

.sp
.ne 2
.na
.B O_CLOFORK
.ad
.RS 12n
The file will be closed in any child processes created with calls to
\fBfork\fR(2).
.RE

.sp
.ne 2
.na
\fB\fBO_NDELAY\fR\fR
.ad
.RS 14n
Non-blocking mode.
.RE

.sp
.ne 2
.na
\fB\fBO_NONBLOCK\fR\fR
.ad
.RS 14n
Non-blocking mode (POSIX; see \fBstandards\fR(7)).
.RE

.sp
.ne 2
.na
\fB\fBO_DSYNC\fR\fR
.ad
.RS 14n
Write I/O operations on the file descriptor complete as defined by synchronized
I/O data integrity completion.
.RE

.sp
.ne 2
.na
\fB\fBO_RSYNC\fR\fR
.ad
.RS 14n
Read I/O operations on the file descriptor complete at the same level of
integrity as specified by the \fBO_DSYNC\fR and  \fBO_SYNC\fR flags. If both
\fBO_DSYNC\fR and \fBO_RSYNC\fR are set in \fIoflag\fR, all I/O operations on
the file descriptor complete as defined by synchronized I/O data integrity
completion.  If both  \fBO_SYNC\fR and \fBO_RSYNC\fR are set in \fIoflag\fR,
all I/O operations on the file descriptor complete as defined by synchronized
I/O file integrity completion.
.RE

.sp
.ne 2
.na
\fB\fBO_SYNC\fR\fR
.ad
.RS 14n
When opening a regular file, this flag affects subsequent writes. If set, each
\fBwrite\fR(2) will wait for both the file data and file status to be
physically updated.  Write I/O operations on the file descriptor complete as
defined by synchronized I/O file integrity completion.
.RE

.sp
.LP
Mask for use with file access modes:
.sp
.ne 2
.na
\fB\fBO_ACCMODE\fR\fR
.ad
.RS 13n
Mask for file access modes.
.RE

.sp
.LP
File access modes used for \fBfcntl()\fR, \fBopen()\fR, and \fBopenat()\fR:
.sp
.ne 2
.na
\fB\fBO_RDONLY\fR\fR
.ad
.RS 12n
Open for reading only.
.RE

.sp
.ne 2
.na
\fB\fBO_RDWR\fR\fR
.ad
.RS 12n
Open for reading and writing.
.RE

.sp
.ne 2
.na
\fB\fBO_WRONLY\fR\fR
.ad
.RS 12n
Open for writing only.
.RE

.sp
.LP
The following constants are used by system calls capable of resolving paths
relative to a provided open file descriptor:
.sp
.ne 2
.na
\fB\fBAT_FDCWD\fR\fR
.ad
.RS 23n
Special value to pass in place of a file descriptor to inform the called
routine that relative path arguments should be resolved from the current
working directory.
.RE

.sp
.ne 2
.na
\fB\fBAT_SYMLINK_NOFOLLOW\fR\fR
.ad
.RS 23n
Flag passed to \fBfstatat\fR(2) and \fBfchownat\fR(2) to change the behavior of
these functions when they are given a file as an argument that is a symbolic
link. In this case the functions operate on the symbolic link file rather than
the file the link references.
.RE

.sp
.ne 2
.na
\fB\fBAT_REMOVEDIR\fR\fR
.ad
.RS 23n
Flag passed to \fBunlinkat\fR(2) to tell it to assume that its path argument
refers to a directory and to attempt to remove this directory.
.RE

.sp
.LP
The \fBflock\fR structure describes a file lock. It includes the following
members:
.sp
.in +2
.nf
short   l_type;   /* Type of lock */
short   l_whence; /* Flag for starting offset */
off_t   l_start;  /* Relative offset in bytes */
off_t   l_len;    /* Size; if 0 then until EOF */
long    l_sysid;  /* Returned with F_GETLK */
pid_t   l_pid;    /* Returned with F_GETLK */
.fi
.in -2

.sp
.LP
The structure \fBfshare\fR describes a file share reservation. It includes the
following members:
.sp
.in +2
.nf
short   f_access; /* Type of reservation */
short   f_deny;   /* Type of reservations to deny */
long    f_id;     /* Process unique identifier */
.fi
.in -2

.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	Committed
_
Standard	See \fBstandards\fR(7).
.TE

.SH SEE ALSO
.BR creat (2),
.BR exec (2),
.BR fcntl (2),
.BR fork (2),
.BR open (2),
.BR fdatasync (3C),
.BR fsync (3C),
.BR attributes (7),
.BR fsattr (7),
.BR standards (7)
.SH NOTES
Data is successfully  transferred for a write operation to a regular file when
the system ensures that all data written is readable on any subsequent open of
the file (even one that follows a system or power failure) in the absence of a
failure of the physical storage medium.
.sp
.LP
Data is successfully transferred for a read operation when an image of the data
on the physical storage medium is available to the requesting process.
.sp
.LP
Synchronized I/O data integrity completion (see \fBfdatasync\fR(3C)):
.RS +4
.TP
.ie t \(bu
.el o
For reads, the operation has been completed or diagnosed if unsuccessful. The
read is complete only when an image of the data has been successfully
transferred to the requesting process. If there were any pending write requests
affecting the data to be read at the time that the synchronized read operation
was requested, these write requests will be successfully transferred prior to
reading the data.
.RE
.RS +4
.TP
.ie t \(bu
.el o
For writes, the operation has been completed or diagnosed if unsuccessful. The
write is complete only when the data specified in the write request is
successfully transferred, and all file system information required to retrieve
the data is successfully transferred.
.RE
.sp
.LP
File attributes that are not necessary for data retrieval (access time,
modification time, status change time) need not be successfully  transferred
prior to returning to the calling process.
.sp
.LP
Synchronized I/O file integrity completion (see \fBfsync\fR(3C)):
.RS +4
.TP
.ie t \(bu
.el o
Identical to a synchronized I/O data integrity completion with the addition
that all file attributes relative to the I/O operation (including access time,
modification time, status change time) will be successfully transferred prior
to returning to the calling process.
.RE