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