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