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 remains open across exec;
otherwise the file is closed upon execution of
exec.
Set the close-on-exec flag associated with
fildes to the low-order bit of arg
(0 or 1 as above).
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 is 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 cmdF_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 sleeps 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, is 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_GETLKcmd 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 is 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 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
are affected by the record locks in effect.
The fcntl system call fails
if one or more of the following is true:
[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.
[EBADF]
The fildes argument is not a valid open file descriptor.
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.
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.
[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.
The cmd argument is F_GETLK,F_SETLK, or SETLKW
and arg or the data it points to is not valid.
[EMFILE]
The cmd argument is F_DUPFD and file-descriptors are
currently open in the calling-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.
[ENOLINK]
fildes is on a remote machine and the link
to that machine is no longer active.
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_GETFL
Value of file flags.
F_GETLK
Value other than -1.
F_SETFD
Value other than -1.
F_SETFL
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.