a9593ccfc5b2cc4aeaf7fa266c11d9b1dda84f3f
[kopensolaris-gnu/glibc.git] / manual / terminal.texi
1 @node Low-Level Terminal Interface
2 @chapter Low-Level Terminal Interface
3
4 This chapter describes functions that are specific to terminal devices.
5 You can use these functions to do things like turn off input echoing;
6 set serial line characteristics such as line speed and flow control; and
7 change which characters are used for end-of-file, command-line editing,
8 sending signals, and similar control functions.
9
10 Most of the functions in this chapter operate on file descriptors.
11 @xref{Low-Level I/O}, for more information about what a file
12 descriptor is and how to open a file descriptor for a terminal device.
13
14 @menu
15 * Is It a Terminal::            How to determine if a file is a terminal
16                                  device, and what its name is.
17 * I/O Queues::                  About flow control and typeahead.
18 * Canonical or Not::            Two basic styles of input processing.
19 * Terminal Modes::              How to examine and modify flags controlling
20                                  details of terminal I/O: echoing,
21                                  signals, editing. 
22 * Line Control::                Sending break sequences, clearing
23                                  terminal buffers @dots{} 
24 * Noncanon Example::            How to read single characters without echo.
25 @end menu
26
27 @node Is It a Terminal
28 @section Identifying Terminals
29 @cindex terminal identification
30 @cindex identifying terminals
31
32 The functions described in this chapter only work on files that
33 correspond to terminal devices.  You can find out whether a file
34 descriptor is associated with a terminal by using the @code{isatty}
35 function.
36
37 @pindex unistd.h
38 Prototypes for both @code{isatty} and @code{ttyname} are declared in
39 the header file @file{unistd.h}.
40
41 @comment unistd.h
42 @comment POSIX.1
43 @deftypefun int isatty (int @var{filedes})
44 This function returns @code{1} if @var{filedes} is a file descriptor
45 associated with an open terminal device, and @code{0} otherwise.
46 @end deftypefun
47
48 If a file descriptor is associated with a terminal, you can get its
49 associated file name using the @code{ttyname} function.  See also the
50 @code{ctermid} function, described in @ref{Identifying the Terminal}.
51
52 @comment unistd.h
53 @comment POSIX.1
54 @deftypefun {char *} ttyname (int @var{filedes})
55 If the file descriptor @var{filedes} is associated with a terminal
56 device, the @code{ttyname} function returns a pointer to a
57 statically-allocated, null-terminated string containing the file name of
58 the terminal file.  The value is a null pointer if the file descriptor
59 isn't associated with a terminal, or the file name cannot be determined.
60 @end deftypefun
61
62 @node I/O Queues
63 @section I/O Queues
64
65 Many of the remaining functions in this section refer to the input and
66 output queues of a terminal device.  These queues implement a form of
67 buffering @emph{within the kernel} independent of the buffering
68 implemented by I/O streams (@pxref{I/O on Streams}).
69
70 @cindex terminal input queue
71 @cindex typeahead buffer
72 The @dfn{terminal input queue} is also sometimes referred to as its
73 @dfn{typeahead buffer}.  It holds the characters that have been received
74 from the terminal but not yet read by any process.
75
76 The size of the terminal's input queue is described by the
77 @code{MAX_INPUT} and @w{@code{_POSIX_MAX_INPUT}} parameters; see @ref{Limits
78 for Files}.  You are guaranteed a queue size of at least
79 @code{MAX_INPUT}, but the queue might be larger, and might even
80 dynamically change size.  If input flow control is enabled by setting
81 the @code{IXOFF} input mode bit (@pxref{Input Modes}), the terminal
82 driver transmits STOP and START characters to the terminal when
83 necessary to prevent the queue from overflowing.  Otherwise, input may
84 be lost if it comes in too fast from the terminal.  In canonical mode,
85 all input stays in the queue until a newline character is received, so
86 the terminal input queue can fill up when you type a very long line.
87 @xref{Canonical or Not}.
88
89 @cindex terminal output queue
90 The @dfn{terminal output queue} is like the input queue, but for output;
91 it contains characters that have been written by processes, but not yet
92 transmitted to the terminal.  If output flow control is enabled by
93 setting the @code{IXON} input mode bit (@pxref{Input Modes}), the
94 terminal driver obeys STOP and STOP characters sent by the terminal to
95 stop and restart transmission of output.
96
97 @dfn{Clearing} the terminal input queue means discarding any characters
98 that have been received but not yet read.  Similarly, clearing the
99 terminal output queue means discarding any characters that have been
100 written but not yet transmitted.
101
102 @node Canonical or Not
103 @section Two Styles of Input: Canonical or Not
104
105 POSIX systems support two basic modes of input: canonical and
106 noncanonical.
107
108 @cindex canonical input processing
109 In @dfn{canonical input processing} mode, terminal input is processed in
110 lines terminated by newline (@code{'\n'}), EOF, or EOL characters.  No
111 input can be read until an entire line has been typed by the user, and
112 the @code{read} function (@pxref{I/O Primitives}) returns at most a
113 single line of input, no matter how many bytes are requested.
114
115 In canonical input mode, the operating system provides input editing
116 facilities: some characters are interpreted specially to perform editing
117 operations within the current line of text, such as ERASE and KILL.
118 @xref{Editing Characters}.
119
120 The constants @code{_POSIX_MAX_CANON} and @code{MAX_CANON} parameterize
121 the maximum number of bytes which may appear in a single line of
122 canonical input.  @xref{Limits for Files}.  You are guaranteed a maximum
123 line length of at least @code{MAX_CANON} bytes, but the maximum might be
124 larger, and might even dynamically change size.
125
126 @cindex noncanonical input processing
127 In @dfn{noncanonical input processing} mode, characters are not grouped
128 into lines, and ERASE and KILL processing is not performed.  The
129 granularity with which bytes are read in noncanonical input mode is
130 controlled by the MIN and TIME settings.  @xref{Noncanonical Input}.
131
132 Most programs use canonical input mode, because this gives the user a
133 way to edit input line by line.  The usual reason to use noncanonical
134 mode is when the program accepts single-character commands or provides
135 its own editing facilities.
136
137 The choice of canonical or noncanonical input is controlled by the
138 @code{ICANON} flag in the @code{c_lflag} member of @code{struct termios}.
139 @xref{Local Modes}.
140
141 @node Terminal Modes
142 @section Terminal Modes
143
144 @pindex termios.h
145 This section describes the various terminal attributes that control how
146 input and output are done.  The functions, data structures, and symbolic
147 constants are all declared in the header file @file{termios.h}.
148 @c !!! should mention terminal attributes are distinct from file attributes
149
150 @menu
151 * Mode Data Types::             The data type @code{struct termios} and
152                                  related types. 
153 * Mode Functions::              Functions to read and set the terminal
154                                  attributes. 
155 * Setting Modes::               The right way to set terminal attributes
156                                  reliably.
157 * Input Modes::                 Flags controlling low-level input handling.
158 * Output Modes::                Flags controlling low-level output handling.
159 * Control Modes::               Flags controlling serial port behavior.
160 * Local Modes::                 Flags controlling high-level input handling.
161 * Line Speed::                  How to read and set the terminal line speed.
162 * Special Characters::          Characters that have special effects,
163                                  and how to change them.
164 * Noncanonical Input::          Controlling how long to wait for input.
165 @end menu
166
167 @node Mode Data Types
168 @subsection Terminal Mode Data Types
169 @cindex terminal mode data types
170
171 The entire collection of attributes of a terminal is stored in a
172 structure of type @code{struct termios}.  This structure is used
173 with the functions @code{tcgetattr} and @code{tcsetattr} to read
174 and set the attributes.
175
176 @comment termios.h
177 @comment POSIX.1
178 @deftp {Data Type} {struct termios}
179 Structure that records all the I/O attributes of a terminal.  The
180 structure includes at least the following members:
181
182 @table @code
183 @item tcflag_t c_iflag
184 A bit mask specifying flags for input modes; see @ref{Input Modes}.
185
186 @item tcflag_t c_oflag
187 A bit mask specifying flags for output modes; see @ref{Output Modes}.
188
189 @item tcflag_t c_cflag
190 A bit mask specifying flags for control modes; see @ref{Control Modes}.
191
192 @item tcflag_t c_lflag
193 A bit mask specifying flags for local modes; see @ref{Local Modes}.
194
195 @item cc_t c_cc[NCCS]
196 An array specifying which characters are associated with various
197 control functions; see @ref{Special Characters}.
198 @end table
199
200 The @code{struct termios} structure also contains members which
201 encode input and output transmission speeds, but the representation is
202 not specified.  @xref{Line Speed}, for how to examine and store the
203 speed values.
204 @end deftp
205
206 The following sections describe the details of the members of the
207 @code{struct termios} structure.
208
209 @comment termios.h
210 @comment POSIX.1
211 @deftp {Data Type} tcflag_t
212 This is an unsigned integer type used to represent the various
213 bit masks for terminal flags.
214 @end deftp
215
216 @comment termios.h
217 @comment POSIX.1
218 @deftp {Data Type} cc_t
219 This is an unsigned integer type used to represent characters associated
220 with various terminal control functions.
221 @end deftp
222
223 @comment termios.h
224 @comment POSIX.1
225 @deftypevr Macro int NCCS
226 The value of this macro is the number of elements in the @code{c_cc}
227 array.
228 @end deftypevr
229
230 @node Mode Functions
231 @subsection Terminal Mode Functions
232 @cindex terminal mode functions
233
234 @comment termios.h
235 @comment POSIX.1
236 @deftypefun int tcgetattr (int @var{filedes}, struct termios *@var{termios-p})
237 This function is used to examine the attributes of the terminal
238 device with file descriptor @var{filedes}.  The attributes are returned
239 in the structure that @var{termios-p} points to.
240
241 If successful, @code{tcgetattr} returns @code{0}.  A return value of @code{-1}
242 indicates an error.  The following @code{errno} error conditions are
243 defined for this function:
244
245 @table @code
246 @item EBADF
247 The @var{filedes} argument is not a valid file descriptor.
248
249 @item ENOTTY
250 The @var{filedes} is not associated with a terminal.
251 @end table
252 @end deftypefun
253
254 @comment termios.h
255 @comment POSIX.1
256 @deftypefun int tcsetattr (int @var{filedes}, int @var{when}, const struct termios *@var{termios-p})
257 This function sets the attributes of the terminal device with file
258 descriptor @var{filedes}.  The new attributes are taken from the
259 structure that @var{termios-p} points to.
260
261 The @var{when} argument specifies how to deal with input and output
262 already queued.  It can be one of the following values:
263
264 @table @code
265 @comment termios.h
266 @comment POSIX.1
267 @item TCSANOW
268 @vindex TCSANOW
269 Make the change immediately.
270
271 @comment termios.h
272 @comment POSIX.1
273 @item TCSADRAIN
274 @vindex TCSADRAIN
275 Make the change after waiting until all queued output has been written.
276 You should usually use this option when changing parameters that affect
277 output.
278
279 @comment termios.h
280 @comment POSIX.1
281 @item TCSAFLUSH
282 @vindex TCSAFLUSH
283 This is like @code{TCSADRAIN}, but also discards any queued input.
284
285 @comment termios.h
286 @comment BSD
287 @item TCSASOFT
288 @vindex TCSASOFT
289 This is a flag bit that you can add to any of the above alternatives.
290 Its meaning is to inhibit alteration of the state of the terminal
291 hardware.  It is a BSD extension; it is only supported on BSD systems
292 and the GNU system.
293
294 Using @code{TCSASOFT} is exactly the same as setting the @code{CIGNORE}
295 bit in the @code{c_cflag} member of the structure @var{termios-p} points
296 to.  @xref{Control Modes}, for a description of @code{CIGNORE}.
297 @end table
298
299 If this function is called from a background process on its controlling
300 terminal, normally all processes in the process group are sent a
301 @code{SIGTTOU} signal, in the same way as if the process were trying to
302 write to the terminal.  The exception is if the calling process itself
303 is ignoring or blocking @code{SIGTTOU} signals, in which case the
304 operation is performed and no signal is sent.  @xref{Job Control}.
305
306 If successful, @code{tcsetattr} returns @code{0}.  A return value of
307 @code{-1} indicates an error.  The following @code{errno} error
308 conditions are defined for this function:
309
310 @table @code
311 @item EBADF
312 The @var{filedes} argument is not a valid file descriptor.
313
314 @item ENOTTY
315 The @var{filedes} is not associated with a terminal.
316
317 @item EINVAL
318 Either the value of the @code{when} argument is not valid, or there is
319 something wrong with the data in the @var{termios-p} argument.
320 @end table
321 @end deftypefun
322
323 Although @code{tcgetattr} and @code{tcsetattr} specify the terminal
324 device with a file descriptor, the attributes are those of the terminal
325 device itself and not of the file descriptor.  This means that the
326 effects of changing terminal attributes are persistent; if another
327 process opens the terminal file later on, it will see the changed
328 attributes even though it doesn't have anything to do with the open file
329 descriptor you originally specified in changing the attributes.
330
331 Similarly, if a single process has multiple or duplicated file
332 descriptors for the same terminal device, changing the terminal
333 attributes affects input and output to all of these file
334 descriptors.  This means, for example, that you can't open one file
335 descriptor or stream to read from a terminal in the normal
336 line-buffered, echoed mode; and simultaneously have another file
337 descriptor for the same terminal that you use to read from it in
338 single-character, non-echoed mode.  Instead, you have to explicitly
339 switch the terminal back and forth between the two modes.
340
341 @node Setting Modes
342 @subsection Setting Terminal Modes Properly
343
344 When you set terminal modes, you should call @code{tcgetattr} first to
345 get the current modes of the particular terminal device, modify only
346 those modes that you are really interested in, and store the result with
347 @code{tcsetattr}.
348
349 It's a bad idea to simply initialize a @code{struct termios} structure
350 to a chosen set of attributes and pass it directly to @code{tcsetattr}.
351 Your program may be run years from now, on systems that support members
352 not documented in this manual.  The way to avoid setting these members
353 to unreasonable values is to avoid changing them.
354
355 What's more, different terminal devices may require different mode
356 settings in order to function properly.  So you should avoid blindly
357 copying attributes from one terminal device to another.
358
359 When a member contains a collection of independent flags, as the
360 @code{c_iflag}, @code{c_oflag} and @code{c_cflag} members do, even
361 setting the entire member is a bad idea, because particular operating
362 systems have their own flags.  Instead, you should start with the
363 current value of the member and alter only the flags whose values matter
364 in your program, leaving any other flags unchanged.
365
366 Here is an example of how to set one flag (@code{ISTRIP}) in the
367 @code{struct termios} structure while properly preserving all the other
368 data in the structure:
369
370 @smallexample
371 @group
372 int
373 set_istrip (int desc, int value)
374 @{
375   struct termios settings;
376   int result;
377 @end group
378
379 @group
380   result = tcgetattr (desc, &settings);
381   if (result < 0)
382     @{
383       perror ("error in tcgetattr");
384       return 0;
385     @}
386 @end group
387 @group
388   settings.c_iflag &= ~ISTRIP;
389   if (value)
390     settings.c_iflag |= ISTRIP;
391 @end group
392 @group
393   result = tcsetattr (desc, TCSANOW, &settings);
394   if (result < 0)
395     @{
396       perror ("error in tcgetattr");
397       return;
398    @}
399   return 1;
400 @}
401 @end group
402 @end smallexample
403
404 @node Input Modes
405 @subsection Input Modes
406
407 This section describes the terminal attribute flags that control
408 fairly low-level aspects of input processing: handling of parity errors,
409 break signals, flow control, and @key{RET} and @key{LFD} characters.
410
411 All of these flags are bits in the @code{c_iflag} member of the
412 @code{struct termios} structure.  The member is an integer, and you
413 change flags using the operators @code{&}, @code{|} and @code{^}.  Don't
414 try to specify the entire value for @code{c_iflag}---instead, change
415 only specific flags and leave the rest untouched (@pxref{Setting
416 Modes}).
417
418 @comment termios.h
419 @comment POSIX.1
420 @deftypevr Macro tcflag_t INPCK
421 @cindex parity checking
422 If this bit is set, input parity checking is enabled.  If it is not set,
423 no checking at all is done for parity errors on input; the
424 characters are simply passed through to the application.
425
426 Parity checking on input processing is independent of whether parity
427 detection and generation on the underlying terminal hardware is enabled;
428 see @ref{Control Modes}.  For example, you could clear the @code{INPCK}
429 input mode flag and set the @code{PARENB} control mode flag to ignore
430 parity errors on input, but still generate parity on output.
431
432 If this bit is set, what happens when a parity error is detected depends
433 on whether the @code{IGNPAR} or @code{PARMRK} bits are set.  If neither
434 of these bits are set, a byte with a parity error is passed to the
435 application as a @code{'\0'} character.
436 @end deftypevr
437
438 @comment termios.h
439 @comment POSIX.1
440 @deftypevr Macro tcflag_t IGNPAR
441 If this bit is set, any byte with a framing or parity error is ignored.
442 This is only useful if @code{INPCK} is also set.
443 @end deftypevr
444
445 @comment termios.h
446 @comment POSIX.1
447 @deftypevr Macro tcflag_t PARMRK
448 If this bit is set, input bytes with parity or framing errors are marked
449 when passed to the program.  This bit is meaningful only when
450 @code{INPCK} is set and @code{IGNPAR} is not set.
451
452 The way erroneous bytes are marked is with two preceding bytes,
453 @code{377} and @code{0}.  Thus, the program actually reads three bytes
454 for one erroneous byte received from the terminal.
455
456 If a valid byte has the value @code{0377}, and @code{ISTRIP} (see below)
457 is not set, the program might confuse it with the prefix that marks a
458 parity error.  So a valid byte @code{0377} is passed to the program as
459 two bytes, @code{0377} @code{0377}, in this case.
460 @end deftypevr
461
462 @comment termios.h
463 @comment POSIX.1
464 @deftypevr Macro tcflag_t ISTRIP
465 If this bit is set, valid input bytes are stripped to seven bits;
466 otherwise, all eight bits are available for programs to read.
467 @end deftypevr
468
469 @comment termios.h
470 @comment POSIX.1
471 @deftypevr Macro tcflag_t IGNBRK
472 If this bit is set, break conditions are ignored.
473
474 @cindex break condition, detecting
475 A @dfn{break condition} is defined in the context of asynchronous
476 serial data transmission as a series of zero-value bits longer than a
477 single byte.
478 @end deftypevr
479
480 @comment termios.h
481 @comment POSIX.1
482 @deftypevr Macro tcflag_t BRKINT
483 If this bit is set and @code{IGNBRK} is not set, a break condition
484 clears the terminal input and output queues and raises a @code{SIGINT}
485 signal for the foreground process group associated with the terminal.
486
487 If neither @code{BRKINT} nor @code{IGNBRK} are set, a break condition is
488 passed to the application as a single @code{'\0'} character if
489 @code{PARMRK} is not set, or otherwise as a three-character sequence 
490 @code{'\377'}, @code{'\0'}, @code{'\0'}.
491 @end deftypevr
492
493 @comment termios.h
494 @comment POSIX.1
495 @deftypevr Macro tcflag_t IGNCR
496 If this bit is set, carriage return characters (@code{'\r'}) are
497 discarded on input.  Discarding carriage return may be useful on
498 terminals that send both carriage return and linefeed when you type the
499 @key{RET} key.
500 @end deftypevr
501
502 @comment termios.h
503 @comment POSIX.1
504 @deftypevr Macro tcflag_t ICRNL
505 If this bit is set and @code{IGNCR} is not set, carriage return characters
506 (@code{'\r'}) received as input are passed to the application as newline
507 characters (@code{'\n'}).
508 @end deftypevr
509
510 @comment termios.h
511 @comment POSIX.1
512 @deftypevr Macro tcflag_t INLCR
513 If this bit is set, newline characters (@code{'\n'}) received as input
514 are passed to the application as carriage return characters (@code{'\r'}).
515 @end deftypevr
516
517 @comment termios.h
518 @comment POSIX.1
519 @deftypevr Macro tcflag_t IXOFF
520 If this bit is set, start/stop control on input is enabled.  In other
521 words, the computer sends STOP and START characters as necessary to
522 prevent input from coming in faster than programs are reading it.  The
523 idea is that the actual terminal hardware that is generating the input
524 data responds to a STOP character by suspending transmission, and to a
525 START character by resuming transmission.  @xref{Start/Stop Characters}.
526 @end deftypevr
527
528 @comment termios.h
529 @comment POSIX.1
530 @deftypevr Macro tcflag_t IXON
531 If this bit is set, start/stop control on output is enabled.  In other
532 words, if the computer receives a STOP character, it suspends output
533 until a START character is received.  In this case, the STOP and START
534 characters are never passed to the application program.  If this bit is
535 not set, then START and STOP can be read as ordinary characters.
536 @xref{Start/Stop Characters}.
537 @c !!! mention this interferes with using C-s and C-q for programs like emacs
538 @end deftypevr
539
540 @comment termios.h
541 @comment BSD
542 @deftypevr Macro tcflag_t IXANY
543 If this bit is set, any input character restarts output when output has
544 been suspended with the STOP character.  Otherwise, only the START
545 character restarts output.
546
547 This is a BSD extension; it exists only on BSD systems and the GNU system.
548 @end deftypevr
549
550 @comment termios.h
551 @comment BSD
552 @deftypevr Macro tcflag_t IMAXBEL
553 If this bit is set, then filling up the terminal input buffer sends a
554 BEL character (code @code{007}) to the terminal to ring the bell.
555
556 This is a BSD extension.
557 @end deftypevr
558
559 @node Output Modes
560 @subsection Output Modes
561
562 This section describes the terminal flags and fields that control how
563 output characters are translated and padded for display.  All of these
564 are contained in the @code{c_oflag} member of the @w{@code{struct termios}}
565 structure.
566
567 The @code{c_oflag} member itself is an integer, and you change the flags
568 and fields using the operators @code{&}, @code{|}, and @code{^}.  Don't
569 try to specify the entire value for @code{c_oflag}---instead, change
570 only specific flags and leave the rest untouched (@pxref{Setting
571 Modes}).
572
573 @comment termios.h
574 @comment POSIX.1
575 @deftypevr Macro tcflag_t OPOST
576 If this bit is set, output data is processed in some unspecified way so
577 that it is displayed appropriately on the terminal device.  This
578 typically includes mapping newline characters (@code{'\n'}) onto
579 carriage return and linefeed pairs.
580
581 If this bit isn't set, the characters are transmitted as-is.
582 @end deftypevr
583
584 The following three bits are BSD features, and they exist only BSD
585 systems and the GNU system.  They are effective only if @code{OPOST} is
586 set.
587
588 @comment termios.h
589 @comment BSD
590 @deftypevr Macro tcflag_t ONLCR
591 If this bit is set, convert the newline character on output into a pair
592 of characters, carriage return followed by linefeed.
593 @end deftypevr
594
595 @comment termios.h
596 @comment BSD
597 @deftypevr Macro tcflag_t OXTABS
598 If this bit is set, convert tab characters on output into the appropriate
599 number of spaces to emulate a tab stop every eight columns.
600 @end deftypevr
601
602 @comment termios.h
603 @comment BSD
604 @deftypevr Macro tcflag_t ONOEOT
605 If this bit is set, discard @kbd{C-d} characters (code @code{004}) on
606 output.  These characters cause many dial-up terminals to disconnect.
607 @end deftypevr
608
609 @node Control Modes
610 @subsection Control Modes
611
612 This section describes the terminal flags and fields that control
613 parameters usually associated with asynchronous serial data
614 transmission.  These flags may not make sense for other kinds of
615 terminal ports (such as a network connection pseudo-terminal).  All of
616 these are contained in the @code{c_cflag} member of the @code{struct
617 termios} structure.
618
619 The @code{c_cflag} member itself is an integer, and you change the flags
620 and fields using the operators @code{&}, @code{|}, and @code{^}.  Don't
621 try to specify the entire value for @code{c_cflag}---instead, change
622 only specific flags and leave the rest untouched (@pxref{Setting
623 Modes}).
624
625 @comment termios.h
626 @comment POSIX.1
627 @deftypevr Macro tcflag_t CLOCAL
628 If this bit is set, it indicates that the terminal is connected
629 ``locally'' and that the modem status lines (such as carrier detect)
630 should be ignored.
631 @cindex modem status lines
632 @cindex carrier detect
633
634 On many systems if this bit is not set and you call @code{open} without
635 the @code{O_NONBLOCK} flag set, @code{open} blocks until a modem
636 connection is established.
637
638 If this bit is not set and a modem disconnect is detected, a
639 @code{SIGHUP} signal is sent to the controlling process group for the
640 terminal (if it has one).  Normally, this causes the process to exit;
641 see @ref{Signal Handling}.  Reading from the terminal after a disconnect
642 causes an end-of-file condition, and writing causes an @code{EIO} error
643 to be returned.  The terminal device must be closed and reopened to
644 clear the condition.
645 @cindex modem disconnect
646 @end deftypevr
647
648 @comment termios.h
649 @comment POSIX.1
650 @deftypevr Macro tcflag_t HUPCL
651 If this bit is set, a modem disconnect is generated when all processes
652 that have the terminal device open have either closed the file or exited.
653 @end deftypevr
654
655 @comment termios.h
656 @comment POSIX.1
657 @deftypevr Macro tcflag_t CREAD
658 If this bit is set, input can be read from the terminal.  Otherwise,
659 input is discarded when it arrives.
660 @end deftypevr
661
662 @comment termios.h
663 @comment POSIX.1
664 @deftypevr Macro tcflag_t CSTOPB
665 If this bit is set, two stop bits are used.  Otherwise, only one stop bit
666 is used.
667 @end deftypevr
668
669 @comment termios.h
670 @comment POSIX.1
671 @deftypevr Macro tcflag_t PARENB
672 If this bit is set, generation and detection of a parity bit are enabled.
673 @xref{Input Modes}, for information on how input parity errors are handled.
674
675 If this bit is not set, no parity bit is added to output characters, and
676 input characters are not checked for correct parity.
677 @end deftypevr
678
679 @comment termios.h
680 @comment POSIX.1
681 @deftypevr Macro tcflag_t PARODD
682 This bit is only useful if @code{PARENB} is set.  If @code{PARODD} is set,
683 odd parity is used, otherwise even parity is used.
684 @end deftypevr
685
686 The control mode flags also includes a field for the number of bits per
687 character.  You can use the @code{CSIZE} macro as a mask to extract the
688 value, like this: @code{settings.c_cflag & CSIZE}.
689
690 @comment termios.h
691 @comment POSIX.1
692 @deftypevr Macro tcflag_t CSIZE
693 This is a mask for the number of bits per character.
694 @end deftypevr
695
696 @comment termios.h
697 @comment POSIX.1
698 @deftypevr Macro tcflag_t CS5
699 This specifies five bits per byte.
700 @end deftypevr
701
702 @comment termios.h
703 @comment POSIX.1
704 @deftypevr Macro tcflag_t CS6
705 This specifies six bits per byte.
706 @end deftypevr
707
708 @comment termios.h
709 @comment POSIX.1
710 @deftypevr Macro tcflag_t CS7
711 This specifies seven bits per byte.
712 @end deftypevr
713
714 @comment termios.h
715 @comment POSIX.1
716 @deftypevr Macro tcflag_t CS8
717 This specifies eight bits per byte.
718 @end deftypevr
719
720 The following four bits are BSD extensions; this exist only on BSD
721 systems and the GNU system.
722
723 @comment termios.h
724 @comment BSD
725 @deftypevr Macro tcflag_t CCTS_OFLOW
726 If this bit is set, enable flow control of output based on the CTS wire
727 (RS232 protocol).
728 @end deftypevr
729
730 @comment termios.h
731 @comment BSD
732 @deftypevr Macro tcflag_t CRTS_IFLOW
733 If this bit is set, enable flow control of input based on the RTS wire
734 (RS232 protocol).
735 @end deftypevr
736
737 @comment termios.h
738 @comment BSD
739 @deftypevr Macro tcflag_t MDMBUF
740 If this bit is set, enable carrier-based flow control of output.
741 @end deftypevr
742
743 @comment termios.h
744 @comment BSD
745 @deftypevr Macro tcflag_t CIGNORE
746 If this bit is set, it says to ignore the control modes and line speed
747 values entirely.  This is only meaningful in a call to @code{tcsetattr}.
748
749 The @code{c_cflag} member and the line speed values returned by
750 @code{cfgetispeed} and @code{cfgetospeed} will be unaffected by the
751 call.  @code{CIGNORE} is useful if you want to set all the software
752 modes in the other members, but leave the hardware details in
753 @code{c_cflag} unchanged.  (This is how the @code{TCSASOFT} flag to
754 @code{tcsettattr} works.)
755
756 This bit is never set in the structure filled in by @code{tcgetattr}.
757 @end deftypevr
758
759 @node Local Modes
760 @subsection Local Modes
761
762 This section describes the flags for the @code{c_lflag} member of the
763 @code{struct termios} structure.  These flags generally control
764 higher-level aspects of input processing than the input modes flags
765 described in @ref{Input Modes}, such as echoing, signals, and the choice
766 of canonical or noncanonical input.
767
768 The @code{c_lflag} member itself is an integer, and you change the flags
769 and fields using the operators @code{&}, @code{|}, and @code{^}.  Don't
770 try to specify the entire value for @code{c_lflag}---instead, change
771 only specific flags and leave the rest untouched (@pxref{Setting
772 Modes}).
773
774 @comment termios.h
775 @comment POSIX.1
776 @deftypevr Macro tcflag_t ICANON
777 This bit, if set, enables canonical input processing mode.  Otherwise,
778 input is processed in noncanonical mode.  @xref{Canonical or Not}.
779 @end deftypevr
780
781 @comment termios.h
782 @comment POSIX.1
783 @deftypevr Macro tcflag_t ECHO
784 If this bit is set, echoing of input characters back to the terminal
785 is enabled.
786 @cindex echo of terminal input
787 @end deftypevr
788
789 @comment termios.h
790 @comment POSIX.1
791 @deftypevr Macro tcflag_t ECHOE
792 If this bit is set, echoing indicates erasure of input with the ERASE
793 character by erasing the last character in the current line from the
794 screen.  Otherwise, the character erased is re-echoed to show what has
795 happened (suitable for a printing terminal).
796
797 This bit only controls the display behavior; the @code{ICANON} bit by
798 itself controls actual recognition of the ERASE character and erasure of
799 input, without which @code{ECHOE} is simply irrelevant.
800 @end deftypevr
801
802 @comment termios.h
803 @comment BSD
804 @deftypevr Macro tcflag_t ECHOPRT
805 This bit is like @code{ECHOE}, enables display of the ERASE character in
806 a way that is geared to a hardcopy terminal.  When you type the ERASE
807 character, a @samp{\} character is printed followed by the first
808 character erased.  Typing the ERASE character again just prints the next
809 character erased.  Then, the next time you type a normal character, a
810 @samp{/} character is printed before the character echoes.
811
812 This is a BSD extension, and exists only in BSD systems and the
813 GNU system.
814 @end deftypevr
815
816 @comment termios.h
817 @comment POSIX.1
818 @deftypevr Macro tcflag_t ECHOK
819 This bit enables special display of the KILL character by moving to a
820 new line after echoing the KILL character normally.  The behavior of
821 @code{ECHOKE} (below) is nicer to look at.
822
823 If this bit is not set, the KILL character echoes just as it would if it
824 were not the KILL character.  Then it is up to the user to remember that
825 the KILL character has erased the preceding input; there is no
826 indication of this on the screen.
827
828 This bit only controls the display behavior; the @code{ICANON} bit by
829 itself controls actual recognition of the KILL character and erasure of
830 input, without which @code{ECHOK} is simply irrelevant.
831 @end deftypevr
832
833 @comment termios.h
834 @comment BSD
835 @deftypevr Macro tcflag_t ECHOKE
836 This bit is similar to @code{ECHOK}.  It enables special display of the
837 KILL character by erasing on the screen the entire line that has been
838 killed.  This is a BSD extension, and exists only in BSD systems and the
839 GNU system.
840 @end deftypevr
841
842 @comment termios.h
843 @comment POSIX.1
844 @deftypevr Macro tcflag_t ECHONL
845 If this bit is set and the @code{ICANON} bit is also set, then the
846 newline (@code{'\n'}) character is echoed even if the @code{ECHO} bit
847 is not set.
848 @end deftypevr
849
850 @comment termios.h
851 @comment BSD
852 @deftypevr Macro tcflag_t ECHOCTL
853 If this bit is set and the @code{ECHO} bit is also set, echo control
854 characters with @samp{^} followed by the corresponding text character.
855 Thus, control-A echoes as @samp{^A}.  This is usually the preferred mode
856 for interactive input, because echoing a control character back to the
857 terminal could have some undesired effect on the terminal.
858
859 This is a BSD extension, and exists only in BSD systems and the
860 GNU system.
861 @end deftypevr
862
863 @comment termios.h
864 @comment POSIX.1
865 @deftypevr Macro tcflag_t ISIG
866 This bit controls whether the INTR, QUIT, and SUSP characters are
867 recognized.  The functions associated with these characters are performed
868 if and only if this bit is set.  Being in canonical or noncanonical
869 input mode has no affect on the interpretation of these characters.
870
871 You should use caution when disabling recognition of these characters.
872 Programs that cannot be interrupted interactively are very
873 user-unfriendly.  If you clear this bit, your program should provide
874 some alternate interface that allows the user to interactively send the
875 signals associated with these characters, or to escape from the program.
876 @cindex interactive signals, from terminal
877
878 @xref{Signal Characters}.
879 @end deftypevr
880
881 @comment termios.h
882 @comment POSIX.1
883 @deftypevr Macro tcflag_t IEXTEN
884 POSIX.1 gives @code{IEXTEN} implementation-defined meaning,
885 so you cannot rely on this interpretation on all systems.
886
887 On BSD systems and the GNU system, it enables the LNEXT and DISCARD characters.
888 @xref{Other Special}.
889 @end deftypevr
890
891 @comment termios.h
892 @comment POSIX.1
893 @deftypevr Macro tcflag_t NOFLSH
894 Normally, the INTR, QUIT, and SUSP characters cause input and output
895 queues for the terminal to be cleared.  If this bit is set, the queues
896 are not cleared.
897 @end deftypevr
898
899 @comment termios.h
900 @comment POSIX.1
901 @deftypevr Macro tcflag_t TOSTOP
902 If this bit is set and the system supports job control, then
903 @code{SIGTTOU} signals are generated by background processes that
904 attempt to write to the terminal.  @xref{Access to the Terminal}.
905 @end deftypevr
906
907 The following bits are BSD extensions; they exist only in BSD systems
908 and the GNU system.
909      
910 @comment termios.h
911 @comment BSD
912 @deftypevr Macro tcflag_t ALTWERASE
913 This bit determines how far the WERASE character should erase.  The
914 WERASE character erases back to the beginning of a word; the question
915 is, where do words begin?
916
917 If this bit is clear, then the beginning of a word is a nonwhitespace
918 character following a whitespace character.  If the bit is set, then the
919 beginning of a word is an alphanumeric character or underscore following
920 a character which is none of those.
921
922 @xref{Editing Characters}, for more information about the WERASE character.
923 @end deftypevr
924
925 @comment termios.h
926 @comment BSD
927 @deftypevr Macro tcflag_t FLUSHO
928 This is the bit that toggles when the user types the DISCARD character.
929 While this bit is set, all output is discarded.  @xref{Other Special}.
930 @end deftypevr
931
932 @comment termios.h
933 @comment BSD
934 @deftypevr Macro tcflag_t NOKERNINFO
935 Setting this bit disables handling of the STATUS character.
936 @xref{Other Special}.
937 @end deftypevr
938
939 @comment termios.h
940 @comment BSD
941 @deftypevr Macro tcflag_t PENDIN
942 If this bit is set, it indicates that there is a line of input that
943 needs to be reprinted.  Typing the REPRINT character sets this bit; the
944 bit remains set until reprinting is finished.  @xref{Editing Characters}.
945 @end deftypevr
946
947 @c EXTPROC is too obscure to document now.  --roland
948
949 @node Line Speed
950 @subsection Line Speed
951 @cindex line speed
952 @cindex baud rate
953 @cindex terminal line speed
954 @cindex terminal line speed
955
956 The terminal line speed tells the computer how fast to read and write
957 data on the terminal.
958
959 If the terminal is connected to a real serial line, the terminal speed
960 you specify actually controls the line---if it doesn't match the
961 terminal's own idea of the speed, communication does not work.  Real
962 serial ports accept only certain standard speeds.  Also, particular
963 hardware may not support even all the standard speeds.  Specifying a
964 speed of zero hangs up a dialup connection and turns off modem control
965 signals.
966
967 If the terminal is not a real serial line (for example, if it is a
968 network connection), then the line speed won't really affect data
969 transmission speed, but some programs will use it to determine the
970 amount of padding needed.  It's best to specify a line speed value that
971 matches the actual speed of the actual terminal, but you can safely
972 experiment with different values to vary the amount of padding.
973
974 There are actually two line speeds for each terminal, one for input and
975 one for output.  You can set them independently, but most often
976 terminals use the same speed for both directions.
977
978 The speed values are stored in the @code{struct termios} structure, but
979 don't try to access them in the @code{struct termios} structure
980 directly.  Instead, you should use the following functions to read and
981 store them:
982
983 @comment termios.h
984 @comment POSIX.1
985 @deftypefun speed_t cfgetospeed (const struct termios *@var{termios-p})
986 This function returns the output line speed stored in the structure
987 @code{*@var{termios-p}}.
988 @end deftypefun
989
990 @comment termios.h
991 @comment POSIX.1
992 @deftypefun speed_t cfgetispeed (const struct termios *@var{termios-p})
993 This function returns the input line speed stored in the structure
994 @code{*@var{termios-p}}.
995 @end deftypefun
996
997 @comment termios.h
998 @comment POSIX.1
999 @deftypefun int cfsetospeed (struct termios *@var{termios-p}, speed_t @var{speed})
1000 This function stores @var{speed} in @code{*@var{termios-p}} as the output
1001 speed.  The normal return value is @code{0}; a value of @code{-1}
1002 indicates an error.  If @var{speed} is not a speed, @code{cfsetospeed}
1003 returns @code{-1}.
1004 @end deftypefun
1005
1006 @comment termios.h
1007 @comment POSIX.1
1008 @deftypefun int cfsetispeed (struct termios *@var{termios-p}, speed_t @var{speed})
1009 This function stores @var{speed} in @code{*@var{termios-p}} as the input
1010 speed.  The normal return value is @code{0}; a value of @code{-1}
1011 indicates an error.  If @var{speed} is not a speed, @code{cfsetospeed}
1012 returns @code{-1}.
1013 @end deftypefun
1014
1015 @comment termios.h
1016 @comment BSD
1017 @deftypefun int cfsetspeed (struct termios *@var{termios-p}, speed_t @var{speed})
1018 This function stores @var{speed} in @code{*@var{termios-p}} as both the
1019 input and output speeds.  The normal return value is @code{0}; a value
1020 of @code{-1} indicates an error.  If @var{speed} is not a speed,
1021 @code{cfsetspeed} returns @code{-1}.  This function is an extension in
1022 4.4 BSD.
1023 @end deftypefun
1024
1025 @comment termios.h
1026 @comment POSIX.1
1027 @deftp {Data Type} speed_t
1028 The @code{speed_t} type is an unsigned integer data type used to
1029 represent line speeds.
1030 @end deftp
1031
1032 The functions @code{cfsetospeed} and @code{cfsetispeed} report errors
1033 only for speed values that the system simply cannot handle.  If you
1034 specify a speed value that is basically acceptable, then those functions
1035 will succeed.  But they do not check that a particular hardware device
1036 can actually support the specified speeds---in fact, they don't know
1037 which device you plan to set the speed for.  If you use @code{tcsetattr}
1038 to set the speed of a particular device to a value that it cannot
1039 handle, @code{tcsetattr} returns @code{-1}.
1040
1041 @strong{Portability note:} In the GNU library, the functions above
1042 accept speeds measured in bits per second as input, and return speed
1043 values measured in bits per second.  Other libraries require speeds to
1044 be indicated by special codes.  For POSIX.1 portability, you must use
1045 one of the following symbols to represent the speed; their precise
1046 numeric values are system-dependent, but each name has a fixed meaning:
1047 @code{B110} stands for 110 bps, @code{B300} for 300 bps, and so on.
1048 There is no portable way to represent any speed but these, but these are
1049 the only speeds that typical serial lines can support.
1050
1051 @comment termios.h
1052 @comment POSIX.1
1053 @vindex B0
1054 @comment termios.h
1055 @comment POSIX.1
1056 @vindex B50
1057 @comment termios.h
1058 @comment POSIX.1
1059 @vindex B75
1060 @comment termios.h
1061 @comment POSIX.1
1062 @vindex B110
1063 @comment termios.h
1064 @comment POSIX.1
1065 @vindex B134
1066 @comment termios.h
1067 @comment POSIX.1
1068 @vindex B150
1069 @comment termios.h
1070 @comment POSIX.1
1071 @vindex B200
1072 @comment termios.h
1073 @comment POSIX.1
1074 @vindex B300
1075 @comment termios.h
1076 @comment POSIX.1
1077 @vindex B600
1078 @comment termios.h
1079 @comment POSIX.1
1080 @vindex B1200
1081 @comment termios.h
1082 @comment POSIX.1
1083 @vindex B1800
1084 @comment termios.h
1085 @comment POSIX.1
1086 @vindex B2400
1087 @comment termios.h
1088 @comment POSIX.1
1089 @vindex B4800
1090 @comment termios.h
1091 @comment POSIX.1
1092 @vindex B9600
1093 @comment termios.h
1094 @comment POSIX.1
1095 @vindex B19200
1096 @comment termios.h
1097 @comment POSIX.1
1098 @vindex B38400
1099 @smallexample
1100 B0  B50  B75  B110  B134  B150  B200
1101 B300  B600  B1200  B1800  B2400  B4800
1102 B9600  B19200  B38400
1103 @end smallexample
1104
1105 @vindex EXTA
1106 @vindex EXTB
1107 BSD defines two additional speed symbols as aliases: @code{EXTA} is an
1108 alias for @code{B19200} and @code{EXTB} is an alias for @code{B38400}.
1109 These aliases are obsolete.
1110
1111 @node Special Characters
1112 @subsection Special Characters
1113
1114 In canonical input, the terminal driver recognizes a number of special
1115 characters which perform various control functions.  These include the
1116 ERASE character (usually @key{DEL}) for editing input, and other editing
1117 characters.  The INTR character (normally @kbd{C-c}) for sending a
1118 @code{SIGINT} signal, and other signal-raising characters, may be
1119 available in either canonical or noncanonical input mode.  All these
1120 characters are described in this section.
1121
1122 The particular characters used are specified in the @code{c_cc} member
1123 of the @code{struct termios} structure.  This member is an array; each
1124 element specifies the character for a particular role.  Each element has
1125 a symbolic constant that stands for the index of that element---for
1126 example, @code{INTR} is the index of the element that specifies the INTR
1127 character, so storing @code{'='} in @code{@var{termios}.c_cc[INTR]}
1128 specifies @samp{=} as the INTR character.
1129
1130 @vindex _POSIX_VDISABLE
1131 On some systems, you can disable a particular special character function
1132 by specifying the value @code{_POSIX_VDISABLE} for that role.  This
1133 value is unequal to any possible character code.  @xref{Options for
1134 Files}, for more information about how to tell whether the operating
1135 system you are using supports @code{_POSIX_VDISABLE}.
1136
1137 @menu
1138 * Editing Characters::          Special characters that terminate lines and
1139                                   delete text, and other editing functions.
1140 * Signal Characters::           Special characters that send or raise signals
1141                                   to or for certain classes of processes.
1142 * Start/Stop Characters::       Special characters that suspend or resume
1143                                   suspended output.
1144 * Other Special::               Other special characters for BSD systems:
1145                                   they can discard output, and print status.
1146 @end menu
1147
1148 @node Editing Characters
1149 @subsubsection Characters for Input Editing
1150
1151 These special characters are active only in canonical input mode.
1152 @xref{Canonical or Not}.
1153
1154 @comment termios.h
1155 @comment POSIX.1
1156 @deftypevr Macro int VEOF
1157 @cindex EOF character
1158 This is the subscript for the EOF character in the special control
1159 character array.  @code{@var{termios}.c_cc[VEOF]} holds the character
1160 itself.
1161
1162 The EOF character is recognized only in canonical input mode.  It acts
1163 as a line terminator in the same way as a newline character, but if the
1164 EOF character is typed at the beginning of a line it causes @code{read}
1165 to return a byte count of zero, indicating end-of-file.  The EOF
1166 character itself is discarded.
1167
1168 Usually, the EOF character is @kbd{C-d}.
1169 @end deftypevr
1170
1171 @comment termios.h
1172 @comment POSIX.1
1173 @deftypevr Macro int VEOL
1174 @cindex EOL character
1175 This is the subscript for the EOL character in the special control
1176 character array.  @code{@var{termios}.c_cc[VEOL]} holds the character
1177 itself.
1178
1179 The EOL character is recognized only in canonical input mode.  It acts
1180 as a line terminator, just like a newline character.  The EOL character
1181 is not discarded; it is read as the last character in the input line.
1182
1183 @c !!! example: this is set to ESC by 4.3 csh with "set filec" so it can
1184 @c complete partial lines without using cbreak or raw mode.
1185
1186 You don't need to use the EOL character to make @key{RET} end a line.
1187 Just set the ICRNL flag.  In fact, this is the default state of
1188 affairs.
1189 @end deftypevr
1190
1191 @comment termios.h
1192 @comment BSD
1193 @deftypevr Macro int VEOL2
1194 @cindex EOL2 character
1195 This is the subscript for the EOL2 character in the special control
1196 character array.  @code{@var{termios}.c_cc[VEOL2]} holds the character
1197 itself.
1198
1199 The EOL2 character works just like the EOL character (see above), but it
1200 can be a different character.  Thus, you can specify two characters to
1201 terminate an input line, by setting EOL to one of them and EOL2 to the
1202 other.
1203
1204 The EOL2 character is a BSD extension; it exists only on BSD systems
1205 and the GNU system.
1206 @end deftypevr
1207
1208 @comment termios.h
1209 @comment POSIX.1
1210 @deftypevr Macro int VERASE
1211 @cindex ERASE character
1212 This is the subscript for the ERASE character in the special control
1213 character array.  @code{@var{termios}.c_cc[VERASE]} holds the
1214 character itself.
1215
1216 The ERASE character is recognized only in canonical input mode.  When
1217 the user types the erase character, the previous character typed is
1218 discarded.  (If the terminal generates multibyte character sequences,
1219 this may cause more than one byte of input to be discarded.)  This
1220 cannot be used to erase past the beginning of the current line of text.
1221 The ERASE character itself is discarded.
1222 @c !!! mention ECHOE here
1223
1224 Usually, the ERASE character is @key{DEL}.
1225 @end deftypevr
1226
1227 @comment termios.h
1228 @comment BSD
1229 @deftypevr Macro int VWERASE
1230 @cindex WERASE character
1231 This is the subscript for the WERASE character in the special control
1232 character array.  @code{@var{termios}.c_cc[VWERASE]} holds the character
1233 itself.
1234
1235 The WERASE character is recognized only in canonical mode.  It erases an
1236 entire word of prior input, and any whitespace after it; whitespace
1237 characters before the word are not erased.
1238
1239 The definition of a ``word'' depends on the setting of the
1240 @code{ALTWERASE} mode; @pxref{Local Modes}.
1241
1242 If the @code{ALTWERASE} mode is not set, a word is defined as a sequence
1243 of any characters except space or tab.
1244
1245 If the @code{ALTWERASE} mode is set, a word is defined as a sequence of
1246 characters containing only letters, numbers, and underscores, optionally
1247 followed by one character that is not a letter, number, or underscore.
1248
1249 The WERASE character is usually @kbd{C-w}.
1250
1251 This is a BSD extension.
1252 @end deftypevr
1253
1254 @comment termios.h
1255 @comment POSIX.1
1256 @deftypevr Macro int VKILL
1257 @cindex KILL character
1258 This is the subscript for the KILL character in the special control
1259 character array.  @code{@var{termios}.c_cc[VKILL]} holds the character
1260 itself.
1261
1262 The KILL character is recognized only in canonical input mode.  When the
1263 user types the kill character, the entire contents of the current line
1264 of input are discarded.  The kill character itself is discarded too.
1265
1266 The KILL character is usually @kbd{C-u}.
1267 @end deftypevr
1268
1269 @comment termios.h
1270 @comment BSD
1271 @deftypevr Macro int VREPRINT
1272 @cindex REPRINT character
1273 This is the subscript for the REPRINT character in the special control
1274 character array.  @code{@var{termios}.c_cc[VREPRINT]} holds the character
1275 itself.
1276
1277 The REPRINT character is recognized only in canonical mode.  It reprints
1278 the current input line.  If some asynchronous output has come while you
1279 are typing, this lets you see the line you are typing clearly again.
1280
1281 The REPRINT character is usually @kbd{C-r}.
1282
1283 This is a BSD extension.
1284 @end deftypevr
1285
1286 @node Signal Characters
1287 @subsubsection Characters that Cause Signals
1288
1289 These special characters may be active in either canonical or noncanonical
1290 input mode, but only when the @code{ISIG} flag is set (@pxref{Local
1291 Modes}).
1292
1293 @comment termios.h
1294 @comment POSIX.1
1295 @deftypevr Macro int VINTR
1296 @cindex INTR character
1297 @cindex interrupt character
1298 This is the subscript for the INTR character in the special control
1299 character array.  @code{@var{termios}.c_cc[VINTR]} holds the character
1300 itself.
1301
1302 The INTR (interrupt) character raises a @code{SIGINT} signal for all
1303 processes in the foreground job associated with the terminal.  The INTR
1304 character itself is then discarded.  @xref{Signal Handling}, for more
1305 information about signals.
1306
1307 Typically, the INTR character is @kbd{C-c}.
1308 @end deftypevr
1309
1310 @comment termios.h
1311 @comment POSIX.1
1312 @deftypevr Macro int VQUIT
1313 @cindex QUIT character
1314 This is the subscript for the QUIT character in the special control
1315 character array.  @code{@var{termios}.c_cc[VQUIT]} holds the character
1316 itself.
1317
1318 The QUIT character raises a @code{SIGQUIT} signal for all processes in
1319 the foreground job associated with the terminal.  The QUIT character
1320 itself is then discarded.  @xref{Signal Handling}, for more information
1321 about signals.
1322
1323 Typically, the QUIT character is @kbd{C-\}.
1324 @end deftypevr
1325
1326 @comment termios.h
1327 @comment POSIX.1
1328 @deftypevr Macro int VSUSP
1329 @cindex SUSP character
1330 @cindex suspend character
1331 This is the subscript for the SUSP character in the special control
1332 character array.  @code{@var{termios}.c_cc[VSUSP]} holds the character
1333 itself.
1334
1335 The SUSP (suspend) character is recognized only if the implementation
1336 supports job control (@pxref{Job Control}).  It causes a @code{SIGTSTP}
1337 signal to be sent to all processes in the foreground job associated with
1338 the terminal.  The SUSP character itself is then discarded.
1339 @xref{Signal Handling}, for more information about signals.
1340
1341 Typically, the SUSP character is @kbd{C-z}.
1342 @end deftypevr
1343
1344 Few applications disable the normal interpretation of the SUSP
1345 character.  If your program does this, it should provide some other
1346 mechanism for the user to stop the job.  When the user invokes this
1347 mechanism, the program should send a @code{SIGTSTP} signal to the
1348 process group of the process, not just to the process itself.
1349 @xref{Signaling Another Process}.
1350
1351 @comment termios.h
1352 @comment BSD
1353 @deftypevr Macro int VDSUSP
1354 @cindex DSUSP character
1355 @cindex delayed suspend character
1356 This is the subscript for the DSUSP character in the special control
1357 character array.  @code{@var{termios}.c_cc[VDSUSP]} holds the character
1358 itself.
1359
1360 The DSUSP (suspend) character is recognized only if the implementation
1361 supports job control (@pxref{Job Control}).  It sends a @code{SIGTSTP}
1362 signal, like the SUSP character, but not right away---only when the
1363 program tries to read it as input.  Not all systems with job control
1364 support DSUSP; only BSD-compatible systems (including the GNU system).
1365
1366 @xref{Signal Handling}, for more information about signals.
1367
1368 Typically, the DSUSP character is @kbd{C-y}.
1369 @end deftypevr
1370
1371 @node Start/Stop Characters
1372 @subsubsection Special Characters for Flow Control
1373
1374 These special characters may be active in either canonical or noncanonical
1375 input mode, but their use is controlled by the flags @code{IXON} and
1376 @code{IXOFF} (@pxref{Input Modes}).
1377
1378 @comment termios.h
1379 @comment POSIX.1
1380 @deftypevr Macro int VSTART
1381 @cindex START character
1382 This is the subscript for the START character in the special control
1383 character array.  @code{@var{termios}.c_cc[VSTART]} holds the
1384 character itself.
1385
1386 The START character is used to support the @code{IXON} and @code{IXOFF}
1387 input modes.  If @code{IXON} is set, receiving a START character resumes
1388 suspended output; the START character itself is discarded.  If
1389 @code{IXANY} is set, receiving any character at all resumes suspended
1390 output; the resuming character is not discarded unless it is the START
1391 character.  @code{IXOFF} is set, the system may also transmit START
1392 characters to the terminal.
1393
1394 The usual value for the START character is @kbd{C-q}.  You may not be
1395 able to change this value---the hardware may insist on using @kbd{C-q}
1396 regardless of what you specify.
1397 @end deftypevr
1398
1399 @comment termios.h
1400 @comment POSIX.1
1401 @deftypevr Macro int VSTOP
1402 @cindex STOP character
1403 This is the subscript for the STOP character in the special control
1404 character array.  @code{@var{termios}.c_cc[VSTOP]} holds the character
1405 itself.
1406
1407 The STOP character is used to support the @code{IXON} and @code{IXOFF}
1408 input modes.  If @code{IXON} is set, receiving a STOP character causes
1409 output to be suspended; the STOP character itself is discarded.  If
1410 @code{IXOFF} is set, the system may also transmit STOP characters to the
1411 terminal, to prevent the input queue from overflowing.
1412
1413 The usual value for the STOP character is @kbd{C-s}.  You may not be
1414 able to change this value---the hardware may insist on using @kbd{C-s}
1415 regardless of what you specify.
1416 @end deftypevr
1417
1418 @node Other Special
1419 @subsubsection Other Special Characters
1420
1421 These special characters exist only in BSD systems and the GNU system.
1422
1423 @comment termios.h
1424 @comment BSD
1425 @deftypevr Macro int VLNEXT
1426 @cindex LNEXT character
1427 This is the subscript for the LNEXT character in the special control
1428 character array.  @code{@var{termios}.c_cc[VLNEXT]} holds the character
1429 itself.
1430
1431 The LNEXT character is recognized only when @code{IEXTEN} is set, but in
1432 both canonical and noncanonical mode.  It disables any special
1433 significance of the next character the user types.  Even if the
1434 character would normally perform some editting function or generate a
1435 signal, it is read as a plain character.  This is the analogue of the
1436 @kbd{C-q} command in Emacs.  ``LNEXT'' stands for ``literal next.''
1437
1438 The LNEXT character is usually @kbd{C-v}.
1439 @end deftypevr
1440
1441 @comment termios.h
1442 @comment BSD
1443 @deftypevr Macro int VDISCARD
1444 @cindex DISCARD character
1445 This is the subscript for the DISCARD character in the special control
1446 character array.  @code{@var{termios}.c_cc[VDISCARD]} holds the character
1447 itself.
1448
1449 The DISCARD character is recognized only when @code{IEXTEN} is set, but
1450 in both canonical and noncanonical mode.  Its effect is to toggle the
1451 discard-output flag.  When this flag is set, all program output is
1452 discarded.  Setting the flag also discards all output currently in the
1453 output buffer.  Typing any other character resets the flag.
1454 @end deftypevr
1455
1456 @comment termios.h
1457 @comment BSD
1458 @deftypevr Macro int VSTATUS
1459 @cindex STATUS character
1460 This is the subscript for the STATUS character in the special control
1461 character array.  @code{@var{termios}.c_cc[VSTATUS]} holds the character
1462 itself.
1463
1464 The STATUS character's effect is to print out a status message about how
1465 the current process is running.
1466
1467 The STATUS character is recognized only in canonical mode, and only if
1468 @code{NOKERNINFO} is not set.
1469 @end deftypevr
1470
1471 @node Noncanonical Input
1472 @subsection Noncanonical Input
1473
1474 In noncanonical input mode, the special editing characters such as
1475 ERASE and KILL are ignored.  The system facilities for the user to edit
1476 input are disabled in noncanonical mode, so that all input characters
1477 (unless they are special for signal or flow-control purposes) are passed
1478 to the application program exactly as typed.  It is up to the
1479 application program to give the user ways to edit the input, if
1480 appropriate.
1481
1482 Noncanonical mode offers special parameters called MIN and TIME for
1483 controlling whether and how long to wait for input to be available.  You
1484 can even use them to avoid ever waiting---to return immediately with
1485 whatever input is available, or with no input.
1486
1487 The MIN and TIME are stored in elements of the @code{c_cc} array, which
1488 is a member of the @w{@code{struct termios}} structure.  Each element of
1489 this array has a particular role, and each element has a symbolic
1490 constant that stands for the index of that element.  @code{VMIN} and
1491 @code{VMAX} are the names for the indices in the array of the MIN and
1492 TIME slots.
1493
1494 @comment termios.h
1495 @comment POSIX.1
1496 @deftypevr Macro int VMIN
1497 @cindex MIN termios slot
1498 This is the subscript for the MIN slot in the @code{c_cc} array.  Thus,
1499 @code{@var{termios}.c_cc[VMIN]} is the value itself.
1500
1501 The MIN slot is only meaningful in noncanonical input mode; it
1502 specifies the minimum number of bytes that must be available in the
1503 input queue in order for @code{read} to return.
1504 @end deftypevr
1505
1506 @comment termios.h
1507 @comment POSIX.1
1508 @deftypevr Macro int VTIME
1509 @cindex TIME termios slot
1510 This is the subscript for the TIME slot in the @code{c_cc} array.  Thus,
1511 @code{@var{termios}.c_cc[VTIME]} is the value itself.
1512
1513 The TIME slot is only meaningful in noncanonical input mode; it
1514 specifies how long to wait for input before returning, in units of 0.1
1515 seconds.
1516 @end deftypevr
1517
1518 The MIN and TIME values interact to determine the criterion for when
1519 @code{read} should return; their precise meanings depend on which of
1520 them are nonzero.  There are four possible cases:
1521
1522 @itemize @bullet
1523 @item
1524 Both TIME and MIN are nonzero.
1525
1526 In this case, TIME specifies how long to wait after each input character
1527 to see if more input arrives.  After the first character received,
1528 @code{read} keeps waiting until either MIN bytes have arrived in all, or
1529 TIME elapses with no further input.
1530
1531 @code{read} always blocks until the first character arrives, even if
1532 TIME elapses first.  @code{read} can return more than MIN characters if
1533 more than MIN happen to be in the queue.
1534
1535 @item 
1536 Both MIN and TIME are zero.
1537
1538 In this case, @code{read} always returns immediately with as many
1539 characters as are available in the queue, up to the number requested.
1540 If no input is immediately available, @code{read} returns a value of
1541 zero.
1542
1543 @item
1544 MIN is zero but TIME has a nonzero value.
1545
1546 In this case, @code{read} waits for time TIME for input to become
1547 available; the availability of a single byte is enough to satisfy the
1548 read request and cause @code{read} to return.  When it returns, it
1549 returns as many characters as are available, up to the number requested.
1550 If no input is available before the timer expires, @code{read} returns a
1551 value of zero.
1552
1553 @item
1554 TIME is zero but MIN has a nonzero value.
1555
1556 In this case, @code{read} waits until at least MIN bytes are available
1557 in the queue.  At that time, @code{read} returns as many characters as
1558 are available, up to the number requested.  @code{read} can return more
1559 than MIN characters if more than MIN happen to be in the queue.
1560 @end itemize
1561
1562 What happens if MIN is 50 and you ask to read just 10 bytes?
1563 Normally, @code{read} waits until there are 50 bytes in the buffer (or,
1564 more generally, the wait condition described above is satisfied), and
1565 then reads 10 of them, leaving the other 40 buffered in the operating
1566 system for a subsequent call to @code{read}.
1567
1568 @strong{Portability note:} On some systems, the MIN and TIME slots are
1569 actually the same as the EOF and EOL slots.  This causes no serious
1570 problem because the MIN and TIME slots are used only in noncanonical
1571 input and the EOF and EOL slots are used only in canonical input, but it
1572 isn't very clean.  The GNU library allocates separate slots for these
1573 uses.
1574
1575 @comment termios.h
1576 @comment BSD
1577 @deftypefun int cfmakeraw (struct termios *@var{termios-p})
1578 This function provides an easy way to set up @code{*@var{termios-p}} for
1579 what has traditionally been called ``raw mode'' in BSD.  This uses
1580 noncanonical input, and turns off most processing to give an unmodified
1581 channel to the terminal.
1582
1583 It does exactly this:
1584 @smallexample
1585   @var{termios-p}->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
1586                                 |INLCR|IGNCR|ICRNL|IXON);
1587   @var{termios-p}->c_oflag &= ~OPOST;
1588   @var{termios-p}->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
1589   @var{termios-p}->c_cflag &= ~(CSIZE|PARENB);
1590   @var{termios-p}->c_cflag |= CS8;
1591 @end smallexample
1592 @end deftypefun
1593
1594 @node Line Control
1595 @section Line Control Functions
1596 @cindex terminal line control functions
1597
1598 These functions perform miscellaneous control actions on terminal
1599 devices.  As regards terminal access, they are treated like doing
1600 output: if any of these functions is used by a background process on its
1601 controlling terminal, normally all processes in the process group are
1602 sent a @code{SIGTTOU} signal.  The exception is if the calling process
1603 itself is ignoring or blocking @code{SIGTTOU} signals, in which case the
1604 operation is performed and no signal is sent.  @xref{Job Control}.
1605
1606 @cindex break condition, generating
1607 @comment termios.h
1608 @comment POSIX.1
1609 @deftypefun int tcsendbreak (int @var{filedes}, int @var{duration})
1610 This function generates a break condition by transmitting a stream of
1611 zero bits on the terminal associated with the file descriptor
1612 @var{filedes}.  The duration of the break is controlled by the
1613 @var{duration} argument.  If zero, the duration is between 0.25 and 0.5
1614 seconds.  The meaning of a nonzero value depends on the operating system.
1615
1616 This function does nothing if the terminal is not an asynchronous serial
1617 data port.
1618
1619 The return value is normally zero.  In the event of an error, a value
1620 of @code{-1} is returned.  The following @code{errno} error conditions
1621 are defined for this function:
1622
1623 @table @code
1624 @item EBADF
1625 The @var{filedes} is not a valid file descriptor.
1626
1627 @item ENOTTY
1628 The @var{filedes} is not associated with a terminal device.
1629 @end table
1630 @end deftypefun
1631
1632
1633 @cindex flushing terminal output queue
1634 @cindex terminal output queue, flushing
1635 @comment termios.h
1636 @comment POSIX.1
1637 @deftypefun int tcdrain (int @var{filedes})
1638 The @code{tcdrain} function waits until all queued
1639 output to the terminal @var{filedes} has been transmitted.
1640
1641 The return value is normally zero.  In the event of an error, a value
1642 of @code{-1} is returned.  The following @code{errno} error conditions
1643 are defined for this function:
1644
1645 @table @code
1646 @item EBADF
1647 The @var{filedes} is not a valid file descriptor.
1648
1649 @item ENOTTY
1650 The @var{filedes} is not associated with a terminal device.
1651
1652 @item EINTR
1653 The operation was interrupted by delivery of a signal.
1654 @xref{Interrupted Primitives}.
1655 @end table
1656 @end deftypefun
1657
1658
1659 @cindex clearing terminal input queue
1660 @cindex terminal input queue, clearing
1661 @comment termios.h
1662 @comment POSIX.1
1663 @deftypefun int tcflush (int @var{filedes}, int @var{queue})
1664 The @code{tcflush} function is used to clear the input and/or output
1665 queues associated with the terminal file @var{filedes}.  The @var{queue}
1666 argument specifies which queue(s) to clear, and can be one of the
1667 following values:
1668
1669 @c Extra blank lines here make it look better.
1670 @table @code
1671 @vindex TCIFLUSH
1672 @item TCIFLUSH
1673
1674 Clear any input data received, but not yet read.
1675
1676 @vindex TCOFLUSH
1677 @item TCOFLUSH
1678
1679 Clear any output data written, but not yet transmitted.
1680
1681 @vindex TCIOFLUSH
1682 @item TCIOFLUSH
1683
1684 Clear both queued input and output.
1685 @end table
1686
1687 The return value is normally zero.  In the event of an error, a value
1688 of @code{-1} is returned.  The following @code{errno} error conditions
1689 are defined for this function:
1690
1691 @table @code
1692 @item EBADF
1693 The @var{filedes} is not a valid file descriptor.
1694
1695 @item ENOTTY
1696 The @var{filedes} is not associated with a terminal device.
1697
1698 @item EINVAL
1699 A bad value was supplied as the @var{queue} argument.
1700 @end table
1701
1702 It is unfortunate that this function is named @code{tcflush}, because
1703 the term ``flush'' is normally used for quite another operation---waiting
1704 until all output is transmitted---and using it for discarding input or
1705 output would be confusing.  Unfortunately, the name @code{tcflush} comes
1706 from POSIX and we cannot change it.
1707 @end deftypefun
1708
1709 @cindex flow control, terminal
1710 @cindex terminal flow control
1711 @comment termios.h
1712 @comment POSIX.1
1713 @deftypefun int tcflow (int @var{filedes}, int @var{action})
1714 The @code{tcflow} function is used to perform operations relating to
1715 XON/XOFF flow control on the terminal file specified by @var{filedes}.
1716
1717 The @var{action} argument specifies what operation to perform, and can
1718 be one of the following values:
1719
1720 @table @code
1721 @vindex TCOOFF
1722 @item TCOOFF
1723 Suspend transmission of output.
1724
1725 @vindex TCOON
1726 @item TCOON
1727 Restart transmission of output.
1728
1729 @vindex TCIOFF
1730 @item TCIOFF
1731 Transmit a STOP character.
1732
1733 @vindex TCION
1734 @item TCION
1735 Transmit a START character.
1736 @end table
1737
1738 For more information about the STOP and START characters, see @ref{Special
1739 Characters}.
1740
1741 The return value is normally zero.  In the event of an error, a value
1742 of @code{-1} is returned.  The following @code{errno} error conditions
1743 are defined for this function:
1744
1745 @table @code
1746 @vindex EBADF
1747 @item EBADF
1748 The @var{filedes} is not a valid file descriptor.
1749
1750 @vindex ENOTTY
1751 @item ENOTTY
1752 The @var{filedes} is not associated with a terminal device.
1753
1754 @vindex EINVAL
1755 @item EINVAL
1756 A bad value was supplied as the @var{action} argument.
1757 @end table
1758 @end deftypefun
1759
1760 @node Noncanon Example
1761 @section Noncanonical Mode Example
1762
1763 Here is an example program that shows how you can set up a terminal
1764 device to read single characters in noncanonical input mode, without
1765 echo.
1766
1767 @smallexample
1768 @include termios.c.texi
1769 @end smallexample
1770
1771 This program is careful to restore the original terminal modes before
1772 exiting or terminating with a signal.  It uses the @code{atexit}
1773 function (@pxref{Cleanups on Exit}) to make sure this is done
1774 by @code{exit}.
1775
1776 @ignore
1777 @c !!!! the example doesn't handle any signals!
1778 The signals handled in the example are the ones that typically occur due
1779 to actions of the user.  It might be desirable to handle other signals
1780 such as SIGSEGV that can result from bugs in the program.
1781 @end ignore
1782
1783 The shell is supposed to take care of resetting the terminal modes when
1784 a process is stopped or continued; see @ref{Job Control}.  But some
1785 existing shells do not actually do this, so you may wish to establish
1786 handlers for job control signals that reset terminal modes.  The above
1787 example does so.