[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / python / lib / module-fcntl.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<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>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<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>
</tr></table>
<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>
</div>
<hr /></div>
</DIV>
<!--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>
</H1>

<P>
<A NAME="module-fcntl"></A>  
<p class="availability">Availability: <span
 class="platform">Unix</span>.</p>

<P>
<a id='l2h-3024' xml:id='l2h-3024'></a><a id='l2h-3025' xml:id='l2h-3025'></a>
<P>
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.

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

<P>
The module defines the following functions:

<P>
<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>
<dd>
  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
  corruption.

<P>
If the <tt class="cfunction">fcntl()</tt> fails, an <tt class="exception">IOError</tt> is
  raised.
</dl>

<P>
<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>
<dd>
  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
  complicated.

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

<P>
In all but the last case, behaviour is as for the <tt class="function">fcntl()</tt>
  function.

<P>
If a mutable buffer is passed, then the behaviour is determined by
  the value of the <var>mutate_flag</var> parameter.

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

<P>
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
  the supplied buffer.

<P>
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
  true.

<P>
An example:

<P>
<div class="verbatim"><pre>
&gt;&gt;&gt; import array, fcntl, struct, termios, os
&gt;&gt;&gt; os.getpgrp()
13341
&gt;&gt;&gt; struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, "  "))[0]
13341
&gt;&gt;&gt; buf = array.array('h', [0])
&gt;&gt;&gt; fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
0
&gt;&gt;&gt; buf
array('h', [13341])
</pre></div>
</dl>

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

<P>
<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>
  <td><var>fd, operation,
    </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>
<dd>
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:

<P>

<UL>
<LI><tt class="constant">LOCK_UN</tt> - unlock
</LI>
<LI><tt class="constant">LOCK_SH</tt> - acquire a shared lock
</LI>
<LI><tt class="constant">LOCK_EX</tt> - acquire an exclusive lock
</LI>
</UL>

<P>
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
writing.

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

<P>

<UL>
<LI><tt class="constant">0</tt> - relative to the start of the file
      (<tt class="constant">SEEK_SET</tt>)
</LI>
<LI><tt class="constant">1</tt> - relative to the current buffer position
      (<tt class="constant">SEEK_CUR</tt>)
</LI>
<LI><tt class="constant">2</tt> - relative to the end of the file
      (<tt class="constant">SEEK_END</tt>)
</LI>
</UL>

<P>
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
0.
</dl>

<P>
Examples (all on a SVR4 compliant system):

<P>
<div class="verbatim"><pre>
import struct, fcntl, os

f = open(...)
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)
</pre></div>

<P>
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
better.

<P>
<div class="seealso">
  <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
                 locking facility.
  </dl>
</div>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<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>
</tr></table>
<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>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
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>