Serhiy Storchaka | 926099d | 2013-10-09 14:20:22 +0300 | [diff] [blame] | 1 | :mod:`fcntl` --- The ``fcntl`` and ``ioctl`` system calls |
| 2 | ========================================================= |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
| 4 | .. module:: fcntl |
| 5 | :platform: Unix |
| 6 | :synopsis: The fcntl() and ioctl() system calls. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 8 | .. sectionauthor:: Jaap Vermeulen |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 9 | |
| 10 | .. index:: |
Georg Brandl | 8569e58 | 2010-05-19 20:57:08 +0000 | [diff] [blame] | 11 | pair: UNIX; file control |
| 12 | pair: UNIX; I/O control |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 14 | ---------------- |
| 15 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 16 | This module performs file control and I/O control on file descriptors. It is an |
Senthil Kumaran | 0779129 | 2016-06-02 23:49:05 -0700 | [diff] [blame] | 17 | interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. For a |
| 18 | complete description of these calls, see :manpage:`fcntl(2)` and |
| 19 | :manpage:`ioctl(2)` Unix manual pages. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 20 | |
| 21 | All functions in this module take a file descriptor *fd* as their first |
| 22 | argument. This can be an integer file descriptor, such as returned by |
Martin Panter | 7462b649 | 2015-11-02 03:37:02 +0000 | [diff] [blame] | 23 | ``sys.stdin.fileno()``, or an :class:`io.IOBase` object, such as ``sys.stdin`` |
Serhiy Storchaka | 926099d | 2013-10-09 14:20:22 +0300 | [diff] [blame] | 24 | itself, which provides a :meth:`~io.IOBase.fileno` that returns a genuine file |
| 25 | descriptor. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 27 | .. versionchanged:: 3.3 |
Martin Panter | 7462b649 | 2015-11-02 03:37:02 +0000 | [diff] [blame] | 28 | Operations in this module used to raise an :exc:`IOError` where they now |
| 29 | raise an :exc:`OSError`. |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 30 | |
| 31 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 32 | The module defines the following functions: |
| 33 | |
| 34 | |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 35 | .. function:: fcntl(fd, cmd, arg=0) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 36 | |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 37 | Perform the operation *cmd* on file descriptor *fd* (file objects providing |
R David Murray | d5a2f0b | 2013-11-07 10:51:07 -0500 | [diff] [blame] | 38 | a :meth:`~io.IOBase.fileno` method are accepted as well). The values used |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 39 | for *cmd* are operating system dependent, and are available as constants |
R David Murray | d5a2f0b | 2013-11-07 10:51:07 -0500 | [diff] [blame] | 40 | in the :mod:`fcntl` module, using the same names as used in the relevant C |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 41 | header files. The argument *arg* can either be an integer value, or a |
| 42 | :class:`bytes` object. With an integer value, the return value of this |
| 43 | function is the integer return value of the C :c:func:`fcntl` call. When |
| 44 | the argument is bytes it represents a binary structure, e.g. created by |
| 45 | :func:`struct.pack`. The binary data is copied to a buffer whose address is |
| 46 | passed to the C :c:func:`fcntl` call. The return value after a successful |
| 47 | call is the contents of the buffer, converted to a :class:`bytes` object. |
| 48 | The length of the returned object will be the same as the length of the |
| 49 | *arg* argument. This is limited to 1024 bytes. If the information returned |
| 50 | in the buffer by the operating system is larger than 1024 bytes, this is |
| 51 | most likely to result in a segmentation violation or a more subtle data |
| 52 | corruption. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 53 | |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 54 | If the :c:func:`fcntl` fails, an :exc:`OSError` is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 55 | |
| 56 | |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 57 | .. function:: ioctl(fd, request, arg=0, mutate_flag=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 58 | |
Serhiy Storchaka | 926099d | 2013-10-09 14:20:22 +0300 | [diff] [blame] | 59 | This function is identical to the :func:`~fcntl.fcntl` function, except |
| 60 | that the argument handling is even more complicated. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 61 | |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 62 | The *request* parameter is limited to values that can fit in 32-bits. |
| 63 | Additional constants of interest for use as the *request* argument can be |
R David Murray | d5a2f0b | 2013-11-07 10:51:07 -0500 | [diff] [blame] | 64 | found in the :mod:`termios` module, under the same names as used in |
| 65 | the relevant C header files. |
Christian Heimes | e25f35e | 2008-03-20 10:49:03 +0000 | [diff] [blame] | 66 | |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 67 | The parameter *arg* can be one of an integer, an object supporting the |
| 68 | read-only buffer interface (like :class:`bytes`) or an object supporting |
| 69 | the read-write buffer interface (like :class:`bytearray`). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 70 | |
Serhiy Storchaka | 926099d | 2013-10-09 14:20:22 +0300 | [diff] [blame] | 71 | In all but the last case, behaviour is as for the :func:`~fcntl.fcntl` |
| 72 | function. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | |
| 74 | If a mutable buffer is passed, then the behaviour is determined by the value of |
| 75 | the *mutate_flag* parameter. |
| 76 | |
| 77 | If it is false, the buffer's mutability is ignored and behaviour is as for a |
| 78 | read-only buffer, except that the 1024 byte limit mentioned above is avoided -- |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 79 | so long as the buffer you pass is at least as long as what the operating system |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 80 | wants to put there, things should work. |
| 81 | |
Georg Brandl | 71515ca | 2009-05-17 12:29:12 +0000 | [diff] [blame] | 82 | If *mutate_flag* is true (the default), then the buffer is (in effect) passed |
| 83 | to the underlying :func:`ioctl` system call, the latter's return code is |
| 84 | passed back to the calling Python, and the buffer's new contents reflect the |
| 85 | action of the :func:`ioctl`. This is a slight simplification, because if the |
| 86 | supplied buffer is less than 1024 bytes long it is first copied into a static |
| 87 | buffer 1024 bytes long which is then passed to :func:`ioctl` and copied back |
| 88 | into the supplied buffer. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 89 | |
Victor Stinner | d0d5154 | 2016-04-09 11:32:58 +0200 | [diff] [blame] | 90 | If the :c:func:`ioctl` fails, an :exc:`OSError` exception is raised. |
Victor Stinner | 9cccfce | 2015-11-13 09:13:48 +0100 | [diff] [blame] | 91 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | An example:: |
| 93 | |
| 94 | >>> import array, fcntl, struct, termios, os |
| 95 | >>> os.getpgrp() |
| 96 | 13341 |
| 97 | >>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0] |
| 98 | 13341 |
| 99 | >>> buf = array.array('h', [0]) |
| 100 | >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1) |
| 101 | 0 |
| 102 | >>> buf |
| 103 | array('h', [13341]) |
| 104 | |
| 105 | |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 106 | .. function:: flock(fd, operation) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 107 | |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 108 | Perform the lock operation *operation* on file descriptor *fd* (file objects providing |
Serhiy Storchaka | 926099d | 2013-10-09 14:20:22 +0300 | [diff] [blame] | 109 | a :meth:`~io.IOBase.fileno` method are accepted as well). See the Unix manual |
Georg Brandl | ec80688 | 2009-06-04 10:23:20 +0000 | [diff] [blame] | 110 | :manpage:`flock(2)` for details. (On some systems, this function is emulated |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 111 | using :c:func:`fcntl`.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 112 | |
Victor Stinner | d0d5154 | 2016-04-09 11:32:58 +0200 | [diff] [blame] | 113 | If the :c:func:`flock` fails, an :exc:`OSError` exception is raised. |
Victor Stinner | 9cccfce | 2015-11-13 09:13:48 +0100 | [diff] [blame] | 114 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 116 | .. function:: lockf(fd, cmd, len=0, start=0, whence=0) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 117 | |
Serhiy Storchaka | 926099d | 2013-10-09 14:20:22 +0300 | [diff] [blame] | 118 | This is essentially a wrapper around the :func:`~fcntl.fcntl` locking calls. |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 119 | *fd* is the file descriptor of the file to lock or unlock, and *cmd* |
Serhiy Storchaka | 926099d | 2013-10-09 14:20:22 +0300 | [diff] [blame] | 120 | is one of the following values: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 121 | |
| 122 | * :const:`LOCK_UN` -- unlock |
| 123 | * :const:`LOCK_SH` -- acquire a shared lock |
| 124 | * :const:`LOCK_EX` -- acquire an exclusive lock |
| 125 | |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 126 | When *cmd* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be |
Christian Heimes | faf2f63 | 2008-01-06 16:59:19 +0000 | [diff] [blame] | 127 | bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 128 | If :const:`LOCK_NB` is used and the lock cannot be acquired, an |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 129 | :exc:`OSError` will be raised and the exception will have an *errno* |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 130 | attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the |
| 131 | operating system; for portability, check for both values). On at least some |
| 132 | systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a |
| 133 | file opened for writing. |
| 134 | |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 135 | *len* is the number of bytes to lock, *start* is the byte offset at |
Serhiy Storchaka | 926099d | 2013-10-09 14:20:22 +0300 | [diff] [blame] | 136 | which the lock starts, relative to *whence*, and *whence* is as with |
| 137 | :func:`io.IOBase.seek`, specifically: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 138 | |
Serhiy Storchaka | 926099d | 2013-10-09 14:20:22 +0300 | [diff] [blame] | 139 | * :const:`0` -- relative to the start of the file (:data:`os.SEEK_SET`) |
| 140 | * :const:`1` -- relative to the current buffer position (:data:`os.SEEK_CUR`) |
| 141 | * :const:`2` -- relative to the end of the file (:data:`os.SEEK_END`) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 142 | |
| 143 | The default for *start* is 0, which means to start at the beginning of the file. |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 144 | The default for *len* is 0 which means to lock to the end of the file. The |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 145 | default for *whence* is also 0. |
| 146 | |
| 147 | Examples (all on a SVR4 compliant system):: |
| 148 | |
| 149 | import struct, fcntl, os |
| 150 | |
| 151 | f = open(...) |
| 152 | rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY) |
| 153 | |
| 154 | lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0) |
| 155 | rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata) |
| 156 | |
| 157 | Note that in the first example the return value variable *rv* will hold an |
Serhiy Storchaka | 17d3a58 | 2015-03-20 20:04:21 +0200 | [diff] [blame] | 158 | integer value; in the second example it will hold a :class:`bytes` object. The |
| 159 | structure lay-out for the *lockdata* variable is system dependent --- therefore |
| 160 | using the :func:`flock` call may be better. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 161 | |
| 162 | |
| 163 | .. seealso:: |
| 164 | |
| 165 | Module :mod:`os` |
Serhiy Storchaka | 926099d | 2013-10-09 14:20:22 +0300 | [diff] [blame] | 166 | If the locking flags :data:`~os.O_SHLOCK` and :data:`~os.O_EXLOCK` are |
| 167 | present in the :mod:`os` module (on BSD only), the :func:`os.open` |
| 168 | function provides an alternative to the :func:`lockf` and :func:`flock` |
| 169 | functions. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 170 | |