fcntl
Purpose
Controls open file descriptors.
Syntax
#include <fcntl.h>
int fcntl (fildes, cmd, arg)
int fildes, cmd, arg;
Description
The fcntl system call performs controlling operations on
open file descriptors. If Distributed Services is
installed on your system, the open file can reside on
another node.
The fildes parameter is an open file descriptor obtained
from a creat, open, dup, fcntl, or pipe system call. The
arg parameter is a variable that depends on the value of
the cmd parameter.
The following cmds get a file descriptor or associated
flags or set those flags:
F_DUPFD Returns a new file descriptor as follows:
o Lowest numbered available file descriptor
greater than or equal to arg
o Same open file (or pipe) as the original
file
o Same file pointer as the original file
(that is, both file descriptors share one
file pointer)
o Same access mode (read, write or
read/write)
o Same locks
o Same file status flags (that is, 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 exec system calls.
F_GETFD Gets the close-on-exec flag associated with
the file descriptor fildes. If the low-order
bit is 0 (zero), then the file remains open
across exec system calls; otherwise the file
closes upon execution of an exec system call.
F_SETFD Sets the close-on-exec flag associated with
the fildes parameter to the value of the low-
order bit of arg (0 or 1 as for F_GETFD).
F_GETFL Gets the file status flags of the file
descriptor fildes.
F_SETFL Sets the file status flags to the value of
the arg parameter. Only the flags O_NDELAY
and O_APPEND should be set. Attempting to
set other flags may cause unexpected results.
When using the file locking and unlocking cmds (F_GETLK,
F_SETLK, and F_SETLKW), the arg parameter is a pointer to
a structure of type flock. The flock structure pointed
to by the arg parameter describes the lock and is defined
in the fcntl.h header file. It contains the following
members:
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 */
unsigned long l_sysid; /* node ID */
short l_pid; /* returned with F_GETLK */
l_type Describes the type of lock. Possible values
are F_RDLCK, F_WRLCK, and F_UNLCK.
l_whence Defines the starting point of the relative
offset, l_start. A value of 0 indicates the
start of the file, 1 selects the current posi-
tion, and 2 indicates the end of the file.
l_start Defines the relative offset in bytes, measured
from the starting point in l_whence.
l_len Specifies the number of consecutive bytes to
be locked.
l_sysid Contains the ID of the node that already has a
lock placed on the area defined by the fcntl
system call. This field is returned only when
the F_GETLK cmd is used.
l_pid Contains the ID of a process that already has
a lock placed on the area defined by the fcntl
system call. This field is returned only when
the F_GETLK cmd is used.
The following cmds use the flock structure and perform
operations associated with file locks:
F_GETLK Gets the first lock that blocks the lock
described in the flock structure pointed to
by arg. If a lock is found, the retrieved
information overwrites the information in
this structure. If no lock is found that
would prevent this lock from being created,
then the structure is passed back unchanged
except that the lock type is set to F_UNLCK.
F_SETLK Sets or clears a file lock according to the
flock structure pointed to by arg. F_SETLK
is used to establish read (F_RDLCK) and write
(F_WRLCK) locks, as well as to remove either
type of lock (F_UNLCK). F_RDLCK, F_WRLCK,
and F_UNLCK are defined by the fcntl.h header
file. If a read or write lock cannot be set,
fcntl returns immediately with an error value
of -1.
F_SETLKW Works like F_SETLK except that if a read or
write lock is blocked by existing locks, the
process sleeps until the section of the file
is free to be locked.
When a read lock has been set on a section of a file,
other processes may also set read locks on that section
or subsets of it. A read lock prevents any other process
from setting a write lock on any part of the protected
area. The file descriptor on which a read lock is being
placed must have been opened with read access.
A write lock prevents any other process from setting a
read lock or a write lock on any part of the protected
area. Only one write lock and no read locks may exist
for a specific section of a file at any time. The file
descriptor on which a write lock is being placed must
have been opened with write access.
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 extend to the end of
the file by setting l_len to 0. If such a lock also has
l_start and l_whence set to 0, the whole file will be
locked.
Some general rules about file locking include:
o Changing or unlocking part of a file in the middle of
a locked section leaves two smaller sections locked
at each end of the originally locked section.
o When the calling process holds a lock on a file, that
lock is replaced by later calls to fcntl.
o All locks associated with a file for a given process
are removed when a file descriptor for that file is
closed by the process or the process holding the file
descriptor ends.
o Locks are not inherited by a child process after exe-
cuting a fork system call.
Notes:
1. In addition to fcntl, the lockf system call can also
be used to set write (exclusive) locks.
2. Deadlocks due to file locks in a distributed system
are not always detected. When such deadlocks are
possible, the programs requesting the locks should
set timeout timers.
Return Value
Upon successful completion, the value returned depends on
the value of the cmd parameter as follows:
cmd Return Value
F_DUPFD A new file descriptor
F_GETFD The value of the flag (only the low-order bit
is defined)
F_GETLK A value other than -1
F_SETFD A value other than -1
F_GETFL The value of file flags
F_SETFL A value other than -1
F_SETLK A value other than -1
F_SETLKW A value other than -1.
If the fcntl system call fails, a value of -1 is returned
and errno is set to indicate the error.
Diagnostics
The fcntl system call fails if one or more of the fol-
lowing are true:
EBADF The fildes parameter is not a valid open
file descriptor.
EMFILE The cmd parameter is F_DUPFD and 200 file
descriptors are currently open.
EACCES The cmd parameter is F_SETLK, the l_type
parameter is F_RDLCK, and the segment of
the file to be locked is already write-
locked by another process.
EACCES The cmd parameter is F_SETLK, the l_type
parameter is F_WRLCK, and the segment of a
file to be locked is already read-locked or
write-locked by another process.
Note: Because in the future errno may be
set to EAGAIN rather than to EACCES for the
two errors described above, programs should
expect and test for both values.
EDEADLK The cmd parameter is F_SETLKW, the lock is
blocked by some lock from another process.
Putting the calling process to sleep while
waiting for that lock to become free would
cause a deadlock.
ENOLCK The cmd parameter is F_SETLK or F_SETLKW,
the type of lock is F_RDLCK or F_WRLCK, and
there are no more file locks available.
(Too many segments are already locked.)
EINVAL The cmd parameter is F_GETLK, F_SETLK, or
F_SETLKW and the arg parameter or the data
it points to is not valid.
EINVAL The cmd parameter is F_DUPFD and the arg
parameter is negative or greater than 199.
If Distributed Services is installed on your system,
fcntl can also fail if one or more of the following are
true:
EDIST The server has blocked new inbound
requests.
EDIST Outbound requests are currently blocked.
EAGAIN The server is too busy to accept the
request.
ENOMEM Either this node or the server does not
have enough memory available to service the
request.
EBADCONNECT An attempt to use an existing network con-
nection with a remote node failed.
Related Information
In this book: "close," "exec: execl, execv, execle,
execve, execlp, execvp," "lockf," "open," and "fcntl.h."