mirror of
https://github.com/python/cpython.git
synced 2024-12-01 11:15:56 +01:00
86 lines
3.5 KiB
TeX
86 lines
3.5 KiB
TeX
\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, 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, 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.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{lockdata} variable is
|
|
system dependent --- therefore using the \function{flock()} call may be
|
|
better.
|