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