/Doc/library/fcntl.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 157 lines · 114 code · 43 blank · 0 comment · 0 complexity · 0a54c9ed76438dcd9fdddc6ab8e396d3 MD5 · raw file

  1. :mod:`fcntl` --- The :func:`fcntl` and :func:`ioctl` system calls
  2. =================================================================
  3. .. module:: fcntl
  4. :platform: Unix
  5. :synopsis: The fcntl() and ioctl() system calls.
  6. .. sectionauthor:: Jaap Vermeulen
  7. .. index::
  8. pair: UNIX@Unix; file control
  9. pair: UNIX@Unix; I/O control
  10. This module performs file control and I/O control on file descriptors. It is an
  11. interface to the :cfunc:`fcntl` and :cfunc:`ioctl` Unix routines.
  12. All functions in this module take a file descriptor *fd* as their first
  13. argument. This can be an integer file descriptor, such as returned by
  14. ``sys.stdin.fileno()``, or a file object, such as ``sys.stdin`` itself, which
  15. provides a :meth:`fileno` which returns a genuine file descriptor.
  16. The module defines the following functions:
  17. .. function:: fcntl(fd, op[, arg])
  18. Perform the requested operation on file descriptor *fd* (file objects providing
  19. a :meth:`fileno` method are accepted as well). The operation is defined by *op*
  20. and is operating system dependent. These codes are also found in the
  21. :mod:`fcntl` module. The argument *arg* is optional, and defaults to the integer
  22. value ``0``. When present, it can either be an integer value, or a string.
  23. With the argument missing or an integer value, the return value of this function
  24. is the integer return value of the C :cfunc:`fcntl` call. When the argument is
  25. a string it represents a binary structure, e.g. created by :func:`struct.pack`.
  26. The binary data is copied to a buffer whose address is passed to the C
  27. :cfunc:`fcntl` call. The return value after a successful call is the contents
  28. of the buffer, converted to a string object. The length of the returned string
  29. will be the same as the length of the *arg* argument. This is limited to 1024
  30. bytes. If the information returned in the buffer by the operating system is
  31. larger than 1024 bytes, this is most likely to result in a segmentation
  32. violation or a more subtle data corruption.
  33. If the :cfunc:`fcntl` fails, an :exc:`IOError` is raised.
  34. .. function:: ioctl(fd, op[, arg[, mutate_flag]])
  35. This function is identical to the :func:`fcntl` function, except that the
  36. operations are typically defined in the library module :mod:`termios` and the
  37. argument handling is even more complicated.
  38. The op parameter is limited to values that can fit in 32-bits.
  39. The parameter *arg* can be one of an integer, absent (treated identically to the
  40. integer ``0``), an object supporting the read-only buffer interface (most likely
  41. a plain Python string) or an object supporting the read-write buffer interface.
  42. In all but the last case, behaviour is as for the :func:`fcntl` function.
  43. If a mutable buffer is passed, then the behaviour is determined by the value of
  44. the *mutate_flag* parameter.
  45. If it is false, the buffer's mutability is ignored and behaviour is as for a
  46. read-only buffer, except that the 1024 byte limit mentioned above is avoided --
  47. so long as the buffer you pass is as least as long as what the operating system
  48. wants to put there, things should work.
  49. If *mutate_flag* is true, then the buffer is (in effect) passed to the
  50. underlying :func:`ioctl` system call, the latter's return code is passed back to
  51. the calling Python, and the buffer's new contents reflect the action of the
  52. :func:`ioctl`. This is a slight simplification, because if the supplied buffer
  53. is less than 1024 bytes long it is first copied into a static buffer 1024 bytes
  54. long which is then passed to :func:`ioctl` and copied back into the supplied
  55. buffer.
  56. If *mutate_flag* is not supplied, then from Python 2.5 it defaults to true,
  57. which is a change from versions 2.3 and 2.4. Supply the argument explicitly if
  58. version portability is a priority.
  59. An example::
  60. >>> import array, fcntl, struct, termios, os
  61. >>> os.getpgrp()
  62. 13341
  63. >>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0]
  64. 13341
  65. >>> buf = array.array('h', [0])
  66. >>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
  67. 0
  68. >>> buf
  69. array('h', [13341])
  70. .. function:: flock(fd, op)
  71. Perform the lock operation *op* on file descriptor *fd* (file objects providing
  72. a :meth:`fileno` method are accepted as well). See the Unix manual
  73. :manpage:`flock(3)` for details. (On some systems, this function is emulated
  74. using :cfunc:`fcntl`.)
  75. .. function:: lockf(fd, operation, [length, [start, [whence]]])
  76. This is essentially a wrapper around the :func:`fcntl` locking calls. *fd* is
  77. the file descriptor of the file to lock or unlock, and *operation* is one of the
  78. following values:
  79. * :const:`LOCK_UN` -- unlock
  80. * :const:`LOCK_SH` -- acquire a shared lock
  81. * :const:`LOCK_EX` -- acquire an exclusive lock
  82. When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be
  83. bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition.
  84. If :const:`LOCK_NB` is used and the lock cannot be acquired, an
  85. :exc:`IOError` will be raised and the exception will have an *errno*
  86. attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the
  87. operating system; for portability, check for both values). On at least some
  88. systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a
  89. file opened for writing.
  90. *length* is the number of bytes to lock, *start* is the byte offset at which the
  91. lock starts, relative to *whence*, and *whence* is as with :func:`fileobj.seek`,
  92. specifically:
  93. * :const:`0` -- relative to the start of the file (:const:`SEEK_SET`)
  94. * :const:`1` -- relative to the current buffer position (:const:`SEEK_CUR`)
  95. * :const:`2` -- relative to the end of the file (:const:`SEEK_END`)
  96. The default for *start* is 0, which means to start at the beginning of the file.
  97. The default for *length* is 0 which means to lock to the end of the file. The
  98. default for *whence* is also 0.
  99. Examples (all on a SVR4 compliant system)::
  100. import struct, fcntl, os
  101. f = open(...)
  102. rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)
  103. lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
  104. rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)
  105. Note that in the first example the return value variable *rv* will hold an
  106. integer value; in the second example it will hold a string value. The structure
  107. lay-out for the *lockdata* variable is system dependent --- therefore using the
  108. :func:`flock` call may be better.
  109. .. seealso::
  110. Module :mod:`os`
  111. If the locking flags :const:`O_SHLOCK` and :const:`O_EXLOCK` are present
  112. in the :mod:`os` module, the :func:`os.open` function provides a more
  113. platform-independent alternative to the :func:`lockf` and :func:`flock`
  114. functions.