Import of man-pages 1.70

[thirdparty/man-pages.git] / man3p / fcntl.3p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "FCNTL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" fcntl 
.SH NAME
fcntl \- file control
.SH SYNOPSIS
.LP
\fB#include <unistd.h> \fP
\fB
.br
#include <fcntl.h>
.br
.sp
int fcntl(int\fP \fIfildes\fP\fB, int\fP \fIcmd\fP\fB, ...);
.br
\fP
.SH DESCRIPTION
.LP
The \fIfcntl\fP() function shall perform the operations described
below on open files. The \fIfildes\fP argument is a file
descriptor.
.LP
The available values for \fIcmd\fP are defined in \fI<fcntl.h>\fP
and are as
follows:
.TP 7
F_DUPFD
Return a new file descriptor which shall be the lowest numbered available
(that is, not already open) file descriptor greater
than or equal to the third argument, \fIarg\fP, taken as an integer
of type \fBint\fP. The new file descriptor shall refer to the
same open file description as the original file descriptor, and shall
share any locks. The FD_CLOEXEC flag associated with the new
file descriptor shall be cleared to keep the file open across calls
to one of the \fIexec\fP
functions.
.TP 7
F_GETFD
Get the file descriptor flags defined in \fI<fcntl.h>\fP that are
associated with
the file descriptor \fIfildes\fP. File descriptor flags are associated
with a single file descriptor and do not affect other file
descriptors that refer to the same file.
.TP 7
F_SETFD
Set the file descriptor flags defined in \fI<fcntl.h>\fP, that are
associated
with \fIfildes\fP, to the third argument, \fIarg\fP, taken as type
\fBint\fP. If the FD_CLOEXEC flag in the third argument is 0,
the file shall remain open across the \fIexec\fP functions; otherwise,
the file shall be
closed upon successful execution of one of the \fIexec\fP functions.
.TP 7
F_GETFL
Get the file status flags and file access modes, defined in \fI<fcntl.h>\fP,
for
the file description associated with \fIfildes\fP. The file access
modes can be extracted from the return value using the mask
O_ACCMODE, which is defined in \fI<fcntl.h>\fP. File status flags
and file access
modes are associated with the file description and do not affect other
file descriptors that refer to the same file with different
open file descriptions.
.TP 7
F_SETFL
Set the file status flags, defined in \fI<fcntl.h>\fP, for the file
description
associated with \fIfildes\fP from the corresponding bits in the third
argument, \fIarg\fP, taken as type \fBint\fP. Bits
corresponding to the file access mode and the file creation flags,
as defined in \fI<fcntl.h>\fP, that are set in \fIarg\fP shall be
ignored. If any bits in \fIarg\fP other
than those mentioned here are changed by the application, the result
is unspecified.
.TP 7
F_GETOWN
If \fIfildes\fP 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
\fIfildes\fP does not refer to a socket, the results are unspecified.
.TP 7
F_SETOWN
If \fIfildes\fP 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 argument, \fIarg\fP,
taken as type \fBint\fP. Positive values indicate a process
ID; negative values, other than -1, indicate a process group ID. If
\fIfildes\fP does not refer to a socket, the results are
unspecified.
.sp
.LP
The following values for \fIcmd\fP are available for advisory record
locking. Record locking shall be supported for regular
files, and may be supported for other files.
.TP 7
F_GETLK
Get the first lock which blocks the lock description pointed to by
the third argument, \fIarg\fP, taken as a pointer to type
\fBstruct flock\fP, defined in \fI<fcntl.h>\fP. The information retrieved
shall
overwrite the information passed to \fIfcntl\fP() in the structure
\fBflock\fP. If no lock is found that would prevent this lock
from being created, then the structure shall be left unchanged except
for the lock type which shall be set to F_UNLCK.
.TP 7
F_SETLK
Set or clear a file segment lock according to the lock description
pointed to by the third argument, \fIarg\fP, taken as a
pointer to type \fBstruct flock\fP, defined in \fI<fcntl.h>\fP. F_SETLK
can
establish shared (or read) locks (F_RDLCK) or exclusive (or write)
locks (F_WRLCK), as well as to remove either type of lock
(F_UNLCK). F_RDLCK, F_WRLCK, and F_UNLCK are defined in \fI<fcntl.h>\fP.
If a shared
or exclusive lock cannot be set, \fIfcntl\fP() shall return immediately
with a return value of -1.
.TP 7
F_SETLKW
This command shall be equivalent to F_SETLK except that if a shared
or exclusive lock is blocked by other locks, the thread
shall wait until the request can be satisfied. If a signal that is
to be caught is received while \fIfcntl\fP() is waiting for a
region, \fIfcntl\fP() shall be interrupted. Upon return from the signal
handler, \fIfcntl\fP() shall return -1 with \fIerrno\fP
set to [EINTR], and the lock operation shall not be done.
.sp
.LP
Additional implementation-defined values for \fIcmd\fP may be defined
in \fI<fcntl.h>\fP. Their names shall start with F_.
.LP
When a shared lock is set on a segment of a file, other processes
shall be able to set shared locks on that segment or a portion
of it. A shared lock prevents any other process from setting an exclusive
lock on any portion of the protected area. A request for
a shared lock shall fail if the file descriptor was not opened with
read access.
.LP
An exclusive lock shall prevent any other process from setting a shared
lock or an exclusive lock on any portion of the
protected area. A request for an exclusive lock shall fail if the
file descriptor was not opened with write access.
.LP
The structure \fBflock\fP describes the type ( \fIl_type\fP), starting
offset ( \fIl_whence\fP), relative offset (
\fIl_start\fP), size ( \fIl_len\fP), and process ID ( \fIl_pid\fP)
of the segment of the file to be affected.
.LP
The value of \fIl_whence\fP is SEEK_SET, SEEK_CUR, or SEEK_END, to
indicate that the relative offset \fIl_start\fP bytes shall
be measured from the start of the file, current position, or end of
the file, respectively. The value of \fIl_len\fP is the number
of consecutive bytes to be locked. The value of \fIl_len\fP may be
negative (where the definition of \fBoff_t\fP permits negative
values of \fIl_len\fP). The \fIl_pid\fP field is only used with F_GETLK
to return the process ID of the process holding a
blocking lock. After a successful F_GETLK request, when a blocking
lock is found, the values returned in the \fBflock\fP structure
shall be as follows:
.TP 7
\fIl_type\fP
Type of blocking lock found.
.TP 7
\fIl_whence\fP
SEEK_SET.
.TP 7
\fIl_start\fP
Start of the blocking lock.
.TP 7
\fIl_len\fP
Length of the blocking lock.
.TP 7
\fIl_pid\fP
Process ID of the process that holds the blocking lock.
.sp
.LP
If the command is F_SETLKW and the process must wait for another process
to release a lock, then the range of bytes to be locked
shall be determined before the \fIfcntl\fP() function blocks. If the
file size or file descriptor seek offset change while
\fIfcntl\fP() is blocked, this shall not affect the range of bytes
locked.
.LP
If \fIl_len\fP is positive, the area affected shall start at \fIl_start\fP
and end at \fIl_start\fP+ \fIl_len\fP-1. If
\fIl_len\fP is negative, the area affected shall start at \fIl_start\fP+
\fIl_len\fP and end at \fIl_start\fP-1. Locks may
start and extend beyond the current end of a file, but shall not extend
before the beginning of the file. A lock shall be set to
extend to the largest possible value of the file offset for that file
by setting \fIl_len\fP to 0. If such a lock also has
\fIl_start\fP set to 0 and \fIl_whence\fP is set to SEEK_SET, the
whole file shall be locked.
.LP
There shall be at most one type of lock set for each byte in the file.
Before a successful return from an F_SETLK or an F_SETLKW
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 shall be replaced by the
new lock type. As specified above under the descriptions of
shared locks and exclusive locks, an F_SETLK or an F_SETLKW request
(respectively) shall fail or block when another process has
existing locks on bytes in the specified region and the type of any
of those locks conflicts with the type specified in the
request.
.LP
All locks associated with a file for a given process shall be 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.
.LP
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, \fIfcntl\fP() shall
fail with an [EDEADLK] error.
.LP
An unlock (F_UNLCK) request in which \fIl_len\fP is non-zero and the
offset of the last byte of the requested segment is the
maximum value for an object of type \fBoff_t\fP, when the process
has an existing lock in which \fIl_len\fP is 0 and which
includes the last byte of the requested segment, shall be treated
as a request to unlock from the start of the requested segment
with an \fIl_len\fP equal to 0. Otherwise, an unlock (F_UNLCK) request
shall attempt to unlock only the requested segment.
.LP
When the file descriptor \fIfildes\fP refers to a shared memory object,
the behavior of \fIfcntl\fP() shall be the same as for a
regular file except the effect of the following values for the argument
\fIcmd\fP shall be unspecified: F_SETFL, F_GETLK, F_SETLK,
and F_SETLKW. 
.LP
If \fIfildes\fP refers to a typed memory object, the result of the
\fIfcntl\fP() function is unspecified. 
.SH RETURN VALUE
.LP
Upon successful completion, the value returned shall depend on \fIcmd\fP
as follows:
.TP 7
F_DUPFD
A new file descriptor.
.TP 7
F_GETFD
Value of flags defined in \fI<fcntl.h>\fP. The return value shall
not be
negative.
.TP 7
F_SETFD
Value other than -1.
.TP 7
F_GETFL
Value of file status flags and access modes. The return value is not
negative.
.TP 7
F_SETFL
Value other than -1.
.TP 7
F_GETLK
Value other than -1.
.TP 7
F_SETLK
Value other than -1.
.TP 7
F_SETLKW
Value other than -1.
.TP 7
F_GETOWN
Value of the socket owner process or process group; this will not
be -1.
.TP 7
F_SETOWN
Value other than -1.
.sp
.LP
Otherwise, -1 shall be returned and \fIerrno\fP set to indicate the
error.
.SH ERRORS
.LP
The \fIfcntl\fP() function shall fail if:
.TP 7
.B EACCES \fRor\fP EAGAIN
.sp
The \fIcmd\fP argument is F_SETLK; the type of lock ( \fIl_type\fP)
is a shared (F_RDLCK) or exclusive (F_WRLCK) 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.
.TP 7
.B EBADF
The \fIfildes\fP argument is not a valid open file descriptor, or
the argument \fIcmd\fP is F_SETLK or F_SETLKW, the type of
lock, \fIl_type\fP, is a shared lock (F_RDLCK), and \fIfildes\fP is
not a valid file descriptor open for reading, or the type of
lock, \fIl_type\fP, is an exclusive lock (F_WRLCK), and \fIfildes\fP
is not a valid file descriptor open for writing.
.TP 7
.B EINTR
The \fIcmd\fP argument is F_SETLKW and the function was interrupted
by a signal.
.TP 7
.B EINVAL
The \fIcmd\fP argument is invalid, or the \fIcmd\fP argument is F_DUPFD
and \fIarg\fP is negative or greater than or equal
to {OPEN_MAX}, or the \fIcmd\fP argument is F_GETLK, F_SETLK, or F_SETLKW
and the data pointed to by \fIarg\fP is not valid, or
\fIfildes\fP refers to a file that does not support locking.
.TP 7
.B EMFILE
The argument \fIcmd\fP is F_DUPFD and {OPEN_MAX} file descriptors
are currently open in the calling process, or no file
descriptors greater than or equal to \fIarg\fP are available.
.TP 7
.B ENOLCK
The argument \fIcmd\fP is F_SETLK or F_SETLKW and satisfying the lock
or unlock request would result in the number of locked
regions in the system exceeding a system-imposed limit.
.TP 7
.B EOVERFLOW
One of the values to be returned cannot be represented correctly.
.TP 7
.B EOVERFLOW
The \fIcmd\fP argument is F_GETLK, F_SETLK, or F_SETLKW and the smallest
or, if \fIl_len\fP is non-zero, the largest offset
of any byte in the requested segment cannot be represented correctly
in an object of type \fBoff_t\fP.
.sp
.LP
The \fIfcntl\fP() function may fail if:
.TP 7
.B EDEADLK
The \fIcmd\fP argument is F_SETLKW, the lock is blocked by a lock
from another process, and putting the calling process to
sleep to wait for that lock to become free would cause a deadlock.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
The ellipsis in the SYNOPSIS is the syntax specified by the ISO\ C
standard for a variable number of arguments. It is used
because System V uses pointers for the implementation of file locking
functions.
.LP
The \fIarg\fP values to F_GETFD, F_SETFD, F_GETFL, and F_SETFL all
represent flag values to allow for future growth.
Applications using these functions should do a read-modify-write operation
on them, rather than assuming that only the values
defined by this volume of IEEE\ Std\ 1003.1-2001 are valid. It is
a common error to forget this, particularly in the case
of F_SETFD.
.LP
This volume of IEEE\ Std\ 1003.1-2001 permits concurrent read and
write access to file data using the \fIfcntl\fP()
function; this is a change from the 1984 /usr/group standard and early
proposals. Without concurrency controls, this feature may
not be fully utilized without occasional loss of data.
.LP
Data losses occur in several ways. One case occurs when several processes
try to update the same record, without sequencing
controls; several updates may occur in parallel and the last writer
"wins". Another case is a bit-tree or other internal
list-based database that is undergoing reorganization. Without exclusive
use to the tree segment by the updating process, other
reading processes chance getting lost in the database when the index
blocks are split, condensed, inserted, or deleted. While
\fIfcntl\fP() is useful for many applications, it is not intended
to be overly general and does not handle the bit-tree example
well.
.LP
This facility is only required for regular files because it is not
appropriate for many devices such as terminals and network
connections.
.LP
Since \fIfcntl\fP() works with "any file descriptor associated with
that file, however it is obtained", the file descriptor
may have been inherited through a \fIfork\fP() or \fIexec\fP operation
and thus may affect a file that another process also has open.
.LP
The use of the open file description to identify what to lock requires
extra calls and presents problems if several processes
are sharing an open file description, but there are too many implementations
of the existing mechanism for this volume of
IEEE\ Std\ 1003.1-2001 to use different specifications.
.LP
Another consequence of this model is that closing any file descriptor
for a given file (whether or not it is the same open file
description that created the lock) causes the locks on that file to
be relinquished for that process. Equivalently, any close for
any file/process pair relinquishes the locks owned on that file for
that process. But note that while an open file description may
be shared through \fIfork\fP(), locks are not inherited through \fIfork\fP().
Yet locks may be inherited through one of the \fIexec\fP functions.
.LP
The identification of a machine in a network environment is outside
the scope of this volume of IEEE\ Std\ 1003.1-2001.
Thus, an \fIl_sysid\fP member, such as found in System V, is not included
in the locking structure.
.LP
Changing of lock types can result in a previously locked region being
split into smaller regions.
.LP
Mandatory locking was a major feature of the 1984 /usr/group standard.
.LP
For advisory file record locking to be effective, all processes that
have access to a file must cooperate and use the advisory
mechanism before doing I/O on the file. Enforcement-mode record locking
is important when it cannot be assumed that all processes
are cooperating. For example, if one user uses an editor to update
a file at the same time that a second user executes another
process that updates the same file and if only one of the two processes
is using advisory locking, the processes are not
cooperating. Enforcement-mode record locking would protect against
accidental collisions.
.LP
Secondly, advisory record locking requires a process using locking
to bracket each I/O operation with lock (or test) and unlock
operations. With enforcement-mode file and record locking, a process
can lock the file once and unlock when all I/O operations have
been completed. Enforcement-mode record locking provides a base that
can be enhanced; for example, with sharable locks. That is,
the mechanism could be enhanced to allow a process to lock a file
so other processes could read it, but none of them could write
it.
.LP
Mandatory locks were omitted for several reasons:
.IP " 1." 4
Mandatory lock setting was done by multiplexing the set-group-ID bit
in most implementations; this was confusing, at best.
.LP
.IP " 2." 4
The relationship to file truncation as supported in 4.2 BSD was not
well specified.
.LP
.IP " 3." 4
Any publicly readable file could be locked by anyone. Many historical
implementations keep the password database in a publicly
readable file. A malicious user could thus prohibit logins. Another
possibility would be to hold open a long-distance telephone
line.
.LP
.IP " 4." 4
Some demand-paged historical implementations offer memory mapped files,
and enforcement cannot be done on that type of file.
.LP
.LP
Since sleeping on a region is interrupted with any signal, \fIalarm\fP()
may be used to
provide a timeout facility in applications requiring it. This is useful
in deadlock detection. Since implementation of full
deadlock detection is not always feasible, the [EDEADLK] error was
made optional.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIalarm\fP() , \fIclose\fP() , \fIexec\fP() , \fIopen\fP() , \fIsigaction\fP()
, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<fcntl.h>\fP,
\fI<signal.h>\fP, \fI<unistd.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .