blob: bcaaed98d38c1bc92e688651a95d35b19c8073d6 [file] [log] [blame]
Fred Drake295da241998-08-10 19:42:37 +00001\section{\module{termios} ---
Fred Drakef6863c11999-03-02 16:37:17 +00002 \POSIX{} style tty control}
Fred Drakeb91e9341998-07-23 17:59:49 +00003
Fred Drakef6863c11999-03-02 16:37:17 +00004\declaremodule{builtin}{termios}
Fred Drakea54a8871999-03-02 17:03:42 +00005 \platform{Unix}
Fred Drakeb91e9341998-07-23 17:59:49 +00006\modulesynopsis{\POSIX{} style tty control.}
7
Fred Drake65b32f71998-02-09 20:27:12 +00008\indexii{\POSIX{}}{I/O control}
Guido van Rossumf9adf481995-03-31 12:26:24 +00009\indexii{tty}{I/O control}
Guido van Rossumecde7811995-03-28 13:35:14 +000010
Guido van Rossumf9adf481995-03-31 12:26:24 +000011
Fred Drake65b32f71998-02-09 20:27:12 +000012This module provides an interface to the \POSIX{} calls for tty I/O
13control. For a complete description of these calls, see the \POSIX{} or
Guido van Rossumf9adf481995-03-31 12:26:24 +000014\UNIX{} manual pages. It is only available for those \UNIX{} versions
Fred Drakee42f5951998-03-11 06:00:23 +000015that support \POSIX{} \emph{termios} style tty I/O control (and then
Guido van Rossumf9adf481995-03-31 12:26:24 +000016only if configured at installation time).
17
18All functions in this module take a file descriptor \var{fd} as their
19first argument. This must be an integer file descriptor, such as
20returned by \code{sys.stdin.fileno()}.
21
Fred Drakee42f5951998-03-11 06:00:23 +000022This module should be used in conjunction with the
Fred Drakef6863c11999-03-02 16:37:17 +000023\refmodule[TERMIOSuppercase]{TERMIOS}\refstmodindex{TERMIOS} module,
24which defines the relevant symbolic constants (see the next section).
Guido van Rossumf9adf481995-03-31 12:26:24 +000025
26The module defines the following functions:
27
28\begin{funcdesc}{tcgetattr}{fd}
29Return a list containing the tty attributes for file descriptor
Fred Drakee42f5951998-03-11 06:00:23 +000030\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
33length 1, except the items with indices \constant{TERMIOS.VMIN} and
34\constant{TERMIOS.VTIME}, which are integers when these fields are
35defined). The interpretation of the flags and the speeds as well as
36the indexing in the \var{cc} array must be done using the symbolic
Fred Drakef6863c11999-03-02 16:37:17 +000037constants defined in the \refmodule[TERMIOSuppercase]{TERMIOS}
38module.
Guido van Rossumf9adf481995-03-31 12:26:24 +000039\end{funcdesc}
40
Fred Drakee42f5951998-03-11 06:00:23 +000041\begin{funcdesc}{tcsetattr}{fd, when, attributes}
Guido van Rossumf9adf481995-03-31 12:26:24 +000042Set the tty attributes for file descriptor \var{fd} from the
43\var{attributes}, which is a list like the one returned by
Fred Drakee42f5951998-03-11 06:00:23 +000044\function{tcgetattr()}. The \var{when} argument determines when the
45attributes are changed: \constant{TERMIOS.TCSANOW} to change
46immediately, \constant{TERMIOS.TCSADRAIN} to change after transmitting
47all queued output, or \constant{TERMIOS.TCSAFLUSH} to change after
48transmitting all queued output and discarding all queued input.
Guido van Rossumf9adf481995-03-31 12:26:24 +000049\end{funcdesc}
50
Fred Drakee42f5951998-03-11 06:00:23 +000051\begin{funcdesc}{tcsendbreak}{fd, duration}
Guido van Rossumf9adf481995-03-31 12:26:24 +000052Send a break on file descriptor \var{fd}. A zero \var{duration} sends
53a break for 0.25--0.5 seconds; a nonzero \var{duration} has a system
54dependent meaning.
55\end{funcdesc}
56
57\begin{funcdesc}{tcdrain}{fd}
58Wait until all output written to file descriptor \var{fd} has been
59transmitted.
60\end{funcdesc}
61
Fred Drakee42f5951998-03-11 06:00:23 +000062\begin{funcdesc}{tcflush}{fd, queue}
Guido van Rossumf9adf481995-03-31 12:26:24 +000063Discard queued data on file descriptor \var{fd}. The \var{queue}
Fred Drakee42f5951998-03-11 06:00:23 +000064selector specifies which queue: \constant{TERMIOS.TCIFLUSH} for the
65input queue, \constant{TERMIOS.TCOFLUSH} for the output queue, or
66\constant{TERMIOS.TCIOFLUSH} for both queues.
Guido van Rossumf9adf481995-03-31 12:26:24 +000067\end{funcdesc}
68
Fred Drakee42f5951998-03-11 06:00:23 +000069\begin{funcdesc}{tcflow}{fd, action}
Guido van Rossumf9adf481995-03-31 12:26:24 +000070Suspend or resume input or output on file descriptor \var{fd}. The
Fred Drakee42f5951998-03-11 06:00:23 +000071\var{action} argument can be \constant{TERMIOS.TCOOFF} to suspend
72output, \constant{TERMIOS.TCOON} to restart output,
73\constant{TERMIOS.TCIOFF} to suspend input, or
74\constant{TERMIOS.TCION} to restart input.
Guido van Rossumf9adf481995-03-31 12:26:24 +000075\end{funcdesc}
76
Fred Drake92f3f411999-06-23 15:12:09 +000077
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 Rossumf9adf481995-03-31 12:26:24 +000086\subsection{Example}
87\nodename{termios Example}
88
Fred Drakee42f5951998-03-11 06:00:23 +000089Here's a function that prompts for a password with echoing turned
90off. Note the technique using a separate \function{tcgetattr()} call
91and a \keyword{try} ... \keyword{finally} statement to ensure that the
92old tty attributes are restored exactly no matter what happens:
Guido van Rossumf9adf481995-03-31 12:26:24 +000093
Fred Drake19479911998-02-13 06:58:54 +000094\begin{verbatim}
Guido van Rossumf9adf481995-03-31 12:26:24 +000095def getpass(prompt = "Password: "):
96 import termios, TERMIOS, sys
97 fd = sys.stdin.fileno()
98 old = termios.tcgetattr(fd)
99 new = termios.tcgetattr(fd)
Fred Drakee42f5951998-03-11 06:00:23 +0000100 new[3] = new[3] & ~TERMIOS.ECHO # lflags
Guido van Rossumf9adf481995-03-31 12:26:24 +0000101 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 Drake19479911998-02-13 06:58:54 +0000107\end{verbatim}
Fred Drake83efb541998-02-19 20:07:39 +0000108
Fred Drakeb91e9341998-07-23 17:59:49 +0000109
Fred Drakebbac4321999-02-20 00:14:17 +0000110\section{\module{TERMIOS} ---
Fred Drakef6863c11999-03-02 16:37:17 +0000111 Constants used with the \module{termios} module}
Fred Drakebbac4321999-02-20 00:14:17 +0000112
113\declaremodule[TERMIOSuppercase]{standard}{TERMIOS}
Fred Drakea54a8871999-03-02 17:03:42 +0000114 \platform{Unix}
Fred Drake295da241998-08-10 19:42:37 +0000115\modulesynopsis{Symbolic constants required to use the
Fred Drakef6863c11999-03-02 16:37:17 +0000116 \module{termios} module.}
Fred Drakeb91e9341998-07-23 17:59:49 +0000117
Fred Drakebbac4321999-02-20 00:14:17 +0000118
Fred Drake65b32f71998-02-09 20:27:12 +0000119\indexii{\POSIX{}}{I/O control}
Guido van Rossumf9adf481995-03-31 12:26:24 +0000120\indexii{tty}{I/O control}
121
Guido van Rossumf9adf481995-03-31 12:26:24 +0000122This module defines the symbolic constants required to use the
Fred Drakef6863c11999-03-02 16:37:17 +0000123\refmodule{termios}\refbimodindex{termios} module (see the previous
Fred Drakee42f5951998-03-11 06:00:23 +0000124section). See the \POSIX{} or \UNIX{} manual pages (or the source)
125for a list of those constants.
Guido van Rossumf9adf481995-03-31 12:26:24 +0000126
127Note: this module resides in a system-dependent subdirectory of the
128Python library directory. You may have to generate it for your
129particular system using the script \file{Tools/scripts/h2py.py}.