FCNTL(2) INTERACTIVE UNIX System FCNTL(2)
NAME
fcntl - file control
SYNOPSIS
#include <fcntl.h>
int fcntl (fildes, cmd, arg)
int fildes, cmd;
DESCRIPTION
The fcntl system call provides for control over open files.
The fildes argument is an open file descriptor obtained from
a creat, open, dup, fcntl, or pipe system call. The data
type and value of arg are specific to the type of command
specified by cmd. The symbolic names for commands and file
status flags are defined by the <fcntl.h> header file.
The commands available are:
F_DUPFD Return a new file descriptor as follows:
Lowest numbered available file descriptor greater
than or equal to arg.
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).
Same file status flags (i.e., both file descrip-
tors share the same file status flags).
The close-on-exec flag associated with the new
file descriptor is set to remain open across
exec(2) system calls.
F_GETFD Get the close-on-exec flag associated with the
file descriptor fildes. If the low-order bit is
0, the file will remain open across exec; other-
wise the file will be closed upon execution of
exec.
F_SETFD Set the close-on-exec flag associated with fildes
to the low-order bit of arg (0 or 1 as above).
F_GETFL Get file status flags [see open(2)].
F_SETFL Set file status flags to arg. Only certain flags
can be set [see fcntl(5)].
The following commands are used for file-locking and
Rev. C Software Development Set Page 1
FCNTL(2) INTERACTIVE UNIX System FCNTL(2)
record-locking. Locks may be placed on an entire file or
segments of a file.
F_GETLK
Get the first lock that blocks the lock description
given by the variable of type struct flock pointed to
by arg. The information retrieved overwrites the
information passed to fcntl 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 a file segment lock according to the vari-
able of type struct flock pointed to by arg [see
fcntl(5)]. The cmd F_SETLK is used to establish read
(F_RDLCK) and write (F_WRLCK) locks, as well as remove
either type of lock (F_UNLCK). If a read or write lock
cannot be set, fcntl will return immediately with an
error value of -1.
F_SETLKW
This cmd is the same as F_SETLK except that if a read
or write lock is blocked by other locks, the process
will sleep until the segment is free to be locked.
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 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 structure flock defined in the <fcntl.h> header file
describes a lock. It describes the type (l_type), starting
offset (l_whence), relative offset (l_start), size (l_len),
and process-ID (l_pid):
short l_type; /* F_RDLCK, F_WRLCK, F_UNLCK */
short l_whence; /* flag for starting offset */
long l_start; /* relative offset in bytes */
long l_len; /* if 0 then until EOF */
short l_pid; /* returned with F_GETLK */
The value of l_whence is 0, 1, or 2 to indicate that the
relative offset, l_start bytes, will be measured from the
start of the file, current position, or end of file,
Rev. C Software Development Set Page 2
FCNTL(2) INTERACTIVE UNIX System FCNTL(2)
respectively. The value of l_len is the number of consecu-
tive bytes to be locked. The process id is used only with
the F_GETLK 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 l_len to zero (0). If such a lock also has
l_whence and l_start set to zero (0), the whole file will be
locked. Changing or unlocking a segment from the middle of
a larger locked segment leaves two smaller segments for
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 descrip-
tor 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)], read and write system calls issued on the
file will be affected by the record locks in effect.
The fcntl system call will fail if one or more of the fol-
lowing is true:
[EBADF] The fildes argument is not a valid open file
descriptor.
[EINVAL] The cmd argument is F_DUPFD. The arg argu-
ment is either negative, or greater than or
equal to the configured value for the maximum
number of open file descriptors allowed each
user.
[EINVAL] The cmd argument is F_GETLK, F_SETLK, or
SETLKW and arg or the data it points to is
not valid.
[EACCES] The cmd argument is F_SETLK, the type of lock
(l_type) is a read (F_RDLCK) lock, and the
segment of a file to be locked is already
write locked by another process or the type
is a write (F_WRLCK) lock and the segment of
a file to be locked is already read or write
locked by another process.
[ENOLCK] The cmd argument is F_SETLK or F_SETLKW, 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.
Rev. C Software Development Set Page 3
FCNTL(2) INTERACTIVE UNIX System FCNTL(2)
[EMFILE] The cmd argument is F_DUPFD and file-
descriptors are currently open in the
calling-process.
[EBADF] The cmd argument is F_SETLK or F_SETLKW, the
type of lock (l_type) is a read-lock
(F_RDLCK), and fildes is not a valid file-
descriptor open for reading.
[EBADF] The cmd argument is F_SETLK or F_SETLKW, the
type of lock (l_type) is a write-lock
(F_WRLCK), and fildes is not a valid file-
descriptor open for writing.
[EDEADLK] The cmd argument is F_SETLKW, the lock is
blocked by some lock from another process,
and putting the calling-process to sleep,
waiting for that lock to become free, would
cause a deadlock.
[EFAULT] The cmd argument is F_SETLK, arg points out-
side the program address space.
[EINTR] A signal was caught during the fcntl system
call.
[ENOLINK] Fildes is on a remote machine and the link to
that machine is no longer active.
SEE ALSO
close(2), creat(2), dup(2), exec(2), fork(2), open(2),
pipe(2), fcntl(5).
DIAGNOSTICS
Upon successful completion, the value returned depends on
cmd as follows:
F_DUPFD A new file descriptor.
F_GETFD Value of flag (only the low-order bit is
defined).
F_SETFD Value other than -1.
F_GETFL Value of file flags.
F_SETFL Value other than -1.
F_GETLK Value other than -1.
F_SETLK Value other than -1.
F_SETLKW Value other than -1.
Otherwise, a value of -1 is returned, and errno is set to
indicate the error.
WARNINGS
Because 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, portable application pro-
grams should expect and test for either value.
Rev. C Software Development Set Page 4