Doc/lib/libtermios.tex

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