fcntl.html

posix标准英文,html格式

<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>
<h5><a name="tag_03_141_06_01"></a>Locking and Unlocking a File</h5>

<p>The following example demonstrates how to place a lock on bytes 100 to 109 of a file and then later remove it. F_SETLK is used
to perform a non-blocking lock request so that the process does not have to wait if an incompatible lock is held by another
process; instead the process can take some other action.</p>

<pre>
<tt>#include &lt;stdlib.h&gt;
#include &lt;unistd.h&gt;
#include &lt;fcntl.h&gt;
#include &lt;errno.h&gt;
<br>
int
main(int argc, char *argv[])
{
    int fd;
    struct flock fl;
<br>
    fd = open("testfile", O_RDWR);
    if (fd == -1)
        /* Handle error */;
<br>
    /* Make a non-blocking request to place a write lock
       on bytes 100-109 of testfile */
<br>
    fl.l_type = F_WRLCK;
    fl.l_whence = SEEK_SET;
    fl.l_start = 100;
    fl.l_len = 10;
<br>
    if (fcntl(fd, F_SETLK, &amp;fl) == -1) {
        if (errno == EACCES || errno == EAGAIN) {
            printf("Already locked by another process\n");
<br>
            /* We can't get the lock at the moment */
<br>
        } else {
            /* Handle unexpected error */;
        }
    } else { /* Lock was granted... */
<br>
        /* Perform I/O on bytes 100 to 109 of file */
<br>
        /* Unlock the locked bytes */
<br>
        fl.l_type = F_UNLCK;
        fl.l_whence = SEEK_SET;
        fl.l_start = 100;
        fl.l_len = 10;
        if (fcntl(fd, F_SETLK, &amp;fl) == -1)
            /* Handle error */;
    }
    exit(EXIT_SUCCESS);
} /* main */
</tt>
</pre>

<h5><a name="tag_03_141_06_02"></a>Setting the Close-on-Exec Flag</h5>

<p>The following example demonstrates how to set the close-on-exec flag for the file descriptor <i>fd</i>.</p>

<pre>
<tt>#include &lt;unistd.h&gt;
#include &lt;fcntl.h&gt;
...
    int flags;
<br>
    flags = fcntl(fd, F_GETFD);
    if (flags == -1)
        /* Handle error */;
    flags |= FD_CLOEXEC;
    if (fcntl(fd, F_SETFD, flags) == -1)
        /* Handle error */;"
</tt>
</pre>
</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>

<p>IEEE&nbsp;Std&nbsp;1003.1-2001/Cor&nbsp;2-2004, item XSH/TC2/D6/29 is applied, adding the example to the EXAMPLES section.</p>
</blockquote>

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

<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>