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 cmds available are:
FDUPFD 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.
FGETFD 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.
FSETFD Set the close-on-exec flag associated with
fildes to the low-order bit of arg (0 or 1 as
above).
FGETFL Get file status flags.
FSETFL Set file status flags to arg. Only certain
flags can be set; see fcntl(5).
Page 1 (last mod. 1/14/87)
fcntl(2) fcntl(2)
FGETLK 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
FUNLCK.
FSETLK Set or clear a file segment lock according to
the variable of type struct flock pointed to
by arg (see fcntl(5)). The cmd FSETLK 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.
FSETLKW This cmd is the same as FSETLK 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.
FGETOWN Get the process ID or process group currently
receiving SIGIO and SIGURG signals; process
groups are returned as negative values.
FSETOWN Set the process or process group to receive
SIGIO and SIGURG signals; process groups are
specified by supplying arg as negative,
otherwise arg is interpreted as a process ID.
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 describes the type (ltype), starting
offset (lwhence), relative offset (lstart), size (llen),
and process id (lpid) of the segment of the file to be
affected. The process ID field is only used with the
FGETLK cmd to return the value for a block in lock. Locks
may start and extend beyond the current end of a file, but
Page 2 (last mod. 1/14/87)
fcntl(2) fcntl(2)
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 llen to zero (0). If such a lock also has lstart
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 affect. 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.
fcntl will fail if one or more of the following are true:
[EBADF] fildes is not a valid open file descriptor.
[EMFILE] cmd is FDUPFD and 20 file descriptors are
currently open.
[EINFILE] cmd is FDUPFD and arg is negative or greater
than 20.
[EINVAL] cmd is FGETLK, FSETLK, or SETLKW and arg or
the data it points to is not valid.
[EACCESS] cmd is FSETLK the type of lock (ltype) is a
read (FRDLCK) or write (FWRLCK) lock and
the segment of a file to be locked is already
write locked by another process or the type
is a write lock and the segment of a file to
be locked is already read or write locked by
another process.
[EMFILE] cmd is FSETLK or FSETLKW, the type of lock
is a read or write lock and there are no more
file locking headers available (too many
files have segments locked).
[ENOSPC] cmd is FSETLK or FSETLKW, the type of lock
is a read or write lock and there are no more
file locking headers available (too many
files have segments locked) or there are no
more record locks available (too many file
segments locked).
[EDEADLK] cmd is FSETLK, when the lock is blocked by
some lock from another process and sleeping
(waiting) for that lock to become free, this
causes a deadlock situation.
Page 3 (last mod. 1/14/87)
fcntl(2) fcntl(2)
[ENOTSOCK] cmd is FGETOWN or FSETOWN and fildes is not
a file descriptor for a socket.
[EREMOTE] cmd is FGETLK FSETLK or FSETLKW and fildes
references a file on a remotely mounted file
system.
RETURN VALUE
Upon successful completion, the value returned depends on
cmd as follows:
FDUPFD A new file descriptor.
FGETFD Value of flag (only the low-order bit is
defined).
FSETFD Value other than -1.
FGETFL Value of file flags.
FSETFL Value other than -1.
FGETLK Value other that -1.
FSETLK Value other than -1.
FSETLKW Value other than -1.
FGETOWN Value other than -1.
FSETOWN Value other than -1.
Otherwise, a value of -1 is returned and errno is set to
indicate the error.
SEE ALSO
close(2), exec(2), open(2), fcntl(5).
Page 4 (last mod. 1/14/87)