cpython/Doc/library/fcntl.rst

157 lines
6.6 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:01 -03:00
:mod:`fcntl` --- The :func:`fcntl` and :func:`ioctl` system calls
=================================================================
.. module:: fcntl
:platform: Unix
:synopsis: The fcntl() and ioctl() system calls.
.. sectionauthor:: Jaap Vermeulen
.. index::
pair: UNIX; file control
pair: UNIX; I/O control
2007-08-15 11:28:01 -03:00
This module performs file control and I/O control on file descriptors. It is an
interface to the :cfunc:`fcntl` and :cfunc:`ioctl` Unix routines.
All functions in this module take a file descriptor *fd* as their first
argument. This can be an integer file descriptor, such as returned by
``sys.stdin.fileno()``, or a file object, such as ``sys.stdin`` itself, which
provides a :meth:`fileno` which returns a genuine file descriptor.
The module defines the following functions:
.. function:: fcntl(fd, op[, arg])
Perform the requested operation on file descriptor *fd* (file objects providing
a :meth:`fileno` method are accepted as well). The operation is defined by *op*
and is operating system dependent. These codes are also found in the
:mod:`fcntl` module. The argument *arg* is optional, and defaults to the integer
value ``0``. 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 :cfunc:`fcntl` call. When the argument is
a string it represents a binary structure, e.g. created by :func:`struct.pack`.
The binary data is copied to a buffer whose address is passed to the C
:cfunc:`fcntl` 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 *arg* 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.
If the :cfunc:`fcntl` fails, an :exc:`IOError` is raised.
.. function:: ioctl(fd, op[, arg[, mutate_flag]])
This function is identical to the :func:`fcntl` function, except that the
operations are typically defined in the library module :mod:`termios` and the
argument handling is even more complicated.
The op parameter is limited to values that can fit in 32-bits.
2007-08-15 11:28:01 -03:00
The parameter *arg* can be one of an integer, absent (treated identically to the
integer ``0``), 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 :func:`fcntl` function.
If a mutable buffer is passed, then the behaviour is determined by the value of
the *mutate_flag* 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 as least as long as what the operating system
wants to put there, things should work.
If *mutate_flag* is true, then the buffer is (in effect) passed to the
underlying :func:`ioctl` 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
:func:`ioctl`. 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 :func:`ioctl` and copied back into the supplied
buffer.
If *mutate_flag* is not supplied, then from Python 2.5 it defaults to true,
which is a change from versions 2.3 and 2.4. Supply the argument explicitly if
version portability is a priority.
An example::
>>> import array, fcntl, struct, termios, os
>>> os.getpgrp()
13341
>>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0]
13341
>>> buf = array.array('h', [0])
>>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
0
>>> buf
array('h', [13341])
.. function:: flock(fd, op)
Perform the lock operation *op* on file descriptor *fd* (file objects providing
a :meth:`fileno` method are accepted as well). See the Unix manual
Merged revisions 72558,72745,72750,72876,73042,73045-73048,73069,73089,73163,73186,73213,73215,73217,73257-73258,73260 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r72558 | benjamin.peterson | 2009-05-11 01:52:09 +0200 (Mo, 11 Mai 2009) | 1 line sys.setdefaultencoding() strikes me as a bad example ........ r72745 | benjamin.peterson | 2009-05-17 16:16:29 +0200 (So, 17 Mai 2009) | 1 line ignore .rst files in sphinx its self ........ r72750 | benjamin.peterson | 2009-05-17 18:59:27 +0200 (So, 17 Mai 2009) | 1 line chop off slash ........ r72876 | benjamin.peterson | 2009-05-23 22:59:09 +0200 (Sa, 23 Mai 2009) | 1 line remove mention of old ctypes version ........ r73042 | benjamin.peterson | 2009-05-30 05:10:52 +0200 (Sa, 30 Mai 2009) | 1 line no fdatasync on macos ........ r73045 | georg.brandl | 2009-05-30 09:26:04 +0200 (Sa, 30 Mai 2009) | 1 line #6146: fix markup bug. ........ r73046 | georg.brandl | 2009-05-30 09:31:25 +0200 (Sa, 30 Mai 2009) | 1 line Use preferred form of raising exceptions. ........ r73047 | georg.brandl | 2009-05-30 12:33:23 +0200 (Sa, 30 Mai 2009) | 1 line Fix some more small markup problems. ........ r73048 | georg.brandl | 2009-05-30 12:34:25 +0200 (Sa, 30 Mai 2009) | 1 line Fix markup problem. ........ r73069 | benjamin.peterson | 2009-05-31 02:42:42 +0200 (So, 31 Mai 2009) | 1 line fix signature ........ r73089 | andrew.kuchling | 2009-06-01 02:14:19 +0200 (Mo, 01 Jun 2009) | 1 line The class for regexes isn't called RegexObject any more; correct the text ........ r73163 | georg.brandl | 2009-06-03 09:25:35 +0200 (Mi, 03 Jun 2009) | 1 line Use the preferred form of raise statements in the docs. ........ r73186 | georg.brandl | 2009-06-03 23:21:09 +0200 (Mi, 03 Jun 2009) | 1 line #6174: fix indentation in code example. ........ r73213 | georg.brandl | 2009-06-04 12:15:57 +0200 (Do, 04 Jun 2009) | 1 line #5967: note that the C slicing APIs do not support negative indices. ........ r73215 | georg.brandl | 2009-06-04 12:22:31 +0200 (Do, 04 Jun 2009) | 1 line #6176: fix man page section for flock(2). ........ r73217 | georg.brandl | 2009-06-04 12:27:21 +0200 (Do, 04 Jun 2009) | 1 line #6175: document that inet_aton supports alternate input formats with less than three dots. ........ r73257 | georg.brandl | 2009-06-06 19:50:05 +0200 (Sa, 06 Jun 2009) | 1 line #6211: elaborate a bit on ways to call the function. ........ r73258 | georg.brandl | 2009-06-06 19:51:31 +0200 (Sa, 06 Jun 2009) | 1 line #6204: use a real reference instead of "see later". ........ r73260 | georg.brandl | 2009-06-06 20:21:58 +0200 (Sa, 06 Jun 2009) | 1 line #6224: s/JPython/Jython/, and remove one link to a module nine years old. ........
2009-10-27 11:19:50 -03:00
:manpage:`flock(2)` for details. (On some systems, this function is emulated
2007-08-15 11:28:01 -03:00
using :cfunc:`fcntl`.)
.. function:: lockf(fd, operation, [length, [start, [whence]]])
This is essentially a wrapper around the :func:`fcntl` locking calls. *fd* is
the file descriptor of the file to lock or unlock, and *operation* is one of the
following values:
* :const:`LOCK_UN` -- unlock
* :const:`LOCK_SH` -- acquire a shared lock
* :const:`LOCK_EX` -- acquire an exclusive lock
When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be
bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition.
2007-08-15 11:28:01 -03:00
If :const:`LOCK_NB` is used and the lock cannot be acquired, an
:exc:`IOError` will be raised and the exception will have an *errno*
attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the
operating system; for portability, check for both values). On at least some
systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a
file opened for writing.
*length* is the number of bytes to lock, *start* is the byte offset at which the
lock starts, relative to *whence*, and *whence* is as with :func:`fileobj.seek`,
specifically:
* :const:`0` -- relative to the start of the file (:const:`SEEK_SET`)
* :const:`1` -- relative to the current buffer position (:const:`SEEK_CUR`)
* :const:`2` -- relative to the end of the file (:const:`SEEK_END`)
The default for *start* is 0, which means to start at the beginning of the file.
The default for *length* is 0 which means to lock to the end of the file. The
default for *whence* is also 0.
Examples (all on a SVR4 compliant system)::
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)
Note that in the first example the return value variable *rv* will hold an
integer value; in the second example it will hold a string value. The structure
lay-out for the *lockdata* variable is system dependent --- therefore using the
:func:`flock` call may be better.
.. seealso::
Module :mod:`os`
If the locking flags :const:`O_SHLOCK` and :const:`O_EXLOCK` are present
Merged revisions 73286,73294,73296,73459,73462-73463,73544,73576-73577,73595-73596,73693-73694,73704-73705,73707,73713,73937-73940,73945,73951,73979 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r73286 | georg.brandl | 2009-06-08 09:57:35 +0200 (Mo, 08 Jun 2009) | 1 line Remove period from end of headings. ........ r73294 | georg.brandl | 2009-06-08 15:34:52 +0200 (Mo, 08 Jun 2009) | 1 line #6194: O_SHLOCK/O_EXLOCK are not really more platform independent than lockf(). ........ r73296 | georg.brandl | 2009-06-08 18:03:41 +0200 (Mo, 08 Jun 2009) | 1 line #6238: add fillchar to string.just function family. ........ r73459 | raymond.hettinger | 2009-06-17 03:43:47 +0200 (Mi, 17 Jun 2009) | 1 line Add usage note. ........ r73462 | georg.brandl | 2009-06-17 11:36:21 +0200 (Mi, 17 Jun 2009) | 1 line #6295: clarify blocking behavior of getch(). ........ r73463 | georg.brandl | 2009-06-17 11:43:31 +0200 (Mi, 17 Jun 2009) | 1 line #6255: document PyInt_FromSize_t. ........ r73544 | georg.brandl | 2009-06-24 08:41:19 +0200 (Mi, 24 Jun 2009) | 1 line #6332: fix word dupes throughout the source. ........ r73576 | benjamin.peterson | 2009-06-27 01:37:06 +0200 (Sa, 27 Jun 2009) | 1 line document is_declared_global() ........ r73577 | benjamin.peterson | 2009-06-27 16:16:23 +0200 (Sa, 27 Jun 2009) | 1 line link to extensive generator docs in the reference manual ........ r73595 | ezio.melotti | 2009-06-28 01:45:39 +0200 (So, 28 Jun 2009) | 1 line stmt and setup can contain multiple statements, see #5896 ........ r73596 | ezio.melotti | 2009-06-28 02:07:45 +0200 (So, 28 Jun 2009) | 1 line Fixed a wrong apostrophe ........ r73693 | jesse.noller | 2009-06-29 20:20:34 +0200 (Mo, 29 Jun 2009) | 1 line Bug 5906: add a documentation note for unix daemons vs. multiprocessing daemons ........ r73694 | jesse.noller | 2009-06-29 20:24:26 +0200 (Mo, 29 Jun 2009) | 1 line Issue 5740: multiprocessing.connection.* authkey fixes ........ r73704 | georg.brandl | 2009-06-30 18:15:43 +0200 (Di, 30 Jun 2009) | 1 line #6376: fix copy-n-paste oversight. ........ r73705 | georg.brandl | 2009-06-30 18:17:28 +0200 (Di, 30 Jun 2009) | 1 line #6374: add a bit of explanation about shell=True on Windows. ........ r73707 | georg.brandl | 2009-06-30 18:35:11 +0200 (Di, 30 Jun 2009) | 1 line #6371: fix link targets. ........ r73713 | ezio.melotti | 2009-07-01 00:56:16 +0200 (Mi, 01 Jul 2009) | 1 line Fixed a backslash that was not supposed to be there ........ r73937 | georg.brandl | 2009-07-11 12:12:36 +0200 (Sa, 11 Jul 2009) | 1 line Fix style. ........ r73938 | georg.brandl | 2009-07-11 12:14:54 +0200 (Sa, 11 Jul 2009) | 1 line #6446: fix import_spam() function to use correct error and reference handling. ........ r73939 | georg.brandl | 2009-07-11 12:18:10 +0200 (Sa, 11 Jul 2009) | 1 line #6448: clarify docs for find_module(). ........ r73940 | georg.brandl | 2009-07-11 12:37:38 +0200 (Sa, 11 Jul 2009) | 1 line #6430: add note about size of "u" type. ........ r73945 | georg.brandl | 2009-07-11 12:51:31 +0200 (Sa, 11 Jul 2009) | 1 line #6456: clarify the meaning of constants used as arguments to nl_langinfo(). ........ r73951 | georg.brandl | 2009-07-11 16:23:38 +0200 (Sa, 11 Jul 2009) | 2 lines array.array is actually a class. ........ r73979 | benjamin.peterson | 2009-07-12 18:56:54 +0200 (So, 12 Jul 2009) | 1 line add versionadded ........
2009-10-27 11:29:22 -03:00
in the :mod:`os` module (on BSD only), the :func:`os.open` function
provides an alternative to the :func:`lockf` and :func:`flock` functions.
2007-08-15 11:28:01 -03:00