1:mod:`!termios` --- POSIX style tty control 2=========================================== 3 4.. module:: termios 5 :platform: Unix 6 :synopsis: POSIX style tty control. 7 8.. index:: 9 pair: POSIX; I/O control 10 pair: tty; I/O control 11 12-------------- 13 14This module provides an interface to the POSIX calls for tty I/O control. For a 15complete description of these calls, see :manpage:`termios(3)` Unix manual 16page. It is only available for those Unix versions that support POSIX 17*termios* style tty I/O control configured during installation. 18 19.. availability:: Unix. 20 21All functions in this module take a file descriptor *fd* as their first 22argument. This can be an integer file descriptor, such as returned by 23``sys.stdin.fileno()``, or a :term:`file object`, such as ``sys.stdin`` itself. 24 25This module also defines all the constants needed to work with the functions 26provided here; these have the same name as their counterparts in C. Please 27refer to your system documentation for more information on using these terminal 28control interfaces. 29 30The module defines the following functions: 31 32 33.. function:: tcgetattr(fd) 34 35 Return a list containing the tty attributes for file descriptor *fd*, as 36 follows: ``[iflag, oflag, cflag, lflag, ispeed, ospeed, cc]`` where *cc* is a 37 list of the tty special characters (each a string of length 1, except the 38 items with indices :const:`VMIN` and :const:`VTIME`, which are integers when 39 these fields are defined). The interpretation of the flags and the speeds as 40 well as the indexing in the *cc* array must be done using the symbolic 41 constants defined in the :mod:`termios` module. 42 43 44.. function:: tcsetattr(fd, when, attributes) 45 46 Set the tty attributes for file descriptor *fd* from the *attributes*, which is 47 a list like the one returned by :func:`tcgetattr`. The *when* argument 48 determines when the attributes are changed: 49 50 .. data:: TCSANOW 51 52 Change attributes immediately. 53 54 .. data:: TCSADRAIN 55 56 Change attributes after transmitting all queued output. 57 58 .. data:: TCSAFLUSH 59 60 Change attributes after transmitting all queued output and 61 discarding all queued input. 62 63 64.. function:: tcsendbreak(fd, duration) 65 66 Send a break on file descriptor *fd*. A zero *duration* sends a break for 67 0.25--0.5 seconds; a nonzero *duration* has a system dependent meaning. 68 69 70.. function:: tcdrain(fd) 71 72 Wait until all output written to file descriptor *fd* has been transmitted. 73 74 75.. function:: tcflush(fd, queue) 76 77 Discard queued data on file descriptor *fd*. The *queue* selector specifies 78 which queue: :const:`TCIFLUSH` for the input queue, :const:`TCOFLUSH` for the 79 output queue, or :const:`TCIOFLUSH` for both queues. 80 81 82.. function:: tcflow(fd, action) 83 84 Suspend or resume input or output on file descriptor *fd*. The *action* 85 argument can be :const:`TCOOFF` to suspend output, :const:`TCOON` to restart 86 output, :const:`TCIOFF` to suspend input, or :const:`TCION` to restart input. 87 88 89.. function:: tcgetwinsize(fd) 90 91 Return a tuple ``(ws_row, ws_col)`` containing the tty window size for file 92 descriptor *fd*. Requires :const:`termios.TIOCGWINSZ` or 93 :const:`termios.TIOCGSIZE`. 94 95 .. versionadded:: 3.11 96 97 98.. function:: tcsetwinsize(fd, winsize) 99 100 Set the tty window size for file descriptor *fd* from *winsize*, which is 101 a two-item tuple ``(ws_row, ws_col)`` like the one returned by 102 :func:`tcgetwinsize`. Requires at least one of the pairs 103 (:const:`termios.TIOCGWINSZ`, :const:`termios.TIOCSWINSZ`); 104 (:const:`termios.TIOCGSIZE`, :const:`termios.TIOCSSIZE`) to be defined. 105 106 .. versionadded:: 3.11 107 108 109.. seealso:: 110 111 Module :mod:`tty` 112 Convenience functions for common terminal control operations. 113 114 115.. _termios-example: 116 117Example 118------- 119 120Here's a function that prompts for a password with echoing turned off. Note the 121technique using a separate :func:`tcgetattr` call and a :keyword:`try` ... 122:keyword:`finally` statement to ensure that the old tty attributes are restored 123exactly no matter what happens:: 124 125 def getpass(prompt="Password: "): 126 import termios, sys 127 fd = sys.stdin.fileno() 128 old = termios.tcgetattr(fd) 129 new = termios.tcgetattr(fd) 130 new[3] = new[3] & ~termios.ECHO # lflags 131 try: 132 termios.tcsetattr(fd, termios.TCSADRAIN, new) 133 passwd = input(prompt) 134 finally: 135 termios.tcsetattr(fd, termios.TCSADRAIN, old) 136 return passwd 137 138