FCNTL(2-BSD) RISC/os Reference Manual FCNTL(2-BSD)
NAME
fcntl - file control
SYNOPSIS
#include <fcntl.h>
res = fcntl(fd, cmd, arg)
int res;
int fd, cmd, arg;
DESCRIPTION
fcntl performs a variety of functions on open descriptors.
The argument fd is an open descriptor to be operated on by
cmd as follows:
F_DUPFD Return a new descriptor as follows:
Lowest numbered available descriptor greater
than or equal to arg.
References the same object as the original
descriptor.
New descriptor shares the same file pointer
if the object was a file.
Same access mode (read, write or read/write).
Same file status flags (i.e., both descrip-
tors share the same file status flags).
The close-on-exec flag associated with the
new descriptor is set to remain open across
execve(2) system calls.
F_GETFD Get the close-on-exec flag associated with
the descriptor fd. If the low-order bit is
0, the file will remain open across exec,
otherwise the file will be closed upon execu-
tion of exec.
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, see
/usr/include/fcntl.h for their definitions.
F_SETFL Set descriptor status flags, see
/usr/include/fcntl.h for their definitions.
F_GETLK Get a description of the first lock which
Printed 11/19/92 Page 1
FCNTL(2-BSD) RISC/os Reference Manual FCNTL(2-BSD)
would block the lock specified in the flock
structure pointed to by arg. The information
retrieved overwrites the information 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 record lock according to the
flock structure pointed to by arg. F_SETLK
is used to establish shared (F_RDLCK) and
exclusive (F_WRLCK) locks, or to remove
either type of lock (F_UNLCK). If the speci-
fied lock cannot be applied, fcntl will
return with an error value of -1.
F_SETLKW This cmd is the same as F_SETLK except that
if a shared or exclusive lock is blocked by
other locks, the requesting process will
sleep until the lock may be applied.
F_GETOWN Get the process ID or process group currently
receiving SIGIO and SIGURG signals; process
groups are returned as negative values.
F_SETOWN Set the process or process group to receive
SIGIO and SIGURG signals; process groups are
specified by supplying arg as negative, oth-
erwise arg is interpreted as a process ID.
The SIGIO facilities are enabled by setting the FASYNC flag
with F_SETFL.
NOTES
The record locking mechanism allows two types of locks:
shared locks (F_RDLCK) and exclusive locks (F_WRLCK). More
than one process may hold a shared lock for a particular
segment of a file at any given time, but multiple exclusive,
or both shared and exclusive, locks may not exist simultane-
ously on any segment.
In order to claim a shared lock, the descriptor must have
been opened with read access. The descriptor on which an
exclusive lock is being placed must have been opened with
write access.
A shared lock may be upgraded to an exclusive lock, and vice
versa, simply by specifying the appropriate lock type with a
cmd of F_SETLK or F_SETLKW; the previous lock will be
released and the new lock applied (possibly after other
processes have gained and released the lock).
Page 2 Printed 11/19/92
FCNTL(2-BSD) RISC/os Reference Manual FCNTL(2-BSD)
If the cmd is F_SETLKW and the requested lock cannot be
claimed immediately (e.g., another process holds an
exclusive lock that partially or completely overlaps the
current request) then the calling process will block until
the lock may be acquired. Processes blocked awaiting a lock
may be awakened by signals.
Care should be taken to avoid deadlock situations in appli-
cations in which multiple processes perform blocking locks
on a set of common records.
The record that is to be locked or unlocked is described by
the flock structure, which is defined in <fcntl.h> as fol-
lows:
struct flock {
short l_type; /* F_RDLCK, F_WRLCK, or F_UNLCK */
short l_whence; /* flag to choose starting offset */
long l_start; /* relative offset, in bytes */
long l_len; /* length, in bytes; 0 means lock to EOF */
short l_pid; /* returned with F_GETLK */
};
The flock structure describes the type (l_type), starting
offset (l_whence), relative offset (l_start), and size
(l_len) of the segment of the file to be affected. L_whence
must be set to 0, 1, or 2 to indicate that the relative
offset will be measured from the start of the file, current
position, or end-of-file, respectively. The process id
field (l_pid) is only used with the F_GETLK cmd to return
the description of a lock held by another process.
Locks may start and extend beyond the current end-of-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 entire file will
be locked. Changing or unlocking a segment from the middle
of a larger locked segment leaves two smaller segments at
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 the file is
closed or the process terminates. Locks are not inherited
by the child process in a fork(2) system call.
In order to maintain consistency in the network case, data
must not be cached on client machines. For this reason,
file buffering for an NFS file is turned off when the first
lock is attempted on the file. Buffering will remain off as
long as the file is open. Programs that do I/O buffering in
the user address space, however, may have inconsistent
Printed 11/19/92 Page 3
FCNTL(2-BSD) RISC/os Reference Manual FCNTL(2-BSD)
results (the standard I/O package, for instance, is a common
source of unexpected buffering).
The record locking capabilities of fcntl are implemented
throughout the network by the network lock daemon; see
lockd(1M). If the file server crashes and is rebooted, the
lock daemon will attempt to recover all locks that were
associated with that server. If a lock cannot be reclaimed,
the process that held the lock will be issued a SIGLOST sig-
nal.
RETURN VALUE
Upon successful completion, the value returned depends on
cmd as follows:
F_DUPFD A new descriptor.
F_GETFD Value of flag (only the low-order bit is defined).
F_GETFL Value of flags.
F_GETOWN Value of descriptor owner.
other Value other than -1.
Otherwise, a value of -1 is returned and errno is set to
indicate the error.
ERRORS
fcntl will fail if one or more of the following are true:
EBADF fd is not a valid open descriptor.
EMFILE cmd is F_DUPFD and the maximum allowed number
of descriptors are currently open.
EINVAL cmd is F_DUPFD and arg is negative or greater
than the maximum allowable number (see
getdtablesize(2)).
EFAULT cmd is F_GETLK, F_SETLK, or F_SETLKW and arg
points to an invalid address.
EINVAL cmd is F_GETLK, F_SETLK, or F_SETLKW and the
data arg points to is not valid.
EBADF cmd is F_SETLK or F_SETLKW and the process
does not have the appropriate read or write
permissions on the file.
EAGAIN cmd is F_SETLK, the lock type (l_type) is
F_RDLCK (shared lock), and the segment of the
file to be locked already has an exclusive
lock held by another process. This error
will also be returned if the lock type is
F_WRLCK (exclusive lock) and another process
already has the segment locked with either a
Page 4 Printed 11/19/92
FCNTL(2-BSD) RISC/os Reference Manual FCNTL(2-BSD)
shared or exclusive lock.
EINTR cmd is F_SETLKW and a signal interrupted the
process while it was waiting for the lock to
be granted.
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.
ENOLCK cmd is F_SETLK or F_SETLKW and there are no
more file lock entries available.
SEE ALSO
close(2), execve(2), getdtablesize(2), open(2), sigvec(2),
lockf(3).
lockd(1M) in the System Administrator's Reference Manual.
CAVEATS
File locks obtained through the fcntl mechanism interact
with those acquired via lockf(3). File locks obtained
through the flock(2) are separate from the other two mechan-
isms.
F_GETLK returns F_UNLCK if the requesting process holds the
specified lock. Thus, there is no way for a process to
determine if it is still holding a specific lock after
catching a SIGLOST signal.
In a network environment, the value of l_pid returned by
F_GETLK is next to useless.
Printed 11/19/92 Page 5