Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libtermios.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents bc02c3b09626
children 03be06bca160
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
1 \section{\module{termios} ---
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 10251
diff changeset
2 \POSIX{} style tty control}
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 10251
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
4 \declaremodule{builtin}{termios}
10335
093fc298afd6 "\platform{UNIX}" should really be spelled "\platform{Unix}".
Fred Drake <fdrake@acm.org>
parents: 10334
diff changeset
5 \platform{Unix}
17724
6dc36078f53e Work around limitations of the module synopsis table generation to avoid
Fred Drake <fdrake@acm.org>
parents: 17705
diff changeset
6 \modulesynopsis{\POSIX\ style tty control.}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
7
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 17724
diff changeset
8 \indexii{\POSIX}{I/O control}
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
9 \indexii{tty}{I/O control}
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
10
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
11
7222
10fdf16f4de9 Consistently use \POSIX{} to denote POSIX. There were at least two different
Fred Drake <fdrake@acm.org>
parents: 6917
diff changeset
12 This module provides an interface to the \POSIX{} calls for tty I/O
10fdf16f4de9 Consistently use \POSIX{} to denote POSIX. There were at least two different
Fred Drake <fdrake@acm.org>
parents: 6917
diff changeset
13 control. For a complete description of these calls, see the \POSIX{} or
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
14 \UNIX{} manual pages. It is only available for those \UNIX{} versions
7643
b95e523dce6c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7395
diff changeset
15 that support \POSIX{} \emph{termios} style tty I/O control (and then
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
16 only if configured at installation time).
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
17
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
18 All functions in this module take a file descriptor \var{fd} as their
17705
2f16062a1b7c Michael Hudson <mwh21@cam.ac.uk>:
Fred Drake <fdrake@acm.org>
parents: 16810
diff changeset
19 first argument. This can be an integer file descriptor, such as
2f16062a1b7c Michael Hudson <mwh21@cam.ac.uk>:
Fred Drake <fdrake@acm.org>
parents: 16810
diff changeset
20 returned by \code{sys.stdin.fileno()}, or a file object, such as
2f16062a1b7c Michael Hudson <mwh21@cam.ac.uk>:
Fred Drake <fdrake@acm.org>
parents: 16810
diff changeset
21 \code{sys.stdin} itself.
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
22
16810
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
23 This module also defines all the constants needed to work with the
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
24 functions provided here; these have the same name as their
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
25 counterparts in C. Please refer to your system documentation for more
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
26 information on using these terminal control interfaces.
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
27
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
28 The module defines the following functions:
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
29
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
30 \begin{funcdesc}{tcgetattr}{fd}
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
31 Return a list containing the tty attributes for file descriptor
7643
b95e523dce6c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7395
diff changeset
32 \var{fd}, as follows: \code{[}\var{iflag}, \var{oflag}, \var{cflag},
b95e523dce6c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7395
diff changeset
33 \var{lflag}, \var{ispeed}, \var{ospeed}, \var{cc}\code{]} where
b95e523dce6c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7395
diff changeset
34 \var{cc} is a list of the tty special characters (each a string of
16810
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
35 length 1, except the items with indices \constant{VMIN} and
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
36 \constant{VTIME}, which are integers when these fields are
7643
b95e523dce6c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7395
diff changeset
37 defined). The interpretation of the flags and the speeds as well as
b95e523dce6c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7395
diff changeset
38 the indexing in the \var{cc} array must be done using the symbolic
16810
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
39 constants defined in the \module{termios}
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 10251
diff changeset
40 module.
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
41 \end{funcdesc}
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
42
7643
b95e523dce6c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7395
diff changeset
43 \begin{funcdesc}{tcsetattr}{fd, when, attributes}
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
44 Set the tty attributes for file descriptor \var{fd} from the
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
45 \var{attributes}, which is a list like the one returned by
7643
b95e523dce6c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7395
diff changeset
46 \function{tcgetattr()}. The \var{when} argument determines when the
16810
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
47 attributes are changed: \constant{TCSANOW} to change immediately,
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
48 \constant{TCSADRAIN} to change after transmitting all queued output,
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
49 or \constant{TCSAFLUSH} to change after transmitting all queued
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
50 output and discarding all queued input.
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
51 \end{funcdesc}
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
52
7643
b95e523dce6c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7395
diff changeset
53 \begin{funcdesc}{tcsendbreak}{fd, duration}
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
54 Send a break on file descriptor \var{fd}. A zero \var{duration} sends
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
55 a break for 0.25--0.5 seconds; a nonzero \var{duration} has a system
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
56 dependent meaning.
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
57 \end{funcdesc}
2609
7ef72873e4d6 restructured library manual accordiung to functional group
Guido van Rossum <guido@python.org>
parents:
diff changeset
58
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
59 \begin{funcdesc}{tcdrain}{fd}
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
60 Wait until all output written to file descriptor \var{fd} has been
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
61 transmitted.
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
62 \end{funcdesc}
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
63
7643
b95e523dce6c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7395
diff changeset
64 \begin{funcdesc}{tcflush}{fd, queue}
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
65 Discard queued data on file descriptor \var{fd}. The \var{queue}
16810
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
66 selector specifies which queue: \constant{TCIFLUSH} for the input
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
67 queue, \constant{TCOFLUSH} for the output queue, or
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
68 \constant{TCIOFLUSH} for both queues.
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
69 \end{funcdesc}
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
70
7643
b95e523dce6c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7395
diff changeset
71 \begin{funcdesc}{tcflow}{fd, action}
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
72 Suspend or resume input or output on file descriptor \var{fd}. The
16810
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
73 \var{action} argument can be \constant{TCOOFF} to suspend output,
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
74 \constant{TCOON} to restart output, \constant{TCIOFF} to suspend
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
75 input, or \constant{TCION} to restart input.
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
76 \end{funcdesc}
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
77
11040
626caeca535a Added "See Also" section for termios module.
Fred Drake <fdrake@acm.org>
parents: 10335
diff changeset
78
626caeca535a Added "See Also" section for termios module.
Fred Drake <fdrake@acm.org>
parents: 10335
diff changeset
79 \begin{seealso}
626caeca535a Added "See Also" section for termios module.
Fred Drake <fdrake@acm.org>
parents: 10335
diff changeset
80 \seemodule{tty}{Convenience functions for common terminal control
626caeca535a Added "See Also" section for termios module.
Fred Drake <fdrake@acm.org>
parents: 10335
diff changeset
81 operations.}
626caeca535a Added "See Also" section for termios module.
Fred Drake <fdrake@acm.org>
parents: 10335
diff changeset
82 \end{seealso}
626caeca535a Added "See Also" section for termios module.
Fred Drake <fdrake@acm.org>
parents: 10335
diff changeset
83
626caeca535a Added "See Also" section for termios module.
Fred Drake <fdrake@acm.org>
parents: 10335
diff changeset
84
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
85 \subsection{Example}
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
86 \nodename{termios Example}
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
87
7643
b95e523dce6c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7395
diff changeset
88 Here's a function that prompts for a password with echoing turned
b95e523dce6c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7395
diff changeset
89 off. Note the technique using a separate \function{tcgetattr()} call
b95e523dce6c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7395
diff changeset
90 and a \keyword{try} ... \keyword{finally} statement to ensure that the
b95e523dce6c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7395
diff changeset
91 old tty attributes are restored exactly no matter what happens:
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
92
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7222
diff changeset
93 \begin{verbatim}
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
94 def getpass(prompt = "Password: "):
16810
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
95 import termios, sys
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
96 fd = sys.stdin.fileno()
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
97 old = termios.tcgetattr(fd)
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
98 new = termios.tcgetattr(fd)
16810
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
99 new[3] = new[3] & ~termios.ECHO # lflags
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
100 try:
16810
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
101 termios.tcsetattr(fd, termios.TCSADRAIN, new)
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
102 passwd = raw_input(prompt)
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
103 finally:
16810
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
104 termios.tcsetattr(fd, termios.TCSADRAIN, old)
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
105 return passwd
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7222
diff changeset
106 \end{verbatim}
7395
786875c4c62c Added \label{} for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
107
10251
d83935d14084 Shorten a few section titles.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
108
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
109 \section{\module{TERMIOS} ---
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 10251
diff changeset
110 Constants used with the \module{termios} module}
10251
d83935d14084 Shorten a few section titles.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
111
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
112 \declaremodule[TERMIOSuppercase]{standard}{TERMIOS}
10335
093fc298afd6 "\platform{UNIX}" should really be spelled "\platform{Unix}".
Fred Drake <fdrake@acm.org>
parents: 10334
diff changeset
113 \platform{Unix}
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
114 \modulesynopsis{Symbolic constants required to use the
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 10251
diff changeset
115 \module{termios} module.}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
116
10251
d83935d14084 Shorten a few section titles.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
117
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 17724
diff changeset
118 \indexii{\POSIX}{I/O control}
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
119 \indexii{tty}{I/O control}
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
120
16810
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
121 \deprecated{2.1}{Import needed constants from \refmodule{termios}
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
122 instead.}
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
123
2626
dbb41712165b documented termios + TERMIOS
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
124 This module defines the symbolic constants required to use the
16810
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
125 \refmodule{termios}\refbimodindex{termios} module (see the previous
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
126 section). See the \POSIX{} or \UNIX{} manual pages for a list of
50d9159edaab Update documentation for termios module; do not refer to the TERMIOS module
Fred Drake <fdrake@acm.org>
parents: 11040
diff changeset
127 those constants.