System Calls fcntl(2)
NAME
fcntl - file control
SYNOPSIS
#include
#include
#include
int fcntl(int fildes, int cmd, /* arg */ ...);
DESCRIPTION
The fcntl() function provides for control over open files.
The fildes argument is an open file descriptor.
The fcntl() function can take a third argument, arg, whose
data type, value, and use depend upon the value of cmd. The
cmd argument specifies the operation to be performed by
fcntl().
The values for cmd are defined in and include:
FDUPFD Return a new file descriptor which 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 open file description as
the original file descriptor, and shares any
locks. The FDCLOEXEC flag associated with
the new file descriptor is cleared to keep
the file open across calls to one of the
exec(2) functions.
FDUP2FD Similar to FDUPFD, but always returns arg.
FDUP2FD closes arg if it is open and not
equal to fildes. FDUP2FD is equivalent to
dup2(fildes, arg).
FRESP Free storage space associated with a section
of the ordinary file fildes. The section is
specified by a variable of data type struct
flock pointed to by arg. The data type struct
flock is defined in the header (see
fcntl.h(3HEAD)) and is described below. Note
that all file systems might not support all
possible variations of FRESP arguments. In
particular, many file systems allow space to
SunOS 5.11 Last change: 17 Jan 2007 1
System Calls fcntl(2)
be freed only at the end of a file.
FRESP64 Equivalent to FRESP, but takes a struct
flock64 argument rather than a struct flock
argument.
FALOCSP Allocate space for a section of the ordinary
file fildes. The section is specified by a
variable of data type struct flock pointed to
by arg. The data type struct flock is defined
in the header (see fcntl.h(3HEAD)
and is described below.
FALOCSP64 Equivalent to FALOCSP, but takes a struct
flock64 argument rather than a struct flock
argument.
FGETFD Get the file descriptor flags defined in
that are associated with the file
descriptor fildes. File descriptor flags are
associated with a single file descriptor and
do not affect other file descriptors that
refer to the same file.
FGETFL Get the file status flags and file access
modes, defined in , for the file
descriptor specified by fildes. The file
access modes can be extracted from the return
value using the mask OACMODE, which is
defined in . File status flags and
file access modes do not affect other file
descriptors that refer to the same file with
different open file descriptions.
FGETOWN If fildes refers to a socket, get the process
or process group ID specified to receive
SIGURG signals when out-of-band data is
available. Positive values indicate a process
ID; negative values, other than -1, indicate
a process group ID. If fildes does not refer
to a socket, the results are unspecified.
FGETXFL Get the file status flags, file access modes,
and file creation and assignment flags,
defined in , for the file descriptor
SunOS 5.11 Last change: 17 Jan 2007 2
System Calls fcntl(2)
specified by fildes. The file access modes
can be extracted from the return value using
the mask OACMODE, which is defined in
. File status flags, file access
modes, and file creation and assignment flags
do not affect other file descriptors that
refer to the same file with different open
file descriptions.
FSETFD Set the file descriptor flags defined in
, that are associated with fildes,
to the third argument, arg, taken as type
int. If the FDCLOEXEC flag in the third
argument is 0, the file will remain open
across the exec() functions; otherwise the
file will be closed upon successful execution
of one of the exec() functions.
FSETFL Set the file status flags, defined in
, for the file descriptor specified
by fildes from the corresponding bits in the
arg argument, taken as type int. Bits
corresponding to the file access mode and
file creation and assignment flags 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 unspeci-
fied.
FSETOWN If fildes refers to a socket, set the process
or process group ID specified to receive
SIGURG signals when out-of-band data is
available, using the value of the third argu-
ment, arg, taken as type int. Positive values
indicate a process ID; negative values, other
than -1, indicate a process group ID. If
fildes does not refer to a socket, the
results are unspecified.
The following commands are available for advisory record
locking. Record locking is supported for regular files, and
may be supported for other files.
FGETLK Get the first lock which blocks the lock
description pointed to by the third argument,
arg, taken as a pointer to type struct flock,
defined in . The information
SunOS 5.11 Last change: 17 Jan 2007 3
System Calls fcntl(2)
retrieved overwrites the information passed to
fcntl() in the structure flock. If no lock is
found that would prevent this lock from being
created, then the structure will be left
unchanged except for the lock type which will
be set to FUNLCK.
FGETLK64 Equivalent to FGETLK, but takes a struct
flock64 argument rather than a struct flock
argument.
FSETLK Set or clear a file segment lock according to
the lock description pointed to by the third
argument, arg, taken as a pointer to type
struct flock, defined in . FSETLK is
used to establish shared (or read) locks
(FRDLCK) or exclusive (or write) locks
(FWRLCK), as well as to remove either type of
lock (FUNLCK). FRDLCK, FWRLCK and FUNLCK
are defined in . If a shared or
exclusive lock cannot be set, fcntl() will
return immediately with a return value of -1.
FSETLK64 Equivalent to FSETLK, but takes a struct
flock64 argument rather than a struct flock
argument.
FSETLKW This command is the same as FSETLK except
that if a shared or exclusive lock is blocked
by other locks, the process will wait until
the request can be satisfied. If a signal that
is to be caught is received while fcntl() is
waiting for a region, fcntl() will be inter-
rupted. Upon return from the process' signal
handler, fcntl() will return -1 with errno set
to EINTR, and the lock operation will not be
done.
FSETLKW64 Equivalent to FSETLKW, but takes a struct
flock64 argument rather than a struct flock
argument.
When a shared lock is set on a segment of a file, other
processes will be able to set shared locks on that segment
or a portion of it. A shared lock prevents any other process
SunOS 5.11 Last change: 17 Jan 2007 4
System Calls fcntl(2)
from setting an exclusive lock on any portion of the pro-
tected area. A request for a shared lock will fail if the
file descriptor was not opened with read access.
An exclusive lock will prevent any other process from set-
ting a shared lock or an exclusive lock on any portion of
the protected area. A request for an exclusive lock will
fail if the file descriptor was not opened with write
access.
The flock structure contains at least the following ele-
ments:
short ltype; /* lock operation type */
short lwhence; /* lock base indicator */
offt lstart; /* starting offset from base */
offt llen; /* lock length; llen == 0 means
until end of file */
int lsysid; /* system ID running process holding lock */
pidt lpid; /* process ID of process holding lock */
The value of lwhence is SEKSET, SEKCUR, or SEKEND, 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). After a successful FGETLK or FGETLK64
request, that is, one in which a lock was found, the value
of lwhence will be SEKSET.
The lpid and lsysid fields are used only with FGETLK or
FGETLK64 to return the process ID of the process holding a
blocking lock and to indicate which system is running that
process.
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 possi-
ble 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 SEKSET, the whole file will be locked.
SunOS 5.11 Last change: 17 Jan 2007 5
System Calls fcntl(2)
If a process has an existing lock in which llen is 0 and
which includes the last byte of the requested segment, and
an unlock (FUNLCK) request is made in which llen is non-
zero and the offset of the last byte of the requested seg-
ment is the maximum value for an object of type offt, then
the FUNLCK request will be treated as a request to unlock
from the start of the requested segment with an llen equal
to 0. Otherwise, the request will attempt to unlock only the
requested segment.
There will be at most one type of lock set for each byte in
the file. Before a successful return from an FSETLK,
FSETLK64, FSETLKW, or FSETLKW64 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 and exclusive locks, an FSETLK, FSETLK64,
FSETLKW, or FSETLKW64 request will (respectively) fail or
block when another process has existing locks on bytes in
the specified region and the type of any of those locks con-
flicts 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 process holding that file descriptor
terminates. Locks are not inherited by a child process
created using fork(2).
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,
fcntl() will fail with an EDEADLK error.
The following values for cmd are used for file share reser-
vations. A share reservation is placed on an entire file to
allow cooperating processes to control access to the file.
FSHARE Sets a share reservation on a file with the
specified access mode and designates which
types of access to deny.
FUNSHARE Remove an existing share reservation.
SunOS 5.11 Last change: 17 Jan 2007 6
System Calls fcntl(2)
File share reservations are an advisory form of access con-
trol among cooperating processes, on both local and remote
machines. They are most often used by DOS or Windows emula-
tors and DOS based NFS clients. However, native UNIX ver-
sions of DOS or Windows applications may also choose to use
this form of access control.
A share reservation is described by an fshare structure
defined in , which is included in as
follows:
typedef struct fshare {
short faccess;
short fdeny;
int fid;
} fsharet;
A share reservation specifies the type of access, faccess,
to be requested on the open file descriptor. If access is
granted, it further specifies what type of access to deny
other processes, fdeny. A single process on the same file
may hold multiple non-conflicting reservations by specify-
ing an identifier, fid, unique to the process, with each
request.
An FUNSHARE request releases the reservation with the
specified fid. The faccess and fdeny fields are ignored.
Valid faccess values are:
FRDAC Set a file share reservation for read-only
access.
FWRAC Set a file share reservation for write-only
access.
FRWAC Set a file share reservation for read and write
access.
Valid fdeny values are:
FCOMPAT Set a file share reservation to compatibility
mode.
SunOS 5.11 Last change: 17 Jan 2007 7
System Calls fcntl(2)
FRDNY Set a file share reservation to deny read access
to other processes.
FWRDNY Set a file share reservation to deny write
access to other processes.
FRWDNY Set a file share reservation to deny read and
write access to other processes.
FNODNY Do not deny read or write access to any other
process.
RETURN VALUES
Upon successful completion, the value returned depends on
cmd as follows:
FDUPFD A new file descriptor.
FRESP Value of 0.
FGETFD Value of flags defined in . The
return value will not be negative.
FGETFL Value of file status flags and access modes.
The return value will not be negative.
FGETLK Value other than -1.
FGETLK64 Value other than -1.
FGETOWN Value of the socket owner process or process
group; this will not be -1.
FGETXFL Value of file status flags, access modes, and
creation and assignment flags. The return
value will not be negative.
FSETFD Value other than -1.
SunOS 5.11 Last change: 17 Jan 2007 8
System Calls fcntl(2)
FSETFL Value other than -1.
FSETLK Value other than -1.
FSETLK64 Value other than -1.
FSETLKW Value other than -1.
FSETLKW64 Value other than -1.
FSETOWN Value other than -1.
FSHARE Value other than -1.
FUNSHARE Value other than -1.
Otherwise, -1 is returned and errno is set to indicate the
error.
ERORS
The fcntl() function will fail if:
EAGAIN The cmd argument is FSETLK or FSETLK64, the
type of lock (ltype) is a shared (FRDLCK) or
exclusive (FWRLCK) lock, and the segment of a
file to be locked is already exclusive-locked
by another process; or the type is an exclusive
lock and some portion of the segment of a file
to be locked is already shared-locked or
exclusive-locked by another process.
The cmd argument is FRESP, the file exists,
mandatory file/record locking is set, and there
are outstanding record locks on the file; or
the cmd argument is FSETLK, FSETLK64,
FSETLKW, or FSETLKW64, mandatory file/record
locking is set, and the file is currently being
mapped to virtual memory using mmap(2).
The cmd argument is FSHARE and faccess con-
flicts with an existing fdeny share reserva-
tion.
SunOS 5.11 Last change: 17 Jan 2007 9
System Calls fcntl(2)
EBADF The fildes argument is not a valid open file
descriptor; or the cmd argument is FSETLK,
FSETLK64, FSETLKW, or FSETLKW64, the type of
lock, ltype, is a shared lock (FRDLCK), and
fildes is not a valid file descriptor open for
reading; or the type of lock ltype is an
exclusive lock (FWRLCK) and fildes is not a
valid file descriptor open for writing.
The cmd argument is FRESP and fildes is not
a valid file descriptor open for writing.
The cmd argument is FDUP2FD, and arg is nega-
tive or is not less than the current resource
limit for RLIMITNOFILE.
The cmd argument is FSHARE, the faccess share
reservation is for write access, and fildes is
not a valid file descriptor open for writing.
The cmd argument is FSHARE, the faccess share
reservation is for read access, and fildes is
not a valid file descriptor open for reading.
EFAULT The cmd argument is FGETLK, FGETLK64,
FSETLK, FSETLK64, FSETLKW, FSETLKW64, or
FRESP and the arg argument points to an
illegal address.
The cmd argument is FSHARE or FUNSHARE and
arg points to an illegal address.
EINTR The cmd argument is FSETLKW or FSETLKW64 and
the function was interrupted by a signal.
EINVAL The cmd argument is invalid or not supported by
the file system; or the cmd argument is FDUPFD
and arg is negative or greater than or equal to
OPENMAX; or the cmd argument is FGETLK,
FGETLK64, FSETLK, FSETLK64, FSETLKW, or
FSETLKW64 and the data pointed to by arg is
not valid; or fildes refers to a file that does
not support locking.
The cmd argument is FUNSHARE and a reservation
with this fid for this process does not exist.
SunOS 5.11 Last change: 17 Jan 2007 10
System Calls fcntl(2)
EIO An I/O error occurred while reading from or
writing to the file system.
EMFILE The cmd argument is FDUPFD and either OPENMAX
file descriptors are currently open in the cal-
ling process, or no file descriptors greater
than or equal to arg are available.
ENOLCK The cmd argument is FSETLK, FSETLK64,
FSETLKW, or FSETLKW64 and satisfying the lock
or unlock request would result in the number of
locked regions in the system exceeding a
system-imposed limit.
ENOLINK Either the fildes argument is on a remote
machine and the link to that machine is no
longer active; or the cmd argument is FRESP,
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.
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.
The cmd argument is FGETLK64, FSETLK64, or
FSETLKW64 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 off64t.
The fcntl() function may fail if:
EAGAIN The cmd argument is FSETLK, FSETLK64, FSETLKW,
or FSETLKW64, and the file is currently being
mapped to virtual memory using mmap(2).
EDEADLK The cmd argument is FSETLKW or FSETLKW64, 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
SunOS 5.11 Last change: 17 Jan 2007 11
System Calls fcntl(2)
deadlock.
The cmd argument is FRESP, mandatory record
locking is enabled, ONDELAY and ONONBLOCK are
clear and a deadlock condition was detected.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard
MT-Level Async-Signal Safe
SEE ALSO
lockd(1M), chmod(2), close(2), creat(2), dup(2), exec(2),
fork(2), mmap(2), open(2), pipe(2), read(2), sigaction(2),
write(2), dup2(3C), fcntl.h(3HEAD), attributes(5), stan-
dards(5)
Programming Interfaces Guide
NOTES
In the past, the variable errno was set to EACES rather
than EAGAIN when a section of a file is already locked by
another process. Therefore, portable application programs
should expect and test for either value.
Advisory locks allow cooperating processes to perform con-
sistent operations on files, but do not guarantee exclusive
access. Files can be accessed without advisory locks, but
inconsistencies may result. The network share locking proto-
col does not support the fdeny value of FCOMPAT. For net-
work file systems, if faccess is FRDAC, fdeny is mapped
to FRDNY. Otherwise, it is mapped to FRWDNY.
To prevent possible file corruption, the system may reject
mmap() requests for advisory locked files, or it may reject
advisory locking requests for mapped files. Applications
that require a file be both locked and mapped should lock
the entire file (lstart and llen both set to 0). If a file
SunOS 5.11 Last change: 17 Jan 2007 12
System Calls fcntl(2)
is mapped, the system may reject an unlock request, result-
ing in a lock that does not cover the entire file.
The process ID returned for locked files on network file
systems might not be meaningful.
If the file server crashes and has to be rebooted, the lock
manager (see lockd(1M)) attempts to recover all locks that
were associated with that server. If a lock cannot be
reclaimed, the process that held the lock is issued a
SIGLOST signal.
SunOS 5.11 Last change: 17 Jan 2007 13
|
