Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{termios}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-termios} |
Guido van Rossum | f9adf48 | 1995-03-31 12:26:24 +0000 | [diff] [blame] | 3 | \bimodindex{termios} |
| 4 | \indexii{Posix}{I/O control} |
| 5 | \indexii{tty}{I/O control} |
Guido van Rossum | ecde781 | 1995-03-28 13:35:14 +0000 | [diff] [blame] | 6 | |
Guido van Rossum | f9adf48 | 1995-03-31 12:26:24 +0000 | [diff] [blame] | 7 | \renewcommand{\indexsubitem}{(in module termios)} |
| 8 | |
| 9 | This module provides an interface to the Posix calls for tty I/O |
| 10 | control. For a complete description of these calls, see the Posix or |
| 11 | \UNIX{} manual pages. It is only available for those \UNIX{} versions |
| 12 | that support Posix \code{termios} style tty I/O control (and then |
| 13 | only if configured at installation time). |
| 14 | |
| 15 | All functions in this module take a file descriptor \var{fd} as their |
| 16 | first argument. This must be an integer file descriptor, such as |
| 17 | returned by \code{sys.stdin.fileno()}. |
| 18 | |
| 19 | This module should be used in conjunction with the \code{TERMIOS} |
| 20 | module, which defines the relevant symbolic constants (see the next |
| 21 | section). |
| 22 | |
| 23 | The module defines the following functions: |
| 24 | |
| 25 | \begin{funcdesc}{tcgetattr}{fd} |
| 26 | Return a list containing the tty attributes for file descriptor |
| 27 | \var{fd}, as follows: \code{[\var{iflag}, \var{oflag}, \var{cflag}, |
| 28 | \var{lflag}, \var{ispeed}, \var{ospeed}, \var{cc}]} where \var{cc} is |
| 29 | a list of the tty special characters (each a string of length 1, |
| 30 | except the items with indices \code{VMIN} and \code{VTIME}, which are |
| 31 | integers when these fields are defined). The interpretation of the |
| 32 | flags and the speeds as well as the indexing in the \var{cc} array |
| 33 | must be done using the symbolic constants defined in the |
| 34 | \code{TERMIOS} module. |
| 35 | \end{funcdesc} |
| 36 | |
| 37 | \begin{funcdesc}{tcsetattr}{fd\, when\, attributes} |
| 38 | Set the tty attributes for file descriptor \var{fd} from the |
| 39 | \var{attributes}, which is a list like the one returned by |
| 40 | \code{tcgetattr()}. The \var{when} argument determines when the |
| 41 | attributes are changed: \code{TERMIOS.TCSANOW} to change immediately, |
| 42 | \code{TERMIOS.TCSADRAIN} to change after transmitting all queued |
| 43 | output, or \code{TERMIOS.TCSAFLUSH} to change after transmitting all |
| 44 | queued output and discarding all queued input. |
| 45 | \end{funcdesc} |
| 46 | |
| 47 | \begin{funcdesc}{tcsendbreak}{fd\, duration} |
| 48 | Send a break on file descriptor \var{fd}. A zero \var{duration} sends |
| 49 | a break for 0.25--0.5 seconds; a nonzero \var{duration} has a system |
| 50 | dependent meaning. |
| 51 | \end{funcdesc} |
| 52 | |
| 53 | \begin{funcdesc}{tcdrain}{fd} |
| 54 | Wait until all output written to file descriptor \var{fd} has been |
| 55 | transmitted. |
| 56 | \end{funcdesc} |
| 57 | |
| 58 | \begin{funcdesc}{tcflush}{fd\, queue} |
| 59 | Discard queued data on file descriptor \var{fd}. The \var{queue} |
| 60 | selector specifies which queue: \code{TERMIOS.TCIFLUSH} for the input |
| 61 | queue, \code{TERMIOS.TCOFLUSH} for the output queue, or |
| 62 | \code{TERMIOS.TCIOFLUSH} for both queues. |
| 63 | \end{funcdesc} |
| 64 | |
| 65 | \begin{funcdesc}{tcflow}{fd\, action} |
| 66 | Suspend or resume input or output on file descriptor \var{fd}. The |
| 67 | \var{action} argument can be \code{TERMIOS.TCOOFF} to suspend output, |
| 68 | \code{TERMIOS.TCOON} to restart output, \code{TERMIOS.TCIOFF} to |
| 69 | suspend input, or \code{TERMIOS.TCION} to restart input. |
| 70 | \end{funcdesc} |
| 71 | |
| 72 | \subsection{Example} |
| 73 | \nodename{termios Example} |
| 74 | |
| 75 | Here's a function that prompts for a password with echoing turned off. |
| 76 | Note the technique using a separate \code{termios.tcgetattr()} call |
Fred Drake | 4b3f031 | 1996-12-13 22:04:31 +0000 | [diff] [blame] | 77 | and a \code{try \ldots{} finally} statement to ensure that the old tty |
Guido van Rossum | f9adf48 | 1995-03-31 12:26:24 +0000 | [diff] [blame] | 78 | attributes are restored exactly no matter what happens: |
| 79 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 80 | \bcode\begin{verbatim} |
Guido van Rossum | f9adf48 | 1995-03-31 12:26:24 +0000 | [diff] [blame] | 81 | def getpass(prompt = "Password: "): |
| 82 | import termios, TERMIOS, sys |
| 83 | fd = sys.stdin.fileno() |
| 84 | old = termios.tcgetattr(fd) |
| 85 | new = termios.tcgetattr(fd) |
| 86 | new[3] = new[3] & ~TERMIOS.ECHO # lflags |
| 87 | try: |
| 88 | termios.tcsetattr(fd, TERMIOS.TCSADRAIN, new) |
| 89 | passwd = raw_input(prompt) |
| 90 | finally: |
| 91 | termios.tcsetattr(fd, TERMIOS.TCSADRAIN, old) |
| 92 | return passwd |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 93 | \end{verbatim}\ecode |
| 94 | % |
Guido van Rossum | f9adf48 | 1995-03-31 12:26:24 +0000 | [diff] [blame] | 95 | \section{Standard Module \sectcode{TERMIOS}} |
| 96 | \stmodindex{TERMIOS} |
| 97 | \indexii{Posix}{I/O control} |
| 98 | \indexii{tty}{I/O control} |
| 99 | |
| 100 | \renewcommand{\indexsubitem}{(in module TERMIOS)} |
| 101 | |
| 102 | This module defines the symbolic constants required to use the |
| 103 | \code{termios} module (see the previous section). See the Posix or |
| 104 | \UNIX{} manual pages (or the source) for a list of those constants. |
| 105 | |
| 106 | Note: this module resides in a system-dependent subdirectory of the |
| 107 | Python library directory. You may have to generate it for your |
| 108 | particular system using the script \file{Tools/scripts/h2py.py}. |