summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libfcntl.tex
diff options
context:
space:
mode:
authorMichael W. Hudson <mwh@python.net>2003-03-03 12:29:42 (GMT)
committerMichael W. Hudson <mwh@python.net>2003-03-03 12:29:42 (GMT)
commitf00899866888408106fea4147a9d2cdc2f1e8dbc (patch)
tree32aae5a6d01192bc79456886bd8d299ad84ecdeb /Doc/lib/libfcntl.tex
parent122152451e1bc7aaff69d28b8950afa7848c6de6 (diff)
downloadcpython-f00899866888408106fea4147a9d2cdc2f1e8dbc.zip
cpython-f00899866888408106fea4147a9d2cdc2f1e8dbc.tar.gz
cpython-f00899866888408106fea4147a9d2cdc2f1e8dbc.tar.bz2
Fix bug
[ 555817 ] Flawed fcntl.ioctl implementation. with my patch that allows for an array to be mutated when passed as the buffer argument to ioctl() (details complicated by backwards compatibility considerations -- read the docs!).
Diffstat (limited to 'Doc/lib/libfcntl.tex')
-rw-r--r--Doc/lib/libfcntl.tex61
1 files changed, 54 insertions, 7 deletions
diff --git a/Doc/lib/libfcntl.tex b/Doc/lib/libfcntl.tex
index 645a97e..6eccb4a 100644
--- a/Doc/lib/libfcntl.tex
+++ b/Doc/lib/libfcntl.tex
@@ -47,10 +47,57 @@ The module defines the following functions:
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
- \refmodule{termios}.
+\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, fnctl, 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}
@@ -122,7 +169,7 @@ 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{fcntl.lockf} and \function{fcntl.flock}
- functions, providing a more platform-independent file
- locking facility.}
+ the \function{fcntl.lockf} and \function{fcntl.flock}
+ functions, providing a more platform-independent file
+ locking facility.}
\end{seealso}