1 

     2 :mod:`termios` --- POSIX style tty control

     3 ==========================================

     4 

     5 .. module:: termios

     6    :platform: Unix

     7    :synopsis: POSIX style tty control.

     8 

     9 

    10 .. index::

    11    pair: POSIX; I/O control

    12    pair: tty; I/O control

    13 

    14 This module provides an interface to the POSIX calls for tty I/O control.  For a

    15 complete description of these calls, see the POSIX or Unix manual pages.  It is

    16 only available for those Unix versions that support POSIX *termios* style tty

    17 I/O control (and then only if configured at installation time).

    18 

    19 All functions in this module take a file descriptor *fd* as their first

    20 argument.  This can be an integer file descriptor, such as returned by

    21 ``sys.stdin.fileno()``, or a file object, such as ``sys.stdin`` itself.

    22 

    23 This module also defines all the constants needed to work with the functions

    24 provided here; these have the same name as their counterparts in C.  Please

    25 refer to your system documentation for more information on using these terminal

    26 control interfaces.

    27 

    28 The module defines the following functions:

    29 

    30 

    31 .. function:: tcgetattr(fd)

    32 

    33    Return a list containing the tty attributes for file descriptor *fd*, as

    34    follows: ``[iflag, oflag, cflag, lflag, ispeed, ospeed, cc]`` where *cc* is a

    35    list of the tty special characters (each a string of length 1, except the

    36    items with indices :const:`VMIN` and :const:`VTIME`, which are integers when

    37    these fields are defined).  The interpretation of the flags and the speeds as

    38    well as the indexing in the *cc* array must be done using the symbolic

    39    constants defined in the :mod:`termios` module.

    40 

    41 

    42 .. function:: tcsetattr(fd, when, attributes)

    43 

    44    Set the tty attributes for file descriptor *fd* from the *attributes*, which is

    45    a list like the one returned by :func:`tcgetattr`.  The *when* argument

    46    determines when the attributes are changed: :const:`TCSANOW` to change

    47    immediately, :const:`TCSADRAIN` to change after transmitting all queued output,

    48    or :const:`TCSAFLUSH` to change after transmitting all queued output and

    49    discarding all queued input.

    50 

    51 

    52 .. function:: tcsendbreak(fd, duration)

    53 

    54    Send a break on file descriptor *fd*.  A zero *duration* sends a break for 0.25

    55    --0.5 seconds; a nonzero *duration* has a system dependent meaning.

    56 

    57 

    58 .. function:: tcdrain(fd)

    59 

    60    Wait until all output written to file descriptor *fd* has been transmitted.

    61 

    62 

    63 .. function:: tcflush(fd, queue)

    64 

    65    Discard queued data on file descriptor *fd*.  The *queue* selector specifies

    66    which queue: :const:`TCIFLUSH` for the input queue, :const:`TCOFLUSH` for the

    67    output queue, or :const:`TCIOFLUSH` for both queues.

    68 

    69 

    70 .. function:: tcflow(fd, action)

    71 

    72    Suspend or resume input or output on file descriptor *fd*.  The *action*

    73    argument can be :const:`TCOOFF` to suspend output, :const:`TCOON` to restart

    74    output, :const:`TCIOFF` to suspend input, or :const:`TCION` to restart input.

    75 

    76 

    77 .. seealso::

    78 

    79    Module :mod:`tty`

    80       Convenience functions for common terminal control operations.

    81 

    82 

    83 Example

    84 -------

    85 

    86 .. _termios-example:

    87 

    88 Here's a function that prompts for a password with echoing turned off.  Note the

    89 technique using a separate :func:`tcgetattr` call and a :keyword:`try` ...

    90 :keyword:`finally` statement to ensure that the old tty attributes are restored

    91 exactly no matter what happens::

    92 

    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