FCNTL(2) BSD Programmer's Manual FCNTL(2)
NAME
fcntl - file control
SYNOPSIS
#include <sys/fcntl.h>
int
fcntl(int fd, int cmd, int arg)
DESCRIPTION
Fcntl() provides for control over descriptors. The argument fd is a de-
scriptor to be operated on by cmd as follows:
F_DUPFD Return a new descriptor as follows:
o Lowest numbered available descriptor greater than or
equal to arg.
o Same object references as the original descriptor.
o New descriptor shares the same file offset if the ob-
ject was a file.
o Same access mode (read, write or read/write).
o Same file status flags (i.e., both file descriptors
share the same file status flags).
o The close-on-exec flag associated with the new file
descriptor is set to remain open across execv(2) sys-
tem calls.
F_GETFD Get the close-on-exec flag associated with the file descriptor
fd. If the low-order bit of the returned value is 0, the file
will remain open across exec(), otherwise the file will be
closed upon execution of exec() (arg is ignored).
F_SETFD Set the close-on-exec flag associated with fd to the low order
bit of arg (0 or 1 as above).
F_GETFL Get descriptor status flags, as described below (arg is ig-
nored).
F_SETFL Set descriptor status flags to arg.
F_GETOWN Get the process ID or process group currently receiving SIGIO
and SIGURG signals; process groups are returned as negative
values (arg is ignored).
F_SETOWN Set the process or process group to receive SIGIO and SIGURG
signals; process groups are specified by supplying arg as neg-
ative, otherwise arg is interpreted as a process ID.
F_GETLK Get advisory file record lock information about the file to
which fd refers. The arg parameter is used as a pointer to an
flock structure (see below for the structure and operation).
F_SETLK Set or clear an advisory file record lock on the file to which
fd refers. The arg parameter is used as a pointer to an flock
structure (see below for the structure and operation). If a
lock cannot be acquired immediately, the function returns im-
mediately.
F_SETLKW Set or clear an advisory file record lock on the file to which
fd refers. The arg parameter is used as a pointer to an flock
structure (see below for the structure and operation). The
function waits if necessary to acquire a lock.
The flags for the F_GETFL and F_SETFL flags are as follows:
O_NONBLOCK
Non-blocking I/O; if no data is available to a read call, or
if a write operation would block, the read or write call re-
turns -1 with the error EAGAIN (also known as EWOULDBLOCK).
was previously known as O_NDELAY or FNDELAY.
O_APPEND Force each write to append at the end of file; corresponds to
the O_APPEND flag of open(2).
O_ASYNC Enable the SIGIO signal to be sent to the process group when
I/O is possible, e.g., upon availability of data to be read.
The advisory record locking functions operate on regions of a file de-
scribed by a range of offsets within the file. These advisory locks have
no effect on I/O operations, but only on the lock operations themselves;
thus, they are ``advisory'', and are effective only among processes that
use this facility. An advisory file lock covers a contiguous range of
offsets in the file, and is set as either a read lock or a write lock.
Any number of read locks may include a region of a file as long as there
is no write lock within the region; a write lock must be the only lock
for the affected range. Locks may start or extend past the end of the
file, but may not begin before the start of the file. Advisory record
locks are associated with a process, not with the descriptor; if a de-
scriptor is shared across processes (for example, after a fork), only one
process owns the lock. If that process closes any descriptor open on the
same file, all locks owned by the process are released.
The advisory file locks described in flock(2) operate in a fashion simi-
lar to advisory record locks that span all possible offsets of the file,
and thus either type of lock may block the other type. However, unlike
record locks, file locks are associated with the descriptor and not with
the process.
Advisory record locks are described and manipulated using an flock struc-
ture as defined in <sys/fcntl.h>:
struct flock {
short l_type; /* lock type: read/write, etc. */
short l_whence; /* type of l_start */
off_t l_start; /* starting offset */
off_t l_len; /* len = 0 means until end of file */
pid_t l_pid; /* lock owner */
};
The value of ltype must be one of the following before each call:
F_RDLCK The lock to be set or tested is to be a read (shared) lock.
F_WRLCK The lock to be set or tested is to be a write (exclusive)
lock.
F_UNLCK The lock is to be cleared.
The starting offset of a region is described by lwhence and lstart in
the style of lseek(2); lwhence must be one of SEEK_SET, SEEK_CUR or
SEEK_END, meaning that the offset is relative to the beginning of the
file, the current offset of the descriptor, or the end of the file, re-
spectively. The field llen is the length of the region, in bytes; a
length of 0 denotes a region extending to the largest possible size of
the file. The contents of the structure before a call define a region of
the file and a lock type.
For the F_GETLK operation, if a lock of the specified type is blocked by
one or more locks, the type and range of one of those locks is returned
in the flock structure, and the lpid field is set to the process ID of
the lock's owner. If the lock could have been granted, the ltype field
is set to F_UNLCK. The lwhence field is always set to SEEK_SET after a
successful call with a cmd of F_GETLK.
The F_SETLK and F_SETLKW commands request a lock as described by an flock
structure. If the ltype field is F_UNLCK, any locks owned by the caller
in the specified region are released. Otherwise, an attempt is made to
acquire the requested lock. If the caller holds a lock on any part of
the specified range before a call requesting a different lock type, the
previous lock is changed to the new type if the call is successful. If a
lock cannot be acquired without blocking, the operation fails immediately
if the command is F_SETLK, and may block if the command is F_SETLKW. The
system may determine that waiting for a lock could result in deadlock;
for example, if the requested lock is blocked by a lock owned by a pro-
cess that in turn is awaiting another lock held by the caller, deadlock
would result if neither attempt timed out. If a deadlock situation is
detected, the call fails immediately.
RETURN VALUES
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 flags.
F_GETOWN Value of file descriptor owner.
other Value other than -1.
Otherwise, a value of -1 is returned and errno is set to indicate the er-
ror.
ERRORS
Fcntl() will fail if:
[EBADF] Fildes is not a valid open file descriptor.
[EMFILE] Cmd is F_DUPFD and the maximum allowed number of file de-
scriptors are currently open.
[EINVAL] Cmd is not one of the values listed here.
[EINVAL] Cmd is F_DUPFD and arg is negative or greater than the max-
imum allowable number (see intro(2)).
[ESRCH] Cmd is F_SETOWN and the process ID given as argument is not
in use.
[EAGAIN] Cmd is F_SETLK, and the requested lock was blocked by an
existing lock owned by another process.
[EBADF] Cmd is one of F_GETLK, F_SETLK, or F_SETLKW, and fildes
refers to a socket rather than to a file.
[EBADF] Cmd is either F_SETLK or F_SETLKW, and either a read lock
was requested on a file that is not open for reading, or a
write lock was requested on a file that is not open for
writing.
[EDEADLK] Cmd is F_SETLKW, and awaiting the requested lock could re-
sult in a deadlock.
[EINVAL] Cmd is one of F_GETLK, F_SETLK, or F_SETLKW, and the param-
eters in the flock structure referenced by arg do not have
the values described above.
[EFAULT] Cmd is one of F_GETLK, F_SETLK, or F_SETLKW, and the flock
structure referenced by arg could not be read or written.
[EINTR] Cmd is F_SETLKW, the operation blocked awaiting a lock, and
the operation was interrupted by receipt of a signal.
SEE ALSO
close(2), execve(2), flock(2), intro(2), lseek(2), open(2), sigac-
tion(2)
BUGS
The asynchronous I/O facilities of O_NONBLOCK and FASYNC are currently
available only for tty and socket operations.
The advisory record locking facility is currently available only for lo-
cal files.
STANDARDS
The fcntl function call is specified by IEEE Std1003.1-1990 (``POSIX'').
BSDI BSD/386 March 26, 1993 4