| % Manual text by Jaap Vermeulen |
| \section{Built-in Module \sectcode{fcntl}} |
| \label{module-fcntl} |
| \bimodindex{fcntl} |
| \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}. The argument \var{arg} is optional, and |
| defaults to 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 \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. In |
| case 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 for details. (On some systems, this function is |
| emulated using \function{fcntl()}.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{lockf}{fd, code, \optional{len, \optional{start, \optional{whence}}}} |
| This is a wrapper around the \constant{FCNTL.F_SETLK} and |
| \constant{FCNTL.F_SETLKW} \function{fcntl()} calls. See the \UNIX{} |
| manual for details. |
| \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 |
| |
| 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} |
| |
| 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. The structure lay-out for the \var{lockadata} variable is |
| system dependent --- therefore using the \function{flock()} call may be |
| better. |