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