Doc/lib/libtermios.tex

\section{\module{termios} ---
         \POSIX{} style tty control}

\declaremodule{builtin}{termios}
  \platform{Unix}
\modulesynopsis{\POSIX{} style tty control.}

\indexii{\POSIX{}}{I/O control}
\indexii{tty}{I/O control}


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
\UNIX{} manual pages.  It is only available for those \UNIX{} versions
that support \POSIX{} \emph{termios} style tty I/O control (and then
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 should be used in conjunction with the
\refmodule[TERMIOSuppercase]{TERMIOS}\refstmodindex{TERMIOS} module,
which defines the relevant symbolic constants (see the next section).

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{TERMIOS.VMIN} and
\constant{TERMIOS.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 \refmodule[TERMIOSuppercase]{TERMIOS}
module.
\end{funcdesc}

\begin{funcdesc}{tcsetattr}{fd, when, attributes}
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{TERMIOS.TCSANOW} to change
immediately, \constant{TERMIOS.TCSADRAIN} to change after transmitting
all queued output, or \constant{TERMIOS.TCSAFLUSH} to change after
transmitting all queued output and discarding all queued input.
\end{funcdesc}

\begin{funcdesc}{tcsendbreak}{fd, duration}
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}
Discard queued data on file descriptor \var{fd}.  The \var{queue}
selector specifies which queue: \constant{TERMIOS.TCIFLUSH} for the
input queue, \constant{TERMIOS.TCOFLUSH} for the output queue, or
\constant{TERMIOS.TCIOFLUSH} for both queues.
\end{funcdesc}

\begin{funcdesc}{tcflow}{fd, action}
Suspend or resume input or output on file descriptor \var{fd}.  The
\var{action} argument can be \constant{TERMIOS.TCOOFF} to suspend
output, \constant{TERMIOS.TCOON} to restart output,
\constant{TERMIOS.TCIOFF} to suspend input, or
\constant{TERMIOS.TCION} to restart input. 
\end{funcdesc}


\begin{seealso}
  \seemodule[TERMIOSuppercase]{TERMIOS}{Constants for use with
                                        \module{termios}.}
  \seemodule{tty}{Convenience functions for common terminal control
                  operations.}
\end{seealso}


\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:

\begin{verbatim}
def getpass(prompt = "Password: "):
    import termios, TERMIOS, sys
    fd = sys.stdin.fileno()
    old = termios.tcgetattr(fd)
    new = termios.tcgetattr(fd)
    new[3] = new[3] & ~TERMIOS.ECHO          # lflags
    try:
        termios.tcsetattr(fd, TERMIOS.TCSADRAIN, new)
        passwd = raw_input(prompt)
    finally:
        termios.tcsetattr(fd, TERMIOS.TCSADRAIN, old)
    return passwd
\end{verbatim}


\section{\module{TERMIOS} ---
         Constants used with the \module{termios} module}

\declaremodule[TERMIOSuppercase]{standard}{TERMIOS}
  \platform{Unix}
\modulesynopsis{Symbolic constants required to use the
  \module{termios} module.}


\indexii{\POSIX{}}{I/O control}
\indexii{tty}{I/O control}

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 (or the source)
for a list of those constants.

Note: this module resides in a system-dependent subdirectory of the
Python library directory.  You may have to generate it for your
particular system using the script \file{Tools/scripts/h2py.py}.