fcntl.html

IEEE 1003.1-2003, Single Unix Specification v3

<p>Otherwise, -1 shall be returned and <i>errno</i> set to indicate the error.</p>
</blockquote>

<h4><a name="tag_03_141_05"></a>ERRORS</h4>

<blockquote>
<p>The <i>fcntl</i>() function shall fail if:</p>

<dl compact>
<dt>[EACCES] or [EAGAIN]</dt>

<dd><br>
The <i>cmd</i> argument is F_SETLK; the type of lock ( <i>l_type</i>) 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.</dd>

<dt>[EBADF]</dt>

<dd>The <i>fildes</i> argument is not a valid open file descriptor, or the argument <i>cmd</i> is F_SETLK or F_SETLKW, the type of
lock, <i>l_type</i>, is a shared lock (F_RDLCK), and <i>fildes</i> is not a valid file descriptor open for reading, or the type of
lock, <i>l_type</i>, is an exclusive lock (F_WRLCK), and <i>fildes</i> is not a valid file descriptor open for writing.</dd>

<dt>[EINTR]</dt>

<dd>The <i>cmd</i> argument is F_SETLKW and the function was interrupted by a signal.</dd>

<dt>[EINVAL]</dt>

<dd>The <i>cmd</i> argument is invalid, or the <i>cmd</i> argument is F_DUPFD and <i>arg</i> is negative or greater than or equal
to {OPEN_MAX}, or the <i>cmd</i> argument is F_GETLK, F_SETLK, or F_SETLKW and the data pointed to by <i>arg</i> is not valid, or
<i>fildes</i> refers to a file that does not support locking.</dd>

<dt>[EMFILE]</dt>

<dd>The argument <i>cmd</i> is F_DUPFD and {OPEN_MAX} file descriptors are currently open in the calling process, or no file
descriptors greater than or equal to <i>arg</i> are available.</dd>

<dt>[ENOLCK]</dt>

<dd>The argument <i>cmd</i> 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.</dd>

<dt>[EOVERFLOW]</dt>

<dd>One of the values to be returned cannot be represented correctly.</dd>

<dt>[EOVERFLOW]</dt>

<dd>The <i>cmd</i> argument is F_GETLK, F_SETLK, or F_SETLKW and the smallest or, if <i>l_len</i> is non-zero, the largest offset
of any byte in the requested segment cannot be represented correctly in an object of type <b>off_t</b>.</dd>
</dl>

<p>The <i>fcntl</i>() function may fail if:</p>

<dl compact>
<dt>[EDEADLK]</dt>

<dd>The <i>cmd</i> 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.</dd>
</dl>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_03_141_06"></a>EXAMPLES</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_141_07"></a>APPLICATION USAGE</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_141_08"></a>RATIONALE</h4>

<blockquote>
<p>The ellipsis in the SYNOPSIS is the syntax specified by the ISO&nbsp;C standard for a variable number of arguments. It is used
because System V uses pointers for the implementation of file locking functions.</p>

<p>The <i>arg</i> 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&nbsp;Std&nbsp;1003.1-2001 are valid. It is a common error to forget this, particularly in the case
of F_SETFD.</p>

<p>This volume of IEEE&nbsp;Std&nbsp;1003.1-2001 permits concurrent read and write access to file data using the <i>fcntl</i>()
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.</p>

<p>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 &quot;wins&quot;. 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
<i>fcntl</i>() is useful for many applications, it is not intended to be overly general and does not handle the bit-tree example
well.</p>

<p>This facility is only required for regular files because it is not appropriate for many devices such as terminals and network
connections.</p>

<p>Since <i>fcntl</i>() works with &quot;any file descriptor associated with that file, however it is obtained&quot;, the file descriptor
may have been inherited through a <a href="../functions/fork.html"><i>fork</i>()</a> or <i><a href=
"../functions/exec.html">exec</a></i> operation and thus may affect a file that another process also has open.</p>

<p>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&nbsp;Std&nbsp;1003.1-2001 to use different specifications.</p>

<p>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 <a href="../functions/fork.html"><i>fork</i>()</a>, locks are not inherited through <a href=
"../functions/fork.html"><i>fork</i>()</a>. Yet locks may be inherited through one of the <i><a href=
"../functions/exec.html">exec</a></i> functions.</p>

<p>The identification of a machine in a network environment is outside the scope of this volume of IEEE&nbsp;Std&nbsp;1003.1-2001.
Thus, an <i>l_sysid</i> member, such as found in System V, is not included in the locking structure.</p>

<p>Changing of lock types can result in a previously locked region being split into smaller regions.</p>

<p>Mandatory locking was a major feature of the 1984 /usr/group standard.</p>

<p>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.</p>

<p>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.</p>

<p>Mandatory locks were omitted for several reasons:</p>

<ol>
<li>
<p>Mandatory lock setting was done by multiplexing the set-group-ID bit in most implementations; this was confusing, at best.</p>
</li>

<li>
<p>The relationship to file truncation as supported in 4.2 BSD was not well specified.</p>
</li>

<li>
<p>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.</p>
</li>

<li>
<p>Some demand-paged historical implementations offer memory mapped files, and enforcement cannot be done on that type of file.</p>
</li>
</ol>

<p>Since sleeping on a region is interrupted with any signal, <a href="../functions/alarm.html"><i>alarm</i>()</a> 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.</p>
</blockquote>

<h4><a name="tag_03_141_09"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_141_10"></a>SEE ALSO</h4>

<blockquote>
<p><a href="alarm.html"><i>alarm</i>()</a> , <a href="close.html"><i>close</i>()</a> , <a href="exec.html"><i><a href=
"../functions/exec.html">exec</a></i>()</a> , <a href="open.html"><i>open</i>()</a> , <a href=
"sigaction.html"><i>sigaction</i>()</a> , the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../basedefs/fcntl.h.html"><i>&lt;fcntl.h&gt;</i></a>, <a href="../basedefs/signal.h.html"><i>&lt;signal.h&gt;</i></a>, <a href=
"../basedefs/unistd.h.html"><i>&lt;unistd.h&gt;</i></a></p>
</blockquote>

<h4><a name="tag_03_141_11"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 1. Derived from Issue 1 of the SVID.</p>
</blockquote>

<h4><a name="tag_03_141_12"></a>Issue 5</h4>

<blockquote>
<p>The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX Threads Extension.</p>

<p>Large File Summit extensions are added.</p>
</blockquote>

<h4><a name="tag_03_141_13"></a>Issue 6</h4>

<blockquote>
<p>In the SYNOPSIS, the optional include of the <a href="../basedefs/sys/types.h.html"><i>&lt;sys/types.h&gt;</i></a> header is
removed.</p>

<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>

<ul>
<li>
<p>The requirement to include <a href="../basedefs/sys/types.h.html"><i>&lt;sys/types.h&gt;</i></a> has been removed. Although <a
href="../basedefs/sys/types.h.html"><i>&lt;sys/types.h&gt;</i></a> was required for conforming implementations of previous POSIX
specifications, it was not required for UNIX applications.</p>
</li>

<li>
<p>In the DESCRIPTION, sentences describing behavior when <i>l_len</i> is negative are now mandated, and the description of unlock
(F_UNLOCK) when <i>l_len</i> is non-negative is mandated.</p>
</li>

<li>
<p>In the ERRORS section, the [EINVAL] error condition has the case mandated when the <i>cmd</i> is invalid, and two [EOVERFLOW]
error conditions are added.</p>
</li>
</ul>

<p>The F_GETOWN and F_SETOWN values are added for sockets.</p>

<p>The following changes were made to align with the IEEE&nbsp;P1003.1a draft standard:</p>

<ul>
<li>
<p>Clarification is added that the extent of the bytes locked is determined prior to the blocking action.</p>
</li>
</ul>

<p>The DESCRIPTION is updated for alignment with IEEE&nbsp;Std&nbsp;1003.1j-2000 by specifying that <i>fcntl</i>() results are
unspecified for typed memory objects.</p>

<p>The DESCRIPTION is updated to avoid use of the term &quot;must&quot; for application requirements.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>