| 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> |