Debian Codegraph @

Doc/library/termios.rst

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