diff options
Diffstat (limited to 'devdocs/python~3.12/library%2Ffcntl.html')
| -rw-r--r-- | devdocs/python~3.12/library%2Ffcntl.html | 45 |
1 files changed, 45 insertions, 0 deletions
diff --git a/devdocs/python~3.12/library%2Ffcntl.html b/devdocs/python~3.12/library%2Ffcntl.html new file mode 100644 index 00000000..e261333e --- /dev/null +++ b/devdocs/python~3.12/library%2Ffcntl.html @@ -0,0 +1,45 @@ + <span id="fcntl-the-fcntl-and-ioctl-system-calls"></span><h1>fcntl — The fcntl and ioctl system calls</h1> <p>This module performs file control and I/O control on file descriptors. It is an interface to the <code>fcntl()</code> and <code>ioctl()</code> Unix routines. For a complete description of these calls, see <em class="manpage"><a class="manpage reference external" href="https://manpages.debian.org/fcntl(2)">fcntl(2)</a></em> and <em class="manpage"><a class="manpage reference external" href="https://manpages.debian.org/ioctl(2)">ioctl(2)</a></em> Unix manual pages.</p> <div class="availability docutils container"> <p><a class="reference internal" href="https://docs.python.org/3.12/library/intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, not Emscripten, not WASI.</p> </div> <p>All functions in this module take a file descriptor <em>fd</em> as their first argument. This can be an integer file descriptor, such as returned by <code>sys.stdin.fileno()</code>, or an <a class="reference internal" href="io#io.IOBase" title="io.IOBase"><code>io.IOBase</code></a> object, such as <code>sys.stdin</code> itself, which provides a <a class="reference internal" href="io#io.IOBase.fileno" title="io.IOBase.fileno"><code>fileno()</code></a> that returns a genuine file descriptor.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span>Operations in this module used to raise an <a class="reference internal" href="exceptions#IOError" title="IOError"><code>IOError</code></a> where they now raise an <a class="reference internal" href="exceptions#OSError" title="OSError"><code>OSError</code></a>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>The fcntl module now contains <code>F_ADD_SEALS</code>, <code>F_GET_SEALS</code>, and <code>F_SEAL_*</code> constants for sealing of <a class="reference internal" href="os#os.memfd_create" title="os.memfd_create"><code>os.memfd_create()</code></a> file descriptors.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.9: </span>On macOS, the fcntl module exposes the <code>F_GETPATH</code> constant, which obtains the path of a file from a file descriptor. On Linux(>=3.15), the fcntl module exposes the <code>F_OFD_GETLK</code>, <code>F_OFD_SETLK</code> and <code>F_OFD_SETLKW</code> constants, which are used when working with open file description locks.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>On Linux >= 2.6.11, the fcntl module exposes the <code>F_GETPIPE_SZ</code> and <code>F_SETPIPE_SZ</code> constants, which allow to check and modify a pipe’s size respectively.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span>On FreeBSD, the fcntl module exposes the <code>F_DUP2FD</code> and <code>F_DUP2FD_CLOEXEC</code> constants, which allow to duplicate a file descriptor, the latter setting <code>FD_CLOEXEC</code> flag in addition.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>On Linux >= 4.5, the <a class="reference internal" href="#module-fcntl" title="fcntl: The fcntl() and ioctl() system calls. (Unix)"><code>fcntl</code></a> module exposes the <code>FICLONE</code> and <code>FICLONERANGE</code> constants, which allow to share some data of one file with another file by reflinking on some filesystems (e.g., btrfs, OCFS2, and XFS). This behavior is commonly referred to as “copy-on-write”.</p> </div> <p>The module defines the following functions:</p> <dl class="py function"> <dt class="sig sig-object py" id="fcntl.fcntl"> +<code>fcntl.fcntl(fd, cmd, arg=0)</code> </dt> <dd> +<p>Perform the operation <em>cmd</em> on file descriptor <em>fd</em> (file objects providing a <a class="reference internal" href="io#io.IOBase.fileno" title="io.IOBase.fileno"><code>fileno()</code></a> method are accepted as well). The values used for <em>cmd</em> 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>fcntl</code></a> module, using the same names as used in the relevant C header files. The argument <em>arg</em> can either be an integer value, or a <a class="reference internal" href="stdtypes#bytes" title="bytes"><code>bytes</code></a> object. With an integer value, the return value of this function is the integer return value of the C <code>fcntl()</code> call. When the argument is bytes it represents a binary structure, e.g. created by <a class="reference internal" href="struct#struct.pack" title="struct.pack"><code>struct.pack()</code></a>. The binary data is copied to a buffer whose address is passed to the C <code>fcntl()</code> call. The return value after a successful call is the contents of the buffer, converted to a <a class="reference internal" href="stdtypes#bytes" title="bytes"><code>bytes</code></a> object. The length of the returned object will be the same as the length of the <em>arg</em> 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.</p> <p>If the <code>fcntl()</code> fails, an <a class="reference internal" href="exceptions#OSError" title="OSError"><code>OSError</code></a> is raised.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>fcntl.fcntl</code> with arguments <code>fd</code>, <code>cmd</code>, <code>arg</code>.</p> </dd> +</dl> <dl class="py function"> <dt class="sig sig-object py" id="fcntl.ioctl"> +<code>fcntl.ioctl(fd, request, arg=0, mutate_flag=True)</code> </dt> <dd> +<p>This function is identical to the <a class="reference internal" href="#fcntl.fcntl" title="fcntl.fcntl"><code>fcntl()</code></a> function, except that the argument handling is even more complicated.</p> <p>The <em>request</em> parameter is limited to values that can fit in 32-bits. Additional constants of interest for use as the <em>request</em> argument can be found in the <a class="reference internal" href="termios#module-termios" title="termios: POSIX style tty control. (Unix)"><code>termios</code></a> module, under the same names as used in the relevant C header files.</p> <p>The parameter <em>arg</em> can be one of an integer, an object supporting the read-only buffer interface (like <a class="reference internal" href="stdtypes#bytes" title="bytes"><code>bytes</code></a>) or an object supporting the read-write buffer interface (like <a class="reference internal" href="stdtypes#bytearray" title="bytearray"><code>bytearray</code></a>).</p> <p>In all but the last case, behaviour is as for the <a class="reference internal" href="#fcntl.fcntl" title="fcntl.fcntl"><code>fcntl()</code></a> function.</p> <p>If a mutable buffer is passed, then the behaviour is determined by the value of the <em>mutate_flag</em> parameter.</p> <p>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 at least as long as what the operating system wants to put there, things should work.</p> <p>If <em>mutate_flag</em> is true (the default), then the buffer is (in effect) passed to the underlying <a class="reference internal" href="#fcntl.ioctl" title="fcntl.ioctl"><code>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>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>ioctl()</code></a> and copied back into the supplied buffer.</p> <p>If the <code>ioctl()</code> fails, an <a class="reference internal" href="exceptions#OSError" title="OSError"><code>OSError</code></a> exception is raised.</p> <p>An example:</p> <pre data-language="python">>>> import array, fcntl, struct, termios, os +>>> os.getpgrp() +13341 +>>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0] +13341 +>>> buf = array.array('h', [0]) +>>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1) +0 +>>> buf +array('h', [13341]) +</pre> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>fcntl.ioctl</code> with arguments <code>fd</code>, <code>request</code>, <code>arg</code>.</p> </dd> +</dl> <dl class="py function"> <dt class="sig sig-object py" id="fcntl.flock"> +<code>fcntl.flock(fd, operation)</code> </dt> <dd> +<p>Perform the lock operation <em>operation</em> on file descriptor <em>fd</em> (file objects providing a <a class="reference internal" href="io#io.IOBase.fileno" title="io.IOBase.fileno"><code>fileno()</code></a> method are accepted as well). See the Unix manual <em class="manpage"><a class="manpage reference external" href="https://manpages.debian.org/flock(2)">flock(2)</a></em> for details. (On some systems, this function is emulated using <code>fcntl()</code>.)</p> <p>If the <code>flock()</code> fails, an <a class="reference internal" href="exceptions#OSError" title="OSError"><code>OSError</code></a> exception is raised.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>fcntl.flock</code> with arguments <code>fd</code>, <code>operation</code>.</p> </dd> +</dl> <dl class="py function"> <dt class="sig sig-object py" id="fcntl.lockf"> +<code>fcntl.lockf(fd, cmd, len=0, start=0, whence=0)</code> </dt> <dd> +<p>This is essentially a wrapper around the <a class="reference internal" href="#fcntl.fcntl" title="fcntl.fcntl"><code>fcntl()</code></a> locking calls. <em>fd</em> is the file descriptor (file objects providing a <a class="reference internal" href="io#io.IOBase.fileno" title="io.IOBase.fileno"><code>fileno()</code></a> method are accepted as well) of the file to lock or unlock, and <em>cmd</em> is one of the following values:</p> <ul class="simple"> <li> +<code>LOCK_UN</code> – unlock</li> <li> +<code>LOCK_SH</code> – acquire a shared lock</li> <li> +<code>LOCK_EX</code> – acquire an exclusive lock</li> </ul> <p>When <em>cmd</em> is <code>LOCK_SH</code> or <code>LOCK_EX</code>, it can also be bitwise ORed with <code>LOCK_NB</code> to avoid blocking on lock acquisition. If <code>LOCK_NB</code> is used and the lock cannot be acquired, an <a class="reference internal" href="exceptions#OSError" title="OSError"><code>OSError</code></a> will be raised and the exception will have an <em>errno</em> attribute set to <code>EACCES</code> or <code>EAGAIN</code> (depending on the operating system; for portability, check for both values). On at least some systems, <code>LOCK_EX</code> can only be used if the file descriptor refers to a file opened for writing.</p> <p><em>len</em> is the number of bytes to lock, <em>start</em> is the byte offset at which the lock starts, relative to <em>whence</em>, and <em>whence</em> is as with <a class="reference internal" href="io#io.IOBase.seek" title="io.IOBase.seek"><code>io.IOBase.seek()</code></a>, specifically:</p> <ul class="simple"> <li> +<code>0</code> – relative to the start of the file (<a class="reference internal" href="os#os.SEEK_SET" title="os.SEEK_SET"><code>os.SEEK_SET</code></a>)</li> <li> +<code>1</code> – relative to the current buffer position (<a class="reference internal" href="os#os.SEEK_CUR" title="os.SEEK_CUR"><code>os.SEEK_CUR</code></a>)</li> <li> +<code>2</code> – relative to the end of the file (<a class="reference internal" href="os#os.SEEK_END" title="os.SEEK_END"><code>os.SEEK_END</code></a>)</li> </ul> <p>The default for <em>start</em> is 0, which means to start at the beginning of the file. The default for <em>len</em> is 0 which means to lock to the end of the file. The default for <em>whence</em> is also 0.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>fcntl.lockf</code> with arguments <code>fd</code>, <code>cmd</code>, <code>len</code>, <code>start</code>, <code>whence</code>.</p> </dd> +</dl> <p>Examples (all on a SVR4 compliant system):</p> <pre data-language="python">import struct, fcntl, os + +f = open(...) +rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY) + +lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0) +rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata) +</pre> <p>Note that in the first example the return value variable <em>rv</em> will hold an integer value; in the second example it will hold a <a class="reference internal" href="stdtypes#bytes" title="bytes"><code>bytes</code></a> object. The structure lay-out for the <em>lockdata</em> variable is system dependent — therefore using the <a class="reference internal" href="#fcntl.flock" title="fcntl.flock"><code>flock()</code></a> call may be better.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt> +<code>Module</code> <a class="reference internal" href="os#module-os" title="os: Miscellaneous operating system interfaces."><code>os</code></a> +</dt> +<dd> +<p>If the locking flags <a class="reference internal" href="os#os.O_SHLOCK" title="os.O_SHLOCK"><code>O_SHLOCK</code></a> and <a class="reference internal" href="os#os.O_EXLOCK" title="os.O_EXLOCK"><code>O_EXLOCK</code></a> are present in the <a class="reference internal" href="os#module-os" title="os: Miscellaneous operating system interfaces."><code>os</code></a> module (on BSD only), the <a class="reference internal" href="os#os.open" title="os.open"><code>os.open()</code></a> function provides an alternative to the <a class="reference internal" href="#fcntl.lockf" title="fcntl.lockf"><code>lockf()</code></a> and <a class="reference internal" href="#fcntl.flock" title="fcntl.flock"><code>flock()</code></a> functions.</p> </dd> </dl> </div> <div class="_attribution"> + <p class="_attribution-p"> + © 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br> + <a href="https://docs.python.org/3.12/library/fcntl.html" class="_attribution-link">https://docs.python.org/3.12/library/fcntl.html</a> + </p> +</div> |