fcntl(2)fcntl(2)Namefcntl - file control
Syntax
#include <fcntl.h>
res = fcntl (fd, request, arg)
int res;
int fd, request, arg
Arguments
The following arguments can be used with
fd Descriptor to be operated on. Depending on the function
selected by the request argument, the fd argument can be a
file descriptor returned by an system call, or a socket
descriptor returned by a system call.
request Defines what you want done. The possible values are defined
in See the Description section for more information.
arg Varies according to the request argument. See the Descrip‐
tion section for more information.
Description
The system call provides for control over descriptors. The descriptors
can be either file descriptors returned by the system call or socket
descriptors returned by the system call.
Possible request arguments are the following:
F_DUPFD - Return New Descriptor
The shell provides an example of when a new descriptor is useful. Sup‐
pose the shell receives a command such as:
cat > myfile
The shell needs to redirect the output of the command from the file
descriptor 1 (standard output) to a new file named The shell issues the
call, using the old file descriptor of 1, to obtain a new file descrip‐
tor for the file
F_DUPFD When request is set for F_DUPFD:
The call returns a new descriptor. The new file descrip‐
tor returned has the following characteristics:
· The file descriptor returned is the lowest numbered
available descriptor that is greater than or equal to
the argument arg.
· The descriptor has the same object references as the
original descriptor. That is, if the original file
descriptor referred to a file, the new file descriptor
refers to a file. If the original descriptor referred
to a socket, the new file descriptor refers to a
socket.
· The new descriptor shares the same file pointer if the
object was a file. (A file pointer points to an inode,
which in turn points to a file. Thus, the new descrip‐
tor refers to the same file as the old descriptor.)
· The new descriptor has the same access mode as the old
descriptor (read, write, or read/write).
· The new descriptor shares the same file status flags as
the old file descriptor. (See the discussion of
F_GETFL and F_SETFL for a description of file status
flags.)
· The close-on-exec flag associated with the new file
descriptor is set to remain open across system calls.
(See the discussion of F_GETFD and F_SETFD for a
description of the close-on-exec flag.)
F_GETFD and F_SETFD - Close-on-exec Flag
Each file descriptor points to an entry in an array of file pointers
that, among other things, define certain characteristics for the file.
One such characteristic is the close-on-exec flag. This flag defines
whether or not a file remains open across calls to If cleared, the file
descriptor remains open in the new image loaded by the call to If set,
the file descriptor is closed in the new image loaded by the call to
F_GETFD When request is set to F_GETFD:
The call returns the close-on-exec flag associated with
the file descriptor fd. If the low-order bit of the value
returned by is 0, the file remains open across calls to If
the low-order bit of the value returned by is 1, the file
descriptor is closed across calls to
F_SETFD When request is set to F_SETFD:
The call sets the close-on-exec flag associated with fd to
the low-order bit of arg (0 or 1).
F_GETFL and F_SETFL - Descriptor Status Flags
Each file descriptor points to an entry in an array of file pointers
that, among other things, define the file's current status. One such
item of status, for example, is whether or not input/output operations
to a file are currently blocked.
You might want to program your process to allow blocking so that a user
who runs your process in the background, while doing other work in the
foreground, need not see output from the background job displayed on
the screen.
These and other status indicators are discussed in the list that fol‐
lows. Some status indicators do not apply to all types of descriptors.
The O_APPEND status, for example, is meaningless for sockets.
F_GETFL When request is set to F_GETFL:
The call returns the file's descriptor status flags. The
following names have been defined in for these status
flags:
O_NDELAY Nonblocking I/O. If no data is available to
a call, or if a write operation would block,
the call returns -1 with the error [EWOULD‐
BLOCK]. The flag FNDELAY is an obsolete syn‐
onym for O_NDELAY.
O_FSYNC (O_SYNC) Synchronous write flag. Forces sub‐
sequent file writes to be done synchronously.
For further information, see The flag OFSYN‐
CRON is an obsolete synonym for FSYNCRON.
O_APPEND Force each write to append at the end of
file. This corresponds to the action taken
with the O_APPEND flag of The flag FAPPEND is
an obsolete synonym for O_APPEND.
FASYNC Enable the SIGIO signal to be sent to the
process group when I/O is possible. For
example, send SIGIO when data is available to
be read.
O_NONBLOCK POSIX environment, nonblocking I/O flag. See
O_NDELAY request for description of opera‐
tion. The flag FNBLOCK is an obsolete syn‐
onym for O_NONBLOCK.
F_SETFL When request is set to F_SETFL:
The call sets descriptor status flags specified in arg
(see F_GETFL). Refer to the F_SETOWN section for more
information.
F_GETOWN and F_SETOWN - Get Or Set Owner
With these requests, your process can recognize the software interrupts
SIGIO or SIGURG. As described in SIGIO is a signal indicating that I/O
is possible on a descriptor. SIGURG indicates an urgent condition
present on a socket.
F_GETOWN When request is set to F_GETOWN:
The call returns the process ID or process group currently
receiving SIGIO and SIGURG signals. Process groups are
returned as negative values.
F_SETOWN When request is set to F_SETOWN:
The call sets 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. See also the F_SETFL request, which sets
descriptor status flags, and the description of the FASYNC
flag in the F_GETFL section.
F_GETLK, F_SETLK, and F_SETLKW - Locking File Regions
With these requests, your process can:
· Test a file for a region that might have been read-locked or write-
locked by another process.
· Set or clear a file region read or write lock.
· Set a file region read or write lock, sleeping, if necessary, until
locks previously set by other processes are unlocked.
When a read lock has been set on a segment of a file, other processes
can also set read locks on that file segment or portions thereof.
A read lock prevents any other process from write locking the protected
area. More than one read lock can exist for a given region 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 other process from read locking or write
locking the protected region. Only one write lock can exist for a
given region 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.
Locks can start and extend beyond the current end of a file, but cannot
be negative relative to the beginning of the file.
Changing or unlocking a region from the middle of a larger locked
region leaves two smaller regions with the old setting at either end.
Locking a region that is already locked by the calling process causes
the old lock 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 in a system call.
F_GETLK When request is set to F_GETLK:
The call gets the lock information for a read or write
locked region. In the call, you pass a lock description
in a variable of type struct flock pointed to by arg.
If the region defined in the flock structure is already
locked by a process other than the caller, a description
of the existing lock is returned 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 is set to F_UNLCK.
The flock structure is defined as follows:
struct flock {
short l_type;
short l_whence;
long l_start;
long l_len;
int l_pid;
};
Data Passed in flock:
In the data you pass in flock, the l_type value defines
the lock type to be tested for: F_RDLCK for a read lock
and F_WRLCK for a write lock.
The l_whence value defines the point from which the start‐
ing byte of the region is to be measured. If l_whence is
0, the value in l_start is taken as the starting byte of
the region. If l_whence is 1, the current file offset
plus the value of l_start is taken as the starting point.
If l_whence is 2, the file size plus the value of l_start
is taken as the starting point.
The l_len value is the length of the region to be tested,
in bytes. If l_len is zero, the length to be tested
extends to the end of file. If l_len is zero and l_start
is zero, the whole file is to be tested. If l_len is neg‐
ative, the area affected starts at l_start + l_len and
ends at l_start - 1.
The l_pid value has no significance in the data passed.
Data Returned in flock:
The l_type value can be F_RDLCK if the region passed is
under a read lock. F_WRLCK means that the region passed
is under a write lock. F_UNLCK means that the region is
not currently locked by any process that would prevent
this lock from being created; for example, the region
might be locked by the caller.
The l_whence, l_start, and l_len values have similar mean‐
ings as discussed under Data Passed, except that they
define the region currently under read or write lock.
The l_pid value is only used with F_GETLK to return the
value for a blocking lock. An example of a blocking lock
is a write lock currently set by a process other than the
calling process.
F_SETLK When request is set to F_SETLK:
You set or clear a file region lock according to the vari‐
able of l_type in the struct flock pointed to by arg.
(The flock structure is shown under the description of
F_GETLK, preceding.)
The l_type value 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,
will return immediately with an error value of -1.
F_SETLKW When request is set to F_SETLKW:
The call takes the same action as for F_SETLK, except that
if a read or write lock is blocked by other locks, the
process sleeps until the segment is free to be locked.
Files and region locking are supported over the Network File System
(NFS) services if you have enabled the NFS locking service.
Return Values
Upon successful completion, the value returned depends upon the request
argument as follows:
F_DUPFDA new file descriptor.
F_GETFDValue of flag (only the low-order bit is defined).
F_GETFLValue of flags.
F_GETOWNValue of file descriptor owner.
otherValue other than -1.
Otherwise, a value of -1 is returned and errno is set to indicate the
error.
Diagnostics
The fails if under the following conditions:
[EBADF] The fildes argument is not a valid open file descriptor.
[EBADF] The environment defined is POSIX, the request argument
is F_SETLK or F_SETLKW, the type of lock, l_type, is a
shared lock (F_RDLCK), and fildes is not a valid file
descriptor open for reading, or the type of lock,
l_type, is an exclusive lock (F_WRLCK), and fildes is
not a valid file descriptor open for writing.
[EFAULT] The arg is pointing to an address outside the process's
allocated space.
[EINVAL] The request argument is F_DUPFD, and arg is negative or
greater than the maximum allowable number. For further
information, see
[EINVAL] The request argument is F_SETSYN, to change the write
mode of a file to synchronous, and this operation is not
valid for the file descriptor. For example, the file
was opened for read-only operations.
[EINVAL] The request argument is F_GETLK,F_SETLK, or SETLKW and
the data arg points to is not valid.
[EINVAL] The request argument is invalid.
[EINVAL] The fildes argument refers to a file that does not sup‐
port locking.
[EACCES] The request argument is F_SETLK, the type of lock (
l_type ) is a read (F_RDLCK) or write (F_WRLCK) lock,
and the region of the file to be locked is already write
locked by another process. Or, the type is a write lock
and the region of the file to be locked is already read
or write locked by another process. Or, the file is
remotely mounted and the NFS locking service is not
enabled.
[EMFILE] The request argument is F_DUPFD, and the maximum allowed
number of file descriptors is currently open, or no file
descriptors greater than or equal to arg are available.
[ENOSPC] The request argument is F_SETLK or F_SETLKW, 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] The request argument is F_SETLKW, and the lock is
blocked by some lock from another process that is sleep‐
ing (waiting) for that lock to become free. This detec‐
tion avoids a deadlock situation.
[EOPNOTSUPP] Attempting an operation that is not valid for the file
descriptor. This can occur if the file descriptor argu‐
ment, fd, points to a socket address, and the request
argument is only valid for files.
[EINTR] The request argument is F_SETLKW and the function was
interrupted by a signal.
Environment
The description differs from the POSIX and XPG3 definitions in that
ENOLCK is not a possible error condition.
See Alsoclose(2), execve(2), getdtablesize(2), open(2), sigvec(2), lockd(8c)fcntl(2)
