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
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 :term:`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
55   0.25--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.. function:: tcgetwinsize(fd)
78
79   Return a tuple ``(ws_row, ws_col)`` containing the tty window size for file
80   descriptor *fd*. Requires :const:`termios.TIOCGWINSZ` or
81   :const:`termios.TIOCGSIZE`.
82
83   .. versionadded:: 3.11
84
85
86.. function:: tcsetwinsize(fd, winsize)
87
88   Set the tty window size for file descriptor *fd* from *winsize*, which is
89   a two-item tuple ``(ws_row, ws_col)`` like the one returned by
90   :func:`tcgetwinsize`. Requires at least one of the pairs
91   (:const:`termios.TIOCGWINSZ`, :const:`termios.TIOCSWINSZ`);
92   (:const:`termios.TIOCGSIZE`, :const:`termios.TIOCSSIZE`) to be defined.
93
94   .. versionadded:: 3.11
95
96
97.. seealso::
98
99   Module :mod:`tty`
100      Convenience functions for common terminal control operations.
101
102
103.. _termios-example:
104
105Example
106-------
107
108Here's a function that prompts for a password with echoing turned off.  Note the
109technique using a separate :func:`tcgetattr` call and a :keyword:`try` ...
110:keyword:`finally` statement to ensure that the old tty attributes are restored
111exactly no matter what happens::
112
113   def getpass(prompt="Password: "):
114       import termios, sys
115       fd = sys.stdin.fileno()
116       old = termios.tcgetattr(fd)
117       new = termios.tcgetattr(fd)
118       new[3] = new[3] & ~termios.ECHO          # lflags
119       try:
120           termios.tcsetattr(fd, termios.TCSADRAIN, new)
121           passwd = input(prompt)
122       finally:
123           termios.tcsetattr(fd, termios.TCSADRAIN, old)
124       return passwd
125
126