mirror of
https://github.com/python/cpython.git
synced 2025-07-23 19:25:40 +00:00

The last call to fcntl (which wasn't changed) doesn't work for me, but the first part works now. Backport candidate.
175 lines
7.1 KiB
TeX
175 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{length, \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, 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} 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}
|