Performs controlling operations on an open file.
Format
#include <sys/types.h>
#include <unistd.h>
#include <fcntl.h>
int fcntl (int file_desc, int request [, int arg]);
int fcntl (int file_desc, int request [, struct flock *arg]);
1 – Arguments
file_desc
An open file descriptor obtained from a successful open, fcntl,
or pipe function.
request
The operation to be performed.
arg
A variable that depends on the value of the request argument.
For a request of F_DUPFD, F_SETFD, or F_SETFL, specify arg as an
int.
For a request of F_GETFD and F_GETFL, do not specify arg.
For a request of F_GETLK, F_SETLK, or F_SETLKW specify arg as a
pointer to a flock structure.
2 – Description
The fcntl function performs controlling operations on the open
file specified by the file_desc argument.
The values for the request argument are defined in the header
file <fcntl.h>, and include the following:
F_DUPFD Returns a new file descriptor that is the lowest
numbered available (that is, not already open)
file descriptor greater than or equal to the third
argument (arg) taken as an integer of type int.
The new file descriptor refers to the same file as
the original file descriptor (file_desc). The FD_
CLOEXEC flag associated with the new file descriptor
is cleared to keep the file open across calls to one
of the exec functions.
The following two calls are equivalent:
fid = dup(file_desc);
fid = fcntl(file_desc, F_DUPFD, 0);
Consider the following call:
fid = dup2(file_desc, arg);
It is similar (but not equivalent) to:
close(arg);
fid = fcntl(file_desc, F_DUPFD, arg);
F_GETFD Gets the value of the close-on-exec flag associated
with the file descriptor file_desc. File descriptor
flags are associated with a single file descriptor
and do not affect other file descriptors that refer
to the same file. The arg argument should not be
specified.
F_SETFD Sets the close-on-exec flag associated with file_
desc to the value of the third argument, taken as
type int.
If the third argument is 0, the file remains open
across the exec functions, which means that a child
process spawned by the exec function inherits this
file descriptor from the parent.
If the third argument is FD_CLOEXEC, the file is
closed on successful execution of the next exec
function, which means that the child process spawned
by the exec function will not inherit this file
descriptor from the parent.
F_GETFL Gets the file status flags and file access modes,
defined in <fcntl.h>, for the file description
associated with file_desc. The file access modes
can be extracted from the return value using the
mask O_ACCMODE, which is defined in <fcntl.h>. File
status flags and file access modes are associated
with the file description and do not affect other
file descriptors that refer to the same file with
different open file descriptions.
F_SETFL Sets the file status flags, defined in <fcntl.h>,
for the file description associated with file_desc
from the corresponding bits in the third argument,
arg, taken as type int. Bits corresponding to the
file access mode and the file creation flags,
as defined in <fcntl.h>, that are set in arg
are ignored. If any bits in arg other than those
mentioned here are changed by the application, the
result is unspecified.
Note: The only status bit recognized is O_APPEND.
Support for O_APPEND is not standard-compliant.
The X/Open standard states that "File status flags
and file access modes are associated with the file
description and do not affect other file descriptors
that refer to the same file with different open
file descriptions." However, because the append bit
is stored in the FCB, all file descriptors using
the same FCB are using the same append flag, so
that setting this flag with fcntl(F_SETFL) will
affect all files sharing the FCB; that is, all files
duplicated from the same file descriptor.
Record Locking Requests
F_GETLK Gets the first lock that blocks the lock description
pointed to by the arg parameter, taken as a pointer
to type struct flock. The information retrieved
overwrites the information passed to the fcntl
function in the flock structure. If no lock is found
that would prevent this lock from being created,
then the structure is left unchanged except for the
lock type, which is set to F_UNLCK.
F_SETLK Sets or clears a file segment lock according to
the lock description pointed to by arg, taken as
a pointer to type struct flock. F_SETLK is used to
establish shared locks (F_RDLCK), or exclusive locks
(F_WRLCK), as well as remove either type of lock (F_
UNLCK). If a shared (read) or exclusive (write)
lock cannot be set, the fcntl function returns
immediately with a value of -1.
An unlock (F_UNLCK) request in which the l_len of
the flock structure is nonzero and the offset of the
last byte of the requested segment is the maximum
value for an object of type off_t, when the process
has an existing lock in which l_len is 0 and which
includes the last byte of the requested segment,
is treated as a request to unlock from the start
of the requested segment with an l_len equal to 0.
Otherwise, an unlock (F_UNLCK) request attempts to
unlock only the requested file.
F_SETLKW Same as F_SETLK except that if a shared or exclusive
lock is blocked by other locks, the process will
wait until it is unblocked. If a signal is received
while fcntl is waiting for a region, the function
is interrupted, -1 is returned, and errno is set to
EINTR.
File Locking
The C RTL supports byte-range file locking using the F_GETLK,
F_SETLK, and F_SETLKW commands of the fcntl function, as defined
in the X/Open specification. Byte-range file locking is supported
across OpenVMS clusters. You can only use offsets that fit into
32-bit unsigned integers.
When a shared lock is set on a segment of a file, other processes
on the cluster are able to set shared locks on that segment or
a portion of it. A shared lock prevents any other process from
setting an exclusive lock on any portion of the protected area.
A request for a shared lock fails if the file descriptor was not
opened with read access.
An exclusive lock prevents any other process on the cluster from
setting a shared lock or an exclusive lock on any portion of the
protected area. A request for an exclusive lock fails if the file
descriptor was not opened with write access.
The flock structure describes the type (l_type), starting offset
(l_whence), relative offset (l_start), size (l_len) and process
ID (l_pid) of the segment of the file to be affected.
The value of l_whence is set to SEEK_SET, SEEK_CUR or SEEK_END,
to indicate that the relative offset l_start bytes is measured
from the start of the file, from the current position, or from
the end of the file, respectively. The value of l_len is the
number of consecutive bytes to be locked. The l_len value may be
negative (where the definition of off_t permits negative values
of l_len). The l_pid field is only used with F_GETLK to return
the process ID of the process holding a blocking lock. After a
successful F_GETLK request, the value of l_whence becomes SEEK_
SET.
If l_len is positive, the area affected starts at l_start and
ends at l_start + l_len - 1. If l_len is negative, the area
affected starts at l_start + l_len and ends at l_start - 1. Locks
may start and extend beyond the current end of a file, but may
not be negative relative to the beginning of the file. If l_len
is set to 0 (zero), a lock may be set to always extend to the
largest possible value of the file offset for that file. If such
a lock also has l_start set to 0 (zero) and l_whence is set to
SEEK_SET, the whole file is locked.
Changing or unlocking a portion from the middle of a larger
locked segment leaves a smaller segment 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
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.
If the request argument is F_SETLKW, the lock is blocked by
some lock from another process, and putting the calling process
to sleep to wait for that lock to become free would cause a
deadlock, then the application will hang.
3 – Return Values
n Upon successful completion, the value returned
depends on the value of the request argument
as follows:
o F_DUPFD - Returns a new file descriptor.
o F_GETFD - Returns FD_CLOEXEC or 0.
o F_SETFD, F_GETLK, F_SETLK, F_UNLCK - Return
a value other than -1.
-1 Indicates that an error occurred. The function
sets errno to one of the following values:
o EACCES - The request argument is F_SETLK;
the type of lock (l_type) is a shared (F_
RDLCK) or exclusive (F_WRLCK) lock, and the
segment of a file to be locked is already
exclusive-locked by another process; or
the type is an exclusive (F_WRLCK) lock and
the some portion of the segment of a file
to be locked is already shared-locked or
exclusive-locked by another process.
o EBADF - The file_desc argument is not a
valid open file descriptor and the arg
argument is negative or greater than or
equal to the per-process limit.
The request parameter is F_SETLK or F_
SETLKW, the type of lock (l_type) is a
shared lock (F_RDLCK), and file_desc is not
a valid file descriptor open for reading.
The type of lock (l_type) is an exclusive
lock (F_WRLCK), and file_desc is not a
valid file descriptor open for writing.
o EFAULT - The arg argument is an invalid
address.
o EINVAL - The request argument is F_DUPFD
and arg is negative or greater than or
equal to OPEN_MAX.
Either the OPEN_MAX value or the per-
process soft descriptor limit is checked.
An illegal value was provided for the
request argument.
The request argument is F_GETLK, F_SETLK,
or F_SETLKW and the data pointed to by arg
is invalid, or file_desc refers to a file
that does not support locking.
o EMFILE - The request argument is F_DUPFD
and too many or OPEN_MAX file descriptors
are currently open in the calling process,
or no file descriptors greater than or
equal to arg are available.
Either the OPEN_MAX value or the per-
process soft descriptor limit is checked.
o EOVERFLOW - One of the values to be
returned cannot be represented correctly.
The request argument is F_GETLK, F_SETLK,
or F_SETLKW and the smallest or, if l_
len is nonzero, the largest offset of any
byte in the requested segment cannot be
represented correctly in an object of type
off_t.
o EINTR - The request argument is F_SETLKW,
and the function was interrupted by a
signal.
o ENOLCK - The request argument is F_SETLK or
F_SETLKW, and satisfying the lock or unlock
request would exceed the configurable
system limit of NLOCK_RECORD.
o ENOMEM - The system was unable to allocate
memory for the requested file descriptor.