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