cpython/Doc/lib/libtermios.tex

127 lines
4.4 KiB
TeX
Raw Normal View History

\section{\module{termios} ---
1999-03-02 12:37:17 -04:00
\POSIX{} style tty control}
1999-03-02 12:37:17 -04:00
\declaremodule{builtin}{termios}
\platform{Unix}
\modulesynopsis{\POSIX{} style tty control.}
\indexii{\POSIX{}}{I/O control}
1995-03-31 08:26:24 -04:00
\indexii{tty}{I/O control}
1995-03-31 08:26:24 -04:00
This module provides an interface to the \POSIX{} calls for tty I/O
control. For a complete description of these calls, see the \POSIX{} or
1995-03-31 08:26:24 -04:00
\UNIX{} manual pages. It is only available for those \UNIX{} versions
that support \POSIX{} \emph{termios} style tty I/O control (and then
1995-03-31 08:26:24 -04:00
only if configured at installation time).
All functions in this module take a file descriptor \var{fd} as their
first argument. This must be an integer file descriptor, such as
returned by \code{sys.stdin.fileno()}.
This module also defines all the constants needed to work with the
functions provided here; these have the same name as their
counterparts in C. Please refer to your system documentation for more
information on using these terminal control interfaces.
1995-03-31 08:26:24 -04:00
The module defines the following functions:
\begin{funcdesc}{tcgetattr}{fd}
Return a list containing the tty attributes for file descriptor
\var{fd}, as follows: \code{[}\var{iflag}, \var{oflag}, \var{cflag},
\var{lflag}, \var{ispeed}, \var{ospeed}, \var{cc}\code{]} where
\var{cc} is a list of the tty special characters (each a string of
length 1, except the items with indices \constant{VMIN} and
\constant{VTIME}, which are integers when these fields are
defined). The interpretation of the flags and the speeds as well as
the indexing in the \var{cc} array must be done using the symbolic
constants defined in the \module{termios}
1999-03-02 12:37:17 -04:00
module.
1995-03-31 08:26:24 -04:00
\end{funcdesc}
\begin{funcdesc}{tcsetattr}{fd, when, attributes}
1995-03-31 08:26:24 -04:00
Set the tty attributes for file descriptor \var{fd} from the
\var{attributes}, which is a list like the one returned by
\function{tcgetattr()}. The \var{when} argument determines when the
attributes are changed: \constant{TCSANOW} to change immediately,
\constant{TCSADRAIN} to change after transmitting all queued output,
or \constant{TCSAFLUSH} to change after transmitting all queued
output and discarding all queued input.
1995-03-31 08:26:24 -04:00
\end{funcdesc}
\begin{funcdesc}{tcsendbreak}{fd, duration}
1995-03-31 08:26:24 -04:00
Send a break on file descriptor \var{fd}. A zero \var{duration} sends
a break for 0.25--0.5 seconds; a nonzero \var{duration} has a system
dependent meaning.
\end{funcdesc}
\begin{funcdesc}{tcdrain}{fd}
Wait until all output written to file descriptor \var{fd} has been
transmitted.
\end{funcdesc}
\begin{funcdesc}{tcflush}{fd, queue}
1995-03-31 08:26:24 -04:00
Discard queued data on file descriptor \var{fd}. The \var{queue}
selector specifies which queue: \constant{TCIFLUSH} for the input
queue, \constant{TCOFLUSH} for the output queue, or
\constant{TCIOFLUSH} for both queues.
1995-03-31 08:26:24 -04:00
\end{funcdesc}
\begin{funcdesc}{tcflow}{fd, action}
1995-03-31 08:26:24 -04:00
Suspend or resume input or output on file descriptor \var{fd}. The
\var{action} argument can be \constant{TCOOFF} to suspend output,
\constant{TCOON} to restart output, \constant{TCIOFF} to suspend
input, or \constant{TCION} to restart input.
1995-03-31 08:26:24 -04:00
\end{funcdesc}
\begin{seealso}
\seemodule{tty}{Convenience functions for common terminal control
operations.}
\end{seealso}
1995-03-31 08:26:24 -04:00
\subsection{Example}
\nodename{termios Example}
Here's a function that prompts for a password with echoing turned
off. Note the technique using a separate \function{tcgetattr()} call
and a \keyword{try} ... \keyword{finally} statement to ensure that the
old tty attributes are restored exactly no matter what happens:
1995-03-31 08:26:24 -04:00
\begin{verbatim}
1995-03-31 08:26:24 -04:00
def getpass(prompt = "Password: "):
import termios, sys
1995-03-31 08:26:24 -04:00
fd = sys.stdin.fileno()
old = termios.tcgetattr(fd)
new = termios.tcgetattr(fd)
new[3] = new[3] & ~termios.ECHO # lflags
1995-03-31 08:26:24 -04:00
try:
termios.tcsetattr(fd, termios.TCSADRAIN, new)
1995-03-31 08:26:24 -04:00
passwd = raw_input(prompt)
finally:
termios.tcsetattr(fd, termios.TCSADRAIN, old)
1995-03-31 08:26:24 -04:00
return passwd
\end{verbatim}
1998-02-19 16:07:39 -04:00
1999-02-19 20:14:17 -04:00
\section{\module{TERMIOS} ---
1999-03-02 12:37:17 -04:00
Constants used with the \module{termios} module}
1999-02-19 20:14:17 -04:00
\declaremodule[TERMIOSuppercase]{standard}{TERMIOS}
\platform{Unix}
\modulesynopsis{Symbolic constants required to use the
1999-03-02 12:37:17 -04:00
\module{termios} module.}
1999-02-19 20:14:17 -04:00
\indexii{\POSIX{}}{I/O control}
1995-03-31 08:26:24 -04:00
\indexii{tty}{I/O control}
\deprecated{2.1}{Import needed constants from \refmodule{termios}
instead.}
1995-03-31 08:26:24 -04:00
This module defines the symbolic constants required to use the
\refmodule{termios}\refbimodindex{termios} module (see the previous
section). See the \POSIX{} or \UNIX{} manual pages for a list of
those constants.