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