fcntl(2) UNIX System V 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 following
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 original 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] associated 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.
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).
10/89 Page 1
fcntl(2) UNIX System V fcntl(2)
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 contains 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 establish 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 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
process ID and the system ID of the process holding the
lock.
This command never creates a lock; it tests whether a
particular lock could be created.
Page 2 10/89
fcntl(2) UNIX System V fcntl(2)
FRSETLK Used by the network lock daemon, lockd(3N), to communicate
with the NFS server kernel to handle locks on NFS files.
FRSETLKW Used by the network lock daemon, lockd(3N), to communicate
with the NFS server kernel to handle locks on NFS files.
FRGETLK Used by the network lock daemon, lockd(3N), to communicate
with the NFS server kernel to handle locks on NFS files.
A read lock prevents any process from write locking the protected 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. 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) system 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 outstanding record locks on
the file.
10/89 Page 3
fcntl(2) UNIX System V fcntl(2)
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 reading.
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 writing.
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.
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 descriptors 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.
Page 4 10/89
fcntl(2) UNIX System V fcntl(2)
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 process 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).
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 negative.
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.
10/89 Page 5