FCNTL(2) FCNTL(2)
NAME
fcntl - file control
SYNOPSIS
#include <fcntl.h>
int fcntl (fildes, cmd, arg)
int fildes, cmd, arg;
DESCRIPTION
fcntl provides for control over open files. Fildes is an
open file descriptor obtained from a creat, open, dup,
fcntl, or pipe system call.
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
descriptors 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, otherwise
the file will be closed upon execution of exec.
Page 1 May 1989
FCNTL(2) FCNTL(2)
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.
F_SETFL Set file status flags to arg. Only certain flags
can be set [see fcntl(5)].
F_GETLK Get the first lock which 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
variable 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
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 may exist
for a given segment of a file at a given time. The file
Page 2 May 1989
FCNTL(2) FCNTL(2)
descriptor on which a write lock is being placed must have
been opened with write access.
The structure flock describes the type (l_type), starting
offset (l_whence), relative offset (l_start), size (l_len),
process id (l_pid), and RFS system id (l_sysid) of the
segment of the file to be affected. The process id and
system id fields are 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 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)], read and write 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:
[EBADF] Fildes is not a valid open file descriptor.
[EINVAL] Cmd is F_DUPFD. arg 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 F_GETLK, F_SETLK, or SETLKW and arg or
the data it points to is not valid.
Page 3 May 1989
FCNTL(2) FCNTL(2)
[EACCES] Cmd 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] Cmd 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.
[EDEADLK] Cmd 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] Cmd is F_SETLK, arg points outside 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.
Page 4 May 1989
FCNTL(2) FCNTL(2)
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
programs should expect and test for either value.
Page 5 May 1989