FCNTL(3P) POSIX Programmer's Manual FCNTL(3P)PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux
implementation of this interface may differ (consult the corresponding
Linux manual page for details of Linux behavior), or the interface may
not be implemented on Linux.
NAMEfcntl — file control
SYNOPSIS
#include <fcntl.h>
int fcntl(int fildes, int cmd, ...);
DESCRIPTION
The fcntl() function shall perform the operations described below on
open files. The fildes argument is a file descriptor.
The available values for cmd are defined in <fcntl.h> and are as fol‐
lows:
F_DUPFD Return a new file descriptor which shall be 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 shall refer to the same open file description
as the original file descriptor, and shall share any
locks. The FD_CLOEXEC flag associated with the new file
descriptor shall be cleared to keep the file open across
calls to one of the exec functions.
F_DUPFD_CLOEXEC
Like F_DUPFD, but the FD_CLOEXEC flag associated with the
new file descriptor shall be set.
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_SETFD Set the file descriptor flags defined in <fcntl.h>, that
are associated with fildes, to the third argument, arg,
taken as type int. If the FD_CLOEXEC flag in the third
argument is 0, the file descriptor shall remain open
across the exec functions; otherwise, the file descriptor
shall be closed upon successful execution of one of the
exec functions.
F_GETFL Get the file status flags and file access modes, defined
in <fcntl.h>, for the file description associated with
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
are associated with the file description and do not
affect other file descriptors that refer to the same file
with different open file descriptions. The flags returned
may include non-standard file status flags which the
application did not set, provided that these additional
flags do not alter the behavior of a conforming applica‐
tion.
F_SETFL Set the file status flags, defined in <fcntl.h>, for the
file description associated with fildes from the corre‐
sponding bits in the third argument, arg, taken as type
int. Bits corresponding to the file access mode and the
file creation flags, as defined in <fcntl.h>, that are
set in arg shall be ignored. If any bits in arg other
than those mentioned here are changed by the application,
the result is unspecified. If fildes does not support
non-blocking operations, it is unspecified whether the
O_NONBLOCK flag will be ignored.
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_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 indi‐
cate a process ID; negative values, other than −1, indi‐
cate a process group ID. If fildes does not refer to a
socket, the results are unspecified.
The following values for cmd are available for advisory record locking.
Record locking shall be supported for regular files, and may be sup‐
ported for other files.
F_GETLK Get the first lock which blocks the lock description
pointed to by the third argument, arg, taken as a pointer
to type struct flock, defined in <fcntl.h>. The informa‐
tion retrieved shall overwrite 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 shall be left unchanged except for the lock
type which shall be set to F_UNLCK.
F_SETLK Set or clear a file segment 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 can 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() shall return imme‐
diately with a return value of −1.
F_SETLKW This command shall be equivalent to F_SETLK except that
if a shared or exclusive lock is blocked by other locks,
the thread shall 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() shall be inter‐
rupted. Upon return from the signal handler, fcntl()
shall return −1 with errno set to [EINTR], and the lock
operation shall not be done.
Additional implementation-defined values for cmd may be defined in
<fcntl.h>. Their names shall start with F_.
When a shared lock is set on a segment of a file, other processes shall
be able to set shared locks on that segment or a portion of it. A
shared lock prevents any other process from setting an exclusive lock
on any portion of the protected area. A request for a shared lock shall
fail if the file descriptor was not opened with read access.
An exclusive lock shall prevent any other process from setting a shared
lock or an exclusive lock on any portion of the protected area. A
request for an exclusive lock shall fail if the file descriptor was not
opened with write access.
The structure flock describes the type (l_type), starting offset
(l_whence), relative offset (l_start), size (l_len), and process ID
(l_pid) of the segment of the file to be affected.
The value of l_whence is SEEK_SET, SEEK_CUR, or SEEK_END, to indicate
that the relative offset l_start bytes shall 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). The l_pid field is only used with F_GETLK
to return the process ID of the process holding a blocking lock. After
a successful F_GETLK request, when a blocking lock is found, the values
returned in the flock structure shall be as follows:
l_type Type of blocking lock found.
l_whence SEEK_SET.
l_start Start of the blocking lock.
l_len Length of the blocking lock.
l_pid Process ID of the process that holds the blocking lock.
If the command is F_SETLKW and the process must wait for another
process to release a lock, then the range of bytes to be locked shall
be determined before the fcntl() function blocks. If the file size or
file descriptor seek offset change while fcntl() is blocked, this shall
not affect the range of bytes locked.
If l_len is positive, the area affected shall start at l_start and end
at l_start+l_len−1. If l_len is negative, the area affected shall
start at l_start+l_len and end at l_start−1. Locks may start and
extend beyond the current end of a file, but shall not extend before
the beginning of the file. A lock shall 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 shall be locked.
There shall be at most one type of lock set for each byte in the file.
Before a successful return from an F_SETLK or an F_SETLKW request when
the calling process has previously existing locks on bytes in the
region specified by the request, the previous lock type for each byte
in the specified region shall be replaced by the new lock type. As
specified above under the descriptions of shared locks and exclusive
locks, an F_SETLK or an F_SETLKW request (respectively) shall fail or
block when another process has existing locks on bytes in the specified
region and the type of any of those locks conflicts with the type spec‐
ified in the request.
All locks associated with a file for a given process shall be removed
when a file descriptor for that file is closed by that process or the
process holding that file descriptor terminates. Locks are not inher‐
ited by a child process.
A potential for deadlock occurs if a process controlling a locked
region is put to sleep by attempting to lock the locked region of
another process. If the system detects that sleeping until a locked
region is unlocked would cause a deadlock, fcntl() shall fail with an
[EDEADLK] error.
An unlock (F_UNLCK) request 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, when the process has an existing lock in which
l_len is 0 and which includes the last byte of the requested segment,
shall be treated as a request to unlock from the start of the requested
segment with an l_len equal to 0. Otherwise, an unlock (F_UNLCK)
request shall attempt to unlock only the requested segment.
When the file descriptor fildes refers to a shared memory object, the
behavior of fcntl() shall be the same as for a regular file except the
effect of the following values for the argument cmd shall be unspeci‐
fied: F_SETFL, F_GETLK, F_SETLK, and F_SETLKW.
If fildes refers to a typed memory object, the result of the fcntl()
function is unspecified.
RETURN VALUE
Upon successful completion, the value returned shall depend on cmd as
follows:
F_DUPFD A new file descriptor.
F_DUPFD_CLOEXEC
A new file descriptor.
F_GETFD Value of flags defined in <fcntl.h>. The return value
shall not be negative.
F_SETFD Value other than −1.
F_GETFL Value of file status flags and access modes. The return
value is not negative.
F_SETFL Value other than −1.
F_GETLK Value other than −1.
F_SETLK Value other than −1.
F_SETLKW Value other than −1.
F_GETOWN Value of the socket owner process or process group; this
will not be −1.
F_SETOWN Value other than −1.
Otherwise, −1 shall be returned and errno set to indicate the error.
ERRORS
The fcntl() function shall fail if:
EACCES or EAGAIN
The cmd argument is F_SETLK; 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 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.
EBADF The fildes argument is not a valid open file descriptor, or the
argument cmd is F_SETLK or F_SETLKW, 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.
EINTR The cmd argument is F_SETLKW and the function was interrupted by
a signal.
EINVAL The cmd argument is invalid, or the cmd argument is F_DUPFD or
F_DUPFD_CLOEXEC and arg is negative or greater than or equal to
{OPEN_MAX}, or the cmd argument is F_GETLK, F_SETLK, or F_SETLKW
and the data pointed to by arg is not valid, or fildes refers to
a file that does not support locking.
EMFILE The argument cmd is F_DUPFD or F_DUPFD_CLOEXEC and all file
descriptors available to the process are currently open, or no
file descriptors greater than or equal to arg are available.
ENOLCK The argument cmd is F_SETLK or F_SETLKW and satisfying the lock
or unlock request would result in the number of locked regions
in the system exceeding a system-imposed limit.
EOVERFLOW
One of the values to be returned cannot be represented cor‐
rectly.
EOVERFLOW
The cmd argument is F_GETLK, F_SETLK, or F_SETLKW and the small‐
est 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 fcntl() function may fail if:
EDEADLK
The cmd argument is F_SETLKW, the lock is blocked by a lock from
another process, and putting the calling process to sleep to
wait for that lock to become free would cause a deadlock.
The following sections are informative.
EXAMPLES
Locking and Unlocking a File
The following example demonstrates how to place a lock on bytes 100 to
109 of a file and then later remove it. F_SETLK is used to perform a
non-blocking lock request so that the process does not have to wait if
an incompatible lock is held by another process; instead the process
can take some other action.
#include <stdlib.h>
#include <unistd.h>
#include <fcntl.h>
#include <errno.h>
#include <stdio.h>
int
main(int argc, char *argv[])
{
int fd;
struct flock fl;
fd = open("testfile", O_RDWR);
if (fd == -1)
/* Handle error */;
/* Make a non-blocking request to place a write lock
on bytes 100-109 of testfile */
fl.l_type = F_WRLCK;
fl.l_whence = SEEK_SET;
fl.l_start = 100;
fl.l_len = 10;
if (fcntl(fd, F_SETLK, &fl) == −1) {
if (errno == EACCES || errno == EAGAIN) {
printf("Already locked by another process\n");
/* We can't get the lock at the moment */
} else {
/* Handle unexpected error */;
}
} else { /* Lock was granted... */
/* Perform I/O on bytes 100 to 109 of file */
/* Unlock the locked bytes */
fl.l_type = F_UNLCK;
fl.l_whence = SEEK_SET;
fl.l_start = 100;
fl.l_len = 10;
if (fcntl(fd, F_SETLK, &fl) == −1)
/* Handle error */;
}
exit(EXIT_SUCCESS);
} /* main */
Setting the Close-on-Exec Flag
The following example demonstrates how to set the close-on-exec flag
for the file descriptor fd.
#include <unistd.h>
#include <fcntl.h>
...
int flags;
flags = fcntl(fd, F_GETFD);
if (flags == −1)
/* Handle error */;
flags |= FD_CLOEXEC;
if (fcntl(fd, F_SETFD, flags) == −1)
/* Handle error */;"
APPLICATION USAGE
The arg values to F_GETFD, F_SETFD, F_GETFL, and F_SETFL all represent
flag values to allow for future growth. Applications using these func‐
tions should do a read-modify-write operation on them, rather than
assuming that only the values defined by this volume of POSIX.1‐2008
are valid. It is a common error to forget this, particularly in the
case of F_SETFD. Some implementations set additional file status flags
to advise the application of default behavior, even though the applica‐
tion did not request these flags.
RATIONALE
The ellipsis in the SYNOPSIS is the syntax specified by the ISO C stan‐
dard for a variable number of arguments. It is used because System V
uses pointers for the implementation of file locking functions.
This volume of POSIX.1‐2008 permits concurrent read and write access to
file data using the fcntl() function; this is a change from the 1984
/usr/group standard and early proposals. Without concurrency controls,
this feature may not be fully utilized without occasional loss of data.
Data losses occur in several ways. One case occurs when several pro‐
cesses try to update the same record, without sequencing controls; sev‐
eral updates may occur in parallel and the last writer ``wins''.
Another case is a bit-tree or other internal list-based database that
is undergoing reorganization. Without exclusive use to the tree segment
by the updating process, other reading processes chance getting lost in
the database when the index blocks are split, condensed, inserted, or
deleted. While fcntl() is useful for many applications, it is not
intended to be overly general and does not handle the bit-tree example
well.
This facility is only required for regular files because it is not
appropriate for many devices such as terminals and network connections.
Since fcntl() works with ``any file descriptor associated with that
file, however it is obtained'', the file descriptor may have been
inherited through a fork() or exec operation and thus may affect a file
that another process also has open.
The use of the open file description to identify what to lock requires
extra calls and presents problems if several processes are sharing an
open file description, but there are too many implementations of the
existing mechanism for this volume of POSIX.1‐2008 to use different
specifications.
Another consequence of this model is that closing any file descriptor
for a given file (whether or not it is the same open file description
that created the lock) causes the locks on that file to be relinquished
for that process. Equivalently, any close for any file/process pair
relinquishes the locks owned on that file for that process. But note
that while an open file description may be shared through fork(), locks
are not inherited through fork(). Yet locks may be inherited through
one of the exec functions.
The identification of a machine in a network environment is outside the
scope of this volume of POSIX.1‐2008. Thus, an l_sysid member, such as
found in System V, is not included in the locking structure.
Changing of lock types can result in a previously locked region being
split into smaller regions.
Mandatory locking was a major feature of the 1984 /usr/group standard.
For advisory file record locking to be effective, all processes that
have access to a file must cooperate and use the advisory mechanism
before doing I/O on the file. Enforcement-mode record locking is impor‐
tant when it cannot be assumed that all processes are cooperating. For
example, if one user uses an editor to update a file at the same time
that a second user executes another process that updates the same file
and if only one of the two processes is using advisory locking, the
processes are not cooperating. Enforcement-mode record locking would
protect against accidental collisions.
Secondly, advisory record locking requires a process using locking to
bracket each I/O operation with lock (or test) and unlock operations.
With enforcement-mode file and record locking, a process can lock the
file once and unlock when all I/O operations have been completed.
Enforcement-mode record locking provides a base that can be enhanced;
for example, with sharable locks. That is, the mechanism could be
enhanced to allow a process to lock a file so other processes could
read it, but none of them could write it.
Mandatory locks were omitted for several reasons:
1. Mandatory lock setting was done by multiplexing the set-group-ID
bit in most implementations; this was confusing, at best.
2. The relationship to file truncation as supported in 4.2 BSD was not
well specified.
3. Any publicly readable file could be locked by anyone. Many histori‐
cal implementations keep the password database in a publicly read‐
able file. A malicious user could thus prohibit logins. Another
possibility would be to hold open a long-distance telephone line.
4. Some demand-paged historical implementations offer memory mapped
files, and enforcement cannot be done on that type of file.
Since sleeping on a region is interrupted with any signal, alarm() may
be used to provide a timeout facility in applications requiring it.
This is useful in deadlock detection. Since implementation of full
deadlock detection is not always feasible, the [EDEADLK] error was made
optional.
FUTURE DIRECTIONS
None.
SEE ALSOalarm(), close(), exec, open(), sigaction()
The Base Definitions volume of POSIX.1‐2008, <fcntl.h>, <signal.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
cal and Electronics Engineers, Inc and The Open Group. (This is
POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
event of any discrepancy between this version 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.unix.org/online.html .
Any typographical or formatting errors that appear in this page are
most likely to have been introduced during the conversion of the source
files to man page format. To report such errors, see https://www.ker‐
nel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group 2013 FCNTL(3P)
