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 can be an integer file descriptor, such as
  20 returned by \code{sys.stdin.fileno()}, or a file object, such as
  21 \code{sys.stdin} itself.
  22
  23 This module also defines all the constants needed to work with the
  24 functions provided here; these have the same name as their
  25 counterparts in C.  Please refer to your system documentation for more
  26 information on using these terminal control interfaces.
  27
  28 The module defines the following functions:
  29
  30 \begin{funcdesc}{tcgetattr}{fd}
  31 Return a list containing the tty attributes for file descriptor
  32 \var{fd}, as follows: \code{[}\var{iflag}, \var{oflag}, \var{cflag},
  33 \var{lflag}, \var{ispeed}, \var{ospeed}, \var{cc}\code{]} where
  34 \var{cc} is a list of the tty special characters (each a string of
  35 length 1, except the items with indices \constant{VMIN} and
  36 \constant{VTIME}, which are integers when these fields are
  37 defined).  The interpretation of the flags and the speeds as well as
  38 the indexing in the \var{cc} array must be done using the symbolic
  39 constants defined in the \module{termios}
  40 module.
  41 \end{funcdesc}
  42
  43 \begin{funcdesc}{tcsetattr}{fd, when, attributes}
  44 Set the tty attributes for file descriptor \var{fd} from the
  45 \var{attributes}, which is a list like the one returned by
  46 \function{tcgetattr()}.  The \var{when} argument determines when the
  47 attributes are changed: \constant{TCSANOW} to change immediately,
  48 \constant{TCSADRAIN} to change after transmitting all queued output,
  49 or \constant{TCSAFLUSH} to change after transmitting all queued
  50 output and discarding all queued input.
  51 \end{funcdesc}
  52
  53 \begin{funcdesc}{tcsendbreak}{fd, duration}
  54 Send a break on file descriptor \var{fd}.  A zero \var{duration} sends
  55 a break for 0.25--0.5 seconds; a nonzero \var{duration} has a system
  56 dependent meaning.
  57 \end{funcdesc}
  58
  59 \begin{funcdesc}{tcdrain}{fd}
  60 Wait until all output written to file descriptor \var{fd} has been
  61 transmitted.
  62 \end{funcdesc}
  63
  64 \begin{funcdesc}{tcflush}{fd, queue}
  65 Discard queued data on file descriptor \var{fd}.  The \var{queue}
  66 selector specifies which queue: \constant{TCIFLUSH} for the input
  67 queue, \constant{TCOFLUSH} for the output queue, or
  68 \constant{TCIOFLUSH} for both queues.
  69 \end{funcdesc}
  70
  71 \begin{funcdesc}{tcflow}{fd, action}
  72 Suspend or resume input or output on file descriptor \var{fd}.  The
  73 \var{action} argument can be \constant{TCOOFF} to suspend output,
  74 \constant{TCOON} to restart output, \constant{TCIOFF} to suspend
  75 input, or \constant{TCION} to restart input.
  76 \end{funcdesc}
  77
  78
  79 \begin{seealso}
  80   \seemodule{tty}{Convenience functions for common terminal control
  81                   operations.}
  82 \end{seealso}
  83
  84
  85 \subsection{Example}
  86 \nodename{termios Example}
  87
  88 Here's a function that prompts for a password with echoing turned
  89 off.  Note the technique using a separate \function{tcgetattr()} call
  90 and a \keyword{try} ... \keyword{finally} statement to ensure that the
  91 old tty attributes are restored exactly no matter what happens:
  92
  93 \begin{verbatim}
  94 def getpass(prompt = "Password: "):
  95     import termios, sys
  96     fd = sys.stdin.fileno()
  97     old = termios.tcgetattr(fd)
  98     new = termios.tcgetattr(fd)
  99     new[3] = new[3] & ~termios.ECHO          # lflags
 100     try:
 101         termios.tcsetattr(fd, termios.TCSADRAIN, new)
 102         passwd = raw_input(prompt)
 103     finally:
 104         termios.tcsetattr(fd, termios.TCSADRAIN, old)
 105     return passwd
 106 \end{verbatim}
 107
 108
 109 \section{\module{TERMIOS} ---
 110          Constants used with the \module{termios} module}
 111
 112 \declaremodule[TERMIOSuppercase]{standard}{TERMIOS}
 113   \platform{Unix}
 114 \modulesynopsis{Symbolic constants required to use the
 115   \module{termios} module.}
 116
 117
 118 \indexii{\POSIX}{I/O control}
 119 \indexii{tty}{I/O control}
 120
 121 \deprecated{2.1}{Import needed constants from \refmodule{termios}
 122                  instead.}
 123
 124 This module defines the symbolic constants required to use the
 125 \refmodule{termios}\refbimodindex{termios} module (see the previous
 126 section).  See the \POSIX{} or \UNIX{} manual pages for a list of
 127 those constants.