fcntl(2) fcntl(2)
NAME
fcntl - control an open file
SYNOPSIS
#include <sys/types.h>
#include <fcntl.h>
#include <unistd.h>
int fcntl(int fildes, int cmd, ... /* arg */);
DESCRIPTION
fcntl() provides for control over open files. fildes is a file
descriptor of an open file.
fcntl() may take a third argument, arg, whose data type, value and use
depend upon the value of cmd. cmd specifies the operation to be per-
formed by fcntl() and may be one of the following:
FDUPFD Returns a new file descriptor with the following charac-
teristics:
- Lowest numbered available file descriptor greater than
or equal to the integer value given as the third argu-
ment.
- 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) as the
original file.
- Shares any locks associated with the original file
descriptor.
- The close-on-exec flag (see FGETFD) associated with
the new file descriptor is set to remain open across
exec(2) system calls.
FFREESP Frees storage space associated with a section of the ordi-
nary file fildes. The section is specified by a variable
of data type struct flock pointed to by the third argument
arg. The data type struct flock is defined in the fcntl.h
header file [see fcntl(5)] and contains the following
members: lwhence is 0, 1, or 2 to indicate that the rela-
tive offset lstart will be measured from the start of the
file, the current position, or the end of the file,
respectively. lstart is the offset from the position
specified in lwhence. llen is the size of the section.
An llen of 0 frees up to the end of the file; in this
case, the end of file (i.e., file size) is set to the
Page 1 Reliant UNIX 5.44 Printed 11/98
fcntl(2) fcntl(2)
beginning of the section freed. Any data previously writ-
ten into this section is no longer accessible.
FGETFD Gets the close-on-exec flag associated with file descrip-
tor 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 Sets the close-on-exec flag associated with fildes to the
low-order bit of the integer value given as the third
argument (0 or 1 as above).
FGETFL Gets the fildes status flag.
Page 2 Reliant UNIX 5.44 Printed 11/98
fcntl(2) fcntl(2)
FSETFL Sets the fildes status flag to the integer value given as
the third argument. Only certain flags can be set [see
fcntl(5)].
The following commands are used for record-locking. Locks may be
placed on an entire file or on segments of a file.
FSETLK Set or clear a file segment lock according to the flock
structure that arg points to [see fcntl(5)]. The cmd
FSETLK is used to establish read (FRDLCK) and write
(FWRLCK) locks, as well as remove either type of lock
(FUNLCK). 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, fcntl() will block
until the segment is free to be locked.
FGETLK If the lock request described by the flock structure that
arg points to could be created, then the structure is
passed back unchanged except that the lock type is set to
FUNLCK and the lwhence field will be set to SEEKSET. If
a lock is found that would prevent this lock from being
created, then the structure is overwritten with a descrip-
tion of the first lock that is preventing such a lock from
being created. The structure also contains the process ID
and the system ID of the process holding the lock.
This command never creates a lock; it tests whether a par-
ticular lock could be created.
FRSETLK Used by the network lock daemon, lockd, to lock NFS files
using the NFS server kernel.
FRSETLKW Used by the network lock daemon, lockd, to lock NFS files
using the NFS server kernel.
FRGETLK Used by the network lock daemon, lockd, to lock NFS files
using the NFS server kernel.
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 and no read locks 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.
Page 3 Reliant UNIX 5.44 Printed 11/98
fcntl(2) fcntl(2)
The flock structure describes the type (ltype), starting offset
(lwhence), relative offset (lstart), size (llen), process ID
(lpid), and system ID (lsysid) of the segment of the file to be
affected.
The value of lwhence is SEEKSET, SEEKCUR or SEEKEND, to indicate
that the relative offset lstart bytes will be measured from the start
of the file, current position or end of the file, respectively. The
value of llen is the number of consecutive bytes to be locked. The
value of llen may be negative (where the definition of offt permits
negative values of llen). The lpid field is only used with FGETLK
to return the process ID of the process holding a blocking lock. After
a successful FGETLK request, that is, one in which a lock was found,
the value of lwhence will be SEEKSET.
If llen is positive, the area affected starts at lstart and ends at
lstart + llen-1. If llen is negative, the area affected starts at
lstart + llen and ends at lstart-1. Locks may start and extend
beyond the current end of a file, but must not be negative relative to
the beginning of the file. A lock will be set to extend to the largest
possible value of the file offset for that file by setting llen to 0.
If such a lock also has lstart set to 0 and lwhence is set to
SEEKSET, the whole file will be locked.
There will be at most one type of lock set for each byte in the file.
Before a successful return from an FSETLK or an FSETLKW request when
the calling process has previously existing locks on bytes in the
region specified by the request, the previous lock type for each byte
in the specified region will be replaced by the new lock type. As
specified above under the descriptions of shared locks an exclusive
locks, an FSETLK or an FSETLKW request will (respectively) fail or
block when another process has existing locks on bytes in the speci-
fied region and the type of any of those locks conflicts with the type
specified in the request.
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 pro-
cess holding that file descriptor terminates. Locks are not inherited
by a child process created using the fork() function.
A potential for deadlock occurs if a process controlling a locked
region is put to sleep by attempting to lock another process' locked
region. If the system detects that sleeping until a locked region is
unlocked would cause a deadlock, the fcntl() function will fail with
an EDEADLK error.
When mandatory file and record locking is active on a file [see
chmod(2)], open(2), read(2) and write(2) system calls issued on the
file will be affected by the record locks in effect.
Page 4 Reliant UNIX 5.44 Printed 11/98
fcntl(2) fcntl(2)
An unlock (FUNLCK) request in which llen is non-zero and the offset
of the last byte of the requested segment is the maximum value for an
object of type offt, when the process has an existing lock in which
llen is 0 and which includes the last byte of the requested segment,
will be treated as a request to unlock from the start of the requested
segment with an llen equal to 0. Otherwise an unlock (FUNLCK)
request will attempt to unlock only the requested segment.
The following additional value may be used in constructing oflag:
OLARGEFILE
If set, the offset maximum in the open file description will be
the largest value that can be represented correctly in an object
of type off64t.
The OLARGEFILE flag may be set or cleared with FSETFL. An incor-
rectly written program may inadvertently clear this flag. For example,
some programs put a file into append mode with:
fcntl(fd, FSETFL, OAPPEND);
This is incorrect because it turns off all the other open flags,
including OLARGEFILE. Instead, to turn on append mode one should
first use FGETFL to get the current flags:
int oflag = fcntl(fd, FGETFL, 0);
then include OAPPEND in the flags:
oflag |= OAPPEND;
and then set the new flags:
fcntl(fd, FSETFL, oflag);
A more complete example would also check for fcntl() failures.
The behavior of the following additional values is equivalent to the
corresponding Single UNIX Specification (SUS) value (FGETLK, FSETLK,
FSETLKW), but they take a struct flock64 argument rather than a struct
flock argument.
FGETLK64
FSETLK64
FSETLKW64
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
fcntl() will fail if one or more of the following apply:
Page 5 Reliant UNIX 5.44 Printed 11/98
fcntl(2) fcntl(2)
EACCES cmd is FSETLK, the type of lock (ltype) is a read lock
(FRDLCK) and the segment of a file to be locked is
already write locked by another process.
EACCES The type is a write lock (FWRLCK) and the segment of a
file to be locked is already read or write locked by
another process.
EAGAIN cmd is FFREESP, the file exists, mandatory file/record
locking is set, and there are outstanding record locks on
the file.
EAGAIN cmd is FSETLK or FSETLKW and the file is currently being
mapped to virtual memory via mmap [see mmap(2)].
EBADF fildes is not a valid open file descriptor.
EBADF cmd is FSETLK or FSETLKW, the type of lock (ltype) is a
read lock (FRDLCK), and fildes is not a valid file
descriptor open for reading.
EBADF cmd is FSETLK or FSETLKW, the type of lock (ltype) is a
write lock (FWRLCK), and fildes is not a valid file
descriptor open for writing.
EBADF cmd is FFREESP, and fildes is not a valid file descriptor
open for writing.
EDEADLK cmd is FSETLKW, the lock is blocked by some lock from
another process, and if fcntl() blocked the calling pro-
cess waiting for that lock to become free, a deadlock
would occur.
EDEADLK cmd is FFREESP, mandatory record locking is enabled,
ONDELAY and ONONBLOCK are clear and a deadlock condition
was detected.
EFAULT cmd is FFREESP and the value pointed to by the third
argument arg resulted in an address outside the process'
allocated address space.
EFAULT cmd is FGETLK, FSETLK or FSETLKW and the value pointed
to by the arg argument resulted in an address outside the
program address space.
EINTR A signal was caught during execution of the fcntl() system
call.
EIO An I/O error occurred while reading from or writing to the
file system.
Page 6 Reliant UNIX 5.44 Printed 11/98
fcntl(2) fcntl(2)
EMFILE cmd is FDUPFD and the number of file descriptors
currently open in the calling process is the configured
value for the maximum number of open file descriptors
allowed each user.
EINVAL cmd is FDUPFD, and arg is either negative, or greater
than or equal to the configured value for the maximum
number of open file descriptors allowed each user.
EINVAL cmd is not a valid value.
EINVAL cmd is FGETLK, FSETLK, or FSETLKW and either arg or the
data it points to is not valid, or fildes refers to a file
that does not support locking.
ENOLCK cmd is FSETLK or FSETLKW, the type of lock is a read or
write lock, and there are no more record locks available
(too many file segments locked) because the system maximum
has been exceeded.
ENOLINK fildes is on a remote machine and the link to that machine
is no longer active.
ENOLINK cmd is FFREESP, the file is on a remote machine, and the
link to that machine is no longer active.
EOVERFLOW One of the values to be returned cannot be represented
correctly.
EOVERFLOW The cmd argument is FGETLK, FSETLK or FSETLKW and the
smallest or, if llen is non-zero, the largest, offset of
any byte in the requested segment cannot be represented
correctly in an object of type offt.
RESULT
On successful completion, fcntl() returns a value that depends on cmd,
as follows:
FDUPFD A new file descriptor.
FGETFD Value of "close-on-exec" status flag (only the low-order
bit is defined).
FSETFD Value other than -1.
FFREESP Value of 0.
FGETFL Value of file status flags. The result will not be nega-
tive.
FSETFL Value other than -1.
Page 7 Reliant UNIX 5.44 Printed 11/98
fcntl(2) fcntl(2)
FGETLK Value other than -1.
FSETLK Value other than -1.
FSETLKW Value other than -1.
On failure, fcntl() returns -1 and sets errno to indicate the error.
NOTES
In the future, the variable errno will be set to EAGAIN rather than
EACCES when a section of a file is already locked by another process.
Therefore, portable application programs should expect and test for
either value.
SEE ALSO
close(2), creat(2), dup(2), exec(2), fork(2), open(2), pipe(2),
unistd(4), fcntl(5), lfs(5), types(5).
Page 8 Reliant UNIX 5.44 Printed 11/98