fcntl(2) 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.
8/91 Page 1
fcntl(2) 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
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
Page 2 8/91
fcntl(2) fcntl(2)
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.
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.
8/91 Page 3
fcntl(2) fcntl(2)
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.
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.
Page 4 8/91
fcntl(2) fcntl(2)
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.
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 Programmer's Guide:
System Services and Application Packaging Tools.
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.
8/91 Page 5
fcntl(2) fcntl(2)
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.
Page 6 8/91