FCNTL(S) UNIX System V FCNTL(S)
Name
fcntl - file control
Syntax
#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 (that is,
both file descriptors share one file pointer).
Same access mode (read, write, or read/write).
Same file status flags (that is, 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(S) 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.
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(S)).
F_SETFL Set file status flags to arg. Only certain flags
can be set (see fcntl(M)).
The following commands are used for file-locking and
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
variable of type struct flock pointed to by arg (see
fcntl(M)), the cmd F_SETLK is used to establish read
(F_RDLCK) and write (F_WRLCK) locks. It also is used
to remove either type of lock (F_UNLCK). If a read or
write lock cannot be set, fcntl returns 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 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,
respectively. The value of l_len is the number of
consecutive 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
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(S) system call.
When mandatory file and record locking is active on a file
(see chmod(S)), 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
following is true:
[EBADF] The fildes argument is not a valid open file
descriptor.
[EINVAL] The cmd argument is F_DUPFD. The arg
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] 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.
[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
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(S), creat(S), dup(S), exec(S), fork(S), open(S),
pipe(S), fcntl(M)
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
programs should expect and test for either value.
Standards Conformance
fcntl is conformant with:
AT&T SVID Issue 2, Select Code 307-127;
The X/Open Portability Guide II of January 1987;
IEEE POSIX Std 1003.1-1988 with C Standard Language-
Dependent System Support;
and NIST FIPS 151-1.
(printed 6/20/89)