FCNTL(2)FCNTL(2)NAMEfcntl - file control
SYNOPSIS
#include <sys/types.h>
/* POSIX applications #include <unistd.h> */
#include <fcntl.h>
int fcntl(int fd, int cmd, ...);
int fcntl(int fd, int cmd, int arg);
int fcntl(int fd, int cmd, struct flock *arg);
DESCRIPTION
The fcntl function performs a variety of functions on open descriptors.
The argument fd is an open descriptor to be operated on by cmd as
follows:
F_DUPFD Return a new descriptor as follows:
Lowest numbered available descriptor greater than or
equal to arg.
References the same object as the original descriptor.
New descriptor shares the same file pointer if the
object was a file.
Same access mode (read, write or read/write).
Same file status flags (that is, both descriptors share
the same file status flags).
The close-on-exec flag associated with the new
descriptor is cleared to keep the file open across
execve(2) system calls.
F_GETFD Get the close-on-exec flag associated with the
descriptor fd. If the low-order bit of this flag is
clear (that is, if it's zero), then the file will remain
open across an exec(2) system call. Otherwise the file
will be closed upon execution of exec(2). POSIX
applications refer to this flag with the constant
FD_CLOEXEC.
F_SETFD Set the close-on-exec flag associated with fd to the
low-order bit of the third argument, arg. POSIX
applications use the constant FD_CLOEXEC to set this
flag and 0 to clear it.
F_GETFL Get the file status flags and file access modes for the
open file descriptor associated with fd.
POSIX applications can extract the file access modes
from the return value using the mask O_ACCMODE (see
<fcntl.h>). The file status flags are O_APPEND (set
append mode) and O_NONBLOCK (no delay). The file access
modes are O_RDONLY (open for reading only), O_RDWR (open
for reading and writing) and O_WRONLY (open for writing
only).
F_SETFL Set the file status flags for the open file descriptor
associated with fd from the corresponding bits in the
third argument, arg. Bits corresponding to the file
access modes and the oflag values that are set in arg
are ignored.
F_GETOWN Get the process ID or process group currently receiving
SIGIO and SIGURG signals; process groups are returned as
negative values.
F_SETOWN Set the process or process group to receive SIGIO and
SIGURG signals; process groups are specified by
supplying arg as negative, otherwise arg is interpreted
as a process ID.
The SIGIO facilities are enabled by setting the FASYNC flag with
F_SETFL.
The following commands are POSIX-specific:
F_GETLK Get a description of the first lock which would block
the lock specified in the flock structure pointed to by
arg. The information retrieved overwrites the
information in the flock structure. If no lock is found
that would prevent this lock from being created, then
the structure is passed back unchanged except for the
lock type which will be set to F_UNLCK.
F_SETLK Set or clear an advisory record lock according to the
flock structure pointed to by arg. F_SETLK is used to
establish shared (F_RDLCK) and exclusive (F_WRLCK)
locks, or to remove either type of lock (F_UNLCK). If
the specified lock cannot be applied, fcntl() will
return with an error value of -1.
F_SETLKW This cmd is the same as F_SETLK except that if a shared
or exclusive lock is blocked by other locks, the
requesting process will sleep until the lock may be
applied.
NOTES ON FILE-LOCKING FOR POSIX APPLICATIONS
Advisory locks allow cooperating processes to perform consistent
operations on files, but do not guarantee exclusive access (i.e.,
processes may still access files without using advisory locks, possibly
resulting in inconsistencies).
The record locking mechanism allows two types of locks: shared locks
(F_RDLCK) and exclusive locks (F_WRLCK). More than one process may
hold a shared lock for a particular segment of a file at any given
time, but multiple exclusive, or both shared and exclusive, locks may
not exist simultaneously on any segment.
In order to claim a shared lock, the descriptor must have been opened
with read access. The descriptor on which an exclusive lock is being
placed must have been opened with write access.
A shared lock may be upgraded to an exclusive lock, and vice versa,
simply by specifying the appropriate lock type with a cmd of F_SETLK or
F_SETLKW; the previous lock will be released and the new lock applied
(possibly after other processes have gained and released the lock).
If the cmd is F_SETLKW and the requested lock cannot be claimed
immediately (e.g., another process holds an exclusive lock that
partially or completely overlaps the current request) then the calling
process will block until the lock may be acquired. Processes blocked
awaiting a lock may be awakened by signals.
Care should be taken to avoid deadlock situations in applications in
which multiple processes perform blocking locks on a set of common
records.
The record that is to be locked or unlocked is described by the flock
structure, which is defined in <fcntl.h> as follows:
struct flock {
short l_type; /* F_RDLCK, F_WRLCK, or F_UNLCK */
short l_whence; /* flag to choose starting offset */
off_t l_start; /* relative offset, in bytes */
off_t l_len; /* length, in bytes; 0 means lock to EOF */
pid_t l_pid; /* returned with F_GETLK */
};
The flock structure describes the type (l_type), starting offset
(l_whence), relative offset (l_start), and size (l_len) of the segment
of the file to be affected. L_whence must be set to 0, 1, or 2 to
indicate that the relative offset will be measured from the start of
the file, current position, or end-of-file, respectively. The process
id field (l_pid) is only used with the F_GETLK cmd to return the
description of a lock held by another process.
Locks may start and extend beyond the current end-of-file, but may not
be negative relative to the beginning of the file. A lock may be set
to always extend to the end-of-file by setting l_len to zero (0). If
such a lock also has l_whence and l_start set to zero (0), the entire
file will be locked. Changing or unlocking a segment from the middle
of a larger locked segment leaves two smaller segments at either end.
Locking a segment that is already locked by the calling process causes
the old lock type to be removed and the new lock type to take affect.
All locks associated with a file for a given process are removed when
the file is closed or the process terminates. Locks are not inherited
by the child process in a fork(2) system call.
RETURN VALUE
Upon successful completion, the value returned depends on cmd as
follows:
F_DUPFD A new descriptor.
F_GETFD Value of flag (only the low-order bit is defined).
F_GETFL Value of flags.
F_GETOWN Value of descriptor owner.
other Value other than -1.
Otherwise, a value of -1 is returned and errno is set to indicate the
error.
ERRORS
The fcntl function will fail if one or more of the following are true:
[EAGAIN] cmd is F_SETLK, the lock type (l_type) is F_RDLCK
(shared lock), and the segment of the file to be locked
already has an exclusive lock held by another process.
This error will also be returned if the lock type is
F_WRLCK (exclusive lock) and another process already has
the segment locked with either a shared or exclusive
lock.
[EBADF] cmd is F_SETLK or F_SETLKW and the process does not have
the appropriate read or write permissions on the file.
[EBADF] fd is not a valid open descriptor.
[EFAULT] cmd is F_GETLK, F_SETLK, or F_SETLKW and arg points to
an invalid address.
[EINTR] cmd is F_SETLKW and a signal interrupted the process
while it was waiting for the lock to be granted.
[EINVAL] cmd is F_GETLK, F_SETLK, or F_SETLKW and the data arg
points to is not valid; or, either cmd is invalid, or
cmd is F_DUPFD and arg is negative or greater than the
maximum allowable number (OPEN_MAX for POSIX
applications, or the return value of getdtablesize(2)
for non-POSIX applications).
[EMFILE] cmd is F_DUPFD and the maximum allowed number of
descriptors are currently open.
[ENOLCK] cmd is F_SETLK or F_SETLKW and there are no more file
lock entries available.
SEE ALSOclose(2), execve(2), getdtablesize(2), open(2), sigvec(2)BUGS (POSIX-SPECIFIC)
File locks obtained through the fcntl mechanism do not interact in any
way with those acquired by using flock(2).
F_GETLK returns F_UNLCK if the requesting process holds the specified
lock. Thus, there is no way for a process to determine if it is still
holding a specific lock after catching a SIGLOST signal.
August 1, 1992 FCNTL(2)
