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