<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"lib.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"lib.html" title='Python Library Reference'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"module-pipes.html" />
<link rel=
"prev" href=
"module-pty.html" />
<link rel=
"parent" href=
"unix.html" />
<link rel=
"next" href=
"module-pipes.html" />
<meta name='aesop' content='information'
/>
<title>8.11 fcntl -- The fcntl() and ioctl() system calls
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"8.10 pty "
href=
"module-pty.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"8. Unix Specific Services"
href=
"unix.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"8.12 pipes "
href=
"module-pipes.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td><td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-pty.html">8.10 pty
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"unix.html">8. Unix Specific Services
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"module-pipes.html">8.12 pipes
</A>
<!--End of Navigation Panel-->
<H1><A NAME=
"SECTION00101100000000000000000">
8.11 <tt class=
"module">fcntl
</tt> --
The
<tt class=
"function">fcntl()
</tt> and
<tt class=
"function">ioctl()
</tt> system calls
</A><A NAME=
"module-fcntl"></A>
<p class=
"availability">Availability:
<span
class=
"platform">Unix
</span>.
</p>
<a id='l2h-
3024' xml:id='l2h-
3024'
></a><a id='l2h-
3025' xml:id='l2h-
3025'
></a>
This module performs file control and I/O control on file descriptors.
It is an interface to the
<tt class=
"cfunction">fcntl()
</tt> and
<tt class=
"cfunction">ioctl()
</tt><span class=
"Unix">Unix
</span> routines.
All functions in this module take a file descriptor
<var>fd
</var> as their
first argument. This can be an integer file descriptor, such as
returned by
<code>sys.stdin.fileno()
</code>, or a file object, such as
<code>sys.stdin
</code> itself, which provides a
<tt class=
"method">fileno()
</tt> which
returns a genuine file descriptor.
The module defines the following functions:
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3026' xml:id='l2h-
3026'
class=
"function">fcntl
</tt></b>(
</nobr></td>
<td><var>fd, op
</var><big>[
</big><var>, arg
</var><big>]
</big><var></var>)
</td></tr></table></dt>
Perform the requested operation on file descriptor
<var>fd
</var> (file
objects providing a
<tt class=
"method">fileno()
</tt> method are accepted as well).
The operation is defined by
<var>op
</var> and is operating system
dependent. These codes are also found in the
<tt class=
"module">fcntl
</tt> module. The argument
<var>arg
</var> is optional, and defaults to the
integer value
<code>0</code>. When present, it can either be an integer
value, or a string. With the argument missing or an integer value,
the return value of this function is the integer return value of the
C
<tt class=
"cfunction">fcntl()
</tt> call. When the argument is a string it
represents a binary structure, e.g. created by
<tt class=
"function"><tt class=
"module"><a href=
"module-struct.html">struct
</a></tt>.pack()
</tt>. The binary data is copied to a buffer
whose address is passed to the C
<tt class=
"cfunction">fcntl()
</tt> call. The
return value after a successful call is the contents of the buffer,
converted to a string object. The length of the returned string
will be the same as the length of the
<var>arg
</var> argument. This is
limited to
1024 bytes. If the information returned in the buffer by
the operating system is larger than
1024 bytes, this is most likely
to result in a segmentation violation or a more subtle data
If the
<tt class=
"cfunction">fcntl()
</tt> fails, an
<tt class=
"exception">IOError
</tt> is
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3027' xml:id='l2h-
3027'
class=
"function">ioctl
</tt></b>(
</nobr></td>
<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>
This function is identical to the
<tt class=
"function">fcntl()
</tt> function,
except that the operations are typically defined in the library
module
<tt class=
"module"><a href=
"module-termios.html">termios
</a></tt> and the argument handling is even more
The parameter
<var>arg
</var> can be one of an integer, absent (treated
identically to the integer
<code>0</code>), an object supporting the
read-only buffer interface (most likely a plain Python string) or an
object supporting the read-write buffer interface.
In all but the last case, behaviour is as for the
<tt class=
"function">fcntl()
</tt>If a mutable buffer is passed, then the behaviour is determined by
the value of the
<var>mutate_flag
</var> parameter.
If it is false, the buffer's mutability is ignored and behaviour is
as for a read-only buffer, except that the
1024 byte limit mentioned
above is avoided - so long as the buffer you pass is longer than
what the operating system wants to put there, things should work.
If
<var>mutate_flag
</var> is true, then the buffer is (in effect) passed
to the underlying
<tt class=
"function">ioctl()
</tt> system call, the latter's
return code is passed back to the calling Python, and the buffer's
new contents reflect the action of the
<tt class=
"function">ioctl()
</tt>. This is a
slight simplification, because if the supplied buffer is less than
1024 bytes long it is first copied into a static buffer
1024 bytes
long which is then passed to
<tt class=
"function">ioctl()
</tt> and copied back into
If
<var>mutate_flag
</var> is not supplied, then in
2.3 it defaults to
false. This is planned to change over the next few Python versions:
in
2.4 failing to supply
<var>mutate_flag
</var> will get a warning but
the same behavior and in versions later than
2.5 it will default to
<div class=
"verbatim"><pre>
>>> import array, fcntl, struct, termios, os
>>> os.getpgrp()
>>> struct.unpack('h', fcntl.ioctl(
0, termios.TIOCGPGRP,
" "))[
0]
>>> buf = array.array('h', [
0])
>>> fcntl.ioctl(
0, termios.TIOCGPGRP, buf,
1)
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3028' xml:id='l2h-
3028'
class=
"function">flock
</tt></b>(
</nobr></td>
<td><var>fd, op
</var>)
</td></tr></table></dt>
Perform the lock operation
<var>op
</var> on file descriptor
<var>fd
</var> (file
objects providing a
<tt class=
"method">fileno()
</tt> method are accepted as well).
See the
<span class=
"Unix">Unix
</span> manual
<span class=
"manpage"><i>flock
</i>(
3)
</span> for details. (On some
systems, this function is emulated using
<tt class=
"cfunction">fcntl()
</tt>.)
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3029' xml:id='l2h-
3029'
class=
"function">lockf
</tt></b>(
</nobr></td>
</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>
This is essentially a wrapper around the
<tt class=
"function">fcntl()
</tt> locking
calls.
<var>fd
</var> is the file descriptor of the file to lock or unlock,
and
<var>operation
</var> is one of the following values:
<LI><tt class=
"constant">LOCK_UN
</tt> - unlock
<LI><tt class=
"constant">LOCK_SH
</tt> - acquire a shared lock
<LI><tt class=
"constant">LOCK_EX
</tt> - acquire an exclusive lock
When
<var>operation
</var> is
<tt class=
"constant">LOCK_SH
</tt> or
<tt class=
"constant">LOCK_EX
</tt>, it
can also be bit-wise OR'd with
<tt class=
"constant">LOCK_NB
</tt> to avoid blocking on
lock acquisition. If
<tt class=
"constant">LOCK_NB
</tt> is used and the lock cannot
be acquired, an
<tt class=
"exception">IOError
</tt> will be raised and the exception
will have an
<var>errno
</var> attribute set to
<tt class=
"constant">EACCES
</tt> or
<tt class=
"constant">EAGAIN
</tt> (depending on the operating system; for portability,
check for both values). On at least some systems,
<tt class=
"constant">LOCK_EX
</tt>can only be used if the file descriptor refers to a file opened for
<var>length
</var> is the number of bytes to lock,
<var>start
</var> is the byte
offset at which the lock starts, relative to
<var>whence
</var>, and
<var>whence
</var> is as with
<tt class=
"function">fileobj.seek()
</tt>, specifically:
<LI><tt class=
"constant">0</tt> - relative to the start of the file
(
<tt class=
"constant">SEEK_SET
</tt>)
<LI><tt class=
"constant">1</tt> - relative to the current buffer position
(
<tt class=
"constant">SEEK_CUR
</tt>)
<LI><tt class=
"constant">2</tt> - relative to the end of the file
(
<tt class=
"constant">SEEK_END
</tt>)
The default for
<var>start
</var> is
0, which means to start at the
beginning of the file. The default for
<var>length
</var> is
0 which means
to lock to the end of the file. The default for
<var>whence
</var> is also
Examples (all on a SVR4 compliant system):
<div class=
"verbatim"><pre>
rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)
lockdata = struct.pack('hhllhh', fcntl.F_WRLCK,
0,
0,
0,
0,
0)
rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)
Note that in the first example the return value variable
<var>rv
</var> will
hold an integer value; in the second example it will hold a string
value. The structure lay-out for the
<var>lockdata
</var> variable is
system dependent -- therefore using the
<tt class=
"function">flock()
</tt> call may be
<p class=
"heading">See Also:
</p>
<dl compact=
"compact" class=
"seemodule">
<dt>Module
<b><tt class=
"module"><a href=
"module-os.html">os
</a></tt>:
</b>
<dd>The
<tt class=
"function">os.open()
</tt> function supports locking flags
and is available on a wider variety of platforms than
the
<tt class=
"function">lockf()
</tt> and
<tt class=
"function">flock()
</tt> functions, providing a more platform-independent file
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"8.10 pty "
href=
"module-pty.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"8. Unix Specific Services"
href=
"unix.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"8.12 pipes "
href=
"module-pipes.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td><td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-pty.html">8.10 pty
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"unix.html">8. Unix Specific Services
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"module-pipes.html">8.12 pipes
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.
projects / OpenSPARC-T2-SAM / blob