fcntl(2)fcntl(2)NAMEfcntl() - file control
SYNOPSIS
Remarks
The ANSI C "" construct denotes a variable length argument list whose
optional [or required] members are given in the associated comment
DESCRIPTION
provides for control over open files. fildes is an open file descrip‐
tor.
The following are possible values for the cmd argument:
Fadvise service request (see
fadvise(2)).
Return a new file descriptor having the following characteris‐
tics:
· Lowest numbered available file descriptor
greater than or equal to the third argument,
arg, taken as an integer of type
· Same open file (or pipe) as the original file.
· Same file pointer as the original file (that
is, both file descriptors share one file
pointer).
· Same access mode (read, write or read/write).
· Same file status flags (that is, both file
descriptors share the same file status flags).
· The close-on-exec flag associated with the new
file descriptor is set to remain open across
system calls.
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.
Set the file descriptor flags (defined in
that are associated with fildes, to the third
argument, arg, taken as an integer of type (see
If the flag in the third argument is the file
will remain open across otherwise, the file will
be closed upon execution of
Get file status flags and access modes; see
fcntl(5).
Set file status flags to
the third argument, arg, taken as an integer of
type Only certain flags can be set; see fcntl(5).
It is not possible to set both and
Get the first lock that blocks the lock
described by the variable of type pointed to by
the third argument, arg, taken as a pointer to
type The information retrieved overwrites the
information passed to in the structure. If no
lock is found that would prevent this lock from
being created, the structure is passed back
unchanged, except that the lock type is set to
Set or clear a file segment lock according to the variable of
type
pointed to by the third argument, arg, taken as a
pointer to type (see fcntl(5)). The cmd is used
to establish read and write locks, as well as to
remove either type of lock If a read or write
lock cannot be set, returns immediately with an
error value of
This cmd is the same as except that if a read or write
lock is blocked by other locks, the process will
sleep until the segment is free to be locked.
Same as except arg is a pointer to instead of
Same as except arg is a pointer to instead of
Same as except arg is a pointer to instead of
If fildes refers to a socket, returns the process or
process group ID specified to receive 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 refers to a socket, sets the process or
process group ID specified to receive signals
when out-of-band data is available, using the
value of the third argument, arg, taken as type
Positive values indicate a process ID; negative
values, other than -1, indicate a process group
ID.
Gets the current times for the file identified by
fildes. The third argument, arg, is a pointer to
the defined in (see
Sets the current times for the file identified by
fildes. To execute the cmd without error,
requires superuser privilege. The third argu‐
ment, arg, is a pointer to the that is defined in
The structure contains the file's atime (access
time), mtime (modification time), and ctime (file
attribute change time) values. Here is the defi‐
nition of the structure:
This cmd is useful when it is necessary to save a
file's current time values and then, after copy‐
ing or moving the file, set back atime and mtime.
Note that ctime is not restored to the original
value; the value of ctime after is file system
dependent.
An example using and follows:
Sets a share reservation on a file with the specified
access mode and designates which types of access
to deny. The details of the file share reserva‐
tion request are specified using the third argu‐
ment arg, which should be a pointer to a (defined
in See the section below.
Removes an existing share reservation.
If fildes refers to fifo, the performance of the
asynchronous fifo reads or writes may improve in
multiprocessor environment when multiple threads
are operating on the same fildes. This cmd will
work only if HP's optional product is installed
on the system.
An example using follows:
A read lock prevents any other process from write-locking the protected
area. More than one read lock can 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 other process from read-locking or write-
locking the protected area. Only one write lock can 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.
The structure describes the type starting offset relative offset size
and process ID of the segment of the file to be affected. The process
ID field is only used with the to return the value of a block in lock.
Locks can start and extend beyond the current end of a file, but cannot
be negative relative to the beginning of the file. A lock can be set
to always extend to the end of file by setting to zero (0). If such a
lock also has set to zero (0), the whole file will be locked. Changing
or unlocking a segment from the middle of a larger locked segment
leaves two smaller segments for either end. Locking a segment 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 ter‐
minates. Locks are not inherited by a child process in a system call.
When enforcement-mode file and record locking is activated on a file
(see chmod(2)), future and system calls on the file are affected by the
record locks in effect.
File Share Reservations
File share reservations are an advisory form of access control among
cooperating processes, on both local and remote machines. File share
reservations are most commonly used by DOS or Windows emulators and DOS
based NFS clients. The system call can be used to set file share
reservations using the command.
A share reservation is described by an fshare structure defined in as
follows:
The structure describes the type of access to be requested on the open
file descriptor. If the command succeeds, it also specifies what type
of access to deny other processes A single process on the same file can
hold several non-conflicting reservations by specifying an identifier,
unique to the process with each share reservation request.
Valid values are:
Set a file share reservation for read-only access.
Set a file share reservation for write-only access.
Set a file share reservation for read-write access.
Valid values are:
Set a file share reservation to compatibility mode.
Set a file share reservation to deny read access to other pro‐
cesses.
Set a file share reservation to deny write access to other pro‐
cesses.
Set a file share reservation to deny read and write access to
other processes.
Set a file share reservation to not deny read or write access to
other
processes.
Oplocks
An is a type of caching hint used mostly by CIFS clients so they can
cache data locally. This caching helps increase performance by not
having to read data across a network each time a file operation is per‐
formed. The oplock guarantees that no other remote process is access‐
ing the file in a way that might lead to data inconsistencies.
The following arguments are supported for oplocks.
Requests an opportunistic lock reservation (oplock) on a file.
The supported oplock types are defined in
Requests an opportunistic lock reservation (oplock) on a file
and will wait
(in other words, block) until the request can be granted.
Removes all oplocks by pid.
Checks to see if an oplock is present on a file. The possible
returns values are one of the oplock types defined in
An oplock request is described by an structure which is defined in as
follows:
The structure describes the details of the lock being requested on the
opened file descriptor. If the command succeeds, it also contains the
owner ID of the process as well as the type of oplock being requested.
The can also be specified. The process ID is the requesting process
with which to associate the oplock. Optional flags and signal value
can also be specified.
The only field in this structure which must be assigned is The other
fields are either optional or not used and should be initialized to
zero (0).
The fields in the structure are described here:
Owner type. Any integer; however, 0x8000 is reserved.
Member ID.
Any unique integer of type
Type of oplock.
is one of these values:
Removes an oplock.
Request a shared oplock.
Request an exclusive oplock.
Request a batch oplock.
(Requires CIFS stacked file system support)
The system ID of the locking process.
is an optional value.
The process ID of the process that owns the oplock.
The process ID does not need to be filled in by the
application, because does this internally.
This field is not currently used and is here for future needs.
HP recommends that this field be initialized to zero (0).
This field is the number of retries to gracefully request that
an oplock be
broken. After the number of retries are exhausted, then
the oplock will be removed without acknowledgment from
the process that owns it.
This value represents the wait time in seconds that the kernel
will wait
before re-sending the oplock break signal. The total
time that an application can wait for an oplock is multi‐
plied by seconds.
A value to be sent with signal to a process upon an oplock being
broken.
Application Usage
Because in the future the external variable will be set to rather than
when a section of a file is already locked by another process, portable
application programs should expect and test for either value. For
example:
NETWORKING FEATURES
NFS
The advisory record-locking capabilities of are implemented throughout
the network by the "network lock daemon" (see lockd(1M)). If the file
server crashes and is rebooted, the lock daemon attempts to recover all
locks associated with the crashed server. If a lock cannot be
reclaimed, the process that held the lock is issued a signal.
Record locking, as implemented for NFS files, is only advisory.
RETURN VALUE
Upon successful completion, the value returned depends on cmd as fol‐
lows:
Value of requested hint operation.
A new file descriptor.
Value of close-on-exec flag (only the low-order bit is defined).
Value other than −1.
Value of file status flags and access modes.
Value other than −1.
Value other than −1.
Value other than −1.
Value other than −1.
Value other than −1.
Value other than −1.
Value other than −1.
Value other than −1.
Value other than −1.
Value other than −1.
Value other than −1.
Value of process or process group ID specified to receive
signals when out-of-band data is available.
Value other than −1.
Value other than −1.
Value other than −1.
Value other than −1.
Value other than −1.
Otherwise, a value of −1 is returned and is set to indicate the error.
ERRORS
fails if any of the following conditions occur:
cmd is the type of lock is a read lock or write lock and the
segment of a file to be locked is already write-locked by
another process, or the type is a write lock and the segment of
a file to be locked is already read- or write-locked by another
process.
cmd is or and the file is mapped in to virtual memory using
the system call (see mmap(2)).
cmd is and conflicts with an existing share reservation.
cmd is and this request conflicts with an existing byte lock
or share reservation.
fildes is not a valid open file descriptor, or was not opened
for reading when setting a read lock, or for writing when
setting a write lock.
cmd arg is and the share reservation is for read or write
access, and the file descriptor is not a valid file
descriptor open for reading.
cmd is and the lock is in a deadlock situation. The deadlock
situation occurs when the lock is blocked by a lock from
another process and the lock sleeps and waits for that
other lock to become free.
cmd is either or and arg points to an illegal address.
cmd is either or and arg points to an illegal address.
cmd is either or and arg points to an illegal address.
cmd is and the call was interrupted by a signal.
cmd is and arg is negative.
cmd is or and arg or the data it points to is not valid, or
fildes refers to a file that does not support locking.
cmd is not a valid command.
cmd is and both and are specified.
cmd is or and the or values are not valid.
cmd is or and arg is invalid.
cmd is and arg is greater than or equal to the maximum number
of file descriptors.
cmd is then, either fildes is not referring to fifo, or HP's
optional product is not installed.
cmd is and the maximum number of file descriptors is cur‐
rently open.
cmd is or the type of lock is a read or write lock, and no
more record locks are available (too many file segments
locked).
cmd is or the type of lock is a read lock or write lock and
the file is an NFS file with access bits set for enforce‐
ment mode.
cmd is or the file is an NFS file, and a system error
occurred on the remote node.
[ENOSYS]
cmd is or and the arg is which is currently defined but
not supported.
cmd is or and fildes does not refer to a socket.
cmd is and the blocking lock's starting offset or length
would not fit in the caller's structure.
cmd is and the user does not have superuser privilege.
cmd is the hint is and VM has detected a blocking condition.
WARNINGS
The oplock support is release specific and as such is not guaranteed to
be supported in future releases and/or with the same interface. HP
reserves the right to change or remove oplock support at any time.
If fildes refers to fifo and cmd is set to then:
1. Major performance improvement can be seen on multiprocessor environ‐
ment when multiple threads are operating on the same fifo.
2. There is no visible performance improvement on systems having less
than eight CPUs.
3. This particular flag should not be set for synchronous fifo reads or
writes which otherwise will cause performance regression.
AUTHOR
was developed by HP, AT&T and the University of California, Berkeley.
SEE ALSOlockd(1M), statd(1M), chmod(2), close(2), creat(2), creat64(2),
exec(2), fadvise(2), lockf(2), open(2), read(2), truncate(2), write(2),
fcntl(5).
STANDARDS CONFORMANCEfcntl(2)