]>
Commit | Line | Data |
---|---|---|
d52b6462 | 1 | @node Low-Level Terminal Interface, Syslog, Sockets, Top |
7a68c94a | 2 | @c %MENU% How to change the characteristics of a terminal device |
28f540f4 RM |
3 | @chapter Low-Level Terminal Interface |
4 | ||
5 | This chapter describes functions that are specific to terminal devices. | |
6 | You can use these functions to do things like turn off input echoing; | |
7 | set serial line characteristics such as line speed and flow control; and | |
8 | change which characters are used for end-of-file, command-line editing, | |
9 | sending signals, and similar control functions. | |
10 | ||
11 | Most of the functions in this chapter operate on file descriptors. | |
12 | @xref{Low-Level I/O}, for more information about what a file | |
13 | descriptor is and how to open a file descriptor for a terminal device. | |
14 | ||
15 | @menu | |
16 | * Is It a Terminal:: How to determine if a file is a terminal | |
17 | device, and what its name is. | |
18 | * I/O Queues:: About flow control and typeahead. | |
19 | * Canonical or Not:: Two basic styles of input processing. | |
20 | * Terminal Modes:: How to examine and modify flags controlling | |
21 | details of terminal I/O: echoing, | |
e52236e5 UD |
22 | signals, editing. Posix. |
23 | * BSD Terminal Modes:: BSD compatible terminal mode setting | |
28f540f4 | 24 | * Line Control:: Sending break sequences, clearing |
6d52618b | 25 | terminal buffers @dots{} |
28f540f4 | 26 | * Noncanon Example:: How to read single characters without echo. |
841785ba | 27 | * getpass:: Prompting the user for a passphrase. |
a53bad16 | 28 | * Pseudo-Terminals:: How to open a pseudo-terminal. |
28f540f4 RM |
29 | @end menu |
30 | ||
31 | @node Is It a Terminal | |
32 | @section Identifying Terminals | |
33 | @cindex terminal identification | |
34 | @cindex identifying terminals | |
35 | ||
36 | The functions described in this chapter only work on files that | |
37 | correspond to terminal devices. You can find out whether a file | |
38 | descriptor is associated with a terminal by using the @code{isatty} | |
39 | function. | |
40 | ||
41 | @pindex unistd.h | |
a53bad16 UD |
42 | Prototypes for the functions in this section are declared in the header |
43 | file @file{unistd.h}. | |
28f540f4 | 44 | |
28f540f4 | 45 | @deftypefun int isatty (int @var{filedes}) |
d08a7e4c | 46 | @standards{POSIX.1, unistd.h} |
f8d529d5 AO |
47 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
48 | @c isatty ok | |
49 | @c tcgetattr dup ok | |
28f540f4 | 50 | This function returns @code{1} if @var{filedes} is a file descriptor |
a53bad16 | 51 | associated with an open terminal device, and @math{0} otherwise. |
28f540f4 RM |
52 | @end deftypefun |
53 | ||
54 | If a file descriptor is associated with a terminal, you can get its | |
55 | associated file name using the @code{ttyname} function. See also the | |
56 | @code{ctermid} function, described in @ref{Identifying the Terminal}. | |
57 | ||
28f540f4 | 58 | @deftypefun {char *} ttyname (int @var{filedes}) |
d08a7e4c | 59 | @standards{POSIX.1, unistd.h} |
f8d529d5 AO |
60 | @safety{@prelim{}@mtunsafe{@mtasurace{:ttyname}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} |
61 | @c ttyname @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd | |
62 | @c isatty dup ok | |
63 | @c fstat dup ok | |
64 | @c memcpy dup ok | |
65 | @c getttyname @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd | |
66 | @c opendir @ascuheap @acsmem @acsfd | |
67 | @c readdir ok [protected by exclusive access] | |
68 | @c strcmp dup ok | |
69 | @c free dup @asulock @aculock @acsfd @acsmem | |
70 | @c malloc dup @asulock @aculock @acsfd @acsmem | |
71 | @c closedir @ascuheap @acsmem @acsfd | |
72 | @c mempcpy dup ok | |
73 | @c stat dup ok | |
28f540f4 RM |
74 | If the file descriptor @var{filedes} is associated with a terminal |
75 | device, the @code{ttyname} function returns a pointer to a | |
76 | statically-allocated, null-terminated string containing the file name of | |
77 | the terminal file. The value is a null pointer if the file descriptor | |
78 | isn't associated with a terminal, or the file name cannot be determined. | |
79 | @end deftypefun | |
80 | ||
a53bad16 | 81 | @deftypefun int ttyname_r (int @var{filedes}, char *@var{buf}, size_t @var{len}) |
d08a7e4c | 82 | @standards{POSIX.1, unistd.h} |
f8d529d5 AO |
83 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} |
84 | @c ttyname_r @ascuheap @acsmem @acsfd | |
85 | @c isatty dup ok | |
86 | @c fstat dup ok | |
87 | @c memcpy dup ok | |
88 | @c getttyname_r @ascuheap @acsmem @acsfd | |
89 | @c opendir @ascuheap @acsmem @acsfd | |
90 | @c readdir ok [protected by exclusive access] | |
91 | @c strcmp dup ok | |
92 | @c closedir @ascuheap @acsmem @acsfd | |
93 | @c stpncpy dup ok | |
94 | @c stat dup ok | |
a53bad16 UD |
95 | The @code{ttyname_r} function is similar to the @code{ttyname} function |
96 | except that it places its result into the user-specified buffer starting | |
97 | at @var{buf} with length @var{len}. | |
98 | ||
99 | The normal return value from @code{ttyname_r} is @math{0}. Otherwise an | |
100 | error number is returned to indicate the error. The following | |
101 | @code{errno} error conditions are defined for this function: | |
102 | ||
103 | @table @code | |
104 | @item EBADF | |
105 | The @var{filedes} argument is not a valid file descriptor. | |
106 | ||
107 | @item ENOTTY | |
108 | The @var{filedes} is not associated with a terminal. | |
109 | ||
110 | @item ERANGE | |
111 | The buffer length @var{len} is too small to store the string to be | |
112 | returned. | |
495a56fd LS |
113 | |
114 | @item ENODEV | |
115 | The @var{filedes} is associated with a terminal device that is a slave | |
116 | pseudo-terminal, but the file name associated with that device could | |
117 | not be determined. This is a GNU extension. | |
a53bad16 UD |
118 | @end table |
119 | @end deftypefun | |
120 | ||
28f540f4 RM |
121 | @node I/O Queues |
122 | @section I/O Queues | |
123 | ||
124 | Many of the remaining functions in this section refer to the input and | |
125 | output queues of a terminal device. These queues implement a form of | |
126 | buffering @emph{within the kernel} independent of the buffering | |
127 | implemented by I/O streams (@pxref{I/O on Streams}). | |
128 | ||
129 | @cindex terminal input queue | |
130 | @cindex typeahead buffer | |
131 | The @dfn{terminal input queue} is also sometimes referred to as its | |
132 | @dfn{typeahead buffer}. It holds the characters that have been received | |
133 | from the terminal but not yet read by any process. | |
134 | ||
838e5ffe UD |
135 | The size of the input queue is described by the @code{MAX_INPUT} and |
136 | @w{@code{_POSIX_MAX_INPUT}} parameters; see @ref{Limits for Files}. You | |
137 | are guaranteed a queue size of at least @code{MAX_INPUT}, but the queue | |
138 | might be larger, and might even dynamically change size. If input flow | |
139 | control is enabled by setting the @code{IXOFF} input mode bit | |
140 | (@pxref{Input Modes}), the terminal driver transmits STOP and START | |
141 | characters to the terminal when necessary to prevent the queue from | |
142 | overflowing. Otherwise, input may be lost if it comes in too fast from | |
143 | the terminal. In canonical mode, all input stays in the queue until a | |
144 | newline character is received, so the terminal input queue can fill up | |
145 | when you type a very long line. @xref{Canonical or Not}. | |
28f540f4 RM |
146 | |
147 | @cindex terminal output queue | |
148 | The @dfn{terminal output queue} is like the input queue, but for output; | |
149 | it contains characters that have been written by processes, but not yet | |
150 | transmitted to the terminal. If output flow control is enabled by | |
151 | setting the @code{IXON} input mode bit (@pxref{Input Modes}), the | |
2d26e9eb | 152 | terminal driver obeys START and STOP characters sent by the terminal to |
28f540f4 RM |
153 | stop and restart transmission of output. |
154 | ||
155 | @dfn{Clearing} the terminal input queue means discarding any characters | |
156 | that have been received but not yet read. Similarly, clearing the | |
157 | terminal output queue means discarding any characters that have been | |
158 | written but not yet transmitted. | |
159 | ||
160 | @node Canonical or Not | |
161 | @section Two Styles of Input: Canonical or Not | |
162 | ||
163 | POSIX systems support two basic modes of input: canonical and | |
164 | noncanonical. | |
165 | ||
166 | @cindex canonical input processing | |
167 | In @dfn{canonical input processing} mode, terminal input is processed in | |
168 | lines terminated by newline (@code{'\n'}), EOF, or EOL characters. No | |
169 | input can be read until an entire line has been typed by the user, and | |
170 | the @code{read} function (@pxref{I/O Primitives}) returns at most a | |
171 | single line of input, no matter how many bytes are requested. | |
172 | ||
173 | In canonical input mode, the operating system provides input editing | |
174 | facilities: some characters are interpreted specially to perform editing | |
175 | operations within the current line of text, such as ERASE and KILL. | |
176 | @xref{Editing Characters}. | |
177 | ||
178 | The constants @code{_POSIX_MAX_CANON} and @code{MAX_CANON} parameterize | |
179 | the maximum number of bytes which may appear in a single line of | |
180 | canonical input. @xref{Limits for Files}. You are guaranteed a maximum | |
181 | line length of at least @code{MAX_CANON} bytes, but the maximum might be | |
182 | larger, and might even dynamically change size. | |
183 | ||
184 | @cindex noncanonical input processing | |
185 | In @dfn{noncanonical input processing} mode, characters are not grouped | |
186 | into lines, and ERASE and KILL processing is not performed. The | |
187 | granularity with which bytes are read in noncanonical input mode is | |
188 | controlled by the MIN and TIME settings. @xref{Noncanonical Input}. | |
189 | ||
190 | Most programs use canonical input mode, because this gives the user a | |
191 | way to edit input line by line. The usual reason to use noncanonical | |
192 | mode is when the program accepts single-character commands or provides | |
193 | its own editing facilities. | |
194 | ||
195 | The choice of canonical or noncanonical input is controlled by the | |
196 | @code{ICANON} flag in the @code{c_lflag} member of @code{struct termios}. | |
197 | @xref{Local Modes}. | |
198 | ||
199 | @node Terminal Modes | |
200 | @section Terminal Modes | |
201 | ||
202 | @pindex termios.h | |
203 | This section describes the various terminal attributes that control how | |
204 | input and output are done. The functions, data structures, and symbolic | |
205 | constants are all declared in the header file @file{termios.h}. | |
e52236e5 UD |
206 | |
207 | Don't confuse terminal attributes with file attributes. A device special | |
208 | file which is associated with a terminal has file attributes as described | |
209 | in @ref{File Attributes}. These are unrelated to the attributes of the | |
210 | terminal device itself, which are discussed in this section. | |
28f540f4 RM |
211 | |
212 | @menu | |
213 | * Mode Data Types:: The data type @code{struct termios} and | |
6d52618b | 214 | related types. |
28f540f4 | 215 | * Mode Functions:: Functions to read and set the terminal |
6d52618b | 216 | attributes. |
28f540f4 RM |
217 | * Setting Modes:: The right way to set terminal attributes |
218 | reliably. | |
219 | * Input Modes:: Flags controlling low-level input handling. | |
220 | * Output Modes:: Flags controlling low-level output handling. | |
221 | * Control Modes:: Flags controlling serial port behavior. | |
222 | * Local Modes:: Flags controlling high-level input handling. | |
223 | * Line Speed:: How to read and set the terminal line speed. | |
224 | * Special Characters:: Characters that have special effects, | |
225 | and how to change them. | |
226 | * Noncanonical Input:: Controlling how long to wait for input. | |
227 | @end menu | |
228 | ||
229 | @node Mode Data Types | |
230 | @subsection Terminal Mode Data Types | |
231 | @cindex terminal mode data types | |
232 | ||
233 | The entire collection of attributes of a terminal is stored in a | |
234 | structure of type @code{struct termios}. This structure is used | |
235 | with the functions @code{tcgetattr} and @code{tcsetattr} to read | |
236 | and set the attributes. | |
237 | ||
28f540f4 | 238 | @deftp {Data Type} {struct termios} |
d08a7e4c | 239 | @standards{POSIX.1, termios.h} |
dc40b233 | 240 | A @code{struct termios} records all the I/O attributes of a terminal. The |
28f540f4 RM |
241 | structure includes at least the following members: |
242 | ||
243 | @table @code | |
244 | @item tcflag_t c_iflag | |
245 | A bit mask specifying flags for input modes; see @ref{Input Modes}. | |
246 | ||
247 | @item tcflag_t c_oflag | |
248 | A bit mask specifying flags for output modes; see @ref{Output Modes}. | |
249 | ||
250 | @item tcflag_t c_cflag | |
251 | A bit mask specifying flags for control modes; see @ref{Control Modes}. | |
252 | ||
253 | @item tcflag_t c_lflag | |
254 | A bit mask specifying flags for local modes; see @ref{Local Modes}. | |
255 | ||
256 | @item cc_t c_cc[NCCS] | |
257 | An array specifying which characters are associated with various | |
258 | control functions; see @ref{Special Characters}. | |
259 | @end table | |
260 | ||
261 | The @code{struct termios} structure also contains members which | |
262 | encode input and output transmission speeds, but the representation is | |
263 | not specified. @xref{Line Speed}, for how to examine and store the | |
264 | speed values. | |
265 | @end deftp | |
266 | ||
267 | The following sections describe the details of the members of the | |
268 | @code{struct termios} structure. | |
269 | ||
28f540f4 | 270 | @deftp {Data Type} tcflag_t |
d08a7e4c | 271 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
272 | This is an unsigned integer type used to represent the various |
273 | bit masks for terminal flags. | |
274 | @end deftp | |
275 | ||
28f540f4 | 276 | @deftp {Data Type} cc_t |
d08a7e4c | 277 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
278 | This is an unsigned integer type used to represent characters associated |
279 | with various terminal control functions. | |
280 | @end deftp | |
281 | ||
28f540f4 | 282 | @deftypevr Macro int NCCS |
d08a7e4c | 283 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
284 | The value of this macro is the number of elements in the @code{c_cc} |
285 | array. | |
286 | @end deftypevr | |
287 | ||
288 | @node Mode Functions | |
289 | @subsection Terminal Mode Functions | |
290 | @cindex terminal mode functions | |
291 | ||
28f540f4 | 292 | @deftypefun int tcgetattr (int @var{filedes}, struct termios *@var{termios-p}) |
d08a7e4c | 293 | @standards{POSIX.1, termios.h} |
f8d529d5 AO |
294 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
295 | @c Converting the kernel-returned termios data structure to the userland | |
296 | @c format does not ensure atomic or consistent writing. | |
28f540f4 RM |
297 | This function is used to examine the attributes of the terminal |
298 | device with file descriptor @var{filedes}. The attributes are returned | |
299 | in the structure that @var{termios-p} points to. | |
300 | ||
a53bad16 | 301 | If successful, @code{tcgetattr} returns @math{0}. A return value of @math{-1} |
28f540f4 RM |
302 | indicates an error. The following @code{errno} error conditions are |
303 | defined for this function: | |
304 | ||
305 | @table @code | |
306 | @item EBADF | |
307 | The @var{filedes} argument is not a valid file descriptor. | |
308 | ||
309 | @item ENOTTY | |
310 | The @var{filedes} is not associated with a terminal. | |
311 | @end table | |
312 | @end deftypefun | |
313 | ||
28f540f4 | 314 | @deftypefun int tcsetattr (int @var{filedes}, int @var{when}, const struct termios *@var{termios-p}) |
d08a7e4c | 315 | @standards{POSIX.1, termios.h} |
f8d529d5 AO |
316 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
317 | @c Converting the incoming termios data structure to the kernel format | |
318 | @c does not ensure atomic or consistent reading. | |
28f540f4 RM |
319 | This function sets the attributes of the terminal device with file |
320 | descriptor @var{filedes}. The new attributes are taken from the | |
321 | structure that @var{termios-p} points to. | |
322 | ||
323 | The @var{when} argument specifies how to deal with input and output | |
324 | already queued. It can be one of the following values: | |
325 | ||
2fe82ca6 | 326 | @vtable @code |
28f540f4 | 327 | @item TCSANOW |
d08a7e4c | 328 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
329 | Make the change immediately. |
330 | ||
28f540f4 | 331 | @item TCSADRAIN |
d08a7e4c | 332 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
333 | Make the change after waiting until all queued output has been written. |
334 | You should usually use this option when changing parameters that affect | |
335 | output. | |
336 | ||
28f540f4 | 337 | @item TCSAFLUSH |
d08a7e4c | 338 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
339 | This is like @code{TCSADRAIN}, but also discards any queued input. |
340 | ||
28f540f4 | 341 | @item TCSASOFT |
d08a7e4c | 342 | @standards{BSD, termios.h} |
28f540f4 RM |
343 | This is a flag bit that you can add to any of the above alternatives. |
344 | Its meaning is to inhibit alteration of the state of the terminal | |
345 | hardware. It is a BSD extension; it is only supported on BSD systems | |
a7a93d50 | 346 | and @gnuhurdsystems{}. |
28f540f4 RM |
347 | |
348 | Using @code{TCSASOFT} is exactly the same as setting the @code{CIGNORE} | |
349 | bit in the @code{c_cflag} member of the structure @var{termios-p} points | |
350 | to. @xref{Control Modes}, for a description of @code{CIGNORE}. | |
2fe82ca6 | 351 | @end vtable |
28f540f4 RM |
352 | |
353 | If this function is called from a background process on its controlling | |
354 | terminal, normally all processes in the process group are sent a | |
355 | @code{SIGTTOU} signal, in the same way as if the process were trying to | |
356 | write to the terminal. The exception is if the calling process itself | |
357 | is ignoring or blocking @code{SIGTTOU} signals, in which case the | |
358 | operation is performed and no signal is sent. @xref{Job Control}. | |
359 | ||
a53bad16 UD |
360 | If successful, @code{tcsetattr} returns @math{0}. A return value of |
361 | @math{-1} indicates an error. The following @code{errno} error | |
28f540f4 RM |
362 | conditions are defined for this function: |
363 | ||
364 | @table @code | |
365 | @item EBADF | |
366 | The @var{filedes} argument is not a valid file descriptor. | |
367 | ||
368 | @item ENOTTY | |
369 | The @var{filedes} is not associated with a terminal. | |
370 | ||
371 | @item EINVAL | |
372 | Either the value of the @code{when} argument is not valid, or there is | |
373 | something wrong with the data in the @var{termios-p} argument. | |
374 | @end table | |
375 | @end deftypefun | |
376 | ||
377 | Although @code{tcgetattr} and @code{tcsetattr} specify the terminal | |
378 | device with a file descriptor, the attributes are those of the terminal | |
379 | device itself and not of the file descriptor. This means that the | |
380 | effects of changing terminal attributes are persistent; if another | |
381 | process opens the terminal file later on, it will see the changed | |
382 | attributes even though it doesn't have anything to do with the open file | |
383 | descriptor you originally specified in changing the attributes. | |
384 | ||
385 | Similarly, if a single process has multiple or duplicated file | |
386 | descriptors for the same terminal device, changing the terminal | |
387 | attributes affects input and output to all of these file | |
388 | descriptors. This means, for example, that you can't open one file | |
389 | descriptor or stream to read from a terminal in the normal | |
390 | line-buffered, echoed mode; and simultaneously have another file | |
391 | descriptor for the same terminal that you use to read from it in | |
392 | single-character, non-echoed mode. Instead, you have to explicitly | |
393 | switch the terminal back and forth between the two modes. | |
394 | ||
395 | @node Setting Modes | |
396 | @subsection Setting Terminal Modes Properly | |
397 | ||
398 | When you set terminal modes, you should call @code{tcgetattr} first to | |
399 | get the current modes of the particular terminal device, modify only | |
400 | those modes that you are really interested in, and store the result with | |
401 | @code{tcsetattr}. | |
402 | ||
403 | It's a bad idea to simply initialize a @code{struct termios} structure | |
404 | to a chosen set of attributes and pass it directly to @code{tcsetattr}. | |
405 | Your program may be run years from now, on systems that support members | |
406 | not documented in this manual. The way to avoid setting these members | |
407 | to unreasonable values is to avoid changing them. | |
408 | ||
409 | What's more, different terminal devices may require different mode | |
410 | settings in order to function properly. So you should avoid blindly | |
411 | copying attributes from one terminal device to another. | |
412 | ||
413 | When a member contains a collection of independent flags, as the | |
414 | @code{c_iflag}, @code{c_oflag} and @code{c_cflag} members do, even | |
415 | setting the entire member is a bad idea, because particular operating | |
416 | systems have their own flags. Instead, you should start with the | |
417 | current value of the member and alter only the flags whose values matter | |
418 | in your program, leaving any other flags unchanged. | |
419 | ||
420 | Here is an example of how to set one flag (@code{ISTRIP}) in the | |
421 | @code{struct termios} structure while properly preserving all the other | |
422 | data in the structure: | |
423 | ||
424 | @smallexample | |
425 | @group | |
426 | int | |
427 | set_istrip (int desc, int value) | |
428 | @{ | |
429 | struct termios settings; | |
430 | int result; | |
431 | @end group | |
432 | ||
433 | @group | |
434 | result = tcgetattr (desc, &settings); | |
435 | if (result < 0) | |
436 | @{ | |
437 | perror ("error in tcgetattr"); | |
438 | return 0; | |
439 | @} | |
440 | @end group | |
441 | @group | |
442 | settings.c_iflag &= ~ISTRIP; | |
443 | if (value) | |
444 | settings.c_iflag |= ISTRIP; | |
445 | @end group | |
446 | @group | |
447 | result = tcsetattr (desc, TCSANOW, &settings); | |
448 | if (result < 0) | |
449 | @{ | |
85adacbd UD |
450 | perror ("error in tcsetattr"); |
451 | return 0; | |
28f540f4 RM |
452 | @} |
453 | return 1; | |
454 | @} | |
455 | @end group | |
456 | @end smallexample | |
457 | ||
458 | @node Input Modes | |
459 | @subsection Input Modes | |
460 | ||
461 | This section describes the terminal attribute flags that control | |
462 | fairly low-level aspects of input processing: handling of parity errors, | |
463 | break signals, flow control, and @key{RET} and @key{LFD} characters. | |
464 | ||
465 | All of these flags are bits in the @code{c_iflag} member of the | |
466 | @code{struct termios} structure. The member is an integer, and you | |
467 | change flags using the operators @code{&}, @code{|} and @code{^}. Don't | |
468 | try to specify the entire value for @code{c_iflag}---instead, change | |
469 | only specific flags and leave the rest untouched (@pxref{Setting | |
470 | Modes}). | |
471 | ||
28f540f4 | 472 | @deftypevr Macro tcflag_t INPCK |
d08a7e4c | 473 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
474 | @cindex parity checking |
475 | If this bit is set, input parity checking is enabled. If it is not set, | |
476 | no checking at all is done for parity errors on input; the | |
477 | characters are simply passed through to the application. | |
478 | ||
479 | Parity checking on input processing is independent of whether parity | |
480 | detection and generation on the underlying terminal hardware is enabled; | |
481 | see @ref{Control Modes}. For example, you could clear the @code{INPCK} | |
482 | input mode flag and set the @code{PARENB} control mode flag to ignore | |
483 | parity errors on input, but still generate parity on output. | |
484 | ||
485 | If this bit is set, what happens when a parity error is detected depends | |
486 | on whether the @code{IGNPAR} or @code{PARMRK} bits are set. If neither | |
487 | of these bits are set, a byte with a parity error is passed to the | |
488 | application as a @code{'\0'} character. | |
489 | @end deftypevr | |
490 | ||
28f540f4 | 491 | @deftypevr Macro tcflag_t IGNPAR |
d08a7e4c | 492 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
493 | If this bit is set, any byte with a framing or parity error is ignored. |
494 | This is only useful if @code{INPCK} is also set. | |
495 | @end deftypevr | |
496 | ||
28f540f4 | 497 | @deftypevr Macro tcflag_t PARMRK |
d08a7e4c | 498 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
499 | If this bit is set, input bytes with parity or framing errors are marked |
500 | when passed to the program. This bit is meaningful only when | |
501 | @code{INPCK} is set and @code{IGNPAR} is not set. | |
502 | ||
503 | The way erroneous bytes are marked is with two preceding bytes, | |
504 | @code{377} and @code{0}. Thus, the program actually reads three bytes | |
505 | for one erroneous byte received from the terminal. | |
506 | ||
507 | If a valid byte has the value @code{0377}, and @code{ISTRIP} (see below) | |
508 | is not set, the program might confuse it with the prefix that marks a | |
509 | parity error. So a valid byte @code{0377} is passed to the program as | |
510 | two bytes, @code{0377} @code{0377}, in this case. | |
511 | @end deftypevr | |
512 | ||
28f540f4 | 513 | @deftypevr Macro tcflag_t ISTRIP |
d08a7e4c | 514 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
515 | If this bit is set, valid input bytes are stripped to seven bits; |
516 | otherwise, all eight bits are available for programs to read. | |
517 | @end deftypevr | |
518 | ||
28f540f4 | 519 | @deftypevr Macro tcflag_t IGNBRK |
d08a7e4c | 520 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
521 | If this bit is set, break conditions are ignored. |
522 | ||
523 | @cindex break condition, detecting | |
524 | A @dfn{break condition} is defined in the context of asynchronous | |
525 | serial data transmission as a series of zero-value bits longer than a | |
526 | single byte. | |
527 | @end deftypevr | |
528 | ||
28f540f4 | 529 | @deftypevr Macro tcflag_t BRKINT |
d08a7e4c | 530 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
531 | If this bit is set and @code{IGNBRK} is not set, a break condition |
532 | clears the terminal input and output queues and raises a @code{SIGINT} | |
533 | signal for the foreground process group associated with the terminal. | |
534 | ||
535 | If neither @code{BRKINT} nor @code{IGNBRK} are set, a break condition is | |
536 | passed to the application as a single @code{'\0'} character if | |
6d52618b | 537 | @code{PARMRK} is not set, or otherwise as a three-character sequence |
28f540f4 RM |
538 | @code{'\377'}, @code{'\0'}, @code{'\0'}. |
539 | @end deftypevr | |
540 | ||
28f540f4 | 541 | @deftypevr Macro tcflag_t IGNCR |
d08a7e4c | 542 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
543 | If this bit is set, carriage return characters (@code{'\r'}) are |
544 | discarded on input. Discarding carriage return may be useful on | |
545 | terminals that send both carriage return and linefeed when you type the | |
546 | @key{RET} key. | |
547 | @end deftypevr | |
548 | ||
28f540f4 | 549 | @deftypevr Macro tcflag_t ICRNL |
d08a7e4c | 550 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
551 | If this bit is set and @code{IGNCR} is not set, carriage return characters |
552 | (@code{'\r'}) received as input are passed to the application as newline | |
553 | characters (@code{'\n'}). | |
554 | @end deftypevr | |
555 | ||
28f540f4 | 556 | @deftypevr Macro tcflag_t INLCR |
d08a7e4c | 557 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
558 | If this bit is set, newline characters (@code{'\n'}) received as input |
559 | are passed to the application as carriage return characters (@code{'\r'}). | |
560 | @end deftypevr | |
561 | ||
28f540f4 | 562 | @deftypevr Macro tcflag_t IXOFF |
d08a7e4c | 563 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
564 | If this bit is set, start/stop control on input is enabled. In other |
565 | words, the computer sends STOP and START characters as necessary to | |
566 | prevent input from coming in faster than programs are reading it. The | |
567 | idea is that the actual terminal hardware that is generating the input | |
568 | data responds to a STOP character by suspending transmission, and to a | |
569 | START character by resuming transmission. @xref{Start/Stop Characters}. | |
570 | @end deftypevr | |
571 | ||
28f540f4 | 572 | @deftypevr Macro tcflag_t IXON |
d08a7e4c | 573 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
574 | If this bit is set, start/stop control on output is enabled. In other |
575 | words, if the computer receives a STOP character, it suspends output | |
576 | until a START character is received. In this case, the STOP and START | |
577 | characters are never passed to the application program. If this bit is | |
578 | not set, then START and STOP can be read as ordinary characters. | |
579 | @xref{Start/Stop Characters}. | |
580 | @c !!! mention this interferes with using C-s and C-q for programs like emacs | |
581 | @end deftypevr | |
582 | ||
28f540f4 | 583 | @deftypevr Macro tcflag_t IXANY |
d08a7e4c | 584 | @standards{BSD, termios.h} |
28f540f4 RM |
585 | If this bit is set, any input character restarts output when output has |
586 | been suspended with the STOP character. Otherwise, only the START | |
587 | character restarts output. | |
588 | ||
a7a93d50 JM |
589 | This is a BSD extension; it exists only on BSD systems and |
590 | @gnulinuxhurdsystems{}. | |
28f540f4 RM |
591 | @end deftypevr |
592 | ||
28f540f4 | 593 | @deftypevr Macro tcflag_t IMAXBEL |
d08a7e4c | 594 | @standards{BSD, termios.h} |
28f540f4 RM |
595 | If this bit is set, then filling up the terminal input buffer sends a |
596 | BEL character (code @code{007}) to the terminal to ring the bell. | |
597 | ||
598 | This is a BSD extension. | |
599 | @end deftypevr | |
600 | ||
601 | @node Output Modes | |
602 | @subsection Output Modes | |
603 | ||
604 | This section describes the terminal flags and fields that control how | |
605 | output characters are translated and padded for display. All of these | |
606 | are contained in the @code{c_oflag} member of the @w{@code{struct termios}} | |
607 | structure. | |
608 | ||
609 | The @code{c_oflag} member itself is an integer, and you change the flags | |
610 | and fields using the operators @code{&}, @code{|}, and @code{^}. Don't | |
611 | try to specify the entire value for @code{c_oflag}---instead, change | |
612 | only specific flags and leave the rest untouched (@pxref{Setting | |
613 | Modes}). | |
614 | ||
28f540f4 | 615 | @deftypevr Macro tcflag_t OPOST |
d08a7e4c | 616 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
617 | If this bit is set, output data is processed in some unspecified way so |
618 | that it is displayed appropriately on the terminal device. This | |
619 | typically includes mapping newline characters (@code{'\n'}) onto | |
620 | carriage return and linefeed pairs. | |
621 | ||
622 | If this bit isn't set, the characters are transmitted as-is. | |
623 | @end deftypevr | |
624 | ||
a7a93d50 | 625 | The following three bits are effective only if @code{OPOST} is set. |
28f540f4 | 626 | |
28f540f4 | 627 | @deftypevr Macro tcflag_t ONLCR |
d08a7e4c | 628 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
629 | If this bit is set, convert the newline character on output into a pair |
630 | of characters, carriage return followed by linefeed. | |
631 | @end deftypevr | |
632 | ||
28f540f4 | 633 | @deftypevr Macro tcflag_t OXTABS |
d08a7e4c | 634 | @standards{BSD, termios.h (optional)} |
28f540f4 | 635 | If this bit is set, convert tab characters on output into the appropriate |
a7a93d50 JM |
636 | number of spaces to emulate a tab stop every eight columns. This bit |
637 | exists only on BSD systems and @gnuhurdsystems{}; on | |
638 | @gnulinuxsystems{} it is available as @code{XTABS}. | |
28f540f4 RM |
639 | @end deftypevr |
640 | ||
28f540f4 | 641 | @deftypevr Macro tcflag_t ONOEOT |
d08a7e4c | 642 | @standards{BSD, termios.h (optional)} |
28f540f4 RM |
643 | If this bit is set, discard @kbd{C-d} characters (code @code{004}) on |
644 | output. These characters cause many dial-up terminals to disconnect. | |
a7a93d50 | 645 | This bit exists only on BSD systems and @gnuhurdsystems{}. |
28f540f4 RM |
646 | @end deftypevr |
647 | ||
648 | @node Control Modes | |
649 | @subsection Control Modes | |
650 | ||
651 | This section describes the terminal flags and fields that control | |
652 | parameters usually associated with asynchronous serial data | |
653 | transmission. These flags may not make sense for other kinds of | |
654 | terminal ports (such as a network connection pseudo-terminal). All of | |
655 | these are contained in the @code{c_cflag} member of the @code{struct | |
656 | termios} structure. | |
657 | ||
658 | The @code{c_cflag} member itself is an integer, and you change the flags | |
659 | and fields using the operators @code{&}, @code{|}, and @code{^}. Don't | |
660 | try to specify the entire value for @code{c_cflag}---instead, change | |
661 | only specific flags and leave the rest untouched (@pxref{Setting | |
662 | Modes}). | |
663 | ||
28f540f4 | 664 | @deftypevr Macro tcflag_t CLOCAL |
d08a7e4c | 665 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
666 | If this bit is set, it indicates that the terminal is connected |
667 | ``locally'' and that the modem status lines (such as carrier detect) | |
668 | should be ignored. | |
669 | @cindex modem status lines | |
670 | @cindex carrier detect | |
671 | ||
672 | On many systems if this bit is not set and you call @code{open} without | |
673 | the @code{O_NONBLOCK} flag set, @code{open} blocks until a modem | |
674 | connection is established. | |
675 | ||
676 | If this bit is not set and a modem disconnect is detected, a | |
677 | @code{SIGHUP} signal is sent to the controlling process group for the | |
678 | terminal (if it has one). Normally, this causes the process to exit; | |
679 | see @ref{Signal Handling}. Reading from the terminal after a disconnect | |
680 | causes an end-of-file condition, and writing causes an @code{EIO} error | |
681 | to be returned. The terminal device must be closed and reopened to | |
682 | clear the condition. | |
683 | @cindex modem disconnect | |
684 | @end deftypevr | |
685 | ||
28f540f4 | 686 | @deftypevr Macro tcflag_t HUPCL |
d08a7e4c | 687 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
688 | If this bit is set, a modem disconnect is generated when all processes |
689 | that have the terminal device open have either closed the file or exited. | |
690 | @end deftypevr | |
691 | ||
28f540f4 | 692 | @deftypevr Macro tcflag_t CREAD |
d08a7e4c | 693 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
694 | If this bit is set, input can be read from the terminal. Otherwise, |
695 | input is discarded when it arrives. | |
696 | @end deftypevr | |
697 | ||
28f540f4 | 698 | @deftypevr Macro tcflag_t CSTOPB |
d08a7e4c | 699 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
700 | If this bit is set, two stop bits are used. Otherwise, only one stop bit |
701 | is used. | |
702 | @end deftypevr | |
703 | ||
28f540f4 | 704 | @deftypevr Macro tcflag_t PARENB |
d08a7e4c | 705 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
706 | If this bit is set, generation and detection of a parity bit are enabled. |
707 | @xref{Input Modes}, for information on how input parity errors are handled. | |
708 | ||
709 | If this bit is not set, no parity bit is added to output characters, and | |
710 | input characters are not checked for correct parity. | |
711 | @end deftypevr | |
712 | ||
28f540f4 | 713 | @deftypevr Macro tcflag_t PARODD |
d08a7e4c | 714 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
715 | This bit is only useful if @code{PARENB} is set. If @code{PARODD} is set, |
716 | odd parity is used, otherwise even parity is used. | |
717 | @end deftypevr | |
718 | ||
719 | The control mode flags also includes a field for the number of bits per | |
720 | character. You can use the @code{CSIZE} macro as a mask to extract the | |
721 | value, like this: @code{settings.c_cflag & CSIZE}. | |
722 | ||
28f540f4 | 723 | @deftypevr Macro tcflag_t CSIZE |
d08a7e4c | 724 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
725 | This is a mask for the number of bits per character. |
726 | @end deftypevr | |
727 | ||
28f540f4 | 728 | @deftypevr Macro tcflag_t CS5 |
d08a7e4c | 729 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
730 | This specifies five bits per byte. |
731 | @end deftypevr | |
732 | ||
28f540f4 | 733 | @deftypevr Macro tcflag_t CS6 |
d08a7e4c | 734 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
735 | This specifies six bits per byte. |
736 | @end deftypevr | |
737 | ||
28f540f4 | 738 | @deftypevr Macro tcflag_t CS7 |
d08a7e4c | 739 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
740 | This specifies seven bits per byte. |
741 | @end deftypevr | |
742 | ||
28f540f4 | 743 | @deftypevr Macro tcflag_t CS8 |
d08a7e4c | 744 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
745 | This specifies eight bits per byte. |
746 | @end deftypevr | |
747 | ||
a7a93d50 JM |
748 | The following four bits are BSD extensions; these exist only on BSD |
749 | systems and @gnuhurdsystems{}. | |
28f540f4 | 750 | |
28f540f4 | 751 | @deftypevr Macro tcflag_t CCTS_OFLOW |
d08a7e4c | 752 | @standards{BSD, termios.h} |
28f540f4 RM |
753 | If this bit is set, enable flow control of output based on the CTS wire |
754 | (RS232 protocol). | |
755 | @end deftypevr | |
756 | ||
28f540f4 | 757 | @deftypevr Macro tcflag_t CRTS_IFLOW |
d08a7e4c | 758 | @standards{BSD, termios.h} |
28f540f4 RM |
759 | If this bit is set, enable flow control of input based on the RTS wire |
760 | (RS232 protocol). | |
761 | @end deftypevr | |
762 | ||
28f540f4 | 763 | @deftypevr Macro tcflag_t MDMBUF |
d08a7e4c | 764 | @standards{BSD, termios.h} |
28f540f4 RM |
765 | If this bit is set, enable carrier-based flow control of output. |
766 | @end deftypevr | |
767 | ||
28f540f4 | 768 | @deftypevr Macro tcflag_t CIGNORE |
d08a7e4c | 769 | @standards{BSD, termios.h} |
28f540f4 RM |
770 | If this bit is set, it says to ignore the control modes and line speed |
771 | values entirely. This is only meaningful in a call to @code{tcsetattr}. | |
772 | ||
773 | The @code{c_cflag} member and the line speed values returned by | |
774 | @code{cfgetispeed} and @code{cfgetospeed} will be unaffected by the | |
775 | call. @code{CIGNORE} is useful if you want to set all the software | |
776 | modes in the other members, but leave the hardware details in | |
777 | @code{c_cflag} unchanged. (This is how the @code{TCSASOFT} flag to | |
778 | @code{tcsettattr} works.) | |
779 | ||
780 | This bit is never set in the structure filled in by @code{tcgetattr}. | |
781 | @end deftypevr | |
782 | ||
783 | @node Local Modes | |
784 | @subsection Local Modes | |
785 | ||
786 | This section describes the flags for the @code{c_lflag} member of the | |
787 | @code{struct termios} structure. These flags generally control | |
788 | higher-level aspects of input processing than the input modes flags | |
789 | described in @ref{Input Modes}, such as echoing, signals, and the choice | |
790 | of canonical or noncanonical input. | |
791 | ||
792 | The @code{c_lflag} member itself is an integer, and you change the flags | |
793 | and fields using the operators @code{&}, @code{|}, and @code{^}. Don't | |
794 | try to specify the entire value for @code{c_lflag}---instead, change | |
795 | only specific flags and leave the rest untouched (@pxref{Setting | |
796 | Modes}). | |
797 | ||
28f540f4 | 798 | @deftypevr Macro tcflag_t ICANON |
d08a7e4c | 799 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
800 | This bit, if set, enables canonical input processing mode. Otherwise, |
801 | input is processed in noncanonical mode. @xref{Canonical or Not}. | |
802 | @end deftypevr | |
803 | ||
28f540f4 | 804 | @deftypevr Macro tcflag_t ECHO |
d08a7e4c | 805 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
806 | If this bit is set, echoing of input characters back to the terminal |
807 | is enabled. | |
808 | @cindex echo of terminal input | |
809 | @end deftypevr | |
810 | ||
28f540f4 | 811 | @deftypevr Macro tcflag_t ECHOE |
d08a7e4c | 812 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
813 | If this bit is set, echoing indicates erasure of input with the ERASE |
814 | character by erasing the last character in the current line from the | |
815 | screen. Otherwise, the character erased is re-echoed to show what has | |
816 | happened (suitable for a printing terminal). | |
817 | ||
818 | This bit only controls the display behavior; the @code{ICANON} bit by | |
819 | itself controls actual recognition of the ERASE character and erasure of | |
820 | input, without which @code{ECHOE} is simply irrelevant. | |
821 | @end deftypevr | |
822 | ||
28f540f4 | 823 | @deftypevr Macro tcflag_t ECHOPRT |
d08a7e4c | 824 | @standards{BSD, termios.h} |
dc40b233 | 825 | This bit, like @code{ECHOE}, enables display of the ERASE character in |
28f540f4 RM |
826 | a way that is geared to a hardcopy terminal. When you type the ERASE |
827 | character, a @samp{\} character is printed followed by the first | |
828 | character erased. Typing the ERASE character again just prints the next | |
829 | character erased. Then, the next time you type a normal character, a | |
830 | @samp{/} character is printed before the character echoes. | |
831 | ||
a7a93d50 JM |
832 | This is a BSD extension, and exists only in BSD systems and |
833 | @gnulinuxhurdsystems{}. | |
28f540f4 RM |
834 | @end deftypevr |
835 | ||
28f540f4 | 836 | @deftypevr Macro tcflag_t ECHOK |
d08a7e4c | 837 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
838 | This bit enables special display of the KILL character by moving to a |
839 | new line after echoing the KILL character normally. The behavior of | |
840 | @code{ECHOKE} (below) is nicer to look at. | |
841 | ||
842 | If this bit is not set, the KILL character echoes just as it would if it | |
843 | were not the KILL character. Then it is up to the user to remember that | |
844 | the KILL character has erased the preceding input; there is no | |
845 | indication of this on the screen. | |
846 | ||
847 | This bit only controls the display behavior; the @code{ICANON} bit by | |
848 | itself controls actual recognition of the KILL character and erasure of | |
849 | input, without which @code{ECHOK} is simply irrelevant. | |
850 | @end deftypevr | |
851 | ||
28f540f4 | 852 | @deftypevr Macro tcflag_t ECHOKE |
d08a7e4c | 853 | @standards{BSD, termios.h} |
28f540f4 RM |
854 | This bit is similar to @code{ECHOK}. It enables special display of the |
855 | KILL character by erasing on the screen the entire line that has been | |
a7a93d50 JM |
856 | killed. This is a BSD extension, and exists only in BSD systems and |
857 | @gnulinuxhurdsystems{}. | |
28f540f4 RM |
858 | @end deftypevr |
859 | ||
28f540f4 | 860 | @deftypevr Macro tcflag_t ECHONL |
d08a7e4c | 861 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
862 | If this bit is set and the @code{ICANON} bit is also set, then the |
863 | newline (@code{'\n'}) character is echoed even if the @code{ECHO} bit | |
864 | is not set. | |
865 | @end deftypevr | |
866 | ||
28f540f4 | 867 | @deftypevr Macro tcflag_t ECHOCTL |
d08a7e4c | 868 | @standards{BSD, termios.h} |
28f540f4 RM |
869 | If this bit is set and the @code{ECHO} bit is also set, echo control |
870 | characters with @samp{^} followed by the corresponding text character. | |
871 | Thus, control-A echoes as @samp{^A}. This is usually the preferred mode | |
872 | for interactive input, because echoing a control character back to the | |
873 | terminal could have some undesired effect on the terminal. | |
874 | ||
a7a93d50 JM |
875 | This is a BSD extension, and exists only in BSD systems and |
876 | @gnulinuxhurdsystems{}. | |
28f540f4 RM |
877 | @end deftypevr |
878 | ||
28f540f4 | 879 | @deftypevr Macro tcflag_t ISIG |
d08a7e4c | 880 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
881 | This bit controls whether the INTR, QUIT, and SUSP characters are |
882 | recognized. The functions associated with these characters are performed | |
883 | if and only if this bit is set. Being in canonical or noncanonical | |
dc40b233 | 884 | input mode has no effect on the interpretation of these characters. |
28f540f4 RM |
885 | |
886 | You should use caution when disabling recognition of these characters. | |
887 | Programs that cannot be interrupted interactively are very | |
888 | user-unfriendly. If you clear this bit, your program should provide | |
889 | some alternate interface that allows the user to interactively send the | |
890 | signals associated with these characters, or to escape from the program. | |
891 | @cindex interactive signals, from terminal | |
892 | ||
893 | @xref{Signal Characters}. | |
894 | @end deftypevr | |
895 | ||
28f540f4 | 896 | @deftypevr Macro tcflag_t IEXTEN |
d08a7e4c | 897 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
898 | POSIX.1 gives @code{IEXTEN} implementation-defined meaning, |
899 | so you cannot rely on this interpretation on all systems. | |
900 | ||
a7a93d50 JM |
901 | On BSD systems and @gnulinuxhurdsystems{}, it enables the LNEXT and |
902 | DISCARD characters. | |
28f540f4 RM |
903 | @xref{Other Special}. |
904 | @end deftypevr | |
905 | ||
28f540f4 | 906 | @deftypevr Macro tcflag_t NOFLSH |
d08a7e4c | 907 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
908 | Normally, the INTR, QUIT, and SUSP characters cause input and output |
909 | queues for the terminal to be cleared. If this bit is set, the queues | |
910 | are not cleared. | |
911 | @end deftypevr | |
912 | ||
28f540f4 | 913 | @deftypevr Macro tcflag_t TOSTOP |
d08a7e4c | 914 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
915 | If this bit is set and the system supports job control, then |
916 | @code{SIGTTOU} signals are generated by background processes that | |
917 | attempt to write to the terminal. @xref{Access to the Terminal}. | |
918 | @end deftypevr | |
919 | ||
a7a93d50 JM |
920 | The following bits are BSD extensions; they exist only on BSD systems |
921 | and @gnuhurdsystems{}. | |
6d52618b | 922 | |
28f540f4 | 923 | @deftypevr Macro tcflag_t ALTWERASE |
d08a7e4c | 924 | @standards{BSD, termios.h} |
28f540f4 RM |
925 | This bit determines how far the WERASE character should erase. The |
926 | WERASE character erases back to the beginning of a word; the question | |
927 | is, where do words begin? | |
928 | ||
929 | If this bit is clear, then the beginning of a word is a nonwhitespace | |
930 | character following a whitespace character. If the bit is set, then the | |
931 | beginning of a word is an alphanumeric character or underscore following | |
932 | a character which is none of those. | |
933 | ||
934 | @xref{Editing Characters}, for more information about the WERASE character. | |
935 | @end deftypevr | |
936 | ||
28f540f4 | 937 | @deftypevr Macro tcflag_t FLUSHO |
d08a7e4c | 938 | @standards{BSD, termios.h} |
28f540f4 RM |
939 | This is the bit that toggles when the user types the DISCARD character. |
940 | While this bit is set, all output is discarded. @xref{Other Special}. | |
941 | @end deftypevr | |
942 | ||
28f540f4 | 943 | @deftypevr Macro tcflag_t NOKERNINFO |
d08a7e4c | 944 | @standards{BSD, termios.h (optional)} |
28f540f4 RM |
945 | Setting this bit disables handling of the STATUS character. |
946 | @xref{Other Special}. | |
947 | @end deftypevr | |
948 | ||
28f540f4 | 949 | @deftypevr Macro tcflag_t PENDIN |
d08a7e4c | 950 | @standards{BSD, termios.h} |
28f540f4 RM |
951 | If this bit is set, it indicates that there is a line of input that |
952 | needs to be reprinted. Typing the REPRINT character sets this bit; the | |
953 | bit remains set until reprinting is finished. @xref{Editing Characters}. | |
954 | @end deftypevr | |
955 | ||
956 | @c EXTPROC is too obscure to document now. --roland | |
957 | ||
958 | @node Line Speed | |
959 | @subsection Line Speed | |
960 | @cindex line speed | |
961 | @cindex baud rate | |
962 | @cindex terminal line speed | |
963 | @cindex terminal line speed | |
964 | ||
965 | The terminal line speed tells the computer how fast to read and write | |
966 | data on the terminal. | |
967 | ||
968 | If the terminal is connected to a real serial line, the terminal speed | |
969 | you specify actually controls the line---if it doesn't match the | |
970 | terminal's own idea of the speed, communication does not work. Real | |
971 | serial ports accept only certain standard speeds. Also, particular | |
972 | hardware may not support even all the standard speeds. Specifying a | |
973 | speed of zero hangs up a dialup connection and turns off modem control | |
974 | signals. | |
975 | ||
976 | If the terminal is not a real serial line (for example, if it is a | |
977 | network connection), then the line speed won't really affect data | |
978 | transmission speed, but some programs will use it to determine the | |
979 | amount of padding needed. It's best to specify a line speed value that | |
980 | matches the actual speed of the actual terminal, but you can safely | |
981 | experiment with different values to vary the amount of padding. | |
982 | ||
983 | There are actually two line speeds for each terminal, one for input and | |
984 | one for output. You can set them independently, but most often | |
985 | terminals use the same speed for both directions. | |
986 | ||
987 | The speed values are stored in the @code{struct termios} structure, but | |
988 | don't try to access them in the @code{struct termios} structure | |
989 | directly. Instead, you should use the following functions to read and | |
990 | store them: | |
991 | ||
28f540f4 | 992 | @deftypefun speed_t cfgetospeed (const struct termios *@var{termios-p}) |
d08a7e4c | 993 | @standards{POSIX.1, termios.h} |
f8d529d5 AO |
994 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
995 | @c Direct access to a single termios field, except on Linux, where | |
996 | @c multiple accesses may take place. No worries either way, callers | |
997 | @c must ensure mutual exclusion on such non-opaque types. | |
28f540f4 RM |
998 | This function returns the output line speed stored in the structure |
999 | @code{*@var{termios-p}}. | |
1000 | @end deftypefun | |
1001 | ||
28f540f4 | 1002 | @deftypefun speed_t cfgetispeed (const struct termios *@var{termios-p}) |
d08a7e4c | 1003 | @standards{POSIX.1, termios.h} |
f8d529d5 | 1004 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 RM |
1005 | This function returns the input line speed stored in the structure |
1006 | @code{*@var{termios-p}}. | |
1007 | @end deftypefun | |
1008 | ||
28f540f4 | 1009 | @deftypefun int cfsetospeed (struct termios *@var{termios-p}, speed_t @var{speed}) |
d08a7e4c | 1010 | @standards{POSIX.1, termios.h} |
f8d529d5 | 1011 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 | 1012 | This function stores @var{speed} in @code{*@var{termios-p}} as the output |
a53bad16 | 1013 | speed. The normal return value is @math{0}; a value of @math{-1} |
28f540f4 | 1014 | indicates an error. If @var{speed} is not a speed, @code{cfsetospeed} |
a53bad16 | 1015 | returns @math{-1}. |
28f540f4 RM |
1016 | @end deftypefun |
1017 | ||
28f540f4 | 1018 | @deftypefun int cfsetispeed (struct termios *@var{termios-p}, speed_t @var{speed}) |
d08a7e4c | 1019 | @standards{POSIX.1, termios.h} |
f8d529d5 | 1020 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28f540f4 | 1021 | This function stores @var{speed} in @code{*@var{termios-p}} as the input |
a53bad16 | 1022 | speed. The normal return value is @math{0}; a value of @math{-1} |
28f540f4 | 1023 | indicates an error. If @var{speed} is not a speed, @code{cfsetospeed} |
a53bad16 | 1024 | returns @math{-1}. |
28f540f4 RM |
1025 | @end deftypefun |
1026 | ||
28f540f4 | 1027 | @deftypefun int cfsetspeed (struct termios *@var{termios-p}, speed_t @var{speed}) |
d08a7e4c | 1028 | @standards{BSD, termios.h} |
f8d529d5 AO |
1029 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1030 | @c There's no guarantee that the two calls are atomic, but since this is | |
1031 | @c not an opaque type, callers ought to ensure mutual exclusion to the | |
1032 | @c termios object. | |
1033 | ||
1034 | @c cfsetspeed ok | |
1035 | @c cfsetispeed ok | |
1036 | @c cfsetospeed ok | |
28f540f4 | 1037 | This function stores @var{speed} in @code{*@var{termios-p}} as both the |
a53bad16 UD |
1038 | input and output speeds. The normal return value is @math{0}; a value |
1039 | of @math{-1} indicates an error. If @var{speed} is not a speed, | |
1040 | @code{cfsetspeed} returns @math{-1}. This function is an extension in | |
28f540f4 RM |
1041 | 4.4 BSD. |
1042 | @end deftypefun | |
1043 | ||
28f540f4 | 1044 | @deftp {Data Type} speed_t |
d08a7e4c | 1045 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
1046 | The @code{speed_t} type is an unsigned integer data type used to |
1047 | represent line speeds. | |
1048 | @end deftp | |
1049 | ||
1050 | The functions @code{cfsetospeed} and @code{cfsetispeed} report errors | |
1051 | only for speed values that the system simply cannot handle. If you | |
1052 | specify a speed value that is basically acceptable, then those functions | |
1053 | will succeed. But they do not check that a particular hardware device | |
1054 | can actually support the specified speeds---in fact, they don't know | |
1055 | which device you plan to set the speed for. If you use @code{tcsetattr} | |
1056 | to set the speed of a particular device to a value that it cannot | |
a53bad16 | 1057 | handle, @code{tcsetattr} returns @math{-1}. |
28f540f4 | 1058 | |
1f77f049 | 1059 | @strong{Portability note:} In @theglibc{}, the functions above |
28f540f4 RM |
1060 | accept speeds measured in bits per second as input, and return speed |
1061 | values measured in bits per second. Other libraries require speeds to | |
1062 | be indicated by special codes. For POSIX.1 portability, you must use | |
1063 | one of the following symbols to represent the speed; their precise | |
1064 | numeric values are system-dependent, but each name has a fixed meaning: | |
1065 | @code{B110} stands for 110 bps, @code{B300} for 300 bps, and so on. | |
1066 | There is no portable way to represent any speed but these, but these are | |
1067 | the only speeds that typical serial lines can support. | |
1068 | ||
1069 | @comment termios.h | |
1070 | @comment POSIX.1 | |
1071 | @vindex B0 | |
1072 | @comment termios.h | |
1073 | @comment POSIX.1 | |
1074 | @vindex B50 | |
1075 | @comment termios.h | |
1076 | @comment POSIX.1 | |
1077 | @vindex B75 | |
1078 | @comment termios.h | |
1079 | @comment POSIX.1 | |
1080 | @vindex B110 | |
1081 | @comment termios.h | |
1082 | @comment POSIX.1 | |
1083 | @vindex B134 | |
1084 | @comment termios.h | |
1085 | @comment POSIX.1 | |
1086 | @vindex B150 | |
1087 | @comment termios.h | |
1088 | @comment POSIX.1 | |
1089 | @vindex B200 | |
1090 | @comment termios.h | |
1091 | @comment POSIX.1 | |
1092 | @vindex B300 | |
1093 | @comment termios.h | |
1094 | @comment POSIX.1 | |
1095 | @vindex B600 | |
1096 | @comment termios.h | |
1097 | @comment POSIX.1 | |
1098 | @vindex B1200 | |
1099 | @comment termios.h | |
1100 | @comment POSIX.1 | |
1101 | @vindex B1800 | |
1102 | @comment termios.h | |
1103 | @comment POSIX.1 | |
1104 | @vindex B2400 | |
1105 | @comment termios.h | |
1106 | @comment POSIX.1 | |
1107 | @vindex B4800 | |
1108 | @comment termios.h | |
1109 | @comment POSIX.1 | |
1110 | @vindex B9600 | |
1111 | @comment termios.h | |
1112 | @comment POSIX.1 | |
1113 | @vindex B19200 | |
1114 | @comment termios.h | |
1115 | @comment POSIX.1 | |
1116 | @vindex B38400 | |
af6f3906 UD |
1117 | @comment termios.h |
1118 | @comment GNU | |
1119 | @vindex B57600 | |
1120 | @comment termios.h | |
1121 | @comment GNU | |
1122 | @vindex B115200 | |
1123 | @comment termios.h | |
1124 | @comment GNU | |
1125 | @vindex B230400 | |
1126 | @comment termios.h | |
1127 | @comment GNU | |
1128 | @vindex B460800 | |
28f540f4 RM |
1129 | @smallexample |
1130 | B0 B50 B75 B110 B134 B150 B200 | |
1131 | B300 B600 B1200 B1800 B2400 B4800 | |
cc3fa755 UD |
1132 | B9600 B19200 B38400 B57600 B115200 |
1133 | B230400 B460800 | |
28f540f4 RM |
1134 | @end smallexample |
1135 | ||
1136 | @vindex EXTA | |
1137 | @vindex EXTB | |
1138 | BSD defines two additional speed symbols as aliases: @code{EXTA} is an | |
1139 | alias for @code{B19200} and @code{EXTB} is an alias for @code{B38400}. | |
1140 | These aliases are obsolete. | |
1141 | ||
1142 | @node Special Characters | |
1143 | @subsection Special Characters | |
1144 | ||
1145 | In canonical input, the terminal driver recognizes a number of special | |
1146 | characters which perform various control functions. These include the | |
1147 | ERASE character (usually @key{DEL}) for editing input, and other editing | |
1148 | characters. The INTR character (normally @kbd{C-c}) for sending a | |
1149 | @code{SIGINT} signal, and other signal-raising characters, may be | |
1150 | available in either canonical or noncanonical input mode. All these | |
1151 | characters are described in this section. | |
1152 | ||
1153 | The particular characters used are specified in the @code{c_cc} member | |
1154 | of the @code{struct termios} structure. This member is an array; each | |
1155 | element specifies the character for a particular role. Each element has | |
1156 | a symbolic constant that stands for the index of that element---for | |
eb406346 UD |
1157 | example, @code{VINTR} is the index of the element that specifies the INTR |
1158 | character, so storing @code{'='} in @code{@var{termios}.c_cc[VINTR]} | |
28f540f4 RM |
1159 | specifies @samp{=} as the INTR character. |
1160 | ||
1161 | @vindex _POSIX_VDISABLE | |
1162 | On some systems, you can disable a particular special character function | |
1163 | by specifying the value @code{_POSIX_VDISABLE} for that role. This | |
1164 | value is unequal to any possible character code. @xref{Options for | |
1165 | Files}, for more information about how to tell whether the operating | |
1166 | system you are using supports @code{_POSIX_VDISABLE}. | |
1167 | ||
1168 | @menu | |
1169 | * Editing Characters:: Special characters that terminate lines and | |
1170 | delete text, and other editing functions. | |
1171 | * Signal Characters:: Special characters that send or raise signals | |
1172 | to or for certain classes of processes. | |
1173 | * Start/Stop Characters:: Special characters that suspend or resume | |
1174 | suspended output. | |
1175 | * Other Special:: Other special characters for BSD systems: | |
1176 | they can discard output, and print status. | |
1177 | @end menu | |
1178 | ||
1179 | @node Editing Characters | |
1180 | @subsubsection Characters for Input Editing | |
1181 | ||
1182 | These special characters are active only in canonical input mode. | |
1183 | @xref{Canonical or Not}. | |
1184 | ||
28f540f4 | 1185 | @deftypevr Macro int VEOF |
d08a7e4c | 1186 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
1187 | @cindex EOF character |
1188 | This is the subscript for the EOF character in the special control | |
1189 | character array. @code{@var{termios}.c_cc[VEOF]} holds the character | |
1190 | itself. | |
1191 | ||
1192 | The EOF character is recognized only in canonical input mode. It acts | |
1193 | as a line terminator in the same way as a newline character, but if the | |
1194 | EOF character is typed at the beginning of a line it causes @code{read} | |
1195 | to return a byte count of zero, indicating end-of-file. The EOF | |
1196 | character itself is discarded. | |
1197 | ||
1198 | Usually, the EOF character is @kbd{C-d}. | |
1199 | @end deftypevr | |
1200 | ||
28f540f4 | 1201 | @deftypevr Macro int VEOL |
d08a7e4c | 1202 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
1203 | @cindex EOL character |
1204 | This is the subscript for the EOL character in the special control | |
1205 | character array. @code{@var{termios}.c_cc[VEOL]} holds the character | |
1206 | itself. | |
1207 | ||
1208 | The EOL character is recognized only in canonical input mode. It acts | |
1209 | as a line terminator, just like a newline character. The EOL character | |
1210 | is not discarded; it is read as the last character in the input line. | |
1211 | ||
1212 | @c !!! example: this is set to ESC by 4.3 csh with "set filec" so it can | |
1213 | @c complete partial lines without using cbreak or raw mode. | |
1214 | ||
1215 | You don't need to use the EOL character to make @key{RET} end a line. | |
1216 | Just set the ICRNL flag. In fact, this is the default state of | |
1217 | affairs. | |
1218 | @end deftypevr | |
1219 | ||
28f540f4 | 1220 | @deftypevr Macro int VEOL2 |
d08a7e4c | 1221 | @standards{BSD, termios.h} |
28f540f4 RM |
1222 | @cindex EOL2 character |
1223 | This is the subscript for the EOL2 character in the special control | |
1224 | character array. @code{@var{termios}.c_cc[VEOL2]} holds the character | |
1225 | itself. | |
1226 | ||
1227 | The EOL2 character works just like the EOL character (see above), but it | |
1228 | can be a different character. Thus, you can specify two characters to | |
1229 | terminate an input line, by setting EOL to one of them and EOL2 to the | |
1230 | other. | |
1231 | ||
1232 | The EOL2 character is a BSD extension; it exists only on BSD systems | |
a7a93d50 | 1233 | and @gnulinuxhurdsystems{}. |
28f540f4 RM |
1234 | @end deftypevr |
1235 | ||
28f540f4 | 1236 | @deftypevr Macro int VERASE |
d08a7e4c | 1237 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
1238 | @cindex ERASE character |
1239 | This is the subscript for the ERASE character in the special control | |
1240 | character array. @code{@var{termios}.c_cc[VERASE]} holds the | |
1241 | character itself. | |
1242 | ||
1243 | The ERASE character is recognized only in canonical input mode. When | |
1244 | the user types the erase character, the previous character typed is | |
1245 | discarded. (If the terminal generates multibyte character sequences, | |
1246 | this may cause more than one byte of input to be discarded.) This | |
1247 | cannot be used to erase past the beginning of the current line of text. | |
1248 | The ERASE character itself is discarded. | |
1249 | @c !!! mention ECHOE here | |
1250 | ||
1251 | Usually, the ERASE character is @key{DEL}. | |
1252 | @end deftypevr | |
1253 | ||
28f540f4 | 1254 | @deftypevr Macro int VWERASE |
d08a7e4c | 1255 | @standards{BSD, termios.h} |
28f540f4 RM |
1256 | @cindex WERASE character |
1257 | This is the subscript for the WERASE character in the special control | |
1258 | character array. @code{@var{termios}.c_cc[VWERASE]} holds the character | |
1259 | itself. | |
1260 | ||
1261 | The WERASE character is recognized only in canonical mode. It erases an | |
1262 | entire word of prior input, and any whitespace after it; whitespace | |
1263 | characters before the word are not erased. | |
1264 | ||
1265 | The definition of a ``word'' depends on the setting of the | |
1266 | @code{ALTWERASE} mode; @pxref{Local Modes}. | |
1267 | ||
1268 | If the @code{ALTWERASE} mode is not set, a word is defined as a sequence | |
1269 | of any characters except space or tab. | |
1270 | ||
1271 | If the @code{ALTWERASE} mode is set, a word is defined as a sequence of | |
1272 | characters containing only letters, numbers, and underscores, optionally | |
1273 | followed by one character that is not a letter, number, or underscore. | |
1274 | ||
1275 | The WERASE character is usually @kbd{C-w}. | |
1276 | ||
1277 | This is a BSD extension. | |
1278 | @end deftypevr | |
1279 | ||
28f540f4 | 1280 | @deftypevr Macro int VKILL |
d08a7e4c | 1281 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
1282 | @cindex KILL character |
1283 | This is the subscript for the KILL character in the special control | |
1284 | character array. @code{@var{termios}.c_cc[VKILL]} holds the character | |
1285 | itself. | |
1286 | ||
1287 | The KILL character is recognized only in canonical input mode. When the | |
1288 | user types the kill character, the entire contents of the current line | |
1289 | of input are discarded. The kill character itself is discarded too. | |
1290 | ||
1291 | The KILL character is usually @kbd{C-u}. | |
1292 | @end deftypevr | |
1293 | ||
28f540f4 | 1294 | @deftypevr Macro int VREPRINT |
d08a7e4c | 1295 | @standards{BSD, termios.h} |
28f540f4 RM |
1296 | @cindex REPRINT character |
1297 | This is the subscript for the REPRINT character in the special control | |
1298 | character array. @code{@var{termios}.c_cc[VREPRINT]} holds the character | |
1299 | itself. | |
1300 | ||
1301 | The REPRINT character is recognized only in canonical mode. It reprints | |
1302 | the current input line. If some asynchronous output has come while you | |
1303 | are typing, this lets you see the line you are typing clearly again. | |
1304 | ||
1305 | The REPRINT character is usually @kbd{C-r}. | |
1306 | ||
1307 | This is a BSD extension. | |
1308 | @end deftypevr | |
1309 | ||
1310 | @node Signal Characters | |
1311 | @subsubsection Characters that Cause Signals | |
1312 | ||
1313 | These special characters may be active in either canonical or noncanonical | |
1314 | input mode, but only when the @code{ISIG} flag is set (@pxref{Local | |
1315 | Modes}). | |
1316 | ||
28f540f4 | 1317 | @deftypevr Macro int VINTR |
d08a7e4c | 1318 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
1319 | @cindex INTR character |
1320 | @cindex interrupt character | |
1321 | This is the subscript for the INTR character in the special control | |
1322 | character array. @code{@var{termios}.c_cc[VINTR]} holds the character | |
1323 | itself. | |
1324 | ||
1325 | The INTR (interrupt) character raises a @code{SIGINT} signal for all | |
1326 | processes in the foreground job associated with the terminal. The INTR | |
1327 | character itself is then discarded. @xref{Signal Handling}, for more | |
1328 | information about signals. | |
1329 | ||
1330 | Typically, the INTR character is @kbd{C-c}. | |
1331 | @end deftypevr | |
1332 | ||
28f540f4 | 1333 | @deftypevr Macro int VQUIT |
d08a7e4c | 1334 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
1335 | @cindex QUIT character |
1336 | This is the subscript for the QUIT character in the special control | |
1337 | character array. @code{@var{termios}.c_cc[VQUIT]} holds the character | |
1338 | itself. | |
1339 | ||
1340 | The QUIT character raises a @code{SIGQUIT} signal for all processes in | |
1341 | the foreground job associated with the terminal. The QUIT character | |
1342 | itself is then discarded. @xref{Signal Handling}, for more information | |
1343 | about signals. | |
1344 | ||
1345 | Typically, the QUIT character is @kbd{C-\}. | |
1346 | @end deftypevr | |
1347 | ||
28f540f4 | 1348 | @deftypevr Macro int VSUSP |
d08a7e4c | 1349 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
1350 | @cindex SUSP character |
1351 | @cindex suspend character | |
1352 | This is the subscript for the SUSP character in the special control | |
1353 | character array. @code{@var{termios}.c_cc[VSUSP]} holds the character | |
1354 | itself. | |
1355 | ||
1356 | The SUSP (suspend) character is recognized only if the implementation | |
1357 | supports job control (@pxref{Job Control}). It causes a @code{SIGTSTP} | |
1358 | signal to be sent to all processes in the foreground job associated with | |
1359 | the terminal. The SUSP character itself is then discarded. | |
1360 | @xref{Signal Handling}, for more information about signals. | |
1361 | ||
1362 | Typically, the SUSP character is @kbd{C-z}. | |
1363 | @end deftypevr | |
1364 | ||
1365 | Few applications disable the normal interpretation of the SUSP | |
1366 | character. If your program does this, it should provide some other | |
1367 | mechanism for the user to stop the job. When the user invokes this | |
1368 | mechanism, the program should send a @code{SIGTSTP} signal to the | |
1369 | process group of the process, not just to the process itself. | |
1370 | @xref{Signaling Another Process}. | |
1371 | ||
28f540f4 | 1372 | @deftypevr Macro int VDSUSP |
d08a7e4c | 1373 | @standards{BSD, termios.h} |
28f540f4 RM |
1374 | @cindex DSUSP character |
1375 | @cindex delayed suspend character | |
1376 | This is the subscript for the DSUSP character in the special control | |
1377 | character array. @code{@var{termios}.c_cc[VDSUSP]} holds the character | |
1378 | itself. | |
1379 | ||
1380 | The DSUSP (suspend) character is recognized only if the implementation | |
1381 | supports job control (@pxref{Job Control}). It sends a @code{SIGTSTP} | |
1382 | signal, like the SUSP character, but not right away---only when the | |
1383 | program tries to read it as input. Not all systems with job control | |
dc40b233 | 1384 | support DSUSP; only BSD-compatible systems do (including @gnuhurdsystems{}). |
28f540f4 RM |
1385 | |
1386 | @xref{Signal Handling}, for more information about signals. | |
1387 | ||
1388 | Typically, the DSUSP character is @kbd{C-y}. | |
1389 | @end deftypevr | |
1390 | ||
1391 | @node Start/Stop Characters | |
1392 | @subsubsection Special Characters for Flow Control | |
1393 | ||
1394 | These special characters may be active in either canonical or noncanonical | |
1395 | input mode, but their use is controlled by the flags @code{IXON} and | |
1396 | @code{IXOFF} (@pxref{Input Modes}). | |
1397 | ||
28f540f4 | 1398 | @deftypevr Macro int VSTART |
d08a7e4c | 1399 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
1400 | @cindex START character |
1401 | This is the subscript for the START character in the special control | |
1402 | character array. @code{@var{termios}.c_cc[VSTART]} holds the | |
1403 | character itself. | |
1404 | ||
1405 | The START character is used to support the @code{IXON} and @code{IXOFF} | |
1406 | input modes. If @code{IXON} is set, receiving a START character resumes | |
1407 | suspended output; the START character itself is discarded. If | |
1408 | @code{IXANY} is set, receiving any character at all resumes suspended | |
1409 | output; the resuming character is not discarded unless it is the START | |
dc40b233 | 1410 | character. If @code{IXOFF} is set, the system may also transmit START |
28f540f4 RM |
1411 | characters to the terminal. |
1412 | ||
1413 | The usual value for the START character is @kbd{C-q}. You may not be | |
1414 | able to change this value---the hardware may insist on using @kbd{C-q} | |
1415 | regardless of what you specify. | |
1416 | @end deftypevr | |
1417 | ||
28f540f4 | 1418 | @deftypevr Macro int VSTOP |
d08a7e4c | 1419 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
1420 | @cindex STOP character |
1421 | This is the subscript for the STOP character in the special control | |
1422 | character array. @code{@var{termios}.c_cc[VSTOP]} holds the character | |
1423 | itself. | |
1424 | ||
1425 | The STOP character is used to support the @code{IXON} and @code{IXOFF} | |
1426 | input modes. If @code{IXON} is set, receiving a STOP character causes | |
1427 | output to be suspended; the STOP character itself is discarded. If | |
1428 | @code{IXOFF} is set, the system may also transmit STOP characters to the | |
1429 | terminal, to prevent the input queue from overflowing. | |
1430 | ||
1431 | The usual value for the STOP character is @kbd{C-s}. You may not be | |
1432 | able to change this value---the hardware may insist on using @kbd{C-s} | |
1433 | regardless of what you specify. | |
1434 | @end deftypevr | |
1435 | ||
1436 | @node Other Special | |
1437 | @subsubsection Other Special Characters | |
1438 | ||
28f540f4 | 1439 | @deftypevr Macro int VLNEXT |
d08a7e4c | 1440 | @standards{BSD, termios.h} |
28f540f4 RM |
1441 | @cindex LNEXT character |
1442 | This is the subscript for the LNEXT character in the special control | |
1443 | character array. @code{@var{termios}.c_cc[VLNEXT]} holds the character | |
1444 | itself. | |
1445 | ||
1446 | The LNEXT character is recognized only when @code{IEXTEN} is set, but in | |
1447 | both canonical and noncanonical mode. It disables any special | |
1448 | significance of the next character the user types. Even if the | |
6d52618b | 1449 | character would normally perform some editing function or generate a |
28f540f4 RM |
1450 | signal, it is read as a plain character. This is the analogue of the |
1451 | @kbd{C-q} command in Emacs. ``LNEXT'' stands for ``literal next.'' | |
1452 | ||
1453 | The LNEXT character is usually @kbd{C-v}. | |
a7a93d50 JM |
1454 | |
1455 | This character is available on BSD systems and @gnulinuxhurdsystems{}. | |
28f540f4 RM |
1456 | @end deftypevr |
1457 | ||
28f540f4 | 1458 | @deftypevr Macro int VDISCARD |
d08a7e4c | 1459 | @standards{BSD, termios.h} |
28f540f4 RM |
1460 | @cindex DISCARD character |
1461 | This is the subscript for the DISCARD character in the special control | |
1462 | character array. @code{@var{termios}.c_cc[VDISCARD]} holds the character | |
1463 | itself. | |
1464 | ||
1465 | The DISCARD character is recognized only when @code{IEXTEN} is set, but | |
1466 | in both canonical and noncanonical mode. Its effect is to toggle the | |
1467 | discard-output flag. When this flag is set, all program output is | |
1468 | discarded. Setting the flag also discards all output currently in the | |
1469 | output buffer. Typing any other character resets the flag. | |
a7a93d50 JM |
1470 | |
1471 | This character is available on BSD systems and @gnulinuxhurdsystems{}. | |
28f540f4 RM |
1472 | @end deftypevr |
1473 | ||
28f540f4 | 1474 | @deftypevr Macro int VSTATUS |
d08a7e4c | 1475 | @standards{BSD, termios.h} |
28f540f4 RM |
1476 | @cindex STATUS character |
1477 | This is the subscript for the STATUS character in the special control | |
1478 | character array. @code{@var{termios}.c_cc[VSTATUS]} holds the character | |
1479 | itself. | |
1480 | ||
1481 | The STATUS character's effect is to print out a status message about how | |
1482 | the current process is running. | |
1483 | ||
1484 | The STATUS character is recognized only in canonical mode, and only if | |
1485 | @code{NOKERNINFO} is not set. | |
a7a93d50 JM |
1486 | |
1487 | This character is available only on BSD systems and @gnuhurdsystems{}. | |
28f540f4 RM |
1488 | @end deftypevr |
1489 | ||
1490 | @node Noncanonical Input | |
1491 | @subsection Noncanonical Input | |
1492 | ||
1493 | In noncanonical input mode, the special editing characters such as | |
1494 | ERASE and KILL are ignored. The system facilities for the user to edit | |
1495 | input are disabled in noncanonical mode, so that all input characters | |
1496 | (unless they are special for signal or flow-control purposes) are passed | |
1497 | to the application program exactly as typed. It is up to the | |
1498 | application program to give the user ways to edit the input, if | |
1499 | appropriate. | |
1500 | ||
1501 | Noncanonical mode offers special parameters called MIN and TIME for | |
1502 | controlling whether and how long to wait for input to be available. You | |
1503 | can even use them to avoid ever waiting---to return immediately with | |
1504 | whatever input is available, or with no input. | |
1505 | ||
1506 | The MIN and TIME are stored in elements of the @code{c_cc} array, which | |
1507 | is a member of the @w{@code{struct termios}} structure. Each element of | |
1508 | this array has a particular role, and each element has a symbolic | |
1509 | constant that stands for the index of that element. @code{VMIN} and | |
dc40b233 | 1510 | @code{VTIME} are the names for the indices in the array of the MIN and |
28f540f4 RM |
1511 | TIME slots. |
1512 | ||
28f540f4 | 1513 | @deftypevr Macro int VMIN |
d08a7e4c | 1514 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
1515 | @cindex MIN termios slot |
1516 | This is the subscript for the MIN slot in the @code{c_cc} array. Thus, | |
1517 | @code{@var{termios}.c_cc[VMIN]} is the value itself. | |
1518 | ||
1519 | The MIN slot is only meaningful in noncanonical input mode; it | |
1520 | specifies the minimum number of bytes that must be available in the | |
1521 | input queue in order for @code{read} to return. | |
1522 | @end deftypevr | |
1523 | ||
28f540f4 | 1524 | @deftypevr Macro int VTIME |
d08a7e4c | 1525 | @standards{POSIX.1, termios.h} |
28f540f4 RM |
1526 | @cindex TIME termios slot |
1527 | This is the subscript for the TIME slot in the @code{c_cc} array. Thus, | |
1528 | @code{@var{termios}.c_cc[VTIME]} is the value itself. | |
1529 | ||
1530 | The TIME slot is only meaningful in noncanonical input mode; it | |
1531 | specifies how long to wait for input before returning, in units of 0.1 | |
1532 | seconds. | |
1533 | @end deftypevr | |
1534 | ||
1535 | The MIN and TIME values interact to determine the criterion for when | |
1536 | @code{read} should return; their precise meanings depend on which of | |
1537 | them are nonzero. There are four possible cases: | |
1538 | ||
1539 | @itemize @bullet | |
1540 | @item | |
1541 | Both TIME and MIN are nonzero. | |
1542 | ||
1543 | In this case, TIME specifies how long to wait after each input character | |
1544 | to see if more input arrives. After the first character received, | |
1545 | @code{read} keeps waiting until either MIN bytes have arrived in all, or | |
1546 | TIME elapses with no further input. | |
1547 | ||
1548 | @code{read} always blocks until the first character arrives, even if | |
1549 | TIME elapses first. @code{read} can return more than MIN characters if | |
1550 | more than MIN happen to be in the queue. | |
1551 | ||
6d52618b | 1552 | @item |
28f540f4 RM |
1553 | Both MIN and TIME are zero. |
1554 | ||
1555 | In this case, @code{read} always returns immediately with as many | |
1556 | characters as are available in the queue, up to the number requested. | |
1557 | If no input is immediately available, @code{read} returns a value of | |
1558 | zero. | |
1559 | ||
1560 | @item | |
1561 | MIN is zero but TIME has a nonzero value. | |
1562 | ||
1563 | In this case, @code{read} waits for time TIME for input to become | |
1564 | available; the availability of a single byte is enough to satisfy the | |
1565 | read request and cause @code{read} to return. When it returns, it | |
1566 | returns as many characters as are available, up to the number requested. | |
1567 | If no input is available before the timer expires, @code{read} returns a | |
1568 | value of zero. | |
1569 | ||
1570 | @item | |
1571 | TIME is zero but MIN has a nonzero value. | |
1572 | ||
1573 | In this case, @code{read} waits until at least MIN bytes are available | |
1574 | in the queue. At that time, @code{read} returns as many characters as | |
1575 | are available, up to the number requested. @code{read} can return more | |
1576 | than MIN characters if more than MIN happen to be in the queue. | |
1577 | @end itemize | |
1578 | ||
1579 | What happens if MIN is 50 and you ask to read just 10 bytes? | |
1580 | Normally, @code{read} waits until there are 50 bytes in the buffer (or, | |
1581 | more generally, the wait condition described above is satisfied), and | |
1582 | then reads 10 of them, leaving the other 40 buffered in the operating | |
1583 | system for a subsequent call to @code{read}. | |
1584 | ||
1585 | @strong{Portability note:} On some systems, the MIN and TIME slots are | |
1586 | actually the same as the EOF and EOL slots. This causes no serious | |
1587 | problem because the MIN and TIME slots are used only in noncanonical | |
1588 | input and the EOF and EOL slots are used only in canonical input, but it | |
1f77f049 | 1589 | isn't very clean. @Theglibc{} allocates separate slots for these |
28f540f4 RM |
1590 | uses. |
1591 | ||
85c54a32 | 1592 | @deftypefun void cfmakeraw (struct termios *@var{termios-p}) |
d08a7e4c | 1593 | @standards{BSD, termios.h} |
f8d529d5 AO |
1594 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1595 | @c There's no guarantee the changes are atomic, but since this is not an | |
1596 | @c opaque type, callers ought to ensure mutual exclusion to the termios | |
1597 | @c object. | |
28f540f4 RM |
1598 | This function provides an easy way to set up @code{*@var{termios-p}} for |
1599 | what has traditionally been called ``raw mode'' in BSD. This uses | |
1600 | noncanonical input, and turns off most processing to give an unmodified | |
1601 | channel to the terminal. | |
1602 | ||
1603 | It does exactly this: | |
1604 | @smallexample | |
1605 | @var{termios-p}->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP | |
1606 | |INLCR|IGNCR|ICRNL|IXON); | |
1607 | @var{termios-p}->c_oflag &= ~OPOST; | |
1608 | @var{termios-p}->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN); | |
1609 | @var{termios-p}->c_cflag &= ~(CSIZE|PARENB); | |
1610 | @var{termios-p}->c_cflag |= CS8; | |
1611 | @end smallexample | |
1612 | @end deftypefun | |
1613 | ||
e52236e5 UD |
1614 | |
1615 | @node BSD Terminal Modes | |
1616 | @section BSD Terminal Modes | |
1617 | @cindex terminal modes, BSD | |
1618 | ||
1619 | The usual way to get and set terminal modes is with the functions described | |
85adacbd | 1620 | in @ref{Terminal Modes}. However, on some systems you can use the |
dc40b233 | 1621 | BSD-derived functions in this section to do some of the same things. On |
1f77f049 | 1622 | many systems, these functions do not exist. Even with @theglibc{}, |
e52236e5 UD |
1623 | the functions simply fail with @code{errno} = @code{ENOSYS} with many |
1624 | kernels, including Linux. | |
1625 | ||
1626 | The symbols used in this section are declared in @file{sgtty.h}. | |
1627 | ||
e52236e5 | 1628 | @deftp {Data Type} {struct sgttyb} |
d08a7e4c | 1629 | @standards{BSD, termios.h} |
e52236e5 UD |
1630 | This structure is an input or output parameter list for @code{gtty} and |
1631 | @code{stty}. | |
1632 | ||
1633 | @table @code | |
1634 | @item char sg_ispeed | |
1635 | Line speed for input | |
1636 | @item char sg_ospeed | |
1637 | Line speed for output | |
1638 | @item char sg_erase | |
1639 | Erase character | |
1640 | @item char sg_kill | |
1641 | Kill character | |
1642 | @item int sg_flags | |
1643 | Various flags | |
1644 | @end table | |
1645 | @end deftp | |
1646 | ||
e52236e5 | 1647 | @deftypefun int gtty (int @var{filedes}, struct sgttyb *@var{attributes}) |
d08a7e4c | 1648 | @standards{BSD, sgtty.h} |
f8d529d5 AO |
1649 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1650 | @c Direct ioctl, BSD only. | |
e52236e5 UD |
1651 | This function gets the attributes of a terminal. |
1652 | ||
1653 | @code{gtty} sets *@var{attributes} to describe the terminal attributes | |
1654 | of the terminal which is open with file descriptor @var{filedes}. | |
1655 | @end deftypefun | |
1656 | ||
8ded91fb | 1657 | @deftypefun int stty (int @var{filedes}, const struct sgttyb *@var{attributes}) |
d08a7e4c | 1658 | @standards{BSD, sgtty.h} |
f8d529d5 AO |
1659 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1660 | @c Direct ioctl, BSD only. | |
e52236e5 UD |
1661 | |
1662 | This function sets the attributes of a terminal. | |
1663 | ||
1664 | @code{stty} sets the terminal attributes of the terminal which is open with | |
dc40b233 | 1665 | file descriptor @var{filedes} to those described by *@var{attributes}. |
e52236e5 UD |
1666 | @end deftypefun |
1667 | ||
28f540f4 RM |
1668 | @node Line Control |
1669 | @section Line Control Functions | |
1670 | @cindex terminal line control functions | |
1671 | ||
1672 | These functions perform miscellaneous control actions on terminal | |
1673 | devices. As regards terminal access, they are treated like doing | |
1674 | output: if any of these functions is used by a background process on its | |
1675 | controlling terminal, normally all processes in the process group are | |
1676 | sent a @code{SIGTTOU} signal. The exception is if the calling process | |
1677 | itself is ignoring or blocking @code{SIGTTOU} signals, in which case the | |
1678 | operation is performed and no signal is sent. @xref{Job Control}. | |
1679 | ||
1680 | @cindex break condition, generating | |
28f540f4 | 1681 | @deftypefun int tcsendbreak (int @var{filedes}, int @var{duration}) |
d08a7e4c | 1682 | @standards{POSIX.1, termios.h} |
f8d529d5 AO |
1683 | @safety{@prelim{}@mtunsafe{@mtasurace{:tcattr(filedes)/bsd}}@asunsafe{}@acunsafe{@acucorrupt{/bsd}}} |
1684 | @c On Linux, this calls just one out of two ioctls; on BSD, it's two | |
1685 | @c ioctls with a select (for the delay only) in between, the first | |
1686 | @c setting and the latter clearing the break status. The BSD | |
1687 | @c implementation may leave the break enabled if cancelled, and threads | |
1688 | @c and signals may cause the break to be interrupted before requested. | |
28f540f4 RM |
1689 | This function generates a break condition by transmitting a stream of |
1690 | zero bits on the terminal associated with the file descriptor | |
1691 | @var{filedes}. The duration of the break is controlled by the | |
1692 | @var{duration} argument. If zero, the duration is between 0.25 and 0.5 | |
1693 | seconds. The meaning of a nonzero value depends on the operating system. | |
1694 | ||
1695 | This function does nothing if the terminal is not an asynchronous serial | |
1696 | data port. | |
1697 | ||
1698 | The return value is normally zero. In the event of an error, a value | |
a53bad16 | 1699 | of @math{-1} is returned. The following @code{errno} error conditions |
28f540f4 RM |
1700 | are defined for this function: |
1701 | ||
1702 | @table @code | |
1703 | @item EBADF | |
1704 | The @var{filedes} is not a valid file descriptor. | |
1705 | ||
1706 | @item ENOTTY | |
1707 | The @var{filedes} is not associated with a terminal device. | |
1708 | @end table | |
1709 | @end deftypefun | |
1710 | ||
1711 | ||
1712 | @cindex flushing terminal output queue | |
1713 | @cindex terminal output queue, flushing | |
28f540f4 | 1714 | @deftypefun int tcdrain (int @var{filedes}) |
d08a7e4c | 1715 | @standards{POSIX.1, termios.h} |
f8d529d5 AO |
1716 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1717 | @c Direct ioctl. | |
28f540f4 RM |
1718 | The @code{tcdrain} function waits until all queued |
1719 | output to the terminal @var{filedes} has been transmitted. | |
1720 | ||
0bc93a2f | 1721 | This function is a cancellation point in multi-threaded programs. This |
dfd2257a UD |
1722 | is a problem if the thread allocates some resources (like memory, file |
1723 | descriptors, semaphores or whatever) at the time @code{tcdrain} is | |
1724 | called. If the thread gets canceled these resources stay allocated | |
1725 | until the program ends. To avoid this calls to @code{tcdrain} should be | |
0bc93a2f | 1726 | protected using cancellation handlers. |
dfd2257a UD |
1727 | @c ref pthread_cleanup_push / pthread_cleanup_pop |
1728 | ||
28f540f4 | 1729 | The return value is normally zero. In the event of an error, a value |
a53bad16 | 1730 | of @math{-1} is returned. The following @code{errno} error conditions |
28f540f4 RM |
1731 | are defined for this function: |
1732 | ||
1733 | @table @code | |
1734 | @item EBADF | |
1735 | The @var{filedes} is not a valid file descriptor. | |
1736 | ||
1737 | @item ENOTTY | |
1738 | The @var{filedes} is not associated with a terminal device. | |
1739 | ||
1740 | @item EINTR | |
1741 | The operation was interrupted by delivery of a signal. | |
1742 | @xref{Interrupted Primitives}. | |
1743 | @end table | |
1744 | @end deftypefun | |
1745 | ||
1746 | ||
1747 | @cindex clearing terminal input queue | |
1748 | @cindex terminal input queue, clearing | |
28f540f4 | 1749 | @deftypefun int tcflush (int @var{filedes}, int @var{queue}) |
d08a7e4c | 1750 | @standards{POSIX.1, termios.h} |
f8d529d5 AO |
1751 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1752 | @c Direct ioctl. | |
28f540f4 RM |
1753 | The @code{tcflush} function is used to clear the input and/or output |
1754 | queues associated with the terminal file @var{filedes}. The @var{queue} | |
1755 | argument specifies which queue(s) to clear, and can be one of the | |
1756 | following values: | |
1757 | ||
1758 | @c Extra blank lines here make it look better. | |
2fe82ca6 | 1759 | @vtable @code |
28f540f4 RM |
1760 | @item TCIFLUSH |
1761 | ||
1762 | Clear any input data received, but not yet read. | |
1763 | ||
28f540f4 RM |
1764 | @item TCOFLUSH |
1765 | ||
1766 | Clear any output data written, but not yet transmitted. | |
1767 | ||
28f540f4 RM |
1768 | @item TCIOFLUSH |
1769 | ||
1770 | Clear both queued input and output. | |
2fe82ca6 | 1771 | @end vtable |
28f540f4 RM |
1772 | |
1773 | The return value is normally zero. In the event of an error, a value | |
a53bad16 | 1774 | of @math{-1} is returned. The following @code{errno} error conditions |
28f540f4 RM |
1775 | are defined for this function: |
1776 | ||
1777 | @table @code | |
1778 | @item EBADF | |
1779 | The @var{filedes} is not a valid file descriptor. | |
1780 | ||
1781 | @item ENOTTY | |
1782 | The @var{filedes} is not associated with a terminal device. | |
1783 | ||
1784 | @item EINVAL | |
1785 | A bad value was supplied as the @var{queue} argument. | |
1786 | @end table | |
1787 | ||
1788 | It is unfortunate that this function is named @code{tcflush}, because | |
1789 | the term ``flush'' is normally used for quite another operation---waiting | |
1790 | until all output is transmitted---and using it for discarding input or | |
1791 | output would be confusing. Unfortunately, the name @code{tcflush} comes | |
1792 | from POSIX and we cannot change it. | |
1793 | @end deftypefun | |
1794 | ||
1795 | @cindex flow control, terminal | |
1796 | @cindex terminal flow control | |
28f540f4 | 1797 | @deftypefun int tcflow (int @var{filedes}, int @var{action}) |
d08a7e4c | 1798 | @standards{POSIX.1, termios.h} |
f8d529d5 AO |
1799 | @safety{@prelim{}@mtunsafe{@mtasurace{:tcattr(filedes)/bsd}}@asunsafe{}@acsafe{}} |
1800 | @c Direct ioctl on Linux. On BSD, the TCO* actions are a single ioctl, | |
1801 | @c whereas the TCI actions first call tcgetattr and then write to the fd | |
1802 | @c the c_cc character corresponding to the action; there's a window for | |
1803 | @c another thread to change the xon/xoff characters. | |
28f540f4 RM |
1804 | The @code{tcflow} function is used to perform operations relating to |
1805 | XON/XOFF flow control on the terminal file specified by @var{filedes}. | |
1806 | ||
1807 | The @var{action} argument specifies what operation to perform, and can | |
1808 | be one of the following values: | |
1809 | ||
2fe82ca6 | 1810 | @vtable @code |
28f540f4 RM |
1811 | @item TCOOFF |
1812 | Suspend transmission of output. | |
1813 | ||
28f540f4 RM |
1814 | @item TCOON |
1815 | Restart transmission of output. | |
1816 | ||
28f540f4 RM |
1817 | @item TCIOFF |
1818 | Transmit a STOP character. | |
1819 | ||
28f540f4 RM |
1820 | @item TCION |
1821 | Transmit a START character. | |
2fe82ca6 | 1822 | @end vtable |
28f540f4 RM |
1823 | |
1824 | For more information about the STOP and START characters, see @ref{Special | |
1825 | Characters}. | |
1826 | ||
1827 | The return value is normally zero. In the event of an error, a value | |
a53bad16 | 1828 | of @math{-1} is returned. The following @code{errno} error conditions |
28f540f4 RM |
1829 | are defined for this function: |
1830 | ||
1831 | @table @code | |
1832 | @vindex EBADF | |
1833 | @item EBADF | |
1834 | The @var{filedes} is not a valid file descriptor. | |
1835 | ||
1836 | @vindex ENOTTY | |
1837 | @item ENOTTY | |
1838 | The @var{filedes} is not associated with a terminal device. | |
1839 | ||
1840 | @vindex EINVAL | |
1841 | @item EINVAL | |
1842 | A bad value was supplied as the @var{action} argument. | |
1843 | @end table | |
1844 | @end deftypefun | |
1845 | ||
1846 | @node Noncanon Example | |
1847 | @section Noncanonical Mode Example | |
1848 | ||
1849 | Here is an example program that shows how you can set up a terminal | |
1850 | device to read single characters in noncanonical input mode, without | |
1851 | echo. | |
1852 | ||
1853 | @smallexample | |
1854 | @include termios.c.texi | |
1855 | @end smallexample | |
1856 | ||
1857 | This program is careful to restore the original terminal modes before | |
1858 | exiting or terminating with a signal. It uses the @code{atexit} | |
1859 | function (@pxref{Cleanups on Exit}) to make sure this is done | |
1860 | by @code{exit}. | |
1861 | ||
1862 | @ignore | |
1863 | @c !!!! the example doesn't handle any signals! | |
1864 | The signals handled in the example are the ones that typically occur due | |
1865 | to actions of the user. It might be desirable to handle other signals | |
1866 | such as SIGSEGV that can result from bugs in the program. | |
1867 | @end ignore | |
1868 | ||
1869 | The shell is supposed to take care of resetting the terminal modes when | |
1870 | a process is stopped or continued; see @ref{Job Control}. But some | |
1871 | existing shells do not actually do this, so you may wish to establish | |
1872 | handlers for job control signals that reset terminal modes. The above | |
1873 | example does so. | |
a53bad16 | 1874 | |
6ab902e4 | 1875 | @node getpass |
841785ba | 1876 | @section Reading Passphrases |
6ab902e4 | 1877 | |
841785ba | 1878 | When reading in a passphrase, it is desirable to avoid displaying it on |
6ab902e4 ZW |
1879 | the screen, to help keep it secret. The following function handles this |
1880 | in a convenient way. | |
1881 | ||
1882 | @deftypefun {char *} getpass (const char *@var{prompt}) | |
1883 | @standards{BSD, unistd.h} | |
1884 | @safety{@prelim{}@mtunsafe{@mtasuterm{}}@asunsafe{@ascuheap{} @asulock{} @asucorrupt{}}@acunsafe{@acuterm{} @aculock{} @acucorrupt{}}} | |
1885 | @c This function will attempt to create a stream for terminal I/O, but | |
1886 | @c will fallback to stdio/stderr. It attempts to change the terminal | |
841785ba | 1887 | @c mode in a thread-unsafe way, write out the prompt, read the passphrase, |
6ab902e4 ZW |
1888 | @c then restore the terminal mode. It has a cleanup to close the stream |
1889 | @c in case of (synchronous) cancellation, but not to restore the | |
1890 | @c terminal mode. | |
1891 | ||
1892 | @code{getpass} outputs @var{prompt}, then reads a string in from the | |
1893 | terminal without echoing it. It tries to connect to the real terminal, | |
1894 | @file{/dev/tty}, if possible, to encourage users not to put plaintext | |
841785ba | 1895 | passphrases in files; otherwise, it uses @code{stdin} and @code{stderr}. |
6ab902e4 ZW |
1896 | @code{getpass} also disables the INTR, QUIT, and SUSP characters on the |
1897 | terminal using the @code{ISIG} terminal attribute (@pxref{Local Modes}). | |
1898 | The terminal is flushed before and after @code{getpass}, so that | |
841785ba | 1899 | characters of a mistyped passphrase are not accidentally visible. |
6ab902e4 ZW |
1900 | |
1901 | In other C libraries, @code{getpass} may only return the first | |
841785ba | 1902 | @code{PASS_MAX} bytes of a passphrase. @Theglibc{} has no limit, so |
6ab902e4 ZW |
1903 | @code{PASS_MAX} is undefined. |
1904 | ||
1905 | The prototype for this function is in @file{unistd.h}. @code{PASS_MAX} | |
1906 | would be defined in @file{limits.h}. | |
1907 | @end deftypefun | |
1908 | ||
1909 | This precise set of operations may not suit all possible situations. In | |
1910 | this case, it is recommended that users write their own @code{getpass} | |
1911 | substitute. For instance, a very simple substitute is as follows: | |
1912 | ||
1913 | @smallexample | |
1914 | @include mygetpass.c.texi | |
1915 | @end smallexample | |
1916 | ||
1917 | The substitute takes the same parameters as @code{getline} | |
1918 | (@pxref{Line Input}); the user must print any prompt desired. | |
a53bad16 UD |
1919 | |
1920 | @node Pseudo-Terminals | |
1921 | @section Pseudo-Terminals | |
1922 | @cindex pseudo-terminals | |
1923 | ||
1924 | A @dfn{pseudo-terminal} is a special interprocess communication channel | |
e951d340 | 1925 | that acts like a terminal. One end of the channel is called the |
a53bad16 | 1926 | @dfn{master} side or @dfn{master pseudo-terminal device}, the other side |
e951d340 | 1927 | is called the @dfn{slave} side. Data written to the master side is |
a53bad16 UD |
1928 | received by the slave side as if it was the result of a user typing at |
1929 | an ordinary terminal, and data written to the slave side is sent to the | |
1930 | master side as if it was written on an ordinary terminal. | |
1931 | ||
1932 | Pseudo terminals are the way programs like @code{xterm} and @code{emacs} | |
1933 | implement their terminal emulation functionality. | |
1934 | ||
1935 | @menu | |
1936 | * Allocation:: Allocating a pseudo terminal. | |
1937 | * Pseudo-Terminal Pairs:: How to open both sides of a | |
1938 | pseudo-terminal in a single operation. | |
1939 | @end menu | |
1940 | ||
1941 | @node Allocation | |
1942 | @subsection Allocating Pseudo-Terminals | |
1943 | @cindex allocating pseudo-terminals | |
1944 | ||
1945 | @pindex stdlib.h | |
e951d340 | 1946 | This subsection describes functions for allocating a pseudo-terminal, |
a53bad16 UD |
1947 | and for making this pseudo-terminal available for actual use. These |
1948 | functions are declared in the header file @file{stdlib.h}. | |
1949 | ||
a53bad16 | 1950 | @deftypefun int getpt (void) |
d08a7e4c | 1951 | @standards{GNU, stdlib.h} |
f8d529d5 AO |
1952 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} |
1953 | @c On BSD, tries to open multiple potential pty names, returning on the | |
1954 | @c first success. On Linux, try posix_openpt first, then fallback to | |
1955 | @c the BSD implementation. The posix implementation opens the ptmx | |
1956 | @c device, checks with statfs that /dev/pts is a devpts or that /dev is | |
1957 | @c a devfs, and returns the fd; static variables devpts_mounted and | |
1958 | @c have_no_dev_ptmx are safely initialized so as to avoid repeated | |
1959 | @c tests. | |
a53bad16 UD |
1960 | The @code{getpt} function returns a new file descriptor for the next |
1961 | available master pseudo-terminal. The normal return value from | |
1962 | @code{getpt} is a non-negative integer file descriptor. In the case of | |
1963 | an error, a value of @math{-1} is returned instead. The following | |
1964 | @code{errno} conditions are defined for this function: | |
1965 | ||
1966 | @table @code | |
5632741e UD |
1967 | @item ENOENT |
1968 | There are no free master pseudo-terminals available. | |
a53bad16 UD |
1969 | @end table |
1970 | ||
1971 | This function is a GNU extension. | |
1972 | @end deftypefun | |
1973 | ||
a53bad16 | 1974 | @deftypefun int grantpt (int @var{filedes}) |
d08a7e4c RJ |
1975 | @standards{SVID, stdlib.h} |
1976 | @standards{XPG4.2, stdlib.h} | |
f8d529d5 AO |
1977 | @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
1978 | @c grantpt @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1979 | @c unix/grantpt:pts_name @acsuheap @acsmem | |
1980 | @c ptsname_internal dup ok (but this is Linux-only!) | |
1981 | @c memchr dup ok | |
1982 | @c realloc dup @acsuheap @acsmem | |
1983 | @c malloc dup @acsuheap @acsmem | |
1984 | @c free dup @acsuheap @acsmem | |
1985 | @c fcntl dup ok | |
1986 | @c getuid dup ok | |
1987 | @c chown dup ok | |
1988 | @c sysconf(_SC_GETGR_R_SIZE_MAX) ok | |
1989 | @c getgrnam_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
1990 | @c getgid dup ok | |
1991 | @c chmod dup ok | |
1992 | @c fork dup @aculock | |
1993 | @c [child] | |
1994 | @c setrlimit | |
1995 | @c dup2 | |
1996 | @c CLOSE_ALL_FDS | |
1997 | @c execle | |
1998 | @c _exit | |
1999 | @c waitpid dup ok | |
2000 | @c WIFEXITED dup ok | |
2001 | @c WEXITSTATUS dup ok | |
2002 | @c free dup @ascuheap @acsmem | |
a53bad16 UD |
2003 | The @code{grantpt} function changes the ownership and access permission |
2004 | of the slave pseudo-terminal device corresponding to the master | |
2005 | pseudo-terminal device associated with the file descriptor | |
2006 | @var{filedes}. The owner is set from the real user ID of the calling | |
2007 | process (@pxref{Process Persona}), and the group is set to a special | |
2008 | group (typically @dfn{tty}) or from the real group ID of the calling | |
2009 | process. The access permission is set such that the file is both | |
2010 | readable and writable by the owner and only writable by the group. | |
2011 | ||
2012 | On some systems this function is implemented by invoking a special | |
2013 | @code{setuid} root program (@pxref{How Change Persona}). As a | |
2014 | consequence, installing a signal handler for the @code{SIGCHLD} signal | |
2015 | (@pxref{Job Control Signals}) may interfere with a call to | |
2016 | @code{grantpt}. | |
2017 | ||
2018 | The normal return value from @code{grantpt} is @math{0}; a value of | |
2019 | @math{-1} is returned in case of failure. The following @code{errno} | |
2020 | error conditions are defined for this function: | |
2021 | ||
2022 | @table @code | |
2023 | @item EBADF | |
2024 | The @var{filedes} argument is not a valid file descriptor. | |
2025 | ||
0bc93a2f | 2026 | @item EINVAL |
a53bad16 UD |
2027 | The @var{filedes} argument is not associated with a master pseudo-terminal |
2028 | device. | |
2029 | ||
0bc93a2f | 2030 | @item EACCES |
a53bad16 UD |
2031 | The slave pseudo-terminal device corresponding to the master associated |
2032 | with @var{filedes} could not be accessed. | |
2033 | @end table | |
2034 | ||
2035 | @end deftypefun | |
2036 | ||
a53bad16 | 2037 | @deftypefun int unlockpt (int @var{filedes}) |
d08a7e4c RJ |
2038 | @standards{SVID, stdlib.h} |
2039 | @standards{XPG4.2, stdlib.h} | |
f8d529d5 AO |
2040 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}} |
2041 | @c unlockpt @ascuheap/bsd @acsmem @acsfd | |
2042 | @c /bsd | |
2043 | @c ptsname_r dup @ascuheap @acsmem @acsfd | |
2044 | @c revoke ok (syscall) | |
2045 | @c /linux | |
2046 | @c ioctl dup ok | |
a53bad16 UD |
2047 | The @code{unlockpt} function unlocks the slave pseudo-terminal device |
2048 | corresponding to the master pseudo-terminal device associated with the | |
2049 | file descriptor @var{filedes}. On many systems, the slave can only be | |
2050 | opened after unlocking, so portable applications should always call | |
2051 | @code{unlockpt} before trying to open the slave. | |
2052 | ||
2053 | The normal return value from @code{unlockpt} is @math{0}; a value of | |
2054 | @math{-1} is returned in case of failure. The following @code{errno} | |
2055 | error conditions are defined for this function: | |
2056 | ||
2057 | @table @code | |
2058 | @item EBADF | |
2059 | The @var{filedes} argument is not a valid file descriptor. | |
2060 | ||
2061 | @item EINVAL | |
2062 | The @var{filedes} argument is not associated with a master pseudo-terminal | |
2063 | device. | |
2064 | @end table | |
2065 | @end deftypefun | |
2066 | ||
a53bad16 | 2067 | @deftypefun {char *} ptsname (int @var{filedes}) |
d08a7e4c RJ |
2068 | @standards{SVID, stdlib.h} |
2069 | @standards{XPG4.2, stdlib.h} | |
f8d529d5 AO |
2070 | @safety{@prelim{}@mtunsafe{@mtasurace{:ptsname}}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}} |
2071 | @c ptsname @mtasurace:ptsname @ascuheap/bsd @acsmem @acsfd | |
2072 | @c ptsname_r dup @ascuheap/bsd @acsmem @acsfd | |
a53bad16 UD |
2073 | If the file descriptor @var{filedes} is associated with a |
2074 | master pseudo-terminal device, the @code{ptsname} function returns a | |
2075 | pointer to a statically-allocated, null-terminated string containing the | |
2076 | file name of the associated slave pseudo-terminal file. This string | |
2077 | might be overwritten by subsequent calls to @code{ptsname}. | |
2078 | @end deftypefun | |
2079 | ||
a53bad16 | 2080 | @deftypefun int ptsname_r (int @var{filedes}, char *@var{buf}, size_t @var{len}) |
d08a7e4c | 2081 | @standards{GNU, stdlib.h} |
f8d529d5 AO |
2082 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd}}@acunsafe{@acsmem{} @acsfd{}}} |
2083 | @c ptsname_r @ascuheap/bsd @acsmem @acsfd | |
2084 | @c /hurd | |
2085 | @c term_get_peername ok | |
2086 | @c strlen dup ok | |
2087 | @c memcpy dup ok | |
2088 | @c /bsd | |
2089 | @c isatty dup ok | |
2090 | @c strlen dup ok | |
2091 | @c ttyname_r dup @ascuheap @acsmem @acsfd | |
2092 | @c stat dup ok | |
2093 | @c /linux | |
2094 | @c ptsname_internal ok | |
2095 | @c isatty dup ok | |
2096 | @c ioctl dup ok | |
2097 | @c strlen dup ok | |
2098 | @c itoa_word dup ok | |
2099 | @c stpcpy dup ok | |
2100 | @c memcpy dup ok | |
2101 | @c fxstat64 dup ok | |
2102 | @c MASTER_P ok | |
2103 | @c major ok | |
2104 | @c gnu_dev_major ok | |
2105 | @c minor ok | |
2106 | @c gnu_dev_minor ok | |
2107 | @c minor dup ok | |
2108 | @c xstat64 dup ok | |
2109 | @c S_ISCHR dup ok | |
2110 | @c SLAVE_P ok | |
2111 | @c major dup ok | |
2112 | @c minor dup ok | |
a53bad16 UD |
2113 | The @code{ptsname_r} function is similar to the @code{ptsname} function |
2114 | except that it places its result into the user-specified buffer starting | |
2115 | at @var{buf} with length @var{len}. | |
2116 | ||
2117 | This function is a GNU extension. | |
2118 | @end deftypefun | |
2119 | ||
a53bad16 UD |
2120 | Typical usage of these functions is illustrated by the following example: |
2121 | @smallexample | |
2122 | int | |
2123 | open_pty_pair (int *amaster, int *aslave) | |
2124 | @{ | |
2125 | int master, slave; | |
14e243ce | 2126 | char *name; |
a53bad16 UD |
2127 | |
2128 | master = getpt (); | |
2129 | if (master < 0) | |
2130 | return 0; | |
2131 | ||
2132 | if (grantpt (master) < 0 || unlockpt (master) < 0) | |
2133 | goto close_master; | |
2134 | name = ptsname (master); | |
2135 | if (name == NULL) | |
2136 | goto close_master; | |
2137 | ||
b195f6bc | 2138 | slave = open (name, O_RDWR); |
a53bad16 UD |
2139 | if (slave == -1) |
2140 | goto close_master; | |
2141 | ||
a53bad16 UD |
2142 | *amaster = master; |
2143 | *aslave = slave; | |
2144 | return 1; | |
2145 | ||
2146 | close_slave: | |
2147 | close (slave); | |
2148 | ||
2149 | close_master: | |
2150 | close (master); | |
2151 | return 0; | |
2152 | @} | |
2153 | @end smallexample | |
2154 | ||
2155 | @node Pseudo-Terminal Pairs | |
2156 | @subsection Opening a Pseudo-Terminal Pair | |
2157 | @cindex opening a pseudo-terminal pair | |
2158 | ||
2159 | These functions, derived from BSD, are available in the separate | |
2160 | @file{libutil} library, and declared in @file{pty.h}. | |
2161 | ||
4bcecfb7 | 2162 | @deftypefun int openpty (int *@var{amaster}, int *@var{aslave}, char *@var{name}, const struct termios *@var{termp}, const struct winsize *@var{winp}) |
d08a7e4c | 2163 | @standards{BSD, pty.h} |
f8d529d5 AO |
2164 | @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
2165 | @c openpty @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2166 | @c getpt @acsfd | |
2167 | @c grantpt @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2168 | @c unlockpt dup @ascuheap/bsd @acsmem @acsfd | |
2169 | @c openpty:pts_name @acsuheap @acsmem @acsfd | |
2170 | @c ptsname_r dup @ascuheap/bsd @acsmem @acsfd | |
2171 | @c realloc dup @acsuheap @acsmem | |
2172 | @c malloc dup @acsuheap @acsmem | |
2173 | @c free dup @acsuheap @acsmem | |
2174 | @c open dup @acsfd | |
2175 | @c free dup @acsuheap @acsmem | |
2176 | @c tcsetattr dup ok | |
2177 | @c ioctl dup ok | |
2178 | @c strcpy dup ok | |
2179 | @c close dup @acsfd | |
a53bad16 UD |
2180 | This function allocates and opens a pseudo-terminal pair, returning the |
2181 | file descriptor for the master in @var{*amaster}, and the file | |
2182 | descriptor for the slave in @var{*aslave}. If the argument @var{name} | |
e951d340 | 2183 | is not a null pointer, the file name of the slave pseudo-terminal |
a53bad16 UD |
2184 | device is stored in @code{*name}. If @var{termp} is not a null pointer, |
2185 | the terminal attributes of the slave are set to the ones specified in | |
2186 | the structure that @var{termp} points to (@pxref{Terminal Modes}). | |
dc40b233 | 2187 | Likewise, if @var{winp} is not a null pointer, the screen size of |
a53bad16 UD |
2188 | the slave is set to the values specified in the structure that |
2189 | @var{winp} points to. | |
2190 | ||
2191 | The normal return value from @code{openpty} is @math{0}; a value of | |
5632741e UD |
2192 | @math{-1} is returned in case of failure. The following @code{errno} |
2193 | conditions are defined for this function: | |
2194 | ||
2195 | @table @code | |
2196 | @item ENOENT | |
2197 | There are no free pseudo-terminal pairs available. | |
2198 | @end table | |
a53bad16 | 2199 | |
e951d340 UD |
2200 | @strong{Warning:} Using the @code{openpty} function with @var{name} not |
2201 | set to @code{NULL} is @strong{very dangerous} because it provides no | |
2202 | protection against overflowing the string @var{name}. You should use | |
2203 | the @code{ttyname} function on the file descriptor returned in | |
2204 | @var{*slave} to find out the file name of the slave pseudo-terminal | |
2205 | device instead. | |
a53bad16 UD |
2206 | @end deftypefun |
2207 | ||
4bcecfb7 | 2208 | @deftypefun int forkpty (int *@var{amaster}, char *@var{name}, const struct termios *@var{termp}, const struct winsize *@var{winp}) |
d08a7e4c | 2209 | @standards{BSD, pty.h} |
f8d529d5 AO |
2210 | @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}} |
2211 | @c forkpty @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2212 | @c openpty dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem | |
2213 | @c fork dup @aculock | |
2214 | @c close dup @acsfd | |
2215 | @c /child | |
2216 | @c close dup @acsfd | |
2217 | @c login_tty dup @mtasurace:ttyname @ascuheap @asulock @aculock @acsmem @acsfd | |
2218 | @c _exit dup ok | |
2219 | @c close dup @acsfd | |
a53bad16 | 2220 | This function is similar to the @code{openpty} function, but in |
b195f6bc UD |
2221 | addition, forks a new process (@pxref{Creating a Process}) and makes the |
2222 | newly opened slave pseudo-terminal device the controlling terminal | |
2223 | (@pxref{Controlling Terminal}) for the child process. | |
a53bad16 UD |
2224 | |
2225 | If the operation is successful, there are then both parent and child | |
2226 | processes and both see @code{forkpty} return, but with different values: | |
2227 | it returns a value of @math{0} in the child process and returns the child's | |
2228 | process ID in the parent process. | |
2229 | ||
2230 | If the allocation of a pseudo-terminal pair or the process creation | |
2231 | failed, @code{forkpty} returns a value of @math{-1} in the parent | |
2232 | process. | |
2233 | ||
2234 | @strong{Warning:} The @code{forkpty} function has the same problems with | |
2235 | respect to the @var{name} argument as @code{openpty}. | |
2236 | @end deftypefun |