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