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