mirror of https://github.com/python/cpython
176 lines
7.1 KiB
TeX
176 lines
7.1 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.
|
|
|
|
All functions in this module take a file descriptor \var{fd} as their
|
|
first argument. This can be an integer file descriptor, such as
|
|
returned by \code{sys.stdin.fileno()}, or a file object, such as
|
|
\code{sys.stdin} itself, which provides a \method{fileno()} which
|
|
returns 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 longer than
|
|
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 in 2.3 it defaults to
|
|
false. This is planned to change over the next few Python versions:
|
|
in 2.4 failing to supply \var{mutate_flag} will get a warning but
|
|
the same behavior and in versions later than 2.5 it will default to
|
|
true.
|
|
|
|
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
|
|
>>> buf
|
|
array('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 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). On at least some systems, \constant{LOCK_EX}
|
|
can only be used if the file descriptor refers to a file opened for
|
|
writing.
|
|
|
|
\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}
|
|
|
|
Examples (all on a SVR4 compliant system):
|
|
|
|
\begin{verbatim}
|
|
import struct, fcntl
|
|
|
|
file = open(...)
|
|
rv = fcntl(file, fcntl.F_SETFL, os.O_NDELAY)
|
|
|
|
lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
|
|
rv = fcntl.fcntl(file, 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.
|
|
|
|
\begin{seealso}
|
|
\seemodule{os}{The \function{os.open()} function supports locking flags
|
|
and is available on a wider variety of platforms than
|
|
the \function{lockf()} and \function{flock()}
|
|
functions, providing a more platform-independent file
|
|
locking facility.}
|
|
\end{seealso}
|