PageRenderTime 36ms CodeModel.GetById 11ms app.highlight 16ms RepoModel.GetById 1ms app.codeStats 1ms

/Doc/library/termios.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 105 lines | 70 code | 35 blank | 0 comment | 0 complexity | faa75b56bdeb035b434cc93f0091d173 MD5 | raw file
  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
 14This module provides an interface to the POSIX calls for tty I/O control.  For a
 15complete description of these calls, see the POSIX or Unix manual pages.  It is
 16only available for those Unix versions that support POSIX *termios* style tty
 17I/O control (and then only if configured at installation time).
 18
 19All functions in this module take a file descriptor *fd* as their first
 20argument.  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
 23This module also defines all the constants needed to work with the functions
 24provided here; these have the same name as their counterparts in C.  Please
 25refer to your system documentation for more information on using these terminal
 26control interfaces.
 27
 28The 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
 83Example
 84-------
 85
 86.. _termios-example:
 87
 88Here's a function that prompts for a password with echoing turned off.  Note the
 89technique using a separate :func:`tcgetattr` call and a :keyword:`try` ...
 90:keyword:`finally` statement to ensure that the old tty attributes are restored
 91exactly 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