\section{\module{fcntl} ---
         The \function{fcntl()} and \function{ioctl()} system calls}

\declaremodule{builtin}{fcntl}
  \platform{Unix}
\modulesynopsis{The \function{fcntl()} and \function{ioctl()} system calls.}
\sectionauthor{Jaap Vermeulen}{}

\indexii{UNIX@\UNIX{}}{file control}
\indexii{UNIX@\UNIX{}}{I/O control}

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

The module defines the following functions:


\begin{funcdesc}{fcntl}{fd, op\optional{, arg}}
  Perform the requested operation on file descriptor \var{fd}.
  The operation is defined by \var{op} and is operating system
  dependent.  Typically these codes can be retrieved from the library
  module \module{FCNTL}\refstmodindex{FCNTL}. The argument \var{arg}
  is optional, and defaults to the integer value \code{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 \cfunction{fcntl()}
  call.  When the argument is a string it represents a binary
  structure, e.g.\ created by \function{struct.pack()}. The binary
  data is copied to a buffer whose address is passed to the C
  \cfunction{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 \var{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 \cfunction{fcntl()} fails, an \exception{IOError} is
  raised.
\end{funcdesc}

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

\begin{funcdesc}{flock}{fd, op}
Perform the lock operation \var{op} on file descriptor \var{fd}.
See the \UNIX{} manual \manpage{flock}{3} for details.  (On some
systems, this function is emulated using \cfunction{fcntl()}.)
\end{funcdesc}

\begin{funcdesc}{lockf}{fd, operation,
    \optional{len, \optional{start, \optional{whence}}}}
This is essentially a wrapper around the \function{fcntl()} locking
calls.  \var{fd} is the file descriptor of the file to lock or unlock,
and \var{operation} is one of the following values:

\begin{itemize}
\item \constant{LOCK_UN} -- unlock
\item \constant{LOCK_SH} -- acquire a shared lock
\item \constant{LOCK_EX} -- acquire an exclusive lock
\end{itemize}

When \var{operation} is \constant{LOCK_SH} or \constant{LOCK_EX}, it
can also be bit-wise OR'd with \constant{LOCK_NB} to avoid blocking on
lock acquisition.  If \constant{LOCK_NB} is used and the lock cannot
be acquired, an \exception{IOError} will be raised and the exception
will have an \var{errno} attribute set to \constant{EACCES} or
\constant{EAGAIN} (depending on the operating system; for portability,
check for both values).

\var{length} is the number of bytes to lock, \var{start} is the byte
offset at which the lock starts, relative to \var{whence}, and
\var{whence} is as with \function{fileobj.seek()}, specifically:

\begin{itemize}
\item \constant{0} -- relative to the start of the file
      (\constant{SEEK_SET})
\item \constant{1} -- relative to the current buffer position
      (\constant{SEEK_CUR})
\item \constant{2} -- relative to the end of the file
      (\constant{SEEK_END})
\end{itemize}

The default for \var{start} is 0, which means to start at the
beginning of the file.  The default for \var{length} is 0 which means
to lock to the end of the file.  The default for \var{whence} is also
0.

\end{funcdesc}

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


Examples (all on a SVR4 compliant system):

\begin{verbatim}
import struct, fcntl, FCNTL

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

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

Note that in the first example the return value variable \var{rv} will
hold an integer value; in the second example it will hold a string
value.  The structure lay-out for the \var{lockdata} variable is
system dependent --- therefore using the \function{flock()} call may be
better.