FCNTL(2) SysV FCNTL(2)
NAME
fcntl - file control
SYNOPSIS
#include <sys/types.h> #include <unistd.h> #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.
arg is an arg to one of the following cmds:
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(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.
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 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.
After a successful F_GETLK cmd, the value of l_whence will be
SEEK_SET.
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 can 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 can 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 describes the type (l_type), starting offset
(l_whence), relative offset (l_start), size (l_len), process id (l_pid),
and 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 they cannot 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 0. If such a lock also has l_whence and l_start
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
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.
DIAGNOSTICS
fcntl returns a value that depends on cmd:
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, the call returns -1 and sets errno to indicate the error.
ERRORS
fcntl will fail if one or more of the following are true:
[EBADF] The fildes parameter is not a valid open file descriptor.
[EBADF] The cmd parameter is F_SETLK or F_SETLKW, the type of lock
(l_type) is a shared lock (F_RDLCK), and fildes is not a valid
file descriptor open for reading.
[EBADF] The type of lock (l_type) is an exclusive lock (F_WRLCK), and
fildes is not a valid file descriptor open for writing.
[EMFILE] The cmd parameter is F_DUPFD and OPEN_MAX file descriptors are
currently open in the calling process, or no file descriptors
greater than or equal to arg are available.
[EINVAL] The cmd parameter is F_DUPFD and the arg parameter is negative
or greater than or equal to OPEN_MAX.
[EINVAL] The cmd parameter is F_GETLK, F_SETLK, or F_SETLKW and the data
pointed to by arg is invalid, or fildes refers to a file that
does not support locking.
[EFAULT] The arg parameter is an invalid address.
[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. fcntl also
fails if:
[EINVAL] An illegal value was provided for the cmd parameter.
SEE ALSO
close(2), creat(2), dup(2), exec(2), fork(2), open(2), pipe(2), fcntl(5).
WARNINGS
In the future, errno will be set to EAGAIN rather than EACCES when a
section of a file is already locked by another process. Applications
that expect to be portable should test for either value.
NOTES
Under other implementations, fcntl fails if the following is true:
[ENOLINK] fildes is on a remote machine and the link to that machine is
no longer active.
BUGS
Record locking works only on the workstation local to the call.