fcntl(2) SYSTEM CALLS fcntl(2)
NAME
fcntl - file control
SYNOPSIS
#include <sys/types.h>
#include <fcntl.h>
#include <unistd.h>
int fcntl (int fildes, int cmd, ... /* arg */);
DESCRIPTION
fcntl provides for control over open files. fildes is an
open file descriptor [see intro(2)].
fcntl may take a third argument, arg, whose data type, value
and use depend upon the value of cmd. cmd specifies the
operation to be performed by fcntl and may be one of the
following:
FDUPFD Return a new file descriptor with the follow-
ing characteristics:
Lowest numbered available file descriptor
greater than or equal to the integer value
given as the third argument.
Same open file (or pipe) as the original
file.
Same file pointer as the original file
(i.e., both file descriptors share one
file pointer).
Same access mode (read, write, or
read/write) as the original file.
Shares any locks associated with the ori-
ginal file descriptor.
Same file status flags (i.e., both file
descriptors share the same file status
flags) as the original file.
The close-on-exec flag [see FGETFD] asso-
ciated with the new file descriptor is set
to remain open across exec(2) system
calls.
FGETFD Get the close-on-exec flag associated with
fildes. If the low-order bit is 0, the file
will remain open across exec. Otherwise, the
file will be closed upon execution of exec.
1
fcntl(2) SYSTEM CALLS fcntl(2)
FSETFD Set the close-on-exec flag associated with
fildes to the low-order bit of the integer
value given as the third argument (0 or 1 as
above).
FGETFL Get fildes status flags.
FSETFL Set fildes status flags to the integer value
given as the third argument. Only certain
flags can be set [see fcntl(5)].
FFREESP 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 the third argument arg.
The data type struct flock is defined in the
<fcntl.h> header file [see fcntl(5)] and con-
tains the following members: lwhence is 0,
1, or 2 to indicate that the relative offset
lstart will be measured from the start of the
file, the current position, or the end of the
file, respectively. lstart is the offset
from the position specified in lwhence.
llen is the size of the section. An llen of
0 frees up to the end of the file; in this
case, the end of file (i.e., file size) is set
to the beginning of the section freed. Any
data previously written into this section is
no longer accessible. The following commands
are used for record-locking. Locks may be
placed on an entire file or on segments of a
file.
FSETLK Set or clear a file segment lock according to
the flock structure that arg points to [see
fcntl(5)]. The cmd FSETLK is used to estab-
lish read (FRDLCK) and write (FWRLCK) locks,
as well as remove either type of lock
(FUNLCK). If a read or write lock cannot be
set, fcntl will return immediately with an
error value of -1.
FSETLKW This cmd is the same as FSETLK except that if
a read or write lock is blocked by other
locks, fcntl will block until the segment is
free to be locked.
FGETLK If the lock request described by the flock
structure that arg points to could be created,
then the structure is passed back unchanged
except that the lock type is set to FUNLCK
and the lwhence field will be set to
2
fcntl(2) SYSTEM CALLS fcntl(2)
SEEKSET.
If a lock is found that would prevent this
lock from being created, then the structure is
overwritten with a description of the first
lock that is preventing such a lock from being
created. The structure also contains the pro-
cess ID and the system ID of the process hold-
ing the lock.
This command never creates a lock; it tests
whether a particular lock could be created.
FRSETLK Used by the network lock daemon, lockd(3N), to
communicate with the NFS server kernel to han-
dle locks on NFS files.
FRSETLKW Used by the network lock daemon, lockd(3N), to
communicate with the NFS server kernel to han-
dle locks on NFS files.
FRGETLK Used by the network lock daemon, lockd(3N), to
communicate with the NFS server kernel to han-
dle locks on NFS files.
A read lock prevents any process from write locking the pro-
tected area. More than one read lock may exist for a given
segment of a file at a given time. The file descriptor on
which a read lock is being placed must have been opened with
read access.
A write lock prevents any process from read locking or write
locking the protected area. Only one write lock and no read
locks may exist for a given segment of a file at a given
time. The file descriptor on which a write lock is being
placed must have been opened with write access.
The flock structure describes the type (ltype), starting
offset (lwhence), relative offset (lstart), size (llen),
process ID (lpid), and system ID (lsysid) of the segment
of the file to be affected. The process ID and system ID
fields are used only with the FGETLK cmd to return the
values for a blocking lock. Locks may start and extend
beyond the current end of a 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 llen to 0. If
such a lock also has lwhence and lstart set to 0, the
whole 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 effect.
3
fcntl(2) SYSTEM CALLS fcntl(2)
All locks associated with a file for a given process are
removed when a file descriptor for that file is closed by
that process or the process holding that file descriptor
terminates. Locks are not inherited by a child process in a
fork(2) system call.
When mandatory file and record locking is active on a file
[see chmod(2)], creat(2), open(2), read(2) and write(2) sys-
tem calls issued on the file will be affected by the record
locks in effect.
fcntl will fail if one or more of the following are true:
EACCES cmd is FSETLK, the type of lock (ltype) is a
read lock (FRDLCK) and the segment of a file
to be locked is already write locked by
another process, or the type is a write lock
(FWRLCK) and the segment of a file to be
locked is already read or write locked by
another process.
EAGAIN cmd is FFREESP, the file exists, mandatory
file/record locking is set, and there are out-
standing record locks on the file.
EAGAIN cmd is FSETLK or FSETLKW and the file is
currently being mapped to virtual memory via
mmap [see mmap(2)].
EBADF fildes is not a valid open file descriptor.
EBADF cmd is FSETLK or FSETLKW, the type of lock
(ltype) is a read lock (FRDLCK), and fildes
is not a valid file descriptor open for read-
ing.
EBADF cmd is FSETLK or FSETLKW, the type of lock
(ltype) is a write lock (FWRLCK), and fildes
is not a valid file descriptor open for writ-
ing.
EBADF cmd is FFREESP, and fildes is not a valid
file descriptor open for writing.
EDEADLK cmd is FSETLKW, the lock is blocked by some
lock from another process, and if fcntl
blocked the calling process waiting for that
lock to become free, a deadlock would occur.
EDEADLK cmd is FFREESP, mandatory record locking is
enabled, ONDELAY and ONONBLOCK are clear and
a deadlock condition was detected.
4
fcntl(2) SYSTEM CALLS fcntl(2)
EFAULT cmd is FFREESP and the value pointed to by
the third argument arg resulted in an address
outside the process's allocated address space.
EFAULT cmd is FGETLK, FSETLK or FSETLKW and the
value pointed to by the third argument
resulted in an address outside the program
address space.
EINTR A signal was caught during execution of the
fcntl system call.
EIO An I/O error occurred while reading from or
writing to the file system.
EMFILE cmd is FDUPFD and the number of file descrip-
tors currently open in the calling process is
the configured value for the maximum number of
open file descriptors allowed each user.
EINVAL cmd is FDUPFD and the third argument is
either negative, or greater than or equal to
the configured value for the maximum number of
open file descriptors allowed each user.
EINVAL cmd is not a valid value.
EINVAL cmd is FGETLK, FSETLK, or FSETLKW and the
third argument or the data it points to is not
valid, or fildes refers to a file that does
not support locking.
ENOLCK cmd is FSETLK or FSETLKW, the type of lock
is a read or write lock, and there are no more
record locks available (too many file segments
locked) because the system maximum has been
exceeded.
ENOLINK fildes is on a remote machine and the link to
that machine is no longer active.
ENOLINK cmd is FFREESP, the file is on a remote
machine, and the link to that machine is no
longer active.
EOVERFLOW cmd is FGETLK and the process ID of the pro-
cess holding the requested lock is too large
to be stored in the l_pid field.
SEE ALSO
close(2), creat(2), dup(2), exec(2), fork(2), open(2),
pipe(2), fcntl(5).
5
fcntl(2) SYSTEM CALLS fcntl(2)
The "File and Record Locking" chapter in the Application
Programmer's Guide.
DIAGNOSTICS
On success, fcntl returns a value that depends on cmd:
FDUPFD A new file descriptor.
FGETFD Value of flag (only the low-order bit is
defined). The return value will not be nega-
tive.
FSETFD Value other than -1.
FFREESP Value of 0.
FGETFL Value of file status flags. The return value
will not be negative.
FSETFL Value other than -1.
FGETLK Value other than -1.
FSETLK Value other than -1.
FSETLKW Value other than -1.
On failure, fcntl returns -1 and sets errno to indicate the
error.
NOTES
In the future, the variable errno will be set to EAGAIN
rather than EACCES when a section of a file is already
locked by another process. Therefore, portable application
programs should expect and test for either value.
6