Doc/lib/libfcntl.tex

% Manual text by Jaap Vermeulen
\section{Built-in module \sectcode{fcntl}}
\bimodindex{fcntl}
\indexii{UNIX}{file control}
\indexii{UNIX}{IO control}

This module performs file control and IO control on file descriptors.
It is an interface to the \dfn{fcntl()} and \dfn{ioctl()} \UNIX routines.
File descriptors can be obtained with the \dfn{fileno()} method of a
file or socket object.

The module defines the following functions:

\renewcommand{\indexsubitem}{(in module struct)}

\begin{funcdesc}{fcntl}{fd\, op\, arg}
  Perform the requested operation on file descriptor \code{\var{fd}}.
  The operation is defined by \code{\var{op}} and is operating system
  dependent.  Typically these codes can be retrieved from the library
  module \code{FCNTL}. The argument \code{\var{arg}} is optional.  When
  it is missing it is interpreted as the integer value \code{0}. When
  it is 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 real \code{fcntl()}
  call.  When the argument is a string it represents a binary
  structure, e.g.  created by \code{struct.pack()}. The binary data is
  copied to a buffer whose address is passed to the real \code{fcntl()}
  call.  The return value after a successful call is the contents of
  the buffer, converted to a string object.  In the case the
  \code{fcntl()} fails, an \code{IOError} will be raised.
\end{funcdesc}

\begin{funcdesc}{ioctl}{fd\, op\, arg}
  This function is identical to the \code{fcntl()} function, except
  that the operations are typically defined in the library module
  \code{IOCTL}.
\end{funcdesc}

If the library modules \code{FCNTL} or \code{IOCTL} are missing, you
can find the opcodes in the C include files \code{sys/fcntl} and
\code{sys/ioctl}. You can create the modules yourself with the h2py
script, found in the \code{Demo/scripts} directory.

Examples (all on a SVR4 compliant system):

\bcode\begin{verbatim}
import struct, FCNTL

file = open(...)
rv = fcntl(file.fileno(), FCNTL.O_NDELAY, 1)

lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0)
rv = fcntl(file.fileno(), FCNTL.F_SETLKW, lockdata)
\end{verbatim}\ecode

Note that in the first example the return value variable \code{rv} will
hold an integer value; in the second example it will hold a string
value.