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