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