Major revisions
[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 Input/Output}, 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 * Indentifying Terminals::   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 * Terminal Modes::      How to examine and modify flags controlling
19                           details of terminal I/O: echoing, signals, editing.
20 * Line Control::        Sending break sequences, clearing terminal buffers...
21 * Terminal Example::    How to read single characters without echo.
22 @end menu
23
24 @node Identifying Terminals
25 @section Identifying Terminals
26 @cindex terminal identification
27 @cindex identifying terminals
28
29 The functions described in this chapter only work on files that
30 correspond to terminal devices.  You can find out whether a file
31 descriptor is associated with a terminal by using the @code{isatty}
32 function.
33
34 @pindex unistd.h
35 Prototypes for both @code{isatty} and @code{ttyname} are declared in
36 the header file @file{unistd.h}.
37
38 @comment unistd.h
39 @comment POSIX.1
40 @deftypefun int isatty (int @var{filedes})
41 This function returns @code{1} if @var{filedes} is a file descriptor
42 associated with an open terminal device, and @code{0} otherwise.
43 @end deftypefun
44
45 If a file descriptor is associated with a terminal, you can get its
46 associated file name using the @code{ttyname} function.  See also the
47 @code{ctermid} function, described in @ref{Controlling Terminal
48 Identification}.
49
50 @comment unistd.h
51 @comment POSIX.1
52 @deftypefun {char *} ttyname (int @var{filedes})
53 If the file descriptor @var{filedes} is associated with a terminal
54 device, the @code{ttyname} function returns a pointer to a
55 statically-allocated, null-terminated string containing the file name of
56 the terminal file.  The value is a null pointer if the file descriptor
57 isn't associated with a terminal, or the file name cannot be determined.
58 @end deftypefun
59
60 @node I/O Queues
61 @section I/O Queues
62
63 Many of the remaining functions in this section refer to the input and
64 output queues of a terminal device.  These queues implement a form of
65 buffering @emph{within the kernel} independent of the buffering
66 implemented by I/O streams (@pxref{Input/Output on Streams}).
67
68 @cindex terminal input queue
69 @cindex typeahead buffer
70 The @dfn{terminal input queue} is also sometimes referred to as its
71 @dfn{typeahead buffer}.  It holds the characters that have been received
72 from the terminal but not yet read by any process.
73
74 The size of the terminal's input queue is described by the
75 @code{_POSIX_MAX_INPUT} and @code{MAX_INPUT} parameters; see @ref{File
76 System Parameters}.  If input flow control is enabled by setting the
77 @code{IXOFF} input mode bit (@pxref{Input Modes}), the terminal driver
78 transmits STOP and START characters to the terminal when necessary to
79 prevent the queue from overflowing.  Otherwise, input may be lost if it
80 comes in too fast from the terminal.  (This is unlikely if you are
81 typing the input by hand!)
82
83 @cindex terminal output queue
84 The @dfn{terminal output queue} is like the input queue, but for output;
85 it contains characters that have been written by processes, but not yet
86 transmitted to the terminal.  If ouput flow control is enabled by
87 setting the @code{IXON} input mode bit (@pxref{Input Modes}), the
88 terminal driver obeys STOP and STOP characters sent by the terminal to
89 stop and restart transmission of output.
90
91 @dfn{Clearing} the terminal input queue means discarding any characters
92 that have been received but not yet read.  Similarly, clearing the
93 terminal output queue means discarding any characters that have been
94 written but not yet transmitted.
95
96 @node Terminal Modes
97 @section Terminal Modes
98
99 @pindex termios.h
100 This section describes the various terminal attributes that control how
101 input and output are done.  The functions, data structures, and symbolic
102 constants are all declared in the header file @file{termios.h}.
103
104 @menu
105 * Mode Data Types::     The data type @code{struct termios} and related types.
106 * Mode Functions::      Functions to read and set the terminal attributes.
107 * Setting Modes::       The right way to set terminal attributes reliably.
108 * Canonical or Not::    Two basic styles of input processing.
109 * Input Modes::         Flags controlling low-level input handling.
110 * Output Modes::        Flags controlling low-level output handling.
111 * Control Modes::       Flags controlling serial port behavior.
112 * Local Modes::         Flags controlling high-level input handling.
113 * Line Speed::          How to read and set the terminal line speed.
114 * Special Characters::  Characters that have special effects,
115                           and how to change them.
116 * Non-canonical Input:: Controlling how long to wait for input.
117 @end menu
118
119 @node Mode Data Types
120 @subsection Terminal Mode Data Types
121 @cindex terminal mode data types
122
123 The entire collection of attributes of a terminal is stored in a
124 structure of type @code{struct termios}.  This structure is used
125 with the functions @code{tcgetattr} and @code{tcsetattr} to read
126 and set the attributes.
127
128 @comment termios.h
129 @comment POSIX.1
130 @deftp {Data Type} {struct termios}
131 Structure that records all the I/O attributes of a terminal.  The
132 structure includes at least the following members:
133
134 @table @code
135 @item tcflag_t c_iflag
136 A bit mask specifying input modes; see @ref{Input Modes}.
137
138 @item tcflag_t c_oflag
139 A bit mask specifying output modes; see @ref{Output Modes}.
140
141 @item tcflag_t c_cflag
142 A bit mask specifying control modes; see @ref{Control Modes}.
143
144 @item tcflag_t c_lflag
145 A bit mask specifying local modes; see @ref{Local Modes}.
146
147 @item cc_t c_cc[NCCS]
148 An array specifying which characters are associated with various
149 control functions; see @ref{Special Characters}.
150 @end table
151
152 The @code{struct termios} structure also contains members which
153 encode input and output transmission speeds, but the representation is
154 not specified.  @xref{Line Speed}, for how to examine and store the
155 speed values.
156 @end deftp
157
158 The following sections describe the details of the members of the
159 @code{struct termios} structure.
160
161 @comment termios.h
162 @comment POSIX.1
163 @deftp {Data Type} tcflag_t
164 This is an unsigned integer type used to represent the various
165 bit masks for terminal flags.
166 @end deftp
167
168 @comment termios.h
169 @comment POSIX.1
170 @deftp {Data Type} cc_t
171 This is an unsigned integer type used to represent characters associated
172 with various terminal control functions.
173 @end deftp
174
175 @comment termios.h
176 @comment POSIX.1
177 @deftypevr Macro int NCCS
178 The value of this macro is the number of elements in the @code{c_cc}
179 array.
180 @end deftypevr
181
182 @node Mode Functions
183 @subsection Terminal Mode Functions
184 @cindex terminal mode functions
185
186 @comment termios.h
187 @comment POSIX.1
188 @deftypefun int tcgetattr (int @var{filedes}, struct termios *@var{termios_p})
189 This function is used to examine the attributes of the terminal
190 device with file descriptor @var{filedes}.  The attributes are returned
191 in the structure that @var{termios_p} points to.
192
193 If successful, @code{tcgetattr} returns @code{0}.  A return value of @code{-1}
194 indicates an error.  The following @code{errno} error conditions are
195 defined for this function:
196
197 @table @code
198 @item EBADF
199 The @var{filedes} argument is not a valid file descriptor.
200
201 @item ENOTTY
202 The @var{filedes} is not associated with a terminal.
203 @end table
204 @end deftypefun
205
206 @comment termios.h
207 @comment POSIX.1
208 @deftypefun int tcsetattr (int @var{filedes}, int @var{when}, const struct termios *@var{termios_p})
209 This function sets the attributes of the terminal device with file
210 descriptor @var{filedes}.  The new attributes are taken from the
211 structure that @var{termios_p} points to.
212
213 The @var{when} argument specifies how to deal with input and output
214 already queued.  It can be one of the following values:
215
216 @table @code
217 @comment termios.h
218 @comment POSIX.1
219 @item TCSANOW
220 @vindex TCSANOW
221 Make the change immediately.
222
223 @comment termios.h
224 @comment POSIX.1
225 @item TCSADRAIN
226 @vindex TCSADRAIN
227 Make the change after waiting until all queued output has been written.
228 You should usually use this option when changing parameters that affect
229 output.
230
231 @comment termios.h
232 @comment POSIX.1
233 @item TCSAFLUSH
234 @vindex TCSAFLUSH
235 This is like @code{TCSADRAIN}, but also discards any queued input.
236 @end table
237
238 If this function is called from a background process on its controlling
239 terminal, normally all processes in the process group are sent a
240 @code{SIGTTOU} signal, in the same way as if the process were trying to
241 write to the terminal.  The exception is if the calling process itself
242 is ignoring or blocking @code{SIGTTOU} signals, in which case the
243 operation is performed and no signal is sent.  @xref{Job Control}.
244
245 If successful, @code{tcsetattr} returns @code{0}.  A return value of
246 @code{-1} indicates an error.  The following @code{errno} error
247 conditions are defined for this function:
248
249 @table @code
250 @item EBADF
251 The @var{filedes} argument is not a valid file descriptor.
252
253 @item ENOTTY
254 The @var{filedes} is not associated with a terminal.
255
256 @item EINVAL
257 Either the value of the @code{when} argument is not valid, or there is
258 something wrong with the data in the @var{termios_p} argument.
259 @end table
260 @end deftypefun
261
262 Although @code{tcgetattr} and @code{tcsetattr} specify the terminal
263 device with a file descriptor, the attributes are those of the terminal
264 device itself and not of the file descriptor.  This means that the
265 effects of changing terminal attributes are persistent; if another
266 process opens the terminal file later on, it will see the changed
267 attributes even though it doesn't have anything to do with the open file
268 descriptor you originally specified in changing the attributes.
269
270 Similarly, if a single process has multiple or duplicated file
271 descriptors for the same terminal device, changing the terminal
272 attributes affects input and output to all of these file
273 descriptors.  This means, for example, that you can't open one file
274 descriptor or stream to read from a terminal in the normal
275 line-buffered, echoed mode; and simultaneously have another file
276 descriptor for the same terminal that you use to read from it in
277 single-character, non-echoed mode.  Instead, you have to explicitly
278 switch the terminal back and forth between the two modes.
279
280 @node Setting Modes
281 @subsection Setting Terminal Modes Properly
282
283 When you set terminal modes, you should call @code{tcgetattr} first to
284 get the current modes of the particular terminal device, modify only
285 those modes that you are really interested in, and store the result with
286 @code{tcsetattr}.
287
288 It's a bad idea to simply initialize a @code{struct termios} structure
289 to a chosen set of attributes and pass it directly to @code{tcsetattr}.
290 Your program may be run years from now, on systems that support members
291 not documented in this manual.  The way to avoid setting these members
292 to unreasonable values is to avoid changing them.
293
294 What's more, different terminal devices may require different mode
295 settings in order to function properly.  So you should avoid blindly
296 copying attributes from one terminal device to another.
297
298 When a member contains a collection of independent flags, as the
299 @code{c_iflag}, @code{c_oflag} and @code{c_cflag} members do, even
300 setting the entire member is a bad idea, because particular operating
301 systems have their own flags.  Instead, you should start with the
302 current value of the member and alter only the flags whose values matter
303 in your program, leaving any other flags unchanged.
304
305 Here is an example of how to set one flag (@code{ISTRIP}) in the
306 @code{struct termios} structure while properly preserving all the other
307 data in the structure:
308
309 @example
310 int
311 set_istrip (int desc, int value)
312 @{
313   struct termios settings;
314   int result;
315
316   result = tcgetattr (desc, &settings);
317   if (result < 0)
318     @{
319       perror ("error in tcgetattr");
320       return 0;
321     @}
322   settings.c_iflag &= ~ISTRIP;
323   if (value)
324     settings.c_iflag |= ISTRIP;
325   result = tcgetattr (desc, &settings);
326   if (result < 0)
327     @{
328       perror ("error in tcgetattr");
329       return;
330    @}
331   return 1;
332 @}
333 @end example
334
335 @node Canonical or Not
336 @section Two Styles of Input: Canonical or Not
337
338 POSIX systems support two basic modes of input: canonical and
339 non-canonical.
340
341 @cindex canonical input processing
342 In @dfn{canonical input processing} mode, terminal input is processed in
343 lines terminated by newline (@code{'\n'}), EOF, or EOL characters.  No
344 input can be read until an entire line has been typed by the user, and
345 the @code{read} function (@pxref{I/O Primitives}) returns at most a
346 single line of input, no matter how many bytes are requested.
347
348 In canonical input mode, the operating system provides input editing
349 facilities: the ERASE and KILL characters are interpreted specially to
350 perform editing operations within the current line of text.
351 @xref{Editing Characters}.
352
353 The constants @code{_POSIX_MAX_CANON} and @code{MAX_CANON} parameterize
354 the maximum number of bytes which may appear in a single line of
355 canonical input.  @xref{File System Parameters}.
356
357 @cindex non-canonical input processing
358 In @dfn{non-canonical input processing} mode, characters are not grouped
359 into lines, and ERASE and KILL processing is not performed.  The
360 granularity with which bytes are read in non-canonical input mode is
361 controlled by the MIN and TIME settings.  @xref{Non-Canonical Input}.
362
363 The choice of canonical or non-canonical input is controlled by the
364 @code{ICANON} flag in the @code{c_lflag} member of @code{struct termios}
365 (@pxref{Local Modes}).
366
367 @node Input Modes
368 @subsection Input Modes
369
370 This section describes the terminal attribute flags that control
371 fairly low-level aspects of input processing: handling of parity errors,
372 break signals, flow control, and @key{RET} and @key{LFD} characters.
373
374 All of these flags are bits in the @code{c_iflag} member of the
375 @code{struct termios} structure.  The member is an integer, and you
376 change flags using the operators @code{&}, @code{|} and @code{^}.  Don't
377 try to specify the entire value for @code{c_iflag}---instead, change
378 only specific flags and leave the rest untouched (@pxref{Setting
379 Modes}).
380
381 @table @code
382 @comment termios.h
383 @comment POSIX.1
384 @vindex INPCK
385 @item INPCK
386 @cindex parity checking
387 If this bit is set, input parity checking is enabled.  If it is not set,
388 no checking at all is done for parity errors on input; the
389 characters are simply passed through to the application.
390
391 Parity checking on input processing is independent of whether parity
392 detection and generation on the underlying terminal hardware is enabled;
393 see @ref{Control Modes}.  For example, you could clear the @code{INPCK}
394 input mode flag and set the @code{PARENB} control mode flag to ignore
395 parity errors on input, but still generate parity on output.
396
397 If this bit is set, what happens when a parity error is detected depends
398 on whether the @code{IGNPAR} or @code{PARMRK} bits are set.  If neither
399 of these bits are set, a byte with a parity error is passed to the
400 application as a @code{'\0'} character.
401
402 @comment termios.h
403 @comment POSIX.1
404 @vindex IGNPAR
405 @item IGNPAR
406 If this bit is set, any byte with a framing or parity error is ignored.
407 This is only useful if @code{INPCK} is also set.
408
409 @comment termios.h
410 @comment POSIX.1
411 @vindex PARMRK
412 @item PARMRK
413 If this bit is set and @code{IGNPAR} is not set, a byte with a framing
414 or parity error is prefixed with the characters @code{'\377'} and
415 @code{'\0'} before being passed to the application.  This is only useful
416 if @code{INPCK} is also set.
417
418 @comment termios.h
419 @comment POSIX.1
420 @vindex ISTRIP
421 @item ISTRIP
422 If this bit is set, valid input bytes are stripped to seven bits;
423 otherwise, all eight bits are available for programs to read.
424
425 If both @code{ISTRIP} and @code{PARMRK} are set, an input byte of 
426 @code{'\377'} is passed to the application as a two-byte sequence
427 @code{'\377'}, @code{'\377'}.
428
429 @c ??? Is this right?
430
431 @comment termios.h
432 @comment POSIX.1
433 @vindex IGNBRK
434 @item IGNBRK
435 If this bit is set, break conditions are ignored.
436
437 @cindex break condition, detecting
438 A @dfn{break condition} is defined in the context of asynchronous
439 serial data transmission as a series of zero-value bits longer than a
440 single byte.
441
442 @comment termios.h
443 @comment POSIX.1
444 @vindex BRKINT
445 @item BRKINT
446 If this bit is set and @code{IGNBRK} is not set, a break condition
447 clears the terminal input and output queues and raises a @code{SIGINT}
448 signal for the foreground process group associated with the terminal.
449
450 If neither @code{BRKINT} nor @code{IGNBRK} are set, a break condition is
451 passed to the application as a single @code{'\0'} character if
452 @code{PARMRK} is not set, or otherwise as a three-character sequence 
453 @code{'\377'}, @code{'\0'}, @code{'\0'}.
454
455 @comment termios.h
456 @comment POSIX.1
457 @vindex IGNCR
458 @item IGNCR
459 If this bit is set, carriage return characters (@code{'\r'}) are
460 discarded on input.  Discarding carriage return may be useful on
461 terminals that send both carriage return and linefeed when you type the
462 @key{RET} key.
463
464 @comment termios.h
465 @comment POSIX.1
466 @vindex ICRNL
467 @item ICRNL
468 If this bit is set and @code{IGNCR} is not set, carriage return characters
469 (@code{'\r'}) received as input are passed to the application as newline
470 characters (@code{'\n'}).
471
472 @comment termios.h
473 @comment POSIX.1
474 @vindex INLCR
475 @item INLCR
476 If this bit is set, newline characters (@code{'\n'}) received as input
477 are passed to the application as carriage return characters (@code{'\r'}).
478
479 @comment termios.h
480 @comment POSIX.1
481 @vindex IXOFF
482 @item IXOFF
483 If this bit is set, start/stop control on input is enabled.  In other
484 words, the computer sends STOP and START characters as necessary to
485 prevent input from coming in faster than programs are reading it.  The
486 idea is that the actual terminal hardware that is generating the input
487 data responds to a STOP character by suspending transmission, and to a
488 START character by resuming transmission.  @xref{Start/Stop Characters}.
489
490 @comment termios.h
491 @comment POSIX.1
492 @vindex IXON
493 @item IXON
494 If this bit is set, start/stop control on output is enabled.  In other
495 words, if the computer receives a STOP character, it suspends output
496 until a START character is received.  In this case, the STOP and START
497 characters are never passed to the application program.  If this bit is
498 not set, then START and STOP can be read as ordinary characters.
499 @xref{Start/Stop Characters}.
500 @end table
501
502 @node Output Modes
503 @subsection Output Modes
504
505 This section describes the terminal flags and fields that control how
506 output characters are translated and padded for display.  All of these
507 are contained in the @code{c_oflag} member of the @code{struct termios}
508 structure.
509
510 The @code{c_oflag} member itself is an integer, and you change the flags
511 and fields using the operators @code{&}, @code{|}, and @code{^}.  Don't
512 try to specify the entire value for @code{c_oflag}---instead, change
513 only specific flags and leave the rest untouched (@pxref{Setting
514 Modes}).
515
516 @comment termios.h
517 @comment POSIX.1
518 @deftypevr Macro int OPOST
519 If this bit is set, output data is processed in some unspecified way so
520 that it is displayed appropriately on the terminal device.  This
521 typically includes mapping newline characters (@code{'\n'}) onto
522 carriage return and linefeed pairs.
523
524 If this bit isn't set, the characters are transmitted as-is.
525 @end deftypevr
526
527 @c ??? Add here the flags and fields libc actually supports.
528
529 @node Control Modes
530 @subsection Control Modes
531
532 This section describes the terminal flags and fields that control
533 parameters usually associated with asynchronous serial data
534 transmission.  These flags may not make sense for other kinds of
535 terminal ports (such as a network connection pseudo-terminal).  All of
536 these are contained in the @code{c_cflag} member of the @code{struct
537 termios} structure.
538
539 The @code{c_cflag} member itself is an integer, and you change the flags
540 and fields using the operators @code{&}, @code{|}, and @code{^}.  Don't
541 try to specify the entire value for @code{c_cflag}---instead, change
542 only specific flags and leave the rest untouched (@pxref{Setting
543 Modes}).
544
545 @table @code
546 @comment termios.h
547 @comment POSIX.1
548 @vindex CLOCAL
549 @item CLOCAL
550 If this bit is set, it indicates that the terminal is connected
551 ``locally'' and that the modem status lines (such as carrier detect)
552 should be ignored.
553 @cindex modem status lines
554 @cindex carrier detect
555
556 If this bit is not set and you call @code{open} without the
557 @code{O_NONBLOCK} flag set, @code{open} blocks until a modem
558 connection is established.
559
560 If this bit is not set and a modem disconnect is detected, a
561 @code{SIGHUP} signal is sent to the controlling process for the terminal
562 (if it has one).  Normally, this causes the process to exit;
563 see @ref{Signal Handling}.  Reading from the terminal after a disconnect
564 causes an end-of-file condition, and writing causes an
565 @code{EIO} error to be returned.  The terminal device must be closed and
566 reopened to clear the condition.
567 @cindex modem disconnect
568
569 @comment termios.h
570 @comment POSIX.1
571 @vindex HUPCL
572 @item HUPCL
573 If this bit is set, a modem disconnect is generated when all processes
574 that have the terminal device open have either closed the file or exited.
575
576 @comment termios.h
577 @comment POSIX.1
578 @vindex CREAD
579 @item CREAD
580 If this bit is set, input can be read from the terminal.  Otherwise,
581 input is not permitted.
582
583 @c ??? What happens if a program tries to do input anyway?
584
585 @comment termios.h
586 @comment POSIX.1
587 @vindex CSTOPB
588 @item CSTOPB
589 If this bit is set, two stop bits are used.  Otherwise, only one stop bit
590 is used.
591
592 @comment termios.h
593 @comment POSIX.1
594 @vindex PARENB
595 @item PARENB
596 If this bit is set, generation and detection of a parity bit are enabled.
597 @xref{Input Modes}, for information on how input parity errors are handled.
598
599 If this bit is not set, no parity bit is added to output characters, and
600 input characters are not checked for correct parity.
601
602 @comment termios.h
603 @comment POSIX.1
604 @vindex PARODD
605 @item PARODD
606 This bit is only useful if @code{PARENB} is set.  If @code{PARODD} is set,
607 odd parity is used, otherwise even parity is used.
608
609 The control mode flags also includes a field for the number of bits per
610 character.  You can use the @code{CSIZE} macro as a mask to extract the
611 value, like this: @code{settings.c_cflag & CSIZE}.
612
613 @comment termios.h
614 @comment POSIX.1
615 @vindex CSIZE
616 @item CSIZE
617 This is a mask for the number of bits per character.
618
619 @comment termios.h
620 @comment POSIX.1
621 @vindex CS5
622 @item CS5
623 This specifies five bits per byte.
624
625 @comment termios.h
626 @comment POSIX.1
627 @vindex CS6
628 @item CS6
629 This specifies six bits per byte.
630
631 @comment termios.h
632 @comment POSIX.1
633 @vindex CS7
634 @item CS7
635 This specifies seven bits per byte.
636
637 @comment termios.h
638 @comment POSIX.1
639 @vindex CS8
640 @item CS8
641 This specifies eight bits per byte.
642 @end table
643
644 @node Local Modes
645 @subsection Local Modes
646
647 This section describes the flags for the @code{c_lflag} member of the
648 @code{struct termios} structure.  These flags generally control
649 higher-level aspects of input processing than the input modes flags
650 described in @ref{Input Modes}, such as echoing, signals, and the choice
651 of canonical or non-canonical input.
652
653 The @code{c_lflag} member itself is an integer, and you change the flags
654 and fields using the operators @code{&}, @code{|}, and @code{^}.  Don't
655 try to specify the entire value for @code{c_lflag}---instead, change
656 only specific flags and leave the rest untouched (@pxref{Setting
657 Modes}).
658
659 @table @code
660 @comment termios.h
661 @comment POSIX.1
662 @vindex ICANON
663 @item ICANON
664 This bit, if set, enables canonical input processing mode.  Otherwise,
665 input is processed in non-canonical mode.  @xref{Canonical or Not}.
666
667 @comment termios.h
668 @comment POSIX.1
669 @vindex ECHO
670 @item ECHO
671 If this bit is set, echoing of input characters back to the terminal
672 is enabled.
673 @cindex echo of terminal input
674
675 @comment termios.h
676 @comment POSIX.1
677 @vindex ECHOE
678 @item ECHOE
679 If this bit is set, erasure of input with the ERASE character is
680 indicated by erasing the last character in the current line from the
681 screen.  Otherwise, the character erased is re-echoed to show what has
682 happened (suitable for a printing terminal).
683
684 This bit only controls the display behavior; the @code{ICANON} bit by
685 itself controls actual recognition of the ERASE character and erasure of
686 input, without which @code{ECHOE} is simply irrelevant.
687
688 @comment termios.h
689 @comment POSIX.1
690 @vindex ECHOK
691 @item ECHOK
692 If this bit is set, then erasure of a whole like with the KILL character
693 is indicated by erasing the current line on the screen.  Otherwise, it
694 is indicated by echoingthe KILL character and moving to a new line
695 (suitable for a printing terminal).
696
697 This bit only controls the display behavior; the @code{ICANON} bit by
698 itself controls actual recognition of the KILL character and erasure of
699 input, without which @code{ECHOK} is simply irrelevant.
700
701 @comment termios.h
702 @comment POSIX.1
703 @vindex ECHONL
704 @item ECHONL
705 If this bit is set and the @code{ICANON} bit is also set, then the
706 newline (@code{'\n'}) character is echoed even if the @code{ECHO} bit
707 is not set.
708
709 @comment termios.h
710 @comment POSIX.1
711 @vindex ISIG
712 @item ISIG
713 This bit controls whether the INTR, QUIT, and SUSP characters are
714 recognized.  The functions associated with these characters are performed
715 if and only if this bit is set.  Being in canonical or non-canonical
716 input mode has no affect on the interpretation of these characters.
717
718 You should use caution when disabling recognition of these characters.
719 Programs that cannot be interrupted interactively are very
720 user-unfriendly.  If you clear this bit, your program should provide
721 some alternate interface that allows the user to interactively send the
722 signals associated with these characters, or to escape from the program.
723 @cindex interactive signals, from terminal
724
725 @xref{Signal Characters}.
726
727 @comment termios.h
728 @comment POSIX.1
729 @vindex IEXTEN
730 @item IEXTEN
731 This bit is similar to @code{ISIG}, but controls implementation-defined
732 special characters.  If it is set, it might override the default behavior
733 for the @code{ICANON} and @code{ISIG} local mode flags, and the @code{IXON}
734 and @code{IXOFF} input mode flags.
735
736 @comment termios.h
737 @comment POSIX.1
738 @vindex NOFLSH
739 @item NOFLSH
740 Normally, the INTR, QUIT, and SUSP characters cause input and output
741 queues for the terminal to be cleared.  If this bit is set, the queues
742 are not cleared.
743
744 @comment termios.h
745 @comment POSIX.1
746 @vindex TOSTOP
747 @item TOSTOP
748 If this bit is set and the system supports job control, then
749 @code{SIGTTOU} signals are generated by background processes that
750 attempt to write to the terminal.  @xref{Access to the Controlling
751 Terminal}.
752 @end table
753
754 @node Line Speed
755 @subsection Line Speed
756 @cindex line speed
757 @cindex baud rate
758 @cindex terminal line speed
759 @cindex terminal line speed
760
761 The terminal line speed tells the computer how fast to read and write
762 data on the terminal.
763
764 If the terminal is connected to a real serial line, the terminal speed
765 you specify actually controls the line---if it doesn't match the
766 terminal's own idea of the speed, communication does not work.  Real
767 serial ports accept only certain standard speeds.  Also, particular
768 hardware may not support even all the standard speeds.  Specifying a
769 speed of zero hangs up a dialup connection and turns off modem control
770 signals.
771
772 If the terminal is not a real serial line (for example, if it is a
773 network connection), then the line speed won't really affect data
774 transmission speed, but some programs will use it to determine the
775 amount of padding needed.  It's best to specify a line speed value that
776 matches the actual speed of the actual terminal, but you can safely
777 experiment with different values to vary the amount of padding.
778
779 There are actually two line speeds for each terminal, one for input and
780 one for output.  You can set them independently, but most often
781 terminals use the same speed for both directions.
782
783 The speed values are stored in the @code{struct termios} structure, but
784 don't try to access them in the @code{struct termios} structure
785 directly.  Instead, you should use the following functions to read and
786 store them:
787
788 @comment termios.h
789 @comment POSIX.1
790 @deftypefun speed_t cfgetospeed (const struct termios *@var{termios_p})
791 This function returns the output line speed stored in the structure
792 @code{*@var{termios_p}}.
793 @end deftypefun
794
795 @comment termios.h
796 @comment POSIX.1
797 @deftypefun speed_t cfgetispeed (const struct termios *@var{termios_p})
798 This function returns the input line speed stored in the structure
799 @code{*@var{termios_p}}.
800 @end deftypefun
801
802 @comment termios.h
803 @comment POSIX.1
804 @deftypefun int cfsetospeed (struct termios *@var{termios_p}, speed_t @var{speed})
805 This function stores @var{speed} in @code{*@var{termios_p}} as the output
806 speed.  The normal return value is @code{0}; a value of @code{-1}
807 indicates an error.  If @var{speed} is not a speed, @code{cfsetospeed}
808 returns @code{-1}.
809 @end deftypefun
810
811 @comment termios.h
812 @comment POSIX.1
813 @deftypefun int cfsetispeed (struct termios *@var{termios_p}, speed_t @var{speed})
814 This function stores @var{speed} in @code{*@var{termios_p}} as the input
815 speed.  The normal return value is @code{0}; a value of @code{-1}
816 indicates an error.  If @var{speed} is not a speed, @code{cfsetospeed}
817 returns @code{-1}.
818 @end deftypefun
819
820 @comment termios.h
821 @comment POSIX.1
822 @deftp {Data Type} speed_t
823 The @code{speed_t} type is an unsigned integer data type used to
824 represent line speeds.
825 @end deftp
826
827 The functions @code{cfsetospeed} and @code{cfsetispeed} report errors
828 only for speed values that the system simply cannot handle.  If you
829 specify a speed value that is basically acceptable, then those functions
830 will succeed.  But they do not check that a particular hardware device
831 can actually support the specified speeds---in fact, they don't know
832 which device you plan to set the speed for.  If you use @code{tcsetattr}
833 to set the speed of a particular device to a value that it cannot
834 handle, @code{tcsetattr} returns @code{-1}.
835
836 @strong{Portability note:} In the GNU library, the functions above
837 accept speeds measured in bits per second as input, and return speed
838 values measured in bits per second.  Other libraries require speeds to
839 be indicated by special codes.  For POSIX.1 portability, you must use
840 one of the following symbols to represent the speed; their precise
841 numeric values are system-dependent, but each name has a fixed meaning:
842 @code{B110} stands for 110 bps, @code{B300} for 300 bps, and so on.
843 There is no portable way to represent any speed but these, but these are
844 the only speeds that typical serial lines can support.
845
846 @comment termios.h
847 @comment POSIX.1
848 @vindex B0
849 @comment termios.h
850 @comment POSIX.1
851 @vindex B50
852 @comment termios.h
853 @comment POSIX.1
854 @vindex B75
855 @comment termios.h
856 @comment POSIX.1
857 @vindex B110
858 @comment termios.h
859 @comment POSIX.1
860 @vindex B134
861 @comment termios.h
862 @comment POSIX.1
863 @vindex B150
864 @comment termios.h
865 @comment POSIX.1
866 @vindex B200
867 @comment termios.h
868 @comment POSIX.1
869 @vindex B300
870 @comment termios.h
871 @comment POSIX.1
872 @vindex B600
873 @comment termios.h
874 @comment POSIX.1
875 @vindex B1200
876 @comment termios.h
877 @comment POSIX.1
878 @vindex B1800
879 @comment termios.h
880 @comment POSIX.1
881 @vindex B2400
882 @comment termios.h
883 @comment POSIX.1
884 @vindex B4800
885 @comment termios.h
886 @comment POSIX.1
887 @vindex B9600
888 @comment termios.h
889 @comment POSIX.1
890 @vindex B19200
891 @comment termios.h
892 @comment POSIX.1
893 @vindex B38400
894 @example
895 B0  B50  B75  B110  B134  B150  B200
896 B300  B600  B1200  B1800  B2400  B4800
897 B9600  B19200  B38400
898 @end example
899
900 @node Special Characters
901 @subsection Special Characters
902
903 In canonical input, the terminal driver recognizes a number of special
904 characters which perform various control functions.  These include the
905 ERASE character (usually @key{DEL}) for editing input, and other editing
906 characters.  The INTR character (normally @kbd{C-c}) for sending a
907 @code{SIGINT} signal, and other signal-raising characters, may be
908 available in either canonical or non-canonical input mode.  All these
909 characters are described in this section.
910
911 The particular characters used are specified in the @code{c_cc} member
912 of the @code{struct termios} structure.  This member is an array; each
913 element specifies the character for a particular role.  Each element has
914 a symbolic constant that stands for the index of that element---for
915 example, @code{INTR} is the index of the element that specifies the INTR
916 character, so storing @code{'='} in @code{@var{termios}.c_cc[INTR]}
917 specifies @samp{=} as the INTR character.
918
919 @vindex _POSIX_VDISABLE
920 On some systems, you can disable a particular special character function
921 by specifying the value @code{_POSIX_VDISABLE} for that role.  This
922 value is unequal to any possible character code.  @xref{File System
923 Parameters}, for more information about how to tell whether the
924 operating system you are using supports @code{_POSIX_VDISABLE}.
925
926 @menu
927 * Editing Characters::
928 * Signal Characters::
929 * Start/Stop Characters::
930 @end menu
931
932 @node Editing Characters
933 @subsubsection Characters for Input Editing
934
935 These special characters are active only in canonical input mode.
936 @xref{Canonical or Not}.
937
938 @comment termios.h
939 @comment POSIX.1
940 @deftypevr Macro int VEOF
941 @cindex EOF character
942 This is the subscript for the EOF character in the special control
943 character array.  @code{@var{termios}.c_cc[VEOF]} holds the character
944 itself.
945
946 The EOF character is recognized only in canonical input mode.  It acts
947 as a line terminator in the same way as a newline character, but if the
948 EOF character is typed at the beginning of a line it causes @code{read}
949 to return a byte count of zero, indicating end-of-file.  The EOF
950 character itself is discarded.
951
952 Usually, the EOF character is @kbd{C-d}.
953 @end deftypevr
954
955 @comment termios.h
956 @comment POSIX.1
957 @deftypevr Macro int VEOL
958 @cindex EOL character
959 This is the subscript for the EOL character in the special control
960 character array.  @code{@var{termios}.c_cc[VEOL]} holds the character
961 itself.
962
963 The EOL character is recognized only in canonical input mode.  It acts
964 as a line terminator, just like a newline character.  The EOL character
965 is not discarded; it is read as the last character in the input line.
966
967 @strong{Incomplete:}  Is this usually a carriage return?
968 @end deftypevr
969
970 @comment termios.h
971 @comment POSIX.1
972 @deftypevr Macro int VERASE
973 @cindex ERASE character
974 This is the subscript for the ERASE character in the special control
975 character array.  @code{@var{termios}.c_cc[VERASE]} holds the
976 character itself.
977
978 The ERASE character is recognized only in canonical input mode.  When
979 the user types the erase character, the previous character typed is
980 discarded.  (If the terminal generates multibyte character sequences,
981 this may cause more than one byte of input to be discarded.)  This
982 cannot be used to erase past the beginning of the current line of text.
983 The ERASE character itself is discarded.
984
985 Usually, the ERASE character is @key{DEL}.
986 @end deftypevr
987
988 @comment termios.h
989 @comment POSIX.1
990 @deftypevr Macro int VKILL
991 @cindex KILL character
992 This is the subscript for the KILL character in the special control
993 character array.  @code{@var{termios}.c_cc[VKILL]} holds the character
994 itself.
995
996 The KILL character is recognized only in canonical input mode.  When the
997 user types the kill character, the entire contents of the current line
998 of input are discarded.  The kill character itself is discarded too.
999
1000 The KILL character is usually @kbd{C-u}.
1001 @end deftypevr
1002
1003 @node Signal Characters
1004 @subsubsection Characters that Cause Signals
1005
1006 These special characters may active in either canonical or non-canonical
1007 input mode, but only when the @code{ISIG} flag is set (@pxref{Local
1008 Modes}).
1009
1010 @comment termios.h
1011 @comment POSIX.1
1012 @deftypevr Macro int VINTR
1013 @cindex INTR character
1014 @cindex interrupt character
1015 This is the subscript for the INTR character in the special control
1016 character array.  @code{@var{termios}.c_cc[VINTR]} holds the character
1017 itself.
1018
1019 The INTR (interrupt) character raises a @code{SIGINT} signal for all
1020 processes in the foreground job associated with the terminal.  The INTR
1021 character itself is then discarded.  @xref{Signal Handling}, for more
1022 information about signals.
1023
1024 Typically, the INTR character is @kbd{C-c}.
1025 @end deftypevr
1026
1027 @comment termios.h
1028 @comment POSIX.1
1029 @deftypevr Macro int VQUIT
1030 @cindex QUIT character
1031 This is the subscript for the QUIT character in the special control
1032 character array.  @code{@var{termios}.c_cc[VQUIT]} holds the character
1033 itself.
1034
1035 The QUIT character raises a @code{SIGQUIT} signal for all processes in
1036 the foreground job associated with the terminal.  The QUIT character
1037 itself is then discarded.  @xref{Signal Handling}, for more information
1038 about signals.
1039
1040 Typically, the QUIT character is @kbd{C-\}.
1041 @end deftypevr
1042
1043 @comment termios.h
1044 @comment POSIX.1
1045 @deftypevr Macro int VSUSP
1046 @cindex SUSP character
1047 @cindex suspend character
1048 This is the subscript for the SUSP character in the special control
1049 character array.  @code{@var{termios}.c_cc[VSUSP]} holds the character
1050 itself.
1051
1052 The SUSP (suspend) character is recognized only if the implementation
1053 supports job control (@pxref{Job Control}).  It causes a @code{SIGTSTP}
1054 signal to be sent to all processes in the foreground job associated with
1055 the terminal.  The SUSP character itself is then discarded.
1056 @xref{Signal Handling}, for more information about signals.
1057
1058 Typically, the SUSP character is @kbd{C-z}.
1059 @end deftypevr
1060
1061 @node Start/Stop Characters
1062 @subsubsection Special Characters for Flow Control
1063
1064 These special characters may active in either canonical or non-canonical
1065 input mode, but their use is controlled by the flags @code{IXON} and
1066 @code{IXOFF} (@pxref{Input Modes}).
1067
1068 @comment termios.h
1069 @comment POSIX.1
1070 @deftypevr Macro int VSTART
1071 @cindex START character
1072 This is the subscript for the START character in the special control
1073 character array.  @code{@var{termios}.c_cc[VSTART]} holds the
1074 character itself.
1075
1076 The START character is used to support the @code{IXON} and @code{IXOFF}
1077 input modes.  If @code{IXON} is set, receiving a START character resumes
1078 suspended output; the START character itself is discarded.  If
1079 @code{IXOFF} is set, the system may also transmit START characters to
1080 the terminal.
1081
1082 The usual value for the START character is @kbd{C-q}.  You may not be
1083 able to change this value---the hardware may insist on using @kbd{C-q}
1084 regardless of what you specify.
1085 @end deftypevr
1086
1087 @comment termios.h
1088 @comment POSIX.1
1089 @deftypevr Macro int VSTOP
1090 @cindex STOP character
1091 This is the subscript for the STOP character in the special control
1092 character array.  @code{@var{termios}.c_cc[VSTOP]} holds the character
1093 itself.
1094
1095 The STOP character is used to support the @code{IXON} and @code{IXOFF}
1096 input modes.  If @code{IXON} is set, receiving a STOP character causes
1097 output to be suspended; the STOP character itself is discarded.  If
1098 @code{IXOFF} is set, the system may also transmit STOP characters to the
1099 terminal, to prevent the input queue from overflowing.
1100
1101 The usual value for the STOP character is @kbd{C-s}.  You may not be
1102 able to change this value---the hardware may insist on using @kbd{C-s}
1103 regardless of what you specify.
1104 @end deftypevr
1105
1106 @node Non-canonical Input
1107 @subsection Non-Canonical Input
1108
1109 In non-canonical input mode, the special editing characters such as
1110 ERASE and KILL are ignored.  The system facilities for the user to edit
1111 input are disabled in non-canonical mode, so that all input characters
1112 (unless they are special for signal or flow-control purposes) are passed
1113 to the application program exactly as typed.  It is up to the
1114 application program to give the user ways to edit the input, if
1115 appropriate.
1116
1117 Non-canonical mode offers special parameters called MIN and TIME for
1118 controlling whether and how long to wait for input to be available.  You
1119 can even use them to avoid ever waiting---to return immediately with
1120 whatever input is available, or with no input.
1121
1122 The MIN and TIME are stored in elements of the @code{c_cc} array, which
1123 is a member of the @code{struct termios} structure.  Each element of
1124 this array has a particular role, and each element has a symbolic
1125 constant that stands for the index of that element.  @code{VMIN} and
1126 @code{VMAX} are the names for the indices in the array of the MIN and
1127 TIME slots.
1128
1129 @comment termios.h
1130 @comment POSIX.1
1131 @deftypevr Macro int VMIN
1132 @cindex MIN termios slot
1133 This is the subscript for the MIN slot in the @code{c_cc} array.  Thus,
1134 @code{@var{termios}.c_cc[VMIN]} is the value itself.
1135
1136 The MIN slot is only meaningful in non-canonical input mode; it
1137 specifies the minimum number of bytes that must be available in the
1138 input queue in order for @code{read} to return.
1139 @end deftypevr
1140
1141 @comment termios.h
1142 @comment POSIX.1
1143 @deftypevr Macro int VTIME
1144 @cindex TIME termios slot
1145 This is the subscript for the TIME slot in the @code{c_cc} array.  Thus,
1146 @code{@var{termios}.c_cc[VTIME]} is the value itself.
1147
1148 The TIME slot is only meaningful in non-canonical input mode; it
1149 specifies how long to wait for input before returning, in units of 0.1
1150 seconds.
1151 @end deftypevr
1152
1153 The MIN and TIME values interact to determine the criterion for when
1154 @code{read} should return; their precise meanings depend on which of
1155 them are nonzero.  There are four possible cases:
1156
1157 @itemize @bullet
1158 @item 
1159 Both MIN and TIME are zero.
1160
1161 In this case, @code{read} always returns immediately with as many
1162 characters as are available in the queue, up to the number requested.
1163 If no input is immediately available, @code{read} returns a value of
1164 zero.
1165
1166 @item
1167 MIN is zero but TIME has a nonzero value.
1168
1169 In this case, @code{read} waits for time TIME for input to become
1170 available; the availability of a single byte is enough to satisfy the
1171 read request and cause @code{read} to return.  When it returns, it
1172 returns as many characters as are available, up to the number requested.
1173 If no input is available before the timer expires, @code{read} returns a
1174 value of zero.
1175
1176 @item
1177 TIME is zero but MIN has a nonzero value.
1178
1179 In this case, @code{read} waits until at least MIN bytes are available
1180 in the queue.  At that time, @code{read} returns as many characters as
1181 are available, up to the number requested.  @code{read} can return more
1182 than MIN characters if more than MIN happen to be in the queue.
1183
1184 @item
1185 Both TIME and MIN are nonzero.
1186
1187 In this case, TIME specifies how long to wait after each input character
1188 to see if more input arrives.  @code{read} keeps waiting until either
1189 MIN bytes have arrived, or TIME elapses with no further input.
1190
1191 @code{read} can return no input if TIME elapses before the first input
1192 character arrives.  @code{read} can return more than MIN characters if
1193 more than MIN happen to be in the queue.
1194 @end itemize
1195
1196 What happens if MIN is 50 and you ask to read just 10 bytes?
1197 Normally, @code{read} waits until there are 50 bytes in the buffer (or,
1198 more generally, the wait condition described above is satisfied), and
1199 then reads 10 of them, leaving the other 40 buffered in the operating
1200 system for a subsequent call to @code{read}.
1201
1202 @strong{Portability note:} On some systems, the MIN and TIME slots are
1203 actually the same as the EOF and EOL slots.  This causes no serious
1204 problem because the MIN and TIME slots are used only in non-canonical
1205 input and the EOF and EOL slots are used only in canonical input, but it
1206 isn't very clean.  The GNU library allocates separate slots for these
1207 uses.
1208
1209 @node Line Control
1210 @section Line Control Functions
1211 @cindex terminal line control functions
1212
1213 These functions perform miscellanous control actions on terminal
1214 devices.  As regards terminal access, they are treated like doing
1215 output: if any of these functions is used by a background process on its
1216 controlling terminal, normally all processes in the process group are
1217 sent a @code{SIGTTOU} signal.  The exception is if the calling process
1218 itself is ignoring or blocking @code{SIGTTOU} signals, in which case the
1219 operation is performed and no signal is sent.  @xref{Job Control}.
1220
1221 @cindex break condition, generating
1222 @comment termios.h
1223 @comment POSIX.1
1224 @deftypefun int tcsendbreak (int @var{filedes}, int @var{duration})
1225 This function generates a break condition by transmitting a stream of
1226 zero bits on the terminal associated with the file descriptor
1227 @var{filedes}.  The duration of the break is controlled by the
1228 @var{duration} argument.  If zero, the duration is between 0.25 and 0.5
1229 seconds.  The meaning of a nonzero value depends on the operating system.
1230
1231 This function does nothing if the terminal is not an asynchronous serial
1232 data port.
1233
1234 The return value is normally zero.  In the event of an error, a value
1235 of @code{-1} is returned.  The following @code{errno} error conditions
1236 are defined for this function:
1237
1238 @table @code
1239 @item EBADF
1240 The @var{filedes} is not a valid file descriptor.
1241
1242 @item ENOTTY
1243 The @var{filedes} is not associated with a terminal device.
1244 @end table
1245 @end deftypefun
1246
1247
1248 @cindex flushing terminal output queue
1249 @cindex terminal output queue, flushing
1250 @comment termios.h
1251 @comment POSIX.1
1252 @deftypefun int tcdrain (int @var{filedes})
1253 The @code{tcdrain} function waits until all queued
1254 output to the terminal @var{filedes} has been transmitted.
1255
1256 The return value is normally zero.  In the event of an error, a value
1257 of @code{-1} is returned.  The following @code{errno} error conditions
1258 are defined for this function:
1259
1260 @table @code
1261 @item EBADF
1262 The @var{filedes} is not a valid file descriptor.
1263
1264 @item ENOTTY
1265 The @var{filedes} is not associated with a terminal device.
1266
1267 @item EINTR
1268 The operation was interrupted by delivery of a signal.
1269 @end table
1270 @end deftypefun
1271
1272
1273 @cindex clearing terminal input queue
1274 @cindex terminal input queue, clearing
1275 @comment termios.h
1276 @comment POSIX.1
1277 @deftypefun int tcflush (int @var{filedes}, int @var{queue})
1278 The @code{tcflush} function is used to clear the input and/or output
1279 queues associated with the terminal file @var{filedes}.  The @var{queue}
1280 argument specifies which queue(s) to clear, and can be one of the
1281 following values:
1282
1283 @table @code
1284 @vindex TCIFLUSH
1285 @item TCIFLUSH
1286 Clear any input data received, but not yet read.
1287
1288 @vindex TCOFLUSH
1289 @item TCOFLUSH
1290 Clear any output data written, but not yet transmitted.
1291
1292 @vindex TCIOFLUSH
1293 @item TCIOFLUSH
1294 Clear both queued input and output.
1295 @end table
1296
1297 The return value is normally zero.  In the event of an error, a value
1298 of @code{-1} is returned.  The following @code{errno} error conditions
1299 are defined for this function:
1300
1301 @table @code
1302 @item EBADF
1303 The @var{filedes} is not a valid file descriptor.
1304
1305 @item ENOTTY
1306 The @var{filedes} is not associated with a terminal device.
1307
1308 @item EINVAL
1309 A bad value was supplied as the @var{queue} argument.
1310 @end table
1311
1312 It is unfortunate that this function is named @code{tcflush}, because
1313 the term ``flush'' is normally used for quite another operation---waiting
1314 until all output is transmitted---and using it for discarding input or
1315 output would be confusing.  Unfortunately, the name @code{tcflush} comes
1316 from POSIX and we cannot change it.
1317 @end deftypefun
1318
1319 @cindex flow control, terminal
1320 @cindex terminal flow control
1321 @comment termios.h
1322 @comment POSIX.1
1323 @deftypefun int tcflow (int @var{filedes}, int @var{action})
1324 The @code{tcflow} function is used to perform operations relating to
1325 XON/XOFF flow control on the terminal file specified by @var{filedes}.
1326
1327 The @var{action} argument specifies what operation to perform, and can
1328 be one of the following values:
1329
1330 @table @code
1331 @vindex TCOOFF
1332 @item TCOOFF
1333 Suspend transmission of output.
1334
1335 @vindex TCOON
1336 @item TCOON
1337 Restart transmission of output.
1338
1339 @vindex TCIOFF
1340 @item TCIOFF
1341 Transmit a STOP character.
1342
1343 @vindex TCION
1344 @item TCION
1345 Transmit a START character.
1346 @end table
1347
1348 For more information about the STOP and START characters, see @ref{Special
1349 Characters}.
1350
1351 The return value is normally zero.  In the event of an error, a value
1352 of @code{-1} is returned.  The following @code{errno} error conditions
1353 are defined for this function:
1354
1355 @table @code
1356 @vindex EBADF
1357 @item EBADF
1358 The @var{filedes} is not a valid file descriptor.
1359
1360 @vindex ENOTTY
1361 @item ENOTTY
1362 The @var{filedes} is not associated with a terminal device.
1363
1364 @vindex EINVAL
1365 @item EINVAL
1366 A bad value was supplied as the @var{action} argument.
1367 @end table
1368 @end deftypefun
1369
1370 @node Terminal Example
1371 @section Terminal Mode Example
1372
1373 Here is an example program that shows how you can set up a terminal
1374 device to read single characters in non-canonical input mode, without
1375 echo.
1376
1377 @example
1378 #include <unistd.h>
1379 #include <stdio.h>
1380 #include <stdlib.h>
1381 #include <termios.h>
1382
1383 /* @r{Use this variable to remember original terminal attributes.} */
1384
1385 struct termios saved_attributes;
1386
1387 void
1388 reset_input_mode (void)
1389 @{
1390   tcsetattr (STDIN_FILENO, TCSANOW, &saved_attributes);
1391   signal (SIGCONT, set_input_mode);
1392 @}
1393   
1394 void 
1395 set_input_mode (void)
1396 @{
1397   struct termios tattr;
1398   char *name;
1399
1400   /* @r{Make sure stdin is a terminal.} */
1401   if (!isatty (STDIN_FILENO)) @{
1402     fprintf (stderr, "Not a terminal.\n");
1403     exit (EXIT_FAILURE);
1404     @}
1405
1406   /* @r{Save the terminal attributes so we can restore them later.} */
1407   tcgetattr (STDIN_FILENO, &saved_attributes);
1408   atexit (reset_input_mode);
1409
1410   /* @r{Set the funny terminal modes.} */
1411   tcgetattr (STDIN_FILENO, &tattr);
1412   tattr.c_lflag = tattr.c_lflag & (~ICANON);   /* @r{Clear ICANON.} */
1413   tattr.c_lflag = tattr.c_lflag & (~ECHO);     /* @r{Clear ECHO.} */
1414   tattr.c_cc[VMIN] = 1;
1415   tattr.c_cc[VTIME] = 0;
1416   tcsetattr (STDIN_FILENO, TCSAFLUSH, &tattr);
1417 @}
1418
1419 /* @r{Handle @code{SIGCONT}.} */
1420 void
1421 resumed (int sig)
1422 @{
1423   set_intput_mode ();
1424 @}
1425
1426 /* @r{Handle signals that take the terminal away.} */
1427 void
1428 handler (int sig)
1429 @{
1430   reset_input_mode ();
1431   signal (sig, SIG_DFL);
1432   /* @r{Make the same signal happen, with no handler.} */
1433   raise (sig);
1434   signal (sig, handler);
1435 @}
1436
1437 void
1438 main (void)
1439 @{
1440   char c;
1441
1442   set_input_mode ();
1443   signal (SIGTERM, handler);
1444   signal (SIGHUP, handler);
1445   signal (SIGINT, handler);
1446   signal (SIGQUIT, handler);
1447   @dots{}
1448   read (STDIN_FILENO, &c, 1);
1449   @dots{}
1450   exit (EXIT_SUCCESS);
1451 @}
1452 @end example
1453
1454 This program is careful to restore the original terminal modes before
1455 exiting or terminating with a signal.  It uses the @code{atexit}
1456 function (@pxref{Normal Program Termination}) to make sure this is done
1457 by @code{exit}.
1458
1459 The signals handled in the example are the ones that typically occur due
1460 to actions of the user.  It might be desirable to handle other signals
1461 such as SIGSEGV that can result from bugs in the program.
1462
1463 The shell is supposed to take care of resetting the terminal modes when
1464 a process is stopped or continued; see @ref{Job Control}.  But some
1465 existing shells do not actually do this, so you may wish to establish
1466 handlers for job control signals that reset terminal modes.  The above
1467 example does so.