Doc/lib/libtermios.tex

   1 \section{\module{termios} ---
   2          \POSIX{} style tty control}
   3
   4 \declaremodule{builtin}{termios}
   5   \platform{Unix}
   6 \modulesynopsis{\POSIX{} style tty control.}
   7
   8 \indexii{\POSIX{}}{I/O control}
   9 \indexii{tty}{I/O control}
  10
  11
  12 This module provides an interface to the \POSIX{} calls for tty I/O
  13 control.  For a complete description of these calls, see the \POSIX{} or
  14 \UNIX{} manual pages.  It is only available for those \UNIX{} versions
  15 that support \POSIX{} \emph{termios} style tty I/O control (and then
  16 only if configured at installation time).
  17
  18 All functions in this module take a file descriptor \var{fd} as their
  19 first argument.  This must be an integer file descriptor, such as
  20 returned by \code{sys.stdin.fileno()}.
  21
  22 This module should be used in conjunction with the
  23 \refmodule[TERMIOSuppercase]{TERMIOS}\refstmodindex{TERMIOS} module,
  24 which defines the relevant symbolic constants (see the next section).
  25
  26 The module defines the following functions:
  27
  28 \begin{funcdesc}{tcgetattr}{fd}
  29 Return a list containing the tty attributes for file descriptor
  30 \var{fd}, as follows: \code{[}\var{iflag}, \var{oflag}, \var{cflag},
  31 \var{lflag}, \var{ispeed}, \var{ospeed}, \var{cc}\code{]} where
  32 \var{cc} is a list of the tty special characters (each a string of
  33 length 1, except the items with indices \constant{TERMIOS.VMIN} and
  34 \constant{TERMIOS.VTIME}, which are integers when these fields are
  35 defined).  The interpretation of the flags and the speeds as well as
  36 the indexing in the \var{cc} array must be done using the symbolic
  37 constants defined in the \refmodule[TERMIOSuppercase]{TERMIOS}
  38 module.
  39 \end{funcdesc}
  40
  41 \begin{funcdesc}{tcsetattr}{fd, when, attributes}
  42 Set the tty attributes for file descriptor \var{fd} from the
  43 \var{attributes}, which is a list like the one returned by
  44 \function{tcgetattr()}.  The \var{when} argument determines when the
  45 attributes are changed: \constant{TERMIOS.TCSANOW} to change
  46 immediately, \constant{TERMIOS.TCSADRAIN} to change after transmitting
  47 all queued output, or \constant{TERMIOS.TCSAFLUSH} to change after
  48 transmitting all queued output and discarding all queued input.
  49 \end{funcdesc}
  50
  51 \begin{funcdesc}{tcsendbreak}{fd, duration}
  52 Send a break on file descriptor \var{fd}.  A zero \var{duration} sends
  53 a break for 0.25--0.5 seconds; a nonzero \var{duration} has a system
  54 dependent meaning.
  55 \end{funcdesc}
  56
  57 \begin{funcdesc}{tcdrain}{fd}
  58 Wait until all output written to file descriptor \var{fd} has been
  59 transmitted.
  60 \end{funcdesc}
  61
  62 \begin{funcdesc}{tcflush}{fd, queue}
  63 Discard queued data on file descriptor \var{fd}.  The \var{queue}
  64 selector specifies which queue: \constant{TERMIOS.TCIFLUSH} for the
  65 input queue, \constant{TERMIOS.TCOFLUSH} for the output queue, or
  66 \constant{TERMIOS.TCIOFLUSH} for both queues.
  67 \end{funcdesc}
  68
  69 \begin{funcdesc}{tcflow}{fd, action}
  70 Suspend or resume input or output on file descriptor \var{fd}.  The
  71 \var{action} argument can be \constant{TERMIOS.TCOOFF} to suspend
  72 output, \constant{TERMIOS.TCOON} to restart output,
  73 \constant{TERMIOS.TCIOFF} to suspend input, or
  74 \constant{TERMIOS.TCION} to restart input.
  75 \end{funcdesc}
  76
  77
  78 \begin{seealso}
  79   \seemodule[TERMIOSuppercase]{TERMIOS}{Constants for use with
  80                                         \module{termios}.}
  81   \seemodule{tty}{Convenience functions for common terminal control
  82                   operations.}
  83 \end{seealso}
  84
  85
  86 \subsection{Example}
  87 \nodename{termios Example}
  88
  89 Here's a function that prompts for a password with echoing turned
  90 off.  Note the technique using a separate \function{tcgetattr()} call
  91 and a \keyword{try} ... \keyword{finally} statement to ensure that the
  92 old tty attributes are restored exactly no matter what happens:
  93
  94 \begin{verbatim}
  95 def getpass(prompt = "Password: "):
  96     import termios, TERMIOS, sys
  97     fd = sys.stdin.fileno()
  98     old = termios.tcgetattr(fd)
  99     new = termios.tcgetattr(fd)
 100     new[3] = new[3] & ~TERMIOS.ECHO          # lflags
 101     try:
 102         termios.tcsetattr(fd, TERMIOS.TCSADRAIN, new)
 103         passwd = raw_input(prompt)
 104     finally:
 105         termios.tcsetattr(fd, TERMIOS.TCSADRAIN, old)
 106     return passwd
 107 \end{verbatim}
 108
 109
 110 \section{\module{TERMIOS} ---
 111          Constants used with the \module{termios} module}
 112
 113 \declaremodule[TERMIOSuppercase]{standard}{TERMIOS}
 114   \platform{Unix}
 115 \modulesynopsis{Symbolic constants required to use the
 116   \module{termios} module.}
 117
 118
 119 \indexii{\POSIX{}}{I/O control}
 120 \indexii{tty}{I/O control}
 121
 122 This module defines the symbolic constants required to use the
 123 \refmodule{termios}\refbimodindex{termios} module (see the previous
 124 section).  See the \POSIX{} or \UNIX{} manual pages (or the source)
 125 for a list of those constants.
 126
 127 Note: this module resides in a system-dependent subdirectory of the
 128 Python library directory.  You may have to generate it for your
 129 particular system using the script \file{Tools/scripts/h2py.py}.