]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
3 | .\" Copyright (c) 1993 Michael Haardt | |
4 | .\" (michael@moria.de) | |
5 | .\" Fri Apr 2 11:32:09 MET DST 1993 | |
6 | .\" | |
7 | .\" This is free documentation; you can redistribute it and/or | |
8 | .\" modify it under the terms of the GNU General Public License as | |
9 | .\" published by the Free Software Foundation; either version 2 of | |
10 | .\" the License, or (at your option) any later version. | |
11 | .\" | |
12 | .\" The GNU General Public License's references to "object code" | |
13 | .\" and "executables" are to be interpreted as the output of any | |
14 | .\" document formatting or typesetting system, including | |
15 | .\" intermediate and printed output. | |
16 | .\" | |
17 | .\" This manual is distributed in the hope that it will be useful, | |
18 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
19 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
20 | .\" GNU General Public License for more details. | |
21 | .\" | |
22 | .\" You should have received a copy of the GNU General Public | |
23 | .\" License along with this manual; if not, write to the Free | |
24 | .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, | |
25 | .\" USA. | |
26 | .\" | |
27 | .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> | |
28 | .\" Modified 1995-02-25 by Jim Van Zandt <jrv@vanzandt.mv.com> | |
29 | .\" Modified 1995-09-02 by Jim Van Zandt <jrv@vanzandt.mv.com> | |
30 | .\" moved to man3, aeb, 950919 | |
c11b1abf | 31 | .\" Modified 2001-09-22 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
32 | .\" Modified 2001-12-17, aeb |
33 | .\" Modified 2004-10-31, aeb | |
19ab0376 MK |
34 | .\" 2006-12-28, mtk: |
35 | .\" Added .SS headers to give some structure to this page; and a | |
36 | .\" small amount of reordering. | |
37 | .\" Added a section on canonical and non-canonical mode. | |
38 | .\" Enhanced the discussion of "raw" mode for cfmakeraw(). | |
39 | .\" Document CMSPAR. | |
fea681da | 40 | .\" |
2ccfac8b | 41 | .TH TERMIOS 3 2007-11-26 "Linux" "Linux Programmer's Manual" |
fea681da MK |
42 | .SH NAME |
43 | termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, | |
44 | cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfsetspeed \- | |
45 | get and set terminal attributes, line control, get and set baud rate | |
46 | .SH SYNOPSIS | |
04bb6cc0 | 47 | .nf |
c91e381d | 48 | .B #include <termios.h> |
fea681da | 49 | .br |
c91e381d | 50 | .B #include <unistd.h> |
fea681da MK |
51 | .sp |
52 | .BI "int tcgetattr(int " fd ", struct termios *" termios_p ); | |
53 | .sp | |
04bb6cc0 MK |
54 | .BI "int tcsetattr(int " fd ", int " optional_actions , |
55 | .BI " const struct termios *" termios_p ); | |
fea681da MK |
56 | .sp |
57 | .BI "int tcsendbreak(int " fd ", int " duration ); | |
58 | .sp | |
59 | .BI "int tcdrain(int " fd ); | |
60 | .sp | |
61 | .BI "int tcflush(int " fd ", int " queue_selector ); | |
62 | .sp | |
63 | .BI "int tcflow(int " fd ", int " action ); | |
64 | .sp | |
65 | .BI "void cfmakeraw(struct termios *" termios_p ); | |
66 | .sp | |
67 | .BI "speed_t cfgetispeed(const struct termios *" termios_p ); | |
68 | .sp | |
69 | .BI "speed_t cfgetospeed(const struct termios *" termios_p ); | |
70 | .sp | |
71 | .BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed ); | |
72 | .sp | |
73 | .BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed ); | |
01d5d366 | 74 | .sp |
52dab97a | 75 | .BI "int cfsetspeed(struct termios *" termios_p ", speed_t " speed ); |
04bb6cc0 | 76 | .fi |
cc4615cc MK |
77 | .sp |
78 | .in -4n | |
79 | Feature Test Macro Requirements for glibc (see | |
80 | .BR feature_test_macros (7)): | |
81 | .in | |
82 | .sp | |
cc4615cc MK |
83 | .BR cfsetspeed (), |
84 | .BR cfmakeraw (): | |
85 | _BSD_SOURCE | |
fea681da MK |
86 | .SH DESCRIPTION |
87 | The termios functions describe a general terminal interface that is | |
88 | provided to control asynchronous communications ports. | |
87d1fd87 | 89 | .SS "The termios structure" |
fea681da MK |
90 | .LP |
91 | Many of the functions described here have a \fItermios_p\fP argument | |
c13182ef MK |
92 | that is a pointer to a \fItermios\fP structure. |
93 | This structure contains at least the following members: | |
fea681da | 94 | .sp |
a6e2f128 | 95 | .in +4n |
fea681da | 96 | .nf |
bd9b2a9c MK |
97 | tcflag_t c_iflag; /* input modes */ |
98 | tcflag_t c_oflag; /* output modes */ | |
99 | tcflag_t c_cflag; /* control modes */ | |
100 | tcflag_t c_lflag; /* local modes */ | |
101 | cc_t c_cc[NCCS]; /* control chars */ | |
fea681da | 102 | .fi |
a6e2f128 | 103 | .in |
fea681da | 104 | .PP |
869ebe5b | 105 | The values that may be assigned to these fields are described below. |
c13182ef MK |
106 | In the case of the first four bit-mask fields, |
107 | the definitions of some of the associated flags that may be set are | |
869ebe5b | 108 | only exposed if a specific feature test macro (see |
a8e7c990 | 109 | .BR feature_test_macros (7)) |
869ebe5b MK |
110 | is defined, as noted in brackets ("[]"). |
111 | .PP | |
42b09930 | 112 | In the descriptions below, "not in POSIX" means that the |
c13182ef MK |
113 | value is not specified in POSIX.1-2001, |
114 | and "XSI" means that the value is specified in POSIX.1-2001 | |
42b09930 MK |
115 | as part of the XSI extension. |
116 | .PP | |
fea681da MK |
117 | \fIc_iflag\fP flag constants: |
118 | .TP | |
119 | .B IGNBRK | |
120 | Ignore BREAK condition on input. | |
121 | .TP | |
122 | .B BRKINT | |
c13182ef MK |
123 | If \fBIGNBRK\fP is set, a BREAK is ignored. |
124 | If it is not set | |
fea681da MK |
125 | but \fBBRKINT\fP is set, then a BREAK causes the input and output |
126 | queues to be flushed, and if the terminal is the controlling | |
127 | terminal of a foreground process group, it will cause a | |
128 | \fBSIGINT\fP to be sent to this foreground process group. | |
129 | When neither \fBIGNBRK\fP nor \fBBRKINT\fP are set, a BREAK | |
f81fb444 | 130 | reads as a null byte (\(aq\\0\(aq), except when \fBPARMRK\fP is set, |
fea681da MK |
131 | in which case it reads as the sequence \\377 \\0 \\0. |
132 | .TP | |
133 | .B IGNPAR | |
134 | Ignore framing errors and parity errors. | |
135 | .TP | |
136 | .B PARMRK | |
c13182ef MK |
137 | If \fBIGNPAR\fP is not set, prefix a character with a parity error or |
138 | framing error with \\377 \\0. | |
139 | If neither \fBIGNPAR\fP nor \fBPARMRK\fP | |
fea681da MK |
140 | is set, read a character with a parity error or framing error |
141 | as \\0. | |
142 | .TP | |
143 | .B INPCK | |
144 | Enable input parity checking. | |
145 | .TP | |
146 | .B ISTRIP | |
147 | Strip off eighth bit. | |
148 | .TP | |
149 | .B INLCR | |
150 | Translate NL to CR on input. | |
151 | .TP | |
152 | .B IGNCR | |
153 | Ignore carriage return on input. | |
154 | .TP | |
155 | .B ICRNL | |
156 | Translate carriage return to newline on input (unless \fBIGNCR\fP is set). | |
157 | .TP | |
158 | .B IUCLC | |
159 | (not in POSIX) Map uppercase characters to lowercase on input. | |
160 | .TP | |
161 | .B IXON | |
162 | Enable XON/XOFF flow control on output. | |
163 | .TP | |
164 | .B IXANY | |
c13182ef | 165 | (XSI) Typing any character will restart stopped output. |
42b09930 | 166 | (The default is to allow just the START character to restart output.) |
fea681da MK |
167 | .TP |
168 | .B IXOFF | |
169 | Enable XON/XOFF flow control on input. | |
170 | .TP | |
171 | .B IMAXBEL | |
172 | (not in POSIX) Ring bell when input queue is full. | |
173 | Linux does not implement this bit, and acts as if it is always set. | |
225c76e9 MK |
174 | .TP |
175 | .BR IUTF8 " (since Linux 2.6.4)" | |
c13182ef | 176 | (not in POSIX) Input is UTF8; |
225c76e9 | 177 | this allows character-erase to be correctly performed in cooked mode. |
fea681da MK |
178 | .PP |
179 | \fIc_oflag\fP flag constants defined in POSIX.1: | |
180 | .TP | |
181 | .B OPOST | |
182 | Enable implementation-defined output processing. | |
183 | .PP | |
68e1685c | 184 | The remaining \fIc_oflag\fP flag constants are defined in POSIX.1-2001, |
fea681da MK |
185 | unless marked otherwise. |
186 | .TP | |
187 | .B OLCUC | |
188 | (not in POSIX) Map lowercase characters to uppercase on output. | |
189 | .TP | |
190 | .B ONLCR | |
191 | (XSI) Map NL to CR-NL on output. | |
192 | .TP | |
193 | .B OCRNL | |
194 | Map CR to NL on output. | |
195 | .TP | |
196 | .B ONOCR | |
197 | Don't output CR at column 0. | |
198 | .TP | |
199 | .B ONLRET | |
200 | Don't output CR. | |
201 | .TP | |
202 | .B OFILL | |
203 | Send fill characters for a delay, rather than using a timed delay. | |
204 | .TP | |
205 | .B OFDEL | |
206 | (not in POSIX) Fill character is ASCII DEL (0177). | |
f81fb444 | 207 | If unset, fill character is ASCII NUL (\(aq\\0\(aq). |
42b09930 | 208 | (Not implemented on Linux.) |
fea681da MK |
209 | .TP |
210 | .B NLDLY | |
c13182ef MK |
211 | Newline delay mask. |
212 | Values are \fBNL0\fP and \fBNL1\fP. | |
db4e96b7 MK |
213 | [requires |
214 | .B _BSD_SOURCE | |
215 | or | |
216 | .B _SVID_SOURCE | |
c90511a6 MK |
217 | or |
218 | .BR _XOPEN_SOURCE ] | |
fea681da MK |
219 | .TP |
220 | .B CRDLY | |
221 | Carriage return delay mask. | |
222 | Values are \fBCR0\fP, \fBCR1\fP, \fBCR2\fP, or \fBCR3\fP. | |
db4e96b7 MK |
223 | [requires |
224 | .B _BSD_SOURCE | |
225 | or | |
226 | .B _SVID_SOURCE | |
c90511a6 MK |
227 | or |
228 | .BR _XOPEN_SOURCE ] | |
fea681da MK |
229 | .TP |
230 | .B TABDLY | |
231 | Horizontal tab delay mask. | |
232 | Values are \fBTAB0\fP, \fBTAB1\fP, \fBTAB2\fP, \fBTAB3\fP (or \fBXTABS\fP). | |
233 | A value of TAB3, that is, XTABS, expands tabs to spaces | |
234 | (with tab stops every eight columns). | |
db4e96b7 MK |
235 | [requires |
236 | .B _BSD_SOURCE | |
237 | or | |
238 | .B _SVID_SOURCE | |
c90511a6 MK |
239 | or |
240 | .BR _XOPEN_SOURCE ] | |
fea681da MK |
241 | .TP |
242 | .B BSDLY | |
c13182ef MK |
243 | Backspace delay mask. |
244 | Values are \fBBS0\fP or \fBBS1\fP. | |
fea681da | 245 | (Has never been implemented.) |
db4e96b7 MK |
246 | [requires |
247 | .B _BSD_SOURCE | |
248 | or | |
249 | .B _SVID_SOURCE | |
c90511a6 MK |
250 | or |
251 | .BR _XOPEN_SOURCE ] | |
fea681da MK |
252 | .TP |
253 | .B VTDLY | |
c13182ef MK |
254 | Vertical tab delay mask. |
255 | Values are \fBVT0\fP or \fBVT1\fP. | |
fea681da MK |
256 | .TP |
257 | .B FFDLY | |
c13182ef MK |
258 | Form feed delay mask. |
259 | Values are \fBFF0\fP or \fBFF1\fP. | |
db4e96b7 MK |
260 | [requires |
261 | .B _BSD_SOURCE | |
262 | or | |
263 | .B _SVID_SOURCE | |
c90511a6 MK |
264 | or |
265 | .BR _XOPEN_SOURCE ] | |
fea681da MK |
266 | .PP |
267 | \fIc_cflag\fP flag constants: | |
268 | .TP | |
269 | .B CBAUD | |
270 | (not in POSIX) Baud speed mask (4+1 bits). | |
db4e96b7 MK |
271 | [requires |
272 | .B _BSD_SOURCE | |
c90511a6 MK |
273 | or |
274 | .BR _SVID_SOURCE ] | |
fea681da MK |
275 | .TP |
276 | .B CBAUDEX | |
097585ed MK |
277 | (not in POSIX) Extra baud speed mask (1 bit), included in |
278 | .BR CBAUD . | |
db4e96b7 MK |
279 | [requires |
280 | .B _BSD_SOURCE | |
c90511a6 MK |
281 | or |
282 | .BR _SVID_SOURCE ] | |
42b09930 | 283 | .sp |
c13182ef MK |
284 | (POSIX says that the baud speed is stored in the |
285 | .I termios | |
42b09930 | 286 | structure without specifying where precisely, and provides |
63aa9df0 | 287 | .BR cfgetispeed () |
fea681da | 288 | and |
63aa9df0 | 289 | .BR cfsetispeed () |
c13182ef | 290 | for getting at it. |
097585ed MK |
291 | Some systems use bits selected by |
292 | .B CBAUD | |
293 | in | |
fea681da | 294 | .IR c_cflag , |
75b94dc3 | 295 | other systems use separate fields, for example, |
fea681da MK |
296 | .I sg_ispeed |
297 | and | |
298 | .IR sg_ospeed .) | |
299 | .TP | |
300 | .B CSIZE | |
301 | Character size mask. | |
302 | Values are \fBCS5\fP, \fBCS6\fP, \fBCS7\fP, or \fBCS8\fP. | |
303 | .TP | |
304 | .B CSTOPB | |
305 | Set two stop bits, rather than one. | |
306 | .TP | |
307 | .B CREAD | |
308 | Enable receiver. | |
309 | .TP | |
310 | .B PARENB | |
311 | Enable parity generation on output and parity checking for input. | |
312 | .TP | |
313 | .B PARODD | |
c13182ef | 314 | If set, then parity for input and output is odd; |
19ab0376 | 315 | otherwise even parity is used. |
fea681da MK |
316 | .TP |
317 | .B HUPCL | |
318 | Lower modem control lines after last process closes the device (hang up). | |
319 | .TP | |
320 | .B CLOCAL | |
321 | Ignore modem control lines. | |
322 | .TP | |
323 | .B LOBLK | |
c382a365 | 324 | (not in POSIX) Block output from a non-current shell layer. |
42b09930 | 325 | For use by \fBshl\fP (shell layers). (Not implemented on Linux.) |
fea681da MK |
326 | .TP |
327 | .B CIBAUD | |
4a837837 | 328 | (not in POSIX) Mask for input speeds. |
097585ed MK |
329 | The values for the |
330 | .B CIBAUD | |
331 | bits are | |
332 | the same as the values for the | |
333 | .B CBAUD | |
334 | bits, shifted left | |
335 | .B IBSHIFT | |
336 | bits. | |
db4e96b7 MK |
337 | [requires |
338 | .B _BSD_SOURCE | |
c90511a6 MK |
339 | or |
340 | .BR _SVID_SOURCE ] | |
42b09930 | 341 | (Not implemented on Linux.) |
fea681da | 342 | .TP |
adab6032 | 343 | .B CMSPAR |
ad715af9 | 344 | (not in POSIX) |
c13182ef | 345 | Use "stick" (mark/space) parity (supported on certain serial |
4a837837 | 346 | devices): if |
c13182ef | 347 | .B PARODD |
adab6032 | 348 | is set, the parity bit is always 1; if |
c13182ef | 349 | .B PARODD |
adab6032 | 350 | is not set, then the parity bit is always 0). |
db4e96b7 MK |
351 | [requires |
352 | .B _BSD_SOURCE | |
c90511a6 MK |
353 | or |
354 | .BR _SVID_SOURCE ] | |
adab6032 | 355 | .TP |
fea681da MK |
356 | .B CRTSCTS |
357 | (not in POSIX) Enable RTS/CTS (hardware) flow control. | |
db4e96b7 MK |
358 | [requires |
359 | .B _BSD_SOURCE | |
c90511a6 MK |
360 | or |
361 | .BR _SVID_SOURCE ] | |
fea681da MK |
362 | .PP |
363 | \fIc_lflag\fP flag constants: | |
364 | .TP | |
365 | .B ISIG | |
366 | When any of the characters INTR, QUIT, SUSP, or DSUSP are received, | |
367 | generate the corresponding signal. | |
368 | .TP | |
369 | .B ICANON | |
c13182ef | 370 | Enable canonical mode (described below). |
fea681da MK |
371 | .TP |
372 | .B XCASE | |
373 | (not in POSIX; not supported under Linux) | |
374 | If \fBICANON\fP is also set, terminal is uppercase only. | |
375 | Input is converted to lowercase, except for characters preceded by \\. | |
376 | On output, uppercase characters are preceded by \\ and lowercase | |
377 | characters are converted to uppercase. | |
eee28e75 | 378 | [requires _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE] |
c3dfd2c8 | 379 | .\" glibc is probably now wrong to allow |
eee28e75 MK |
380 | .\" Define |
381 | .\" .B _XOPEN_SOURCE | |
382 | .\" to expose | |
383 | .\" .BR XCASE . | |
fea681da MK |
384 | .TP |
385 | .B ECHO | |
386 | Echo input characters. | |
387 | .TP | |
388 | .B ECHOE | |
389 | If \fBICANON\fP is also set, the ERASE character erases the preceding | |
390 | input character, and WERASE erases the preceding word. | |
391 | .TP | |
392 | .B ECHOK | |
393 | If \fBICANON\fP is also set, the KILL character erases the current line. | |
394 | .TP | |
395 | .B ECHONL | |
396 | If \fBICANON\fP is also set, echo the NL character even if ECHO is not set. | |
397 | .TP | |
398 | .B ECHOCTL | |
399 | (not in POSIX) If \fBECHO\fP is also set, ASCII control signals other than | |
8bb93cd4 MK |
400 | TAB, NL, START, and STOP are echoed as \fB^X\fP, |
401 | where X is the character with | |
c13182ef MK |
402 | ASCII code 0x40 greater than the control signal. |
403 | For example, character | |
8bb93cd4 | 404 | 0x08 (BS) is echoed as \fB^H\fP. |
db4e96b7 MK |
405 | [requires |
406 | .B _BSD_SOURCE | |
c90511a6 MK |
407 | or |
408 | .BR _SVID_SOURCE ] | |
fea681da MK |
409 | .TP |
410 | .B ECHOPRT | |
411 | (not in POSIX) If \fBICANON\fP and \fBIECHO\fP are also set, characters | |
412 | are printed as they are being erased. | |
db4e96b7 MK |
413 | [requires |
414 | .B _BSD_SOURCE | |
c90511a6 MK |
415 | or |
416 | .BR _SVID_SOURCE ] | |
fea681da MK |
417 | .TP |
418 | .B ECHOKE | |
419 | (not in POSIX) If \fBICANON\fP is also set, KILL is echoed by erasing | |
420 | each character on the line, as specified by \fBECHOE\fP and \fBECHOPRT\fP. | |
db4e96b7 MK |
421 | [requires |
422 | .B _BSD_SOURCE | |
c90511a6 MK |
423 | or |
424 | .BR _SVID_SOURCE ] | |
fea681da MK |
425 | .TP |
426 | .B DEFECHO | |
427 | (not in POSIX) Echo only when a process is reading. | |
42b09930 | 428 | (Not implemented on Linux.) |
fea681da MK |
429 | .TP |
430 | .B FLUSHO | |
431 | (not in POSIX; not supported under Linux) | |
c13182ef MK |
432 | Output is being flushed. |
433 | This flag is toggled by typing | |
fea681da | 434 | the DISCARD character. |
db4e96b7 MK |
435 | [requires |
436 | .B _BSD_SOURCE | |
c90511a6 MK |
437 | or |
438 | .BR _SVID_SOURCE ] | |
fea681da MK |
439 | .TP |
440 | .B NOFLSH | |
8bd58774 MK |
441 | Disable flushing the input and output queues when generating the |
442 | .BR SIGINT , | |
988db661 | 443 | .BR SIGQUIT , |
8bd58774 MK |
444 | and |
445 | .B SIGSUSP | |
446 | signals. | |
fea681da MK |
447 | .\" Stevens lets SIGSUSP only flush the input queue |
448 | .TP | |
449 | .B TOSTOP | |
8bd58774 MK |
450 | Send the |
451 | .B SIGTTOU | |
452 | signal to the process group of a background process | |
fea681da MK |
453 | which tries to write to its controlling terminal. |
454 | .TP | |
455 | .B PENDIN | |
456 | (not in POSIX; not supported under Linux) | |
457 | All characters in the input queue are reprinted when | |
c13182ef | 458 | the next character is read. |
5852aba2 MK |
459 | .RB ( bash (1) |
460 | handles typeahead this way.) | |
db4e96b7 MK |
461 | [requires |
462 | .B _BSD_SOURCE | |
c90511a6 MK |
463 | or |
464 | .BR _SVID_SOURCE ] | |
fea681da MK |
465 | .TP |
466 | .B IEXTEN | |
467 | Enable implementation-defined input processing. | |
0425de01 | 468 | This flag, as well as \fBICANON\fP must be enabled for the |
fea681da MK |
469 | special characters EOL2, LNEXT, REPRINT, WERASE to be interpreted, |
470 | and for the \fBIUCLC\fP flag to be effective. | |
471 | .PP | |
472 | The \fIc_cc\fP array defines the special control characters. | |
473 | The symbolic indices (initial values) and meaning are: | |
474 | .TP | |
475 | .B VINTR | |
476 | (003, ETX, Ctrl-C, or also 0177, DEL, rubout) | |
c13182ef | 477 | Interrupt character. |
8bd58774 MK |
478 | Send a |
479 | .B SIGINT | |
480 | signal. | |
097585ed MK |
481 | Recognized when |
482 | .B ISIG | |
483 | is set, and then not passed as input. | |
fea681da MK |
484 | .TP |
485 | .B VQUIT | |
486 | (034, FS, Ctrl-\e) | |
c13182ef | 487 | Quit character. |
8bd58774 | 488 | Send |
0daa9e92 | 489 | .B SIGQUIT |
8bd58774 | 490 | signal. |
097585ed MK |
491 | Recognized when |
492 | .B ISIG | |
493 | is set, and then not passed as input. | |
fea681da MK |
494 | .TP |
495 | .B VERASE | |
496 | (0177, DEL, rubout, or 010, BS, Ctrl-H, or also #) | |
c13182ef MK |
497 | Erase character. |
498 | This erases the previous not-yet-erased character, | |
fea681da | 499 | but does not erase past EOF or beginning-of-line. |
097585ed MK |
500 | Recognized when |
501 | .B ICANON | |
502 | is set, and then not passed as input. | |
fea681da MK |
503 | .TP |
504 | .B VKILL | |
505 | (025, NAK, Ctrl-U, or Ctrl-X, or also @) | |
c13182ef | 506 | Kill character. |
19ab0376 | 507 | This erases the input since the last EOF or beginning-of-line. |
097585ed MK |
508 | Recognized when |
509 | .B ICANON | |
510 | is set, and then not passed as input. | |
fea681da MK |
511 | .TP |
512 | .B VEOF | |
513 | (004, EOT, Ctrl-D) | |
514 | End-of-file character. | |
515 | More precisely: this character causes the pending tty buffer to be sent | |
516 | to the waiting user program without waiting for end-of-line. | |
d9c1ae64 MK |
517 | If it is the first character of the line, the |
518 | .BR read (2) | |
519 | in the user program returns 0, which signifies end-of-file. | |
097585ed MK |
520 | Recognized when |
521 | .B ICANON | |
522 | is set, and then not passed as input. | |
fea681da MK |
523 | .TP |
524 | .B VMIN | |
525 | Minimum number of characters for non-canonical read. | |
526 | .TP | |
527 | .B VEOL | |
528 | (0, NUL) | |
529 | Additional end-of-line character. | |
097585ed MK |
530 | Recognized when |
531 | .B ICANON | |
532 | is set. | |
fea681da MK |
533 | .TP |
534 | .B VTIME | |
535 | Timeout in deciseconds for non-canonical read. | |
536 | .TP | |
537 | .B VEOL2 | |
538 | (not in POSIX; 0, NUL) | |
539 | Yet another end-of-line character. | |
097585ed MK |
540 | Recognized when |
541 | .B ICANON | |
542 | is set. | |
fea681da MK |
543 | .TP |
544 | .B VSWTCH | |
545 | (not in POSIX; not supported under Linux; 0, NUL) | |
c13182ef MK |
546 | Switch character. |
547 | (Used by \fBshl\fP only.) | |
fea681da MK |
548 | .TP |
549 | .B VSTART | |
550 | (021, DC1, Ctrl-Q) | |
c13182ef MK |
551 | Start character. |
552 | Restarts output stopped by the Stop character. | |
097585ed MK |
553 | Recognized when |
554 | .B IXON | |
555 | is set, and then not passed as input. | |
fea681da MK |
556 | .TP |
557 | .B VSTOP | |
558 | (023, DC3, Ctrl-S) | |
c13182ef MK |
559 | Stop character. |
560 | Stop output until Start character typed. | |
097585ed MK |
561 | Recognized when |
562 | .B IXON | |
563 | is set, and then not passed as input. | |
fea681da MK |
564 | .TP |
565 | .B VSUSP | |
566 | (032, SUB, Ctrl-Z) | |
c13182ef | 567 | Suspend character. |
8bd58774 MK |
568 | Send |
569 | .B SIGTSTP | |
570 | signal. | |
097585ed MK |
571 | Recognized when |
572 | .B ISIG | |
573 | is set, and then not passed as input. | |
fea681da MK |
574 | .TP |
575 | .B VDSUSP | |
576 | (not in POSIX; not supported under Linux; 031, EM, Ctrl-Y) | |
577 | Delayed suspend character: | |
8bd58774 MK |
578 | send |
579 | .B SIGTSTP | |
580 | signal when the character is read by the user program. | |
097585ed MK |
581 | Recognized when |
582 | .B IEXTEN | |
583 | and | |
74d32233 MK |
584 | .B ISIG |
585 | are set, and the system supports | |
fea681da MK |
586 | job control, and then not passed as input. |
587 | .TP | |
588 | .B VLNEXT | |
589 | (not in POSIX; 026, SYN, Ctrl-V) | |
c13182ef MK |
590 | Literal next. |
591 | Quotes the next input character, depriving it of | |
fea681da | 592 | a possible special meaning. |
097585ed MK |
593 | Recognized when |
594 | .B IEXTEN | |
595 | is set, and then not passed as input. | |
fea681da MK |
596 | .TP |
597 | .B VWERASE | |
598 | (not in POSIX; 027, ETB, Ctrl-W) | |
599 | Word erase. | |
097585ed MK |
600 | Recognized when |
601 | .B ICANON | |
602 | and | |
603 | .B IEXTEN | |
604 | are set, and then not passed as input. | |
fea681da MK |
605 | .TP |
606 | .B VREPRINT | |
607 | (not in POSIX; 022, DC2, Ctrl-R) | |
608 | Reprint unread characters. | |
097585ed MK |
609 | Recognized when |
610 | .B ICANON | |
611 | and | |
612 | .B IEXTEN | |
613 | are set, and then not passed as input. | |
fea681da MK |
614 | .TP |
615 | .B VDISCARD | |
616 | (not in POSIX; not supported under Linux; 017, SI, Ctrl-O) | |
617 | Toggle: start/stop discarding pending output. | |
097585ed MK |
618 | Recognized when |
619 | .B IEXTEN | |
620 | is set, and then not passed as input. | |
fea681da MK |
621 | .TP |
622 | .B VSTATUS | |
623 | (not in POSIX; not supported under Linux; | |
624 | status request: 024, DC4, Ctrl-T). | |
625 | .LP | |
626 | These symbolic subscript values are all different, except that | |
097585ed | 627 | .BR VTIME , |
0daa9e92 | 628 | .B VMIN |
097585ed MK |
629 | may have the same value as |
630 | .BR VEOL , | |
631 | .BR VEOF , | |
632 | respectively. | |
42b09930 | 633 | In non-canonical mode the special character meaning is replaced |
c13182ef | 634 | by the timeout meaning. |
097585ed MK |
635 | For an explanation of |
636 | .B VMIN | |
637 | and | |
638 | .BR VTIME , | |
639 | see the description of | |
19ab0376 | 640 | non-canonical mode below. |
87d1fd87 | 641 | .SS "Retrieving and changing terminal settings" |
fea681da | 642 | .PP |
63aa9df0 | 643 | .BR tcgetattr () |
fea681da | 644 | gets the parameters associated with the object referred by \fIfd\fP and |
869ebe5b | 645 | stores them in the \fItermios\fP structure referenced by |
c13182ef MK |
646 | \fItermios_p\fP. |
647 | This function may be invoked from a background process; | |
fea681da MK |
648 | however, the terminal attributes may be subsequently changed by a |
649 | foreground process. | |
650 | .LP | |
63aa9df0 | 651 | .BR tcsetattr () |
fea681da MK |
652 | sets the parameters associated with the terminal (unless support is |
653 | required from the underlying hardware that is not available) from the | |
c13182ef | 654 | \fItermios\fP structure referred to by \fItermios_p\fP. |
fea681da MK |
655 | \fIoptional_actions\fP specifies when the changes take effect: |
656 | .IP \fBTCSANOW\fP | |
657 | the change occurs immediately. | |
658 | .IP \fBTCSADRAIN\fP | |
659 | the change occurs after all output written to | |
660 | .I fd | |
c13182ef MK |
661 | has been transmitted. |
662 | This function should be used when changing | |
fea681da MK |
663 | parameters that affect output. |
664 | .IP \fBTCSAFLUSH\fP | |
665 | the change occurs after all output written to the object referred by | |
666 | .I fd | |
667 | has been transmitted, and all input that has been received but not read | |
668 | will be discarded before the change is made. | |
19ab0376 MK |
669 | .SS "Canonical and non-canonical mode" |
670 | The setting of the | |
671 | .B ICANON | |
672 | canon flag in | |
673 | .I c_lflag | |
674 | determines whether the terminal is operating in canonical mode | |
675 | .RB ( ICANON | |
676 | set) or | |
677 | non-canonical mode | |
c13182ef | 678 | .RB ( ICANON |
19ab0376 MK |
679 | unset). |
680 | By default, | |
681 | .B ICANON | |
682 | set. | |
683 | ||
684 | In canonical mode: | |
685 | .IP * 2 | |
686 | Input is made available line by line. | |
687 | An input line is available when one of the line delimiters | |
688 | is typed (NL, EOL, EOL2; or EOF at the start of line). | |
689 | Except in the case of EOF, the line delimiter is included | |
690 | in the buffer returned by | |
691 | .BR read (2). | |
692 | .IP * 2 | |
c13182ef MK |
693 | Line editing is enabled (ERASE, KILL; |
694 | and if the | |
19ab0376 MK |
695 | .B IEXTEN |
696 | flag is set: WERASE, REPRINT, LNEXT). | |
c13182ef | 697 | A |
fb186734 | 698 | .BR read (2) |
19ab0376 | 699 | returns at most one line of input; if the |
fb186734 | 700 | .BR read (2) |
19ab0376 MK |
701 | requested fewer bytes than are available in the current line of input, |
702 | then only as many bytes as requested are read, | |
703 | and the remaining characters will be available for a future | |
fb186734 | 704 | .BR read (2). |
19ab0376 | 705 | .PP |
c13182ef | 706 | In non-canonical mode input is available immediately (without |
19ab0376 MK |
707 | the user having to type a line-delimiter character), |
708 | and line editing is disabled. | |
c13182ef | 709 | The settings of MIN |
19ab0376 | 710 | .RI ( c_cc[VMIN] ) |
0f8b10eb | 711 | and TIME |
19ab0376 MK |
712 | .RI ( c_cc[VTIME] ) |
713 | determine the circumstances in which a | |
714 | .BR read (2) | |
715 | completes; there are four distinct cases: | |
716 | .IP * 2 | |
717 | MIN == 0; TIME == 0: | |
718 | If data is available, | |
fb186734 | 719 | .BR read (2) |
19ab0376 MK |
720 | returns immediately, with the lesser of the number of bytes |
721 | available, or the number of bytes requested. | |
722 | If no data is available, | |
fb186734 | 723 | .BR read (2) |
19ab0376 MK |
724 | returns 0. |
725 | .IP * 2 | |
726 | MIN > 0; TIME == 0: | |
fb186734 | 727 | .BR read (2) |
19ab0376 MK |
728 | blocks until the lesser of MIN bytes or the number of bytes requested |
729 | are available, and returns the lesser of these two values. | |
730 | .IP * 2 | |
731 | MIN == 0; TIME > 0: | |
732 | TIME specifies the limit for a timer in tenths of a second. | |
c13182ef | 733 | The timer is started when |
fb186734 | 734 | .BR read (2) |
19ab0376 | 735 | is called. |
fb186734 | 736 | .BR read (2) |
19ab0376 MK |
737 | returns either when at least one byte of data is available, |
738 | or when the timer expires. | |
739 | If the timer expires without any input becoming available, | |
fb186734 | 740 | .BR read (2) |
19ab0376 MK |
741 | returns 0. |
742 | .IP * 2 | |
743 | MIN > 0; TIME > 0: | |
744 | TIME specifies the limit for a timer in tenths of a second. | |
745 | Once an initial byte of input becomes available, | |
746 | the timer is restarted after each further byte is received. | |
fb186734 | 747 | .BR read (2) |
c13182ef | 748 | returns either when the lesser of the number of bytes requested or |
19ab0376 MK |
749 | MIN byte have been read, |
750 | or when the inter-byte timeout expires. | |
c13182ef | 751 | Because the timer is only started after the initial byte |
19ab0376 MK |
752 | becomes available, at least one byte will be read. |
753 | .SS "Raw mode" | |
754 | .LP | |
60a90ecd MK |
755 | .BR cfmakeraw () |
756 | sets the terminal to something like the | |
1954b6a9 | 757 | "raw" mode of the old Version 7 terminal driver: |
19ab0376 | 758 | input is available character by character, |
c13182ef | 759 | echoing is disabled, and all special processing of |
19ab0376 MK |
760 | terminal input and output characters is disabled. |
761 | The terminal attributes are set as follows: | |
762 | .nf | |
763 | ||
94e9d9fe | 764 | termios_p\->c_iflag &= ~(IGNBRK | BRKINT | PARMRK | ISTRIP |
19ab0376 | 765 | | INLCR | IGNCR | ICRNL | IXON); |
94e9d9fe MK |
766 | termios_p\->c_oflag &= ~OPOST; |
767 | termios_p\->c_lflag &= ~(ECHO | ECHONL | ICANON | ISIG | IEXTEN); | |
768 | termios_p\->c_cflag &= ~(CSIZE | PARENB); | |
769 | termios_p\->c_cflag |= CS8; | |
19ab0376 | 770 | .fi |
87d1fd87 | 771 | .SS "Line control" |
fea681da | 772 | .LP |
63aa9df0 | 773 | .BR tcsendbreak () |
fea681da MK |
774 | transmits a continuous stream of zero-valued bits for a specific |
775 | duration, if the terminal is using asynchronous serial data | |
c13182ef MK |
776 | transmission. |
777 | If \fIduration\fP is zero, it transmits zero-valued bits | |
778 | for at least 0.25 seconds, and not more that 0.5 seconds. | |
779 | If \fIduration\fP is not zero, it sends zero-valued bits for some | |
fea681da MK |
780 | implementation-defined length of time. |
781 | .LP | |
782 | If the terminal is not using asynchronous serial data transmission, | |
60a90ecd MK |
783 | .BR tcsendbreak () |
784 | returns without taking any action. | |
fea681da | 785 | .LP |
63aa9df0 | 786 | .BR tcdrain () |
fea681da MK |
787 | waits until all output written to the object referred to by |
788 | .I fd | |
789 | has been transmitted. | |
790 | .LP | |
63aa9df0 | 791 | .BR tcflush () |
fea681da MK |
792 | discards data written to the object referred to by |
793 | .I fd | |
794 | but not transmitted, or data received but not read, depending on the | |
795 | value of | |
796 | .IR queue_selector : | |
797 | .IP \fBTCIFLUSH\fP | |
798 | flushes data received but not read. | |
799 | .IP \fBTCOFLUSH\fP | |
800 | flushes data written but not transmitted. | |
801 | .IP \fBTCIOFLUSH\fP | |
802 | flushes both data received but not read, and data written but not | |
803 | transmitted. | |
804 | .LP | |
63aa9df0 | 805 | .BR tcflow () |
fea681da MK |
806 | suspends transmission or reception of data on the object referred to by |
807 | .IR fd , | |
808 | depending on the value of | |
809 | .IR action : | |
810 | .IP \fBTCOOFF\fP | |
811 | suspends output. | |
812 | .IP \fBTCOON\fP | |
813 | restarts suspended output. | |
814 | .IP \fBTCIOFF\fP | |
c13182ef | 815 | transmits a STOP character, which stops the terminal device from |
35478399 | 816 | transmitting data to the system. |
fea681da | 817 | .IP \fBTCION\fP |
c13182ef | 818 | transmits a START character, which starts the terminal device |
35478399 | 819 | transmitting data to the system. |
fea681da MK |
820 | .LP |
821 | The default on open of a terminal file is that neither its input nor its | |
822 | output is suspended. | |
87d1fd87 MK |
823 | .SS "Line speed" |
824 | The baud rate functions are provided for getting and setting the values | |
c13182ef MK |
825 | of the input and output baud rates in the \fItermios\fP structure. |
826 | The new values do not take effect | |
60a90ecd MK |
827 | until |
828 | .BR tcsetattr () | |
829 | is successfully called. | |
87d1fd87 MK |
830 | |
831 | Setting the speed to \fBB0\fP instructs the modem to "hang up". | |
832 | The actual bit rate corresponding to \fBB38400\fP may be altered with | |
60a90ecd | 833 | .BR setserial (8). |
87d1fd87 MK |
834 | .LP |
835 | The input and output baud rates are stored in the \fItermios\fP | |
836 | structure. | |
fea681da | 837 | .LP |
63aa9df0 | 838 | .BR cfgetospeed () |
869ebe5b | 839 | returns the output baud rate stored in the \fItermios\fP structure |
fea681da MK |
840 | pointed to by |
841 | .IR termios_p . | |
842 | .LP | |
63aa9df0 | 843 | .BR cfsetospeed () |
869ebe5b | 844 | sets the output baud rate stored in the \fItermios\fP structure pointed |
fea681da MK |
845 | to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: |
846 | .nf | |
869ebe5b | 847 | |
fea681da MK |
848 | .ft B |
849 | B0 | |
850 | B50 | |
851 | B75 | |
852 | B110 | |
853 | B134 | |
854 | B150 | |
855 | B200 | |
856 | B300 | |
857 | B600 | |
858 | B1200 | |
859 | B1800 | |
860 | B2400 | |
861 | B4800 | |
862 | B9600 | |
863 | B19200 | |
864 | B38400 | |
865 | B57600 | |
866 | B115200 | |
867 | B230400 | |
868 | .ft P | |
869ebe5b | 869 | |
fea681da MK |
870 | .fi |
871 | The zero baud rate, \fBB0\fP, | |
c13182ef MK |
872 | is used to terminate the connection. |
873 | If B0 is specified, the modem control lines shall no longer be asserted. | |
be7fff26 MK |
874 | Normally, this will disconnect the line. |
875 | \fBCBAUDEX\fP is a mask | |
fea681da | 876 | for the speeds beyond those defined in POSIX.1 (57600 and above). |
eba72288 | 877 | Thus, \fBB57600\fP & \fBCBAUDEX\fP is non-zero. |
fea681da | 878 | .LP |
63aa9df0 | 879 | .BR cfgetispeed () |
869ebe5b | 880 | returns the input baud rate stored in the \fItermios\fP structure. |
fea681da | 881 | .LP |
63aa9df0 | 882 | .BR cfsetispeed () |
869ebe5b | 883 | sets the input baud rate stored in the \fItermios\fP structure to |
c13182ef | 884 | .IR speed , |
869ebe5b MK |
885 | which must be specified as one of the \fBBnnn\fP constants listed above for |
886 | .BR cfsetospeed (). | |
fea681da MK |
887 | If the input baud rate is set to zero, the input baud rate will be |
888 | equal to the output baud rate. | |
889 | .LP | |
63aa9df0 | 890 | .BR cfsetspeed () |
c13182ef MK |
891 | is a 4.4BSD extension. |
892 | It takes the same arguments as | |
869ebe5b MK |
893 | .BR cfsetispeed (), |
894 | and sets both input and output speed. | |
fea681da MK |
895 | .SH "RETURN VALUE" |
896 | .LP | |
63aa9df0 | 897 | .BR cfgetispeed () |
fea681da | 898 | returns the input baud rate stored in the |
869ebe5b | 899 | \fItermios\fP |
fea681da MK |
900 | structure. |
901 | .LP | |
63aa9df0 | 902 | .BR cfgetospeed () |
869ebe5b | 903 | returns the output baud rate stored in the \fItermios\fP structure. |
fea681da MK |
904 | .LP |
905 | All other functions return: | |
906 | .IP 0 | |
907 | on success. | |
908 | .IP \-1 | |
909 | on failure and set | |
910 | .I errno | |
911 | to indicate the error. | |
912 | .LP | |
913 | Note that | |
f87925c6 | 914 | .BR tcsetattr () |
fea681da | 915 | returns success if \fIany\fP of the requested changes could be |
c13182ef MK |
916 | successfully carried out. |
917 | Therefore, when making multiple changes | |
fea681da | 918 | it may be necessary to follow this call with a further call to |
f87925c6 | 919 | .BR tcgetattr () |
fea681da | 920 | to check that all changes have been performed successfully. |
dfb631a8 MK |
921 | .SH CONFORMING TO |
922 | .BR tcgetattr (), | |
923 | .BR tcsetattr (), | |
924 | .BR tcsendbreak (), | |
925 | .BR tcdrain (), | |
926 | .BR tcflush (), | |
927 | .BR tcflow (), | |
928 | .BR cfgetispeed (), | |
929 | .BR cfgetospeed (), | |
930 | .BR cfsetispeed (), | |
931 | and | |
932 | .BR cfsetospeed () | |
933 | are specified in POSIX.1-2001. | |
934 | ||
935 | .BR cfmakeraw () | |
01d5d366 MK |
936 | and |
937 | .BR cfsetspeed () | |
938 | are non-standard, but available on the BSDs. | |
fea681da MK |
939 | .SH NOTES |
940 | Unix V7 and several later systems have a list of baud rates | |
941 | where after the fourteen values B0, ..., B9600 one finds the | |
942 | two constants EXTA, EXTB ("External A" and "External B"). | |
943 | Many systems extend the list with much higher baud rates. | |
944 | .LP | |
eba72288 | 945 | The effect of a non-zero \fIduration\fP with |
60a90ecd MK |
946 | .BR tcsendbreak () |
947 | varies. | |
c13182ef | 948 | SunOS specifies a break of |
8b8d0001 | 949 | .I "duration\ *\ N" |
fea681da MK |
950 | seconds, where \fIN\fP is at least 0.25, and not more than 0.5. |
951 | Linux, AIX, DU, Tru64 send a break of | |
952 | .I duration | |
953 | milliseconds. | |
954 | FreeBSD and NetBSD and HP-UX and MacOS ignore the value of | |
955 | .IR duration . | |
956 | Under Solaris and Unixware, | |
e511ffb6 | 957 | .BR tcsendbreak () |
eba72288 | 958 | with non-zero |
fea681da MK |
959 | .I duration |
960 | behaves like | |
e511ffb6 | 961 | .BR tcdrain (). |
fea681da MK |
962 | .\" libc4 until 4.7.5, glibc for sysv: EINVAL for duration > 0. |
963 | .\" libc4.7.6, libc5, glibc for unix: duration in ms. | |
964 | .\" glibc for bsd: duration in us | |
965 | .\" glibc for sunos4: ignore duration | |
966 | .SH "SEE ALSO" | |
967 | .BR stty (1), | |
fe62e3de MK |
968 | .BR console_ioctl (4), |
969 | .BR tty_ioctl (4), | |
fea681da | 970 | .BR setserial (8) |