0x1949 Team - FAZEMRX - MANAGER

Edit File: fcntl.html

<!DOCTYPE html>

<title>36.10. fcntl — The fcntl and ioctl system calls &#8212; Python 2.7.18 documentation</title>
 <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
 <link rel="stylesheet" type="text/css" href="../_static/classic.css" />
 
 <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
 <script src="../_static/jquery.js"></script>
 <script src="../_static/underscore.js"></script>
 <script src="../_static/doctools.js"></script>
 
 <script src="../_static/sidebar.js"></script>
 
 <link rel="search" type="application/opensearchdescription+xml"
 title="Search within Python 2.7.18 documentation"
 href="../_static/opensearch.xml"/>
 <link rel="author" title="About these documents" href="../about.html" />
 <link rel="index" title="Index" href="../genindex.html" />
 <link rel="search" title="Search" href="../search.html" />
 <link rel="copyright" title="Copyright" href="../copyright.html" />
 <link rel="next" title="36.11. pipes — Interface to shell pipelines" href="pipes.html" />
 <link rel="prev" title="36.9. pty — Pseudo-terminal utilities" href="pty.html" />
 <link rel="shortcut icon" type="image/png" href="../_static/py.png" />
 <link rel="canonical" href="file:///usr/share/doc/python2.7/html/library/fcntl.html" />
 <script type="text/javascript" src="../_static/copybutton.js"></script>

</head><body>
<div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;">
 This document is for an old version of Python that is <a href="https://devguide.python.org/devcycle/#end-of-life-branches">no longer supported</a>.
 You should install the python3 and python3-doc packages and read the 
 <a href="file:///usr/share/doc/python3-doc/html/library/fcntl.html"> Python documentation for the Python3 version packaged in this release</a>.
</div>
 
 <div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../genindex.html" title="General Index"
 accesskey="I">index</a></li>
 <li class="right" >
 <a href="../py-modindex.html" title="Python Module Index"
 >modules</a> |</li>
 <li class="right" >
 <a href="pipes.html" title="36.11. pipes — Interface to shell pipelines"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="pty.html" title="36.9. pty — Pseudo-terminal utilities"
 accesskey="P">previous</a> |</li>
 <li><img src="../_static/py.png" alt=""
 style="vertical-align: middle; margin-top: -1px"/></li>
 <li><a href="https://www.python.org/">Python</a> &#187;</li>
 <li>
 <a href="../index.html">Python 2.7.18 documentation</a> &#187;
 </li>

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
 <li class="nav-item nav-item-2"><a href="unix.html" accesskey="U">36. Unix Specific Services</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">36.10. <code class="xref py py-mod docutils literal notranslate">fcntl</code> — The <code class="docutils literal notranslate">fcntl</code> and <code class="docutils literal notranslate">ioctl</code> system calls</a></li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body" role="main">
 
 <section id="module-fcntl">
<h1>36.10. <a class="reference internal" href="#module-fcntl" title="fcntl: The fcntl() and ioctl() system calls. (Unix)"><code class="xref py py-mod docutils literal notranslate">fcntl</code></a> — The <code class="docutils literal notranslate">fcntl</code> and <code class="docutils literal notranslate">ioctl</code> system calls<a class="headerlink" href="#module-fcntl" title="Permalink to this headline">¶</a></h1>
This module performs file control and I/O control on file descriptors. It is an
interface to the <code class="xref c c-func docutils literal notranslate">fcntl()</code> and <code class="xref c c-func docutils literal notranslate">ioctl()</code> Unix routines. For a
complete description of these calls, see fcntl(2) and
ioctl(2) Unix manual pages.
All functions in this module take a file descriptor fd as their first
argument. This can be an integer file descriptor, such as returned by
<code class="docutils literal notranslate">sys.stdin.fileno()</code>, or a file object, such as <code class="docutils literal notranslate">sys.stdin</code> itself, which
provides a <a class="reference internal" href="io.html#io.IOBase.fileno" title="io.IOBase.fileno"><code class="xref py py-meth docutils literal notranslate">fileno()</code></a> which returns a genuine file descriptor.
The module defines the following functions:
<dl class="py function">
<dt class="sig sig-object py" id="fcntl.fcntl">
fcntl.fcntl(fd, op[, arg])<a class="headerlink" href="#fcntl.fcntl" title="Permalink to this definition">¶</a></dt>
<dd>Perform the operation op on file descriptor fd (file objects providing
a <a class="reference internal" href="io.html#io.IOBase.fileno" title="io.IOBase.fileno"><code class="xref py py-meth docutils literal notranslate">fileno()</code></a> method are accepted as well). The values used
for for op are operating system dependent, and are available as constants
in the <a class="reference internal" href="#module-fcntl" title="fcntl: The fcntl() and ioctl() system calls. (Unix)"><code class="xref py py-mod docutils literal notranslate">fcntl</code></a> module, using the same names as used in the relevant C
header files. The argument arg is optional, and defaults to the integer
value <code class="docutils literal notranslate">0</code>. When present, it can either be an integer value, or a string.
With the argument missing or an integer value, the return value of this function
is the integer return value of the C <code class="xref c c-func docutils literal notranslate">fcntl()</code> call. When the argument is
a string it represents a binary structure, e.g. created by <a class="reference internal" href="struct.html#struct.pack" title="struct.pack"><code class="xref py py-func docutils literal notranslate">struct.pack()</code></a>.
The binary data is copied to a buffer whose address is passed to the C
<code class="xref c c-func docutils literal notranslate">fcntl()</code> call. The return value after a successful call is the contents
of the buffer, converted to a string object. The length of the returned string
will be the same as the length of the arg argument. This is limited to 1024
bytes. If the information returned in the buffer by the operating system is
larger than 1024 bytes, this is most likely to result in a segmentation
violation or a more subtle data corruption.
If the <code class="xref c c-func docutils literal notranslate">fcntl()</code> fails, an <code class="xref py py-exc docutils literal notranslate">IOError</code> is raised.
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="fcntl.ioctl">
fcntl.ioctl(fd, op[, arg[, mutate_flag]])<a class="headerlink" href="#fcntl.ioctl" title="Permalink to this definition">¶</a></dt>
<dd>This function is identical to the <a class="reference internal" href="#fcntl.fcntl" title="fcntl.fcntl"><code class="xref py py-func docutils literal notranslate">fcntl()</code></a> function, except that the
operations are typically defined in the library module <a class="reference internal" href="termios.html#module-termios" title="termios: POSIX style tty control. (Unix)"><code class="xref py py-mod docutils literal notranslate">termios</code></a> and the
argument handling is even more complicated.
The op parameter is limited to values that can fit in 32-bits.
Additional constants of interest for use as the op argument can be
found in the <a class="reference internal" href="termios.html#module-termios" title="termios: POSIX style tty control. (Unix)"><code class="xref py py-mod docutils literal notranslate">termios</code></a> module, under the same names as used in
the relevant C header files.
The parameter arg can be one of an integer, absent (treated identically to the
integer <code class="docutils literal notranslate">0</code>), an object supporting the read-only buffer interface (most likely
a plain Python string) or an object supporting the read-write buffer interface.
In all but the last case, behaviour is as for the <a class="reference internal" href="#fcntl.fcntl" title="fcntl.fcntl"><code class="xref py py-func docutils literal notranslate">fcntl()</code></a>
function.
If a mutable buffer is passed, then the behaviour is determined by the value of
the mutate_flag parameter.
If it is false, the buffer’s mutability is ignored and behaviour is as for a
read-only buffer, except that the 1024 byte limit mentioned above is avoided –
so long as the buffer you pass is as least as long as what the operating system
wants to put there, things should work.
If mutate_flag is true, then the buffer is (in effect) passed to the
underlying <a class="reference internal" href="#fcntl.ioctl" title="fcntl.ioctl"><code class="xref py py-func docutils literal notranslate">ioctl()</code></a> system call, the latter’s return code is passed back to
the calling Python, and the buffer’s new contents reflect the action of the
<a class="reference internal" href="#fcntl.ioctl" title="fcntl.ioctl"><code class="xref py py-func docutils literal notranslate">ioctl()</code></a>. This is a slight simplification, because if the supplied buffer
is less than 1024 bytes long it is first copied into a static buffer 1024 bytes
long which is then passed to <a class="reference internal" href="#fcntl.ioctl" title="fcntl.ioctl"><code class="xref py py-func docutils literal notranslate">ioctl()</code></a> and copied back into the supplied
buffer.
If mutate_flag is not supplied, then from Python 2.5 it defaults to true,
which is a change from versions 2.3 and 2.4. Supply the argument explicitly if
version portability is a priority.
If the <code class="xref c c-func docutils literal notranslate">ioctl()</code> fails, an <code class="xref py py-exc docutils literal notranslate">IOError</code> exception is raised.
An example:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; import array, fcntl, struct, termios, os
&gt;&gt;&gt; os.getpgrp()
13341
&gt;&gt;&gt; struct.unpack(&#39;h&#39;, fcntl.ioctl(0, termios.TIOCGPGRP, &quot; &quot;))[0]
13341
&gt;&gt;&gt; buf = array.array(&#39;h&#39;, [0])
&gt;&gt;&gt; fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
0
&gt;&gt;&gt; buf
array(&#39;h&#39;, [13341])
</pre></div>
</div>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="fcntl.flock">
fcntl.flock(fd, op)<a class="headerlink" href="#fcntl.flock" title="Permalink to this definition">¶</a></dt>
<dd>Perform the lock operation op on file descriptor fd (file objects providing
a <a class="reference internal" href="io.html#io.IOBase.fileno" title="io.IOBase.fileno"><code class="xref py py-meth docutils literal notranslate">fileno()</code></a> method are accepted as well). See the Unix manual
flock(2) for details. (On some systems, this function is emulated
using <code class="xref c c-func docutils literal notranslate">fcntl()</code>.)
If the <code class="xref c c-func docutils literal notranslate">flock()</code> fails, an <code class="xref py py-exc docutils literal notranslate">IOError</code> exception is raised.
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="fcntl.lockf">
fcntl.lockf(fd, operation[, length[, start[, whence]]])<a class="headerlink" href="#fcntl.lockf" title="Permalink to this definition">¶</a></dt>
<dd>This is essentially a wrapper around the <a class="reference internal" href="#fcntl.fcntl" title="fcntl.fcntl"><code class="xref py py-func docutils literal notranslate">fcntl()</code></a> locking calls.
fd is the file descriptor of the file to lock or unlock, and operation
is one of the following values:
<ul class="simple">
<li><code class="xref py py-const docutils literal notranslate">LOCK_UN</code> – unlock</li>
<li><code class="xref py py-const docutils literal notranslate">LOCK_SH</code> – acquire a shared lock</li>
<li><code class="xref py py-const docutils literal notranslate">LOCK_EX</code> – acquire an exclusive lock</li>
</ul>
When operation is <code class="xref py py-const docutils literal notranslate">LOCK_SH</code> or <code class="xref py py-const docutils literal notranslate">LOCK_EX</code>, it can also be
bitwise ORed with <code class="xref py py-const docutils literal notranslate">LOCK_NB</code> to avoid blocking on lock acquisition.
If <code class="xref py py-const docutils literal notranslate">LOCK_NB</code> is used and the lock cannot be acquired, an
<code class="xref py py-exc docutils literal notranslate">IOError</code> will be raised and the exception will have an errno
attribute set to <code class="xref py py-const docutils literal notranslate">EACCES</code> or <code class="xref py py-const docutils literal notranslate">EAGAIN</code> (depending on the
operating system; for portability, check for both values). On at least some
systems, <code class="xref py py-const docutils literal notranslate">LOCK_EX</code> can only be used if the file descriptor refers to a
file opened for writing.
length is the number of bytes to lock, start is the byte offset at
which the lock starts, relative to whence, and whence is as with
<a class="reference internal" href="io.html#io.IOBase.seek" title="io.IOBase.seek"><code class="xref py py-func docutils literal notranslate">io.IOBase.seek()</code></a>, specifically:
<ul class="simple">
<li><code class="xref py py-const docutils literal notranslate">0</code> – relative to the start of the file (<a class="reference internal" href="os.html#os.SEEK_SET" title="os.SEEK_SET"><code class="xref py py-data docutils literal notranslate">os.SEEK_SET</code></a>)</li>
<li><code class="xref py py-const docutils literal notranslate">1</code> – relative to the current buffer position (<a class="reference internal" href="os.html#os.SEEK_CUR" title="os.SEEK_CUR"><code class="xref py py-data docutils literal notranslate">os.SEEK_CUR</code></a>)</li>
<li><code class="xref py py-const docutils literal notranslate">2</code> – relative to the end of the file (<a class="reference internal" href="os.html#os.SEEK_END" title="os.SEEK_END"><code class="xref py py-data docutils literal notranslate">os.SEEK_END</code></a>)</li>
</ul>
The default for start is 0, which means to start at the beginning of the file.
The default for length is 0 which means to lock to the end of the file. The
default for whence is also 0.
</dd></dl>

Examples (all on a SVR4 compliant system):
<div class="highlight-default notranslate"><div class="highlight"><pre>import struct, fcntl, os

f = open(...)
rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)

lockdata = struct.pack(&#39;hhllhh&#39;, fcntl.F_WRLCK, 0, 0, 0, 0, 0)
rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)
</pre></div>
</div>
Note that in the first example the return value variable rv will hold an
integer value; in the second example it will hold a string value. The structure
lay-out for the lockdata variable is system dependent — therefore using the
<a class="reference internal" href="#fcntl.flock" title="fcntl.flock"><code class="xref py py-func docutils literal notranslate">flock()</code></a> call may be better.
<div class="admonition seealso">
See also
<dl class="simple">
<dt>Module <a class="reference internal" href="os.html#module-os" title="os: Miscellaneous operating system interfaces."><code class="xref py py-mod docutils literal notranslate">os</code></a></dt><dd>If the locking flags <a class="reference internal" href="os.html#os.O_SHLOCK" title="os.O_SHLOCK"><code class="xref py py-data docutils literal notranslate">O_SHLOCK</code></a> and <a class="reference internal" href="os.html#os.O_EXLOCK" title="os.O_EXLOCK"><code class="xref py py-data docutils literal notranslate">O_EXLOCK</code></a> are
present in the <a class="reference internal" href="os.html#module-os" title="os: Miscellaneous operating system interfaces."><code class="xref py py-mod docutils literal notranslate">os</code></a> module (on BSD only), the <a class="reference internal" href="os.html#os.open" title="os.open"><code class="xref py py-func docutils literal notranslate">os.open()</code></a>
function provides an alternative to the <a class="reference internal" href="#fcntl.lockf" title="fcntl.lockf"><code class="xref py py-func docutils literal notranslate">lockf()</code></a> and <a class="reference internal" href="#fcntl.flock" title="fcntl.flock"><code class="xref py py-func docutils literal notranslate">flock()</code></a>
functions.
</dd>
</dl>
</div>
</section>

<div class="clearer"></div>
 </div>
 </div>
 </div>
 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 <div class="sphinxsidebarwrapper">
 <h4>Previous topic</h4>
 <a href="pty.html"
 title="previous chapter">36.9. <code class="xref py py-mod docutils literal notranslate">pty</code> — Pseudo-terminal utilities</a>
 <h4>Next topic</h4>
 <a href="pipes.html"
 title="next chapter">36.11. <code class="xref py py-mod docutils literal notranslate">pipes</code> — Interface to shell pipelines</a>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="../_sources/library/fcntl.rst.txt"
 rel="nofollow">Show Source</a></li>
 </ul>
 </div>
<div id="searchbox" style="display: none" role="search">
 <h3 id="searchlabel">Quick search</h3>
 <div class="searchformwrapper">
 <form class="search" action="../search.html" method="get">
 <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
 <input type="submit" value="Go" />
 </form>
 </div>
</div>
<script>$('#searchbox').show(0);</script>
 </div>
 </div>
 <div class="clearer"></div>
 </div> 
 <div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../genindex.html" title="General Index"
 >index</a></li>
 <li class="right" >
 <a href="../py-modindex.html" title="Python Module Index"
 >modules</a> |</li>
 <li class="right" >
 <a href="pipes.html" title="36.11. pipes — Interface to shell pipelines"
 >next</a> |</li>
 <li class="right" >
 <a href="pty.html" title="36.9. pty — Pseudo-terminal utilities"
 >previous</a> |</li>
 <li><img src="../_static/py.png" alt=""
 style="vertical-align: middle; margin-top: -1px"/></li>
 <li><a href="https://www.python.org/">Python</a> &#187;</li>
 <li>
 <a href="../index.html">Python 2.7.18 documentation</a> &#187;
 </li>

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
 <li class="nav-item nav-item-2"><a href="unix.html" >36. Unix Specific Services</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">36.10. <code class="xref py py-mod docutils literal notranslate">fcntl</code> — The <code class="docutils literal notranslate">fcntl</code> and <code class="docutils literal notranslate">ioctl</code> system calls</a></li> 
 </ul>
 </div> 
 <div class="footer">
 &copy; <a href="../copyright.html">Copyright</a> 1990-2024, Python Software Foundation.
 
 The Python Software Foundation is a non-profit corporation.
 <a href="https://www.python.org/psf/donations/">Please donate.</a>
 
 Last updated on November 21, 2024.
 <a href="../bugs.html">Found a bug</a>?
 
 Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 4.3.2.
 </div>

</body>
</html>