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