fcntl(2) System Calls Manual fcntl(2)
NAME
fcntl() - 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 descriptor.
The following are possible values for the cmd argument:
Fadvise service request (see
fadvise(2)).
Return a new file descriptor having the following characteristics:
o Lowest numbered available file descriptor greater than or equal to the third argument, arg, taken as an integer of
type
o Same open file (or pipe) as the original file.
o Same file pointer as the original file (that is, both file descriptors share one file pointer).
o Same access mode (read, write or read/write).
o Same file status flags (that is, both file descriptors share the same file status flags).
o 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 argument, 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 definition of the structure:
This cmd is useful when it is necessary to save a file's current time values and then, after copying 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 reservation request are
specified using the third argument 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 envi-
ronment 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 terminates. 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 processes.
Set a file share reservation to deny write access to other processes.
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 performed. The oplock guarantees that no other remote process is
accessing 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 multiplied by sec-
onds.
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, por-
table 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 follows:
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 currently 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 enforcement 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 environment 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 ALSO
lockd(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 CONFORMANCE
fcntl(2)