| 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 |
|