\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. All functions in this module take a file descriptor \var{fd} as theirfirst argument.  This can be an integer file descriptor, such asreturned by \code{sys.stdin.fileno()}, or a file object, such as\code{sys.stdin} itself, which provides a \method{fileno()} whichreturns a genuine file descriptor. The module defines the following functions:  \begin{funcdesc}{fcntl}{fd, op\optional{, arg}}  Perform the requested operation on file descriptor \var{fd} (file  objects providing a \method{fileno()} method are accepted as well).  The operation is defined by \var{op} and is operating system  dependent.  These codes are also found in the \module{fcntl}  module. 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{\refmodule{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\optional{, arg\optional{, mutate_flag}}}  This function is identical to the \function{fcntl()} function,  except that the operations are typically defined in the library  module \refmodule{termios} and the argument handling is even more  complicated.    The parameter \var{arg} can be one of an integer, absent (treated  identically to the integer \code{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 \function{fcntl()}  function.    If a mutable buffer is passed, then the behaviour is determined by  the value of the \var{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 \var{mutate_flag} is true, then the buffer is (in effect) passed  to the underlying \function{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 \function{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 \function{ioctl()} and copied back into  the supplied buffer.    If \var{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: \begin{verbatim}>>> 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>>> bufarray('h', [13341])\end{verbatim}\end{funcdesc} \begin{funcdesc}{flock}{fd, op}Perform the lock operation \var{op} on file descriptor \var{fd} (file  objects providing a \method{fileno()} method are accepted as well).See the \UNIX{} manual \manpage{flock}{3} for details.  (On somesystems, this function is emulated using \cfunction{fcntl()}.)\end{funcdesc} \begin{funcdesc}{lockf}{fd, operation,    \optional{length, \optional{start, \optional{whence}}}}This is essentially a wrapper around the \function{fcntl()} lockingcalls.  \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}, itcan also be bit-wise OR'd with \constant{LOCK_NB} to avoid blocking onlock acquisition.  If \constant{LOCK_NB} is used and the lock cannotbe acquired, an \exception{IOError} will be raised and the exceptionwill have an \var{errno} attribute set to \constant{EACCES} or\constant{EAGAIN} (depending on the operating system; for portability,check for both values).  On at least some systems, \constant{LOCK_EX}can only be used if the file descriptor refers to a file opened forwriting. \var{length} is the number of bytes to lock, \var{start} is the byteoffset 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 thebeginning of the file.  The default for \var{length} is 0 which meansto lock to the end of the file.  The default for \var{whence} is also0.\end{funcdesc} Examples (all on a SVR4 compliant system): \begin{verbatim}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)\end{verbatim} Note that in the first example the return value variable \var{rv} willhold an integer value; in the second example it will hold a stringvalue.  The structure lay-out for the \var{lockdata} variable issystem dependent --- therefore using the \function{flock()} call may bebetter. \begin{seealso}  \seemodule{os}{If the locking flags \constant{O_SHLOCK} and		 \constant{O_EXLOCK} are present in the \module{os} module,  		 the \function{os.open()} function provides a more  		 platform-independent alternative to the \function{lockf()}  		 and \function{flock()} functions.}\end{seealso}