cpython/Doc/library/fcntl.rst

194 lines
8.0 KiB
ReStructuredText
Raw Normal View History

:mod:`fcntl` --- The ``fcntl`` and ``ioctl`` system calls
=========================================================
2007-08-15 11:28:22 -03:00
.. module:: fcntl
:platform: Unix
:synopsis: The fcntl() and ioctl() system calls.
.. sectionauthor:: Jaap Vermeulen
2007-08-15 11:28:22 -03:00
.. index::
Merged revisions 80030,80067,80069,80080-80081,80084,80432-80433,80465-80470,81059,81065-81067 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r80030 | georg.brandl | 2010-04-13 08:43:54 +0200 (Di, 13 Apr 2010) | 1 line Get rid of multi-row cells. ........ r80067 | georg.brandl | 2010-04-14 10:53:38 +0200 (Mi, 14 Apr 2010) | 1 line #5341: typo. ........ r80069 | georg.brandl | 2010-04-14 15:50:31 +0200 (Mi, 14 Apr 2010) | 1 line Add an x-ref to where the O_ constants are documented and move the SEEK_ constants after lseek(). ........ r80080 | georg.brandl | 2010-04-14 21:16:38 +0200 (Mi, 14 Apr 2010) | 1 line #8399: add note about Windows and O_BINARY. ........ r80081 | georg.brandl | 2010-04-14 23:34:44 +0200 (Mi, 14 Apr 2010) | 1 line #5250: document __instancecheck__ and __subclasscheck__. I hope the part about the class/metaclass distinction is understandable. ........ r80084 | georg.brandl | 2010-04-14 23:46:45 +0200 (Mi, 14 Apr 2010) | 1 line Fix missing. ........ r80432 | georg.brandl | 2010-04-24 10:56:58 +0200 (Sa, 24 Apr 2010) | 1 line Markup fixes. ........ r80433 | georg.brandl | 2010-04-24 11:08:10 +0200 (Sa, 24 Apr 2010) | 1 line #7507: quote "!" in pipes.quote(); it is a special character for some shells. ........ r80465 | georg.brandl | 2010-04-25 12:29:17 +0200 (So, 25 Apr 2010) | 1 line Remove LaTeXy index entry syntax. ........ r80466 | georg.brandl | 2010-04-25 12:54:42 +0200 (So, 25 Apr 2010) | 1 line Patch from Tim Hatch: Better cross-referencing in socket and winreg docs. ........ r80467 | georg.brandl | 2010-04-25 12:55:16 +0200 (So, 25 Apr 2010) | 1 line Patch from Tim Hatch: Remove reference to winreg being the fabled high-level registry interface. ........ r80468 | georg.brandl | 2010-04-25 12:55:58 +0200 (So, 25 Apr 2010) | 1 line Patch from Tim Hatch: Minor spelling changes to _winreg docs. ........ r80469 | georg.brandl | 2010-04-25 12:56:41 +0200 (So, 25 Apr 2010) | 1 line Fix code example to have valid syntax so that it can be highlighted. ........ r80470 | georg.brandl | 2010-04-25 12:57:15 +0200 (So, 25 Apr 2010) | 1 line Patch from Tim Hatch: Make socket setblocking <-> settimeout examples symmetric. ........ r81059 | georg.brandl | 2010-05-10 23:02:51 +0200 (Mo, 10 Mai 2010) | 1 line #8642: fix wrong function name. ........ r81065 | georg.brandl | 2010-05-10 23:46:50 +0200 (Mo, 10 Mai 2010) | 1 line Fix reference direction. ........ r81066 | georg.brandl | 2010-05-10 23:50:57 +0200 (Mo, 10 Mai 2010) | 1 line Consolidate deprecation messages. ........ r81067 | georg.brandl | 2010-05-10 23:51:33 +0200 (Mo, 10 Mai 2010) | 1 line Fix typo. ........
2010-05-19 17:57:08 -03:00
pair: UNIX; file control
pair: UNIX; I/O control
2007-08-15 11:28:22 -03:00
----------------
2007-08-15 11:28:22 -03:00
This module performs file control and I/O control on file descriptors. It is an
interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. For a
complete description of these calls, see :manpage:`fcntl(2)` and
:manpage:`ioctl(2)` Unix manual pages.
2007-08-15 11:28:22 -03:00
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
``sys.stdin.fileno()``, or an :class:`io.IOBase` object, such as ``sys.stdin``
itself, which provides a :meth:`~io.IOBase.fileno` that returns a genuine file
descriptor.
2007-08-15 11:28:22 -03:00
2011-10-12 15:10:51 -03:00
.. versionchanged:: 3.3
Operations in this module used to raise an :exc:`IOError` where they now
raise an :exc:`OSError`.
2011-10-12 15:10:51 -03:00
.. versionchanged:: 3.8
The fcntl module now contains ``F_ADD_SEALS``, ``F_GET_SEALS``, and
``F_SEAL_*`` constants for sealing of :func:`os.memfd_create` file
descriptors.
2011-10-12 15:10:51 -03:00
.. versionchanged:: 3.9
On macOS, the fcntl module exposes the ``F_GETPATH`` constant, which obtains
the path of a file from a file descriptor.
On Linux(>=3.15), the fcntl module exposes the ``F_OFD_GETLK``, ``F_OFD_SETLK``
and ``F_OFD_SETLKW`` constants, which working with open file description locks.
.. versionchanged:: 3.10
On Linux >= 2.6.11, the fcntl module exposes the ``F_GETPIPE_SZ`` and
``F_SETPIPE_SZ`` constants, which allow to check and modify a pipe's size
respectively.
2007-08-15 11:28:22 -03:00
The module defines the following functions:
.. function:: fcntl(fd, cmd, arg=0)
2007-08-15 11:28:22 -03:00
Perform the operation *cmd* on file descriptor *fd* (file objects providing
a :meth:`~io.IOBase.fileno` method are accepted as well). The values used
for *cmd* are operating system dependent, and are available as constants
in the :mod:`fcntl` module, using the same names as used in the relevant C
header files. The argument *arg* can either be an integer value, or a
:class:`bytes` object. With an integer value, the return value of this
function is the integer return value of the C :c:func:`fcntl` call. When
the argument is bytes it represents a binary structure, e.g. created by
:func:`struct.pack`. The binary data is copied to a buffer whose address is
passed to the C :c:func:`fcntl` call. The return value after a successful
call is the contents of the buffer, converted to a :class:`bytes` object.
The length of the returned object 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.
2007-08-15 11:28:22 -03:00
2011-10-12 15:10:51 -03:00
If the :c:func:`fcntl` fails, an :exc:`OSError` is raised.
2007-08-15 11:28:22 -03:00
.. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl
2007-08-15 11:28:22 -03:00
.. function:: ioctl(fd, request, arg=0, mutate_flag=True)
2007-08-15 11:28:22 -03:00
This function is identical to the :func:`~fcntl.fcntl` function, except
that the argument handling is even more complicated.
2007-08-15 11:28:22 -03:00
The *request* parameter is limited to values that can fit in 32-bits.
Additional constants of interest for use as the *request* argument can be
found in the :mod:`termios` module, under the same names as used in
the relevant C header files.
Merged revisions 61644,61646-61647,61649-61652,61656-61658,61663,61665,61667 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r61644 | trent.nelson | 2008-03-19 22:51:16 +0100 (Mi, 19 Mär 2008) | 1 line Force a clean of the tcltk/tcltk64 directories now that we've completely changed the tcl/tk build environment. ........ r61646 | gregory.p.smith | 2008-03-19 23:23:51 +0100 (Mi, 19 Mär 2008) | 2 lines Improve the error message when the CRCs don't match. ........ r61647 | trent.nelson | 2008-03-19 23:41:10 +0100 (Mi, 19 Mär 2008) | 1 line Comment out tcltk/tcltk64 removal. ........ r61649 | raymond.hettinger | 2008-03-19 23:47:48 +0100 (Mi, 19 Mär 2008) | 1 line Remove unnecessary traceback save/restore pair. ........ r61650 | trent.nelson | 2008-03-19 23:51:42 +0100 (Mi, 19 Mär 2008) | 1 line Bump the SIGALM delay from 3 seconds to 20 seconds, mainly in an effort to see if it fixes the alarm failures in this test experienced by some of the buildbots. ........ r61651 | brett.cannon | 2008-03-20 00:01:17 +0100 (Do, 20 Mär 2008) | 5 lines Make sure that the warnings filter is not reset or changed beyond the current running test file. Closes issue2407. Thanks Jerry Seutter. ........ r61652 | gregory.p.smith | 2008-03-20 00:03:25 +0100 (Do, 20 Mär 2008) | 10 lines Prevent ioctl op codes from being sign extended from int to unsigned long when used on platforms that actually define ioctl as taking an unsigned long. (the BSDs and OS X / Darwin) Adds a unittest for fcntl.ioctl that tests what happens with both positive and negative numbers. This was done because of issue1471 but I'm not able to reproduce -that- problem in the first place on Linux 32bit or 64bit or OS X 10.4 & 10.5 32bit or 64 bit. ........ r61656 | sean.reifschneider | 2008-03-20 01:46:50 +0100 (Do, 20 Mär 2008) | 2 lines Issue #2143: Fix embedded readline() hang on SSL socket EOF. ........ r61657 | sean.reifschneider | 2008-03-20 01:50:07 +0100 (Do, 20 Mär 2008) | 2 lines Forgot to add NEWS item about smtplib SSL readline hang fix. ........ r61658 | trent.nelson | 2008-03-20 01:58:44 +0100 (Do, 20 Mär 2008) | 1 line Revert r61650; the intent of this commit was to try and address alarm failures on some of the build slaves. As Neal points out, it's called after test_main(), so it's not going to factor into the test when run via regrtest.py (and removes the original functionality that Jeffrey wanted that would kill the test if it took longer than 3 seconds to run when executing it directly during development). ........ r61663 | sean.reifschneider | 2008-03-20 04:20:48 +0100 (Do, 20 Mär 2008) | 2 lines Issue 2188: Documentation hint about disabling proxy detection. ........ r61665 | gregory.p.smith | 2008-03-20 06:41:53 +0100 (Do, 20 Mär 2008) | 7 lines Attempt to fix the Solaris Sparc 10 buildbot. It was failing with an invalid argument error on ioctl. This was caused by the added test_fcntl ioctl test that hard coded 0 as the fd to use. Without a terminal, this fails on solaris. (it passed from the command line on sol 10, both 32 and 64 bit) Also, test_ioctl exists so I moved the test into there where it belongs. ........ r61667 | georg.brandl | 2008-03-20 08:25:55 +0100 (Do, 20 Mär 2008) | 2 lines #2383: remove obsolete XXX comment in stat.py. ........
2008-03-20 07:49:03 -03:00
The parameter *arg* can be one of an integer, an object supporting the
read-only buffer interface (like :class:`bytes`) or an object supporting
the read-write buffer interface (like :class:`bytearray`).
2007-08-15 11:28:22 -03:00
In all but the last case, behaviour is as for the :func:`~fcntl.fcntl`
function.
2007-08-15 11:28:22 -03:00
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 at least as long as what the operating system
2007-08-15 11:28:22 -03:00
wants to put there, things should work.
If *mutate_flag* is true (the default), then the buffer is (in effect) passed
to the underlying :func:`ioctl` 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 :func:`ioctl`. 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 :func:`ioctl` and copied back
into the supplied buffer.
2007-08-15 11:28:22 -03:00
If the :c:func:`ioctl` fails, an :exc:`OSError` exception is raised.
2007-08-15 11:28:22 -03:00
An example::
>>> 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])
.. audit-event:: fcntl.ioctl fd,request,arg fcntl.ioctl
2007-08-15 11:28:22 -03:00
.. function:: flock(fd, operation)
2007-08-15 11:28:22 -03:00
Perform the lock operation *operation* on file descriptor *fd* (file objects providing
a :meth:`~io.IOBase.fileno` method are accepted as well). See the Unix manual
:manpage:`flock(2)` for details. (On some systems, this function is emulated
using :c:func:`fcntl`.)
2007-08-15 11:28:22 -03:00
If the :c:func:`flock` fails, an :exc:`OSError` exception is raised.
.. audit-event:: fcntl.flock fd,operation fcntl.flock
2007-08-15 11:28:22 -03:00
.. function:: lockf(fd, cmd, len=0, start=0, whence=0)
2007-08-15 11:28:22 -03:00
This is essentially a wrapper around the :func:`~fcntl.fcntl` locking calls.
*fd* is the file descriptor (file objects providing a :meth:`~io.IOBase.fileno`
method are accepted as well) of the file to lock or unlock, and *cmd*
is one of the following values:
2007-08-15 11:28:22 -03:00
* :const:`LOCK_UN` -- unlock
* :const:`LOCK_SH` -- acquire a shared lock
* :const:`LOCK_EX` -- acquire an exclusive lock
When *cmd* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be
Merged revisions 59703-59773 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r59704 | christian.heimes | 2008-01-04 04:15:05 +0100 (Fri, 04 Jan 2008) | 1 line Moved include "Python.h" in front of other imports to silence a warning. ........ r59706 | raymond.hettinger | 2008-01-04 04:22:53 +0100 (Fri, 04 Jan 2008) | 10 lines Minor fix-ups to named tuples: * Make the _replace() method respect subclassing. * Using property() to make _fields read-only wasn't a good idea. It caused len(Point._fields) to fail. * Add note to _cast() about length checking and alternative with the star-operator. ........ r59707 | jeffrey.yasskin | 2008-01-04 09:01:23 +0100 (Fri, 04 Jan 2008) | 3 lines Make math.{floor,ceil}({int,long}) return float again for backwards compatibility after r59671 made them return integral types. ........ r59709 | christian.heimes | 2008-01-04 14:21:07 +0100 (Fri, 04 Jan 2008) | 1 line Bug #1713: posixpath.ismount() claims symlink to a mountpoint is a mountpoint. ........ r59712 | lars.gustaebel | 2008-01-04 15:00:33 +0100 (Fri, 04 Jan 2008) | 5 lines Issue #1735: TarFile.extractall() now correctly sets directory permissions and times. (will backport to 2.5) ........ r59714 | andrew.kuchling | 2008-01-04 15:47:17 +0100 (Fri, 04 Jan 2008) | 1 line Update links to bug/patch tracker ........ r59716 | christian.heimes | 2008-01-04 16:23:30 +0100 (Fri, 04 Jan 2008) | 1 line Added interface to Windows' WSAIoctl and a simple example for a network sniffer. ........ r59717 | christian.heimes | 2008-01-04 16:29:00 +0100 (Fri, 04 Jan 2008) | 1 line And here is the rest of Hirokazu Yamamoto's patch for VS6.0 support. Thanks Hiro! ........ r59719 | christian.heimes | 2008-01-04 16:34:06 +0100 (Fri, 04 Jan 2008) | 1 line Reverted last transaction. It's the wrong branch. ........ r59721 | christian.heimes | 2008-01-04 16:48:06 +0100 (Fri, 04 Jan 2008) | 1 line socket.ioctl is only available on Windows ........ r59722 | andrew.kuchling | 2008-01-04 19:24:41 +0100 (Fri, 04 Jan 2008) | 1 line Fix markup ........ r59723 | andrew.kuchling | 2008-01-04 19:25:05 +0100 (Fri, 04 Jan 2008) | 1 line Fix markup ........ r59725 | guido.van.rossum | 2008-01-05 01:59:59 +0100 (Sat, 05 Jan 2008) | 3 lines Patch #1725 by Mark Dickinson, fixes incorrect conversion of -1e1000 and adds errors for -0x. ........ r59726 | guido.van.rossum | 2008-01-05 02:21:57 +0100 (Sat, 05 Jan 2008) | 2 lines Patch #1698 by Senthil: allow '@' in username when parsed by urlparse.py. ........ r59727 | raymond.hettinger | 2008-01-05 02:35:43 +0100 (Sat, 05 Jan 2008) | 1 line Improve namedtuple's _cast() method with a docstring, new name, and error-checking. ........ r59728 | raymond.hettinger | 2008-01-05 03:17:24 +0100 (Sat, 05 Jan 2008) | 1 line Add error-checking to namedtuple's _replace() method. ........ r59730 | fred.drake | 2008-01-05 05:38:38 +0100 (Sat, 05 Jan 2008) | 2 lines clean up a comment ........ r59731 | jeffrey.yasskin | 2008-01-05 09:47:13 +0100 (Sat, 05 Jan 2008) | 11 lines Continue rolling back pep-3141 changes that changed behavior from 2.5. This round included: * Revert round to its 2.6 behavior (half away from 0). * Because round, floor, and ceil always return float again, it's no longer necessary to have them delegate to __xxx___, so I've ripped that out of their implementations and the Real ABC. This also helps in implementing types that work in both 2.6 and 3.0: you return int from the __xxx__ methods, and let it get enabled by the version upgrade. * Make pow(-1, .5) raise a ValueError again. ........ r59736 | andrew.kuchling | 2008-01-05 16:13:49 +0100 (Sat, 05 Jan 2008) | 1 line Fix comment typo ........ r59738 | thomas.heller | 2008-01-05 18:15:44 +0100 (Sat, 05 Jan 2008) | 1 line Add myself. ........ r59739 | georg.brandl | 2008-01-05 18:49:17 +0100 (Sat, 05 Jan 2008) | 2 lines Fix C++-style comment. ........ r59742 | georg.brandl | 2008-01-05 20:28:16 +0100 (Sat, 05 Jan 2008) | 2 lines Remove with_statement future imports from 2.6 docs. ........ r59743 | georg.brandl | 2008-01-05 20:29:45 +0100 (Sat, 05 Jan 2008) | 2 lines Simplify index entries; fix #1712. ........ r59744 | georg.brandl | 2008-01-05 20:44:22 +0100 (Sat, 05 Jan 2008) | 2 lines Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst. ........ r59749 | georg.brandl | 2008-01-05 21:29:13 +0100 (Sat, 05 Jan 2008) | 2 lines Revert socket.rst to unix-eol. ........ r59750 | georg.brandl | 2008-01-05 21:33:46 +0100 (Sat, 05 Jan 2008) | 2 lines Set native svn:eol-style property for text files. ........ r59752 | georg.brandl | 2008-01-05 21:46:29 +0100 (Sat, 05 Jan 2008) | 2 lines #1719: capitalization error in "UuidCreate". ........ r59753 | georg.brandl | 2008-01-05 22:02:25 +0100 (Sat, 05 Jan 2008) | 2 lines Repair markup. ........ r59754 | georg.brandl | 2008-01-05 22:10:50 +0100 (Sat, 05 Jan 2008) | 2 lines Use markup. ........ r59757 | christian.heimes | 2008-01-05 22:35:52 +0100 (Sat, 05 Jan 2008) | 1 line Final adjustments for #1601 ........ r59758 | guido.van.rossum | 2008-01-05 23:19:06 +0100 (Sat, 05 Jan 2008) | 3 lines Patch #1637: fix urlparse for URLs like 'http://x.com?arg=/foo'. Fix by John Nagle. ........ r59759 | guido.van.rossum | 2008-01-05 23:20:01 +0100 (Sat, 05 Jan 2008) | 2 lines Add John Nagle (of issue #1637). ........ r59765 | raymond.hettinger | 2008-01-06 10:02:24 +0100 (Sun, 06 Jan 2008) | 1 line Small code simplification. Forgot that classmethods can be called from intances. ........ r59766 | martin.v.loewis | 2008-01-06 11:09:48 +0100 (Sun, 06 Jan 2008) | 2 lines Use vcbuild for VS 2009. ........ r59767 | martin.v.loewis | 2008-01-06 12:03:43 +0100 (Sun, 06 Jan 2008) | 2 lines Package using VS 2008. ........ r59768 | martin.v.loewis | 2008-01-06 12:13:16 +0100 (Sun, 06 Jan 2008) | 2 lines Don't try to package msvcr90 for the moment. ........ r59769 | georg.brandl | 2008-01-06 15:17:36 +0100 (Sun, 06 Jan 2008) | 4 lines #1696393: don't check for '.' and '..' in ntpath.walk since they aren't returned from os.listdir anymore. Reported by Michael Haggerty. ........ r59770 | georg.brandl | 2008-01-06 15:27:15 +0100 (Sun, 06 Jan 2008) | 3 lines #1742: don't raise exception on os.path.relpath("a", "a"), but return os.curdir. Reported by Jesse Towner. ........ r59771 | georg.brandl | 2008-01-06 15:33:52 +0100 (Sun, 06 Jan 2008) | 2 lines #1591: Clarify docstring of Popen3. ........ r59772 | georg.brandl | 2008-01-06 16:30:34 +0100 (Sun, 06 Jan 2008) | 2 lines #1680: fix context manager example function name. ........ r59773 | georg.brandl | 2008-01-06 16:34:57 +0100 (Sun, 06 Jan 2008) | 2 lines #1755097: document default values for [].sort() and sorted(). ........
2008-01-06 12:59:19 -04:00
bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition.
2007-08-15 11:28:22 -03:00
If :const:`LOCK_NB` is used and the lock cannot be acquired, an
2011-10-12 15:10:51 -03:00
:exc:`OSError` will be raised and the exception will have an *errno*
2007-08-15 11:28:22 -03:00
attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the
operating system; for portability, check for both values). On at least some
systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a
file opened for writing.
*len* 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
:func:`io.IOBase.seek`, specifically:
2007-08-15 11:28:22 -03:00
* :const:`0` -- relative to the start of the file (:data:`os.SEEK_SET`)
* :const:`1` -- relative to the current buffer position (:data:`os.SEEK_CUR`)
* :const:`2` -- relative to the end of the file (:data:`os.SEEK_END`)
2007-08-15 11:28:22 -03:00
The default for *start* is 0, which means to start at the beginning of the file.
The default for *len* is 0 which means to lock to the end of the file. The
2007-08-15 11:28:22 -03:00
default for *whence* is also 0.
.. audit-event:: fcntl.lockf fd,cmd,len,start,whence fcntl.lockf
2007-08-15 11:28:22 -03:00
Examples (all on a SVR4 compliant system)::
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)
Note that in the first example the return value variable *rv* will hold an
integer value; in the second example it will hold a :class:`bytes` object. The
structure lay-out for the *lockdata* variable is system dependent --- therefore
using the :func:`flock` call may be better.
2007-08-15 11:28:22 -03:00
.. seealso::
Module :mod:`os`
If the locking flags :data:`~os.O_SHLOCK` and :data:`~os.O_EXLOCK` are
present in the :mod:`os` module (on BSD only), the :func:`os.open`
function provides an alternative to the :func:`lockf` and :func:`flock`
functions.