Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="lib.html" title='Python Library Reference' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='index' href='genindex.html' title='Index' /> | |
10 | <link rel='last' href='about.html' title='About this document...' /> | |
11 | <link rel='help' href='about.html' title='About this document...' /> | |
12 | <link rel="next" href="module-pipes.html" /> | |
13 | <link rel="prev" href="module-pty.html" /> | |
14 | <link rel="parent" href="unix.html" /> | |
15 | <link rel="next" href="module-pipes.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>8.11 fcntl -- The fcntl() and ioctl() system calls</title> | |
18 | </head> | |
19 | <body> | |
20 | <DIV CLASS="navigation"> | |
21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
23 | <tr> | |
24 | <td class='online-navigation'><a rel="prev" title="8.10 pty " | |
25 | href="module-pty.html"><img src='../icons/previous.png' | |
26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
27 | <td class='online-navigation'><a rel="parent" title="8. Unix Specific Services" | |
28 | href="unix.html"><img src='../icons/up.png' | |
29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
30 | <td class='online-navigation'><a rel="next" title="8.12 pipes " | |
31 | href="module-pipes.html"><img src='../icons/next.png' | |
32 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
33 | <td align="center" width="100%">Python Library Reference</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="contents.html"><img src='../icons/contents.png' | |
36 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
38 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
39 | <td class='online-navigation'><a rel="index" title="Index" | |
40 | href="genindex.html"><img src='../icons/index.png' | |
41 | border='0' height='32' alt='Index' width='32' /></A></td> | |
42 | </tr></table> | |
43 | <div class='online-navigation'> | |
44 | <b class="navlabel">Previous:</b> | |
45 | <a class="sectref" rel="prev" href="module-pty.html">8.10 pty </A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="unix.html">8. Unix Specific Services</A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="module-pipes.html">8.12 pipes </A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H1><A NAME="SECTION00101100000000000000000"> | |
56 | 8.11 <tt class="module">fcntl</tt> -- | |
57 | The <tt class="function">fcntl()</tt> and <tt class="function">ioctl()</tt> system calls</A> | |
58 | </H1> | |
59 | ||
60 | <P> | |
61 | <A NAME="module-fcntl"></A> | |
62 | <p class="availability">Availability: <span | |
63 | class="platform">Unix</span>.</p> | |
64 | ||
65 | <P> | |
66 | <a id='l2h-3024' xml:id='l2h-3024'></a><a id='l2h-3025' xml:id='l2h-3025'></a> | |
67 | <P> | |
68 | This module performs file control and I/O control on file descriptors. | |
69 | It is an interface to the <tt class="cfunction">fcntl()</tt> and <tt class="cfunction">ioctl()</tt> | |
70 | <span class="Unix">Unix</span> routines. | |
71 | ||
72 | <P> | |
73 | All functions in this module take a file descriptor <var>fd</var> as their | |
74 | first argument. This can be an integer file descriptor, such as | |
75 | returned by <code>sys.stdin.fileno()</code>, or a file object, such as | |
76 | <code>sys.stdin</code> itself, which provides a <tt class="method">fileno()</tt> which | |
77 | returns a genuine file descriptor. | |
78 | ||
79 | <P> | |
80 | The module defines the following functions: | |
81 | ||
82 | <P> | |
83 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
84 | <td><nobr><b><tt id='l2h-3026' xml:id='l2h-3026' class="function">fcntl</tt></b>(</nobr></td> | |
85 | <td><var>fd, op</var><big>[</big><var>, arg</var><big>]</big><var></var>)</td></tr></table></dt> | |
86 | <dd> | |
87 | Perform the requested operation on file descriptor <var>fd</var> (file | |
88 | objects providing a <tt class="method">fileno()</tt> method are accepted as well). | |
89 | The operation is defined by <var>op</var> and is operating system | |
90 | dependent. These codes are also found in the <tt class="module">fcntl</tt> | |
91 | module. The argument <var>arg</var> is optional, and defaults to the | |
92 | integer value <code>0</code>. When present, it can either be an integer | |
93 | value, or a string. With the argument missing or an integer value, | |
94 | the return value of this function is the integer return value of the | |
95 | C <tt class="cfunction">fcntl()</tt> call. When the argument is a string it | |
96 | represents a binary structure, e.g. created by | |
97 | <tt class="function"><tt class="module"><a href="module-struct.html">struct</a></tt>.pack()</tt>. The binary data is copied to a buffer | |
98 | whose address is passed to the C <tt class="cfunction">fcntl()</tt> call. The | |
99 | return value after a successful call is the contents of the buffer, | |
100 | converted to a string object. The length of the returned string | |
101 | will be the same as the length of the <var>arg</var> argument. This is | |
102 | limited to 1024 bytes. If the information returned in the buffer by | |
103 | the operating system is larger than 1024 bytes, this is most likely | |
104 | to result in a segmentation violation or a more subtle data | |
105 | corruption. | |
106 | ||
107 | <P> | |
108 | If the <tt class="cfunction">fcntl()</tt> fails, an <tt class="exception">IOError</tt> is | |
109 | raised. | |
110 | </dl> | |
111 | ||
112 | <P> | |
113 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
114 | <td><nobr><b><tt id='l2h-3027' xml:id='l2h-3027' class="function">ioctl</tt></b>(</nobr></td> | |
115 | <td><var>fd, op</var><big>[</big><var>, arg</var><big>[</big><var>, mutate_flag</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
116 | <dd> | |
117 | This function is identical to the <tt class="function">fcntl()</tt> function, | |
118 | except that the operations are typically defined in the library | |
119 | module <tt class="module"><a href="module-termios.html">termios</a></tt> and the argument handling is even more | |
120 | complicated. | |
121 | ||
122 | <P> | |
123 | The parameter <var>arg</var> can be one of an integer, absent (treated | |
124 | identically to the integer <code>0</code>), an object supporting the | |
125 | read-only buffer interface (most likely a plain Python string) or an | |
126 | object supporting the read-write buffer interface. | |
127 | ||
128 | <P> | |
129 | In all but the last case, behaviour is as for the <tt class="function">fcntl()</tt> | |
130 | function. | |
131 | ||
132 | <P> | |
133 | If a mutable buffer is passed, then the behaviour is determined by | |
134 | the value of the <var>mutate_flag</var> parameter. | |
135 | ||
136 | <P> | |
137 | If it is false, the buffer's mutability is ignored and behaviour is | |
138 | as for a read-only buffer, except that the 1024 byte limit mentioned | |
139 | above is avoided - so long as the buffer you pass is longer than | |
140 | what the operating system wants to put there, things should work. | |
141 | ||
142 | <P> | |
143 | If <var>mutate_flag</var> is true, then the buffer is (in effect) passed | |
144 | to the underlying <tt class="function">ioctl()</tt> system call, the latter's | |
145 | return code is passed back to the calling Python, and the buffer's | |
146 | new contents reflect the action of the <tt class="function">ioctl()</tt>. This is a | |
147 | slight simplification, because if the supplied buffer is less than | |
148 | 1024 bytes long it is first copied into a static buffer 1024 bytes | |
149 | long which is then passed to <tt class="function">ioctl()</tt> and copied back into | |
150 | the supplied buffer. | |
151 | ||
152 | <P> | |
153 | If <var>mutate_flag</var> is not supplied, then in 2.3 it defaults to | |
154 | false. This is planned to change over the next few Python versions: | |
155 | in 2.4 failing to supply <var>mutate_flag</var> will get a warning but | |
156 | the same behavior and in versions later than 2.5 it will default to | |
157 | true. | |
158 | ||
159 | <P> | |
160 | An example: | |
161 | ||
162 | <P> | |
163 | <div class="verbatim"><pre> | |
164 | >>> import array, fcntl, struct, termios, os | |
165 | >>> os.getpgrp() | |
166 | 13341 | |
167 | >>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0] | |
168 | 13341 | |
169 | >>> buf = array.array('h', [0]) | |
170 | >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1) | |
171 | 0 | |
172 | >>> buf | |
173 | array('h', [13341]) | |
174 | </pre></div> | |
175 | </dl> | |
176 | ||
177 | <P> | |
178 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
179 | <td><nobr><b><tt id='l2h-3028' xml:id='l2h-3028' class="function">flock</tt></b>(</nobr></td> | |
180 | <td><var>fd, op</var>)</td></tr></table></dt> | |
181 | <dd> | |
182 | Perform the lock operation <var>op</var> on file descriptor <var>fd</var> (file | |
183 | objects providing a <tt class="method">fileno()</tt> method are accepted as well). | |
184 | See the <span class="Unix">Unix</span> manual <span class="manpage"><i>flock</i>(3)</span> for details. (On some | |
185 | systems, this function is emulated using <tt class="cfunction">fcntl()</tt>.) | |
186 | </dl> | |
187 | ||
188 | <P> | |
189 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
190 | <td><nobr><b><tt id='l2h-3029' xml:id='l2h-3029' class="function">lockf</tt></b>(</nobr></td> | |
191 | <td><var>fd, operation, | |
192 | </var><big>[</big><var>length, </var><big>[</big><var>start, </var><big>[</big><var>whence</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
193 | <dd> | |
194 | This is essentially a wrapper around the <tt class="function">fcntl()</tt> locking | |
195 | calls. <var>fd</var> is the file descriptor of the file to lock or unlock, | |
196 | and <var>operation</var> is one of the following values: | |
197 | ||
198 | <P> | |
199 | ||
200 | <UL> | |
201 | <LI><tt class="constant">LOCK_UN</tt> - unlock | |
202 | </LI> | |
203 | <LI><tt class="constant">LOCK_SH</tt> - acquire a shared lock | |
204 | </LI> | |
205 | <LI><tt class="constant">LOCK_EX</tt> - acquire an exclusive lock | |
206 | </LI> | |
207 | </UL> | |
208 | ||
209 | <P> | |
210 | When <var>operation</var> is <tt class="constant">LOCK_SH</tt> or <tt class="constant">LOCK_EX</tt>, it | |
211 | can also be bit-wise OR'd with <tt class="constant">LOCK_NB</tt> to avoid blocking on | |
212 | lock acquisition. If <tt class="constant">LOCK_NB</tt> is used and the lock cannot | |
213 | be acquired, an <tt class="exception">IOError</tt> will be raised and the exception | |
214 | will have an <var>errno</var> attribute set to <tt class="constant">EACCES</tt> or | |
215 | <tt class="constant">EAGAIN</tt> (depending on the operating system; for portability, | |
216 | check for both values). On at least some systems, <tt class="constant">LOCK_EX</tt> | |
217 | can only be used if the file descriptor refers to a file opened for | |
218 | writing. | |
219 | ||
220 | <P> | |
221 | <var>length</var> is the number of bytes to lock, <var>start</var> is the byte | |
222 | offset at which the lock starts, relative to <var>whence</var>, and | |
223 | <var>whence</var> is as with <tt class="function">fileobj.seek()</tt>, specifically: | |
224 | ||
225 | <P> | |
226 | ||
227 | <UL> | |
228 | <LI><tt class="constant">0</tt> - relative to the start of the file | |
229 | (<tt class="constant">SEEK_SET</tt>) | |
230 | </LI> | |
231 | <LI><tt class="constant">1</tt> - relative to the current buffer position | |
232 | (<tt class="constant">SEEK_CUR</tt>) | |
233 | </LI> | |
234 | <LI><tt class="constant">2</tt> - relative to the end of the file | |
235 | (<tt class="constant">SEEK_END</tt>) | |
236 | </LI> | |
237 | </UL> | |
238 | ||
239 | <P> | |
240 | The default for <var>start</var> is 0, which means to start at the | |
241 | beginning of the file. The default for <var>length</var> is 0 which means | |
242 | to lock to the end of the file. The default for <var>whence</var> is also | |
243 | 0. | |
244 | </dl> | |
245 | ||
246 | <P> | |
247 | Examples (all on a SVR4 compliant system): | |
248 | ||
249 | <P> | |
250 | <div class="verbatim"><pre> | |
251 | import struct, fcntl, os | |
252 | ||
253 | f = open(...) | |
254 | rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY) | |
255 | ||
256 | lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0) | |
257 | rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata) | |
258 | </pre></div> | |
259 | ||
260 | <P> | |
261 | Note that in the first example the return value variable <var>rv</var> will | |
262 | hold an integer value; in the second example it will hold a string | |
263 | value. The structure lay-out for the <var>lockdata</var> variable is | |
264 | system dependent -- therefore using the <tt class="function">flock()</tt> call may be | |
265 | better. | |
266 | ||
267 | <P> | |
268 | <div class="seealso"> | |
269 | <p class="heading">See Also:</p> | |
270 | ||
271 | <dl compact="compact" class="seemodule"> | |
272 | <dt>Module <b><tt class="module"><a href="module-os.html">os</a></tt>:</b> | |
273 | <dd>The <tt class="function">os.open()</tt> function supports locking flags | |
274 | and is available on a wider variety of platforms than | |
275 | the <tt class="function">lockf()</tt> and <tt class="function">flock()</tt> | |
276 | functions, providing a more platform-independent file | |
277 | locking facility. | |
278 | </dl> | |
279 | </div> | |
280 | ||
281 | <DIV CLASS="navigation"> | |
282 | <div class='online-navigation'> | |
283 | <p></p><hr /> | |
284 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
285 | <tr> | |
286 | <td class='online-navigation'><a rel="prev" title="8.10 pty " | |
287 | href="module-pty.html"><img src='../icons/previous.png' | |
288 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
289 | <td class='online-navigation'><a rel="parent" title="8. Unix Specific Services" | |
290 | href="unix.html"><img src='../icons/up.png' | |
291 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
292 | <td class='online-navigation'><a rel="next" title="8.12 pipes " | |
293 | href="module-pipes.html"><img src='../icons/next.png' | |
294 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
295 | <td align="center" width="100%">Python Library Reference</td> | |
296 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
297 | href="contents.html"><img src='../icons/contents.png' | |
298 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
299 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
300 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
301 | <td class='online-navigation'><a rel="index" title="Index" | |
302 | href="genindex.html"><img src='../icons/index.png' | |
303 | border='0' height='32' alt='Index' width='32' /></A></td> | |
304 | </tr></table> | |
305 | <div class='online-navigation'> | |
306 | <b class="navlabel">Previous:</b> | |
307 | <a class="sectref" rel="prev" href="module-pty.html">8.10 pty </A> | |
308 | <b class="navlabel">Up:</b> | |
309 | <a class="sectref" rel="parent" href="unix.html">8. Unix Specific Services</A> | |
310 | <b class="navlabel">Next:</b> | |
311 | <a class="sectref" rel="next" href="module-pipes.html">8.12 pipes </A> | |
312 | </div> | |
313 | </div> | |
314 | <hr /> | |
315 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
316 | </DIV> | |
317 | <!--End of Navigation Panel--> | |
318 | <ADDRESS> | |
319 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
320 | </ADDRESS> | |
321 | </BODY> | |
322 | </HTML> |