1termio(7I) Ioctl Requests termio(7I)
2
6 termio - general terminal interface
7
9 #include <termio.h>
10 ioctl(int fildes, int request, struct termio *arg);
12 ioctl(int fildes, int request, int arg);
15 #include <termios.h>
18 ioctl(int fildes, int request, struct termios *arg);
20
23 This release supports a general interface for asynchronous communica‐
24 tions ports that is hardware-independent. The user interface to this
25 functionality is using function calls (the preferred interface)
26 described in termios(3C) or ioctl commands described in this section.
27 This section also discusses the common features of the terminal sub‐
28 system which are relevant with both user interfaces.
29 When a terminal file is opened, it normally causes the process to wait
32 until a connection is established. In practice, user programs seldom
33 open terminal files; they are opened by the system and become a user's
34 standard input, output, and error files. The first terminal file opened
35 by the session leader that is not already associated with a session
36 becomes the controlling terminal for that session. The controlling ter‐
37 minal plays a special role in handling quit and interrupt signals, as
38 discussed below. The controlling terminal is inherited by a child
39 process during a fork(2). A process can break this association by
40 changing its session using setsid() (see setsid(2)).
41 A terminal associated with one of these files ordinarily operates in
44 full-duplex mode. Characters may be typed at any time, even while out‐
45 put is occurring, and are only lost when the character input buffers of
46 the system become completely full, which is rare. For example, the num‐
47 ber of characters in the line discipline buffer may exceed {MAX_CANON}
48 and IMAXBEL (see below) is not set, or the user may accumulate {
49 MAX_INPUT} number of input characters that have not yet been read by
50 some program. When the input limit is reached, all the characters saved
51 in the buffer up to that point are thrown away without notice.
52 Session Management (Job Control)
54 A control terminal will distinguish one of the process groups in the
55 session associated with it to be the foreground process group. All
56 other process groups in the session are designated as background
57 process groups. This foreground process group plays a special role in
58 handling signal-generating input characters, as discussed below. By
59 default, when a controlling terminal is allocated, the controlling
60 process's process group is assigned as foreground process group.
61 Background process groups in the controlling process's session are sub‐
64 ject to a job control line discipline when they attempt to access their
65 controlling terminal. Process groups can be sent signals that will
66 cause them to stop, unless they have made other arrangements. An excep‐
67 tion is made for members of orphaned process groups.
68 An orphaned process group is one where the process group (see
71 getpgid(2)) has no members with a parent in a different process group
72 but sharing the same controlling terminal. When a member of an orphaned
73 process group attempts to access its controlling terminal, EIO is
74 returned because there would be no way to restart the process if it
75 were stopped on one of these signals.
76 If a member of a background process group attempts to read its control‐
79 ling terminal, its process group will be sent a SIGTTIN signal, which
80 will normally cause the members of that process group to stop. If, how‐
81 ever, the process is ignoring or holding SIGTTIN, or is a member of an
82 orphaned process group, the read will fail with errno set to EIO, and
83 no signal is sent.
84 If a member of a background process group attempts to write its con‐
87 trolling terminal and the TOSTOP bit is set in the c_lflag field, its
88 process group is sent a SIGTTOU signal, which will normally cause the
89 members of that process group to stop. If, however, the process is
90 ignoring or holding SIGTTOU, the write will succeed. If the process is
91 not ignoring or holding SIGTTOU and is a member of an orphaned process
92 group, the write will fail with errno set to EIO, and no signal will
93 be sent.
94 If TOSTOP is set and a member of a background process group attempts
97 to ioctl its controlling terminal, and that ioctl will modify terminal
98 parameters (for example, TCSETA, TCSETAW, TCSETAF, or TIOCSPGRP), its
99 process group will be sent a SIGTTOU signal, which will normally cause
100 the members of that process group to stop. If, however, the process is
101 ignoring or holding SIGTTOU, the ioctl will succeed. If the process is
102 not ignoring or holding SIGTTOU and is a member of an orphaned process
103 group, the write will fail with errno set to EIO, and no signal will
104 be sent.
105 Canonical Mode Input Processing
107 Normally, terminal input is processed in units of lines. A line is
108 delimited by a newline (ASCII LF) character, an end-of-file (ASCII EOT)
109 character, or an end-of-line character. This means that a program
110 attempting to read will block until an entire line has been typed.
111 Also, no matter how many characters are requested in the read call, at
112 most one line will be returned. It is not necessary, however, to read a
113 whole line at once; any number of characters may be requested in a
114 read, even one, without losing information.
115 During input, erase and kill processing is normally done. The ERASE
118 character (by default, the character DEL) erases the last character
119 typed. The WERASE character (the character Control-w) erases the last
120 "word" typed in the current input line (but not any preceding spaces or
121 tabs). A "word" is defined as a sequence of non-blank characters, with
122 tabs counted as blanks. Neither ERASE nor WERASE will erase beyond the
123 beginning of the line. The KILL character (by default, the character
124 NAK) kills (deletes) the entire input line, and optionally outputs a
125 newline character. All these characters operate on a key stroke basis,
126 independent of any backspacing or tabbing that may have been done. The
127 REPRINT character (the character Control-r) prints a newline followed
128 by all characters that have not been read. Reprinting also occurs auto‐
129 matically if characters that would normally be erased from the screen
130 are fouled by program output. The characters are reprinted as if they
131 were being echoed; consequencely, if ECHO is not set, they are not
132 printed.
133 The ERASE and KILL characters may be entered literally by preceding
136 them with the escape character. In this case, the escape character is
137 not read. The erase and kill characters may be changed.
138 Non-canonical Mode Input Processing
140 In non-canonical mode input processing, input characters are not assem‐
141 bled into lines, and erase and kill processing does not occur. The MIN
142 and TIME values are used to determine how to process the characters
143 received.
144 MIN represents the minimum number of characters that should be received
147 when the read is satisfied (that is, when the characters are returned
148 to the user). TIME is a timer of 0.10-second granularity that is used
149 to timeout bursty and short-term data transmissions. The four possible
150 values for MIN and TIME and their interactions are described below.
151 Case A: MIN > 0, TIME > 0 In this case, TIME serves as an interchar‐
153 acter timer and is activated after the
154 first character is received. Since it is
155 an intercharacter timer, it is reset after
156 a character is received. The interaction
157 between MIN and TIME is as follows: as
158 soon as one character is received, the
159 intercharacter timer is started. If MIN
160 characters are received before the inter‐
161 character timer expires (note that the
162 timer is reset upon receipt of each char‐
163 acter), the read is satisfied. If the
164 timer expires before MIN characters are
165 received, the characters received to that
166 point are returned to the user. Note that
167 if TIME expires, at least one character
168 will be returned because the timer would
169 not have been enabled unless a character
170 was received. In this case (MIN > 0, TIME
171 > 0), the read sleeps until the MIN and
172 TIME mechanisms are activated by the
173 receipt of the first character. If the
174 number of characters read is less than the
175 number of characters available, the timer
176 is not reactivated and the subsequent read
177 is satisfied immediately.
178 Case B: MIN > 0, TIME = 0 In this case, since the value of TIME is
181 zero, the timer plays no role and only MIN
182 is significant. A pending read is not
183 satisfied until MIN characters are
184 received (the pending read sleeps until
185 MIN characters are received). A program
186 that uses this case to read record based
187 terminal I/O may block indefinitely in the
188 read operation.
189 Case C: MIN = 0, TIME > 0 In this case, since MIN = 0, TIME no
192 longer represents an intercharacter
193 timer: it now serves as a read timer that
194 is activated as soon as a read is done. A
195 read is satisfied as soon as a single
196 character is received or the read timer
197 expires. Note that, in this case, if the
198 timer expires, no character is returned.
199 If the timer does not expire, the only way
200 the read can be satisfied is if a charac‐
201 ter is received. In this case, the read
202 will not block indefinitely waiting for a
203 character; if no character is received
204 within TIME *.10 seconds after the read is
205 initiated, the read returns with zero
206 characters.
207 Case D: MIN = 0, TIME = 0 In this case, return is immediate. The
210 minimum of either the number of characters
211 requested or the number of characters cur‐
212 rently available is returned without wait‐
213 ing for more characters to be input.
214 Comparing Different Cases of MIN, TIME Interaction
217 Some points to note about MIN and TIME :
218 o In the following explanations, note that the interactions of
220 MIN and TIME are not symmetric. For example, when MIN > 0
221 and TIME = 0, TIME has no effect. However, in the opposite
222 case, where MIN = 0 and TIME > 0, both MIN and TIME play
223 a role in that MIN is satisfied with the receipt of a single
224 character.
225 o Also note that in case A (MIN > 0, TIME > 0), TIME repre‐
227 sents an intercharacter timer, whereas in case C ( MIN = 0,
228 TIME > 0), TIME represents a read timer.
229 These two points highlight the dual purpose of the MIN/TIME feature.
232 Cases A and B, where MIN > 0, exist to handle burst mode activity (for
233 example, file transfer programs), where a program would like to process
234 at least MIN characters at a time. In case A, the intercharacter timer
235 is activated by a user as a safety measure; in case B, the timer is
236 turned off.
237 Cases C and D exist to handle single character, timed transfers. These
240 cases are readily adaptable to screen-based applications that need to
241 know if a character is present in the input queue before refreshing the
242 screen. In case C, the read is timed, whereas in case D, it is not.
243 Another important note is that MIN is always just a minimum. It does
246 not denote a record length. For example, if a program does a read of 20
247 bytes, MIN is 10, and 25 characters are present, then 20 characters
248 will be returned to the user.
249 Writing Characters
251 When one or more characters are written, they are transmitted to the
252 terminal as soon as previously written characters have finished typing.
253 Input characters are echoed as they are typed if echoing has been
254 enabled. If a process produces characters more rapidly than they can be
255 typed, it will be suspended when its output queue exceeds some limit.
256 When the queue is drained down to some threshold, the program is
257 resumed.
258 Special Characters
260 Certain characters have special functions on input. These functions and
261 their default character values are summarized as follows:
262 INTR (Control-c or ASCII ETX) generates a SIGINT signal. SIGINT
264 is sent to all foreground processes associated with the con‐
265 trolling terminal. Normally, each such process is forced to
266 terminate, but arrangements may be made either to ignore the
267 signal or to receive a trap to an agreed upon location. (See
268 signal.h(3HEAD)).
269 QUIT (Control-| or ASCII FS) generates a SIGQUIT signal. Its
272 treatment is identical to the interrupt signal except that,
273 unless a receiving process has made other arrangements, it
274 will not only be terminated but a core image file (called
275 core) will be created in the current working directory.
276 ERASE (DEL) erases the preceding character. It does not erase
279 beyond the start of a line, as delimited by a NL, EOF, EOL,
280 or EOL2 character.
281 WERASE (Control-w or ASCII ETX) erases the preceding "word". It
284 does not erase beyond the start of a line, as delimited by a
285 NL, EOF, EOL, or EOL2 character.
286 KILL (Control-u or ASCII NAK) deletes the entire line, as delim‐
289 ited by a NL, EOF, EOL, or EOL2 character.
290 REPRINT (Control-r or ASCII DC2) reprints all characters, preceded
293 by a newline, that have not been read.
294 EOF (Control-d or ASCII EOT) may be used to generate an end-of-
297 file from a terminal. When received, all the characters
298 waiting to be read are immediately passed to the program,
299 without waiting for a newline, and the EOF is discarded.
300 Thus, if no characters are waiting (that is, the EOF
301 occurred at the beginning of a line) zero characters are
302 passed back, which is the standard end-of-file indication.
303 Unless escaped, the EOF character is not echoed. Because EOT
304 is the default EOF character, this prevents terminals that
305 respond to EOT from hanging up.
306 NL (ASCII LF) is the normal line delimiter. It cannot be
309 changed or escaped.
310 EOL (ASCII NULL) is an additional line delimiter, like NL . It
313 is not normally used.
314 EOL2 is another additional line delimiter.
317 SWTCH (Control-z or ASCII EM) Header file symbols related to this
320 special character are present for compatibility purposes
321 only and the kernel takes no special action on matching
322 SWTCH (except to discard the character).
323 SUSP (Control-z or ASCII SUB) generates a SIGTSTP signal. SIGT‐
326 STP stops all processes in the foreground process group for
327 that terminal.
328 DSUSP (Control-y or ASCII EM). It generates a SIGTSTP signal as
331 SUSP does, but the signal is sent when a process in the
332 foreground process group attempts to read the DSUSP charac‐
333 ter, rather than when it is typed.
334 STOP (Control-s or ASCII DC3) can be used to suspend output tem‐
337 porarily. It is useful with CRT terminals to prevent output
338 from disappearing before it can be read. While output is
339 suspended, STOP characters are ignored and not read.
340 START (Control-q or ASCII DC1) is used to resume output. Output
343 has been suspended by a STOP character. While output is not
344 suspended, START characters are ignored and not read.
345 DISCARD (Control-o or ASCII SI) causes subsequent output to be dis‐
348 carded. Output is discarded until another DISCARD character
349 is typed, more input arrives, or the condition is cleared
350 by a program.
351 LNEXT (Control-v or ASCII SYN) causes the special meaning of the
354 next character to be ignored. This works for all the spe‐
355 cial characters mentioned above. It allows characters to be
356 input that would otherwise be interpreted by the system (for
357 example KILL, QUIT). The character values for INTR, QUIT,
358 ERASE, WERASE, KILL, REPRINT, EOF, EOL, EOL2, SWTCH, SUSP,
359 DSUSP, STOP, START, DISCARD, and LNEXT may be changed to
360 suit individual tastes. If the value of a special control
361 character is _POSIX_VDISABLE (0), the function of that spe‐
362 cial control character is disabled. The ERASE, KILL, and EOF
363 characters may be escaped by a preceding backslash (\) char‐
364 acter, in which case no special function is done. Any of the
365 special characters may be preceded by the LNEXT character,
366 in which case no special function is done.
367 Modem Disconnect
370 When a modem disconnect is detected, a SIGHUP signal is sent to the
371 terminal's controlling process. Unless other arrangements have been
372 made, these signals cause the process to terminate. If SIGHUP is
373 ignored or caught, any subsequent read returns with an end-of-file
374 indication until the terminal is closed.
375 If the controlling process is not in the foreground process group of
378 the terminal, a SIGTSTP is sent to the terminal's foreground process
379 group. Unless other arrangements have been made, these signals cause
380 the processes to stop.
381 Processes in background process groups that attempt to access the con‐
384 trolling terminal after modem disconnect while the terminal is still
385 allocated to the session will receive appropriate SIGTTOU and SIGTTIN
386 signals. Unless other arrangements have been made, this signal causes
387 the processes to stop.
388 The controlling terminal will remain in this state until it is reini‐
391 tialized with a successful open by the controlling process, or deallo‐
392 cated by the controlling process.
393 Terminal Parameters
395 The parameters that control the behavior of devices and modules provid‐
396 ing the termios interface are specified by the termios structure
397 defined by termios.h. Several ioctl(2) system calls that fetch or
398 change these parameters use this structure that contains the following
399 members:
400 tcflag_t c_iflag; /* input modes */
402 tcflag_t c_oflag; /* output modes */
403 tcflag_t c_cflag; /* control modes */
404 tcflag_t c_lflag; /* local modes */
405 cc_t c_cc[NCCS]; /* control chars */
406 The special control characters are defined by the array c_cc. The sym‐
410 bolic name NCCS is the size of the Control-character array and is also
411 defined by <termios.h>. The relative positions, subscript names, and
412 typical default values for each function are as follows:
413 ┌────────────────────┬────────────────────┬───────────────────────┐
418 │Relative Position │ Subscript Name │ Typical Default Value │
419 ├────────────────────┼────────────────────┼───────────────────────┤
420 │0 │VINTR │ ETX │
421 ├────────────────────┼────────────────────┼───────────────────────┤
422 │1 │VQUIT │ FS │
423 ├────────────────────┼────────────────────┼───────────────────────┤
424 │2 │VERASE │ DEL │
425 ├────────────────────┼────────────────────┼───────────────────────┤
426 │3 │VKILL │ NAK │
427 ├────────────────────┼────────────────────┼───────────────────────┤
428 │4 │VEOF │ EOT │
429 ├────────────────────┼────────────────────┼───────────────────────┤
430 │5 │VEOL │ NUL │
431 ├────────────────────┼────────────────────┼───────────────────────┤
432 │6 │VEOL2 │ NUL │
433 ├────────────────────┼────────────────────┼───────────────────────┤
434 │7 │VWSTCH │ NUL │
435 ├────────────────────┼────────────────────┼───────────────────────┤
436 │8 │VSTART │ NUL │
437 ├────────────────────┼────────────────────┼───────────────────────┤
438 │9 │VSTOP │ DC3 │
439 ├────────────────────┼────────────────────┼───────────────────────┤
440 │10 │VSUSP │ SUB │
441 ├────────────────────┼────────────────────┼───────────────────────┤
442 │11 │VDSUSP │ EM │
443 ├────────────────────┼────────────────────┼───────────────────────┤
444 │12 │VREPRINT │ DC2 │
445 ├────────────────────┼────────────────────┼───────────────────────┤
446 │13 │VDISCARD │ SI │
447 ├────────────────────┼────────────────────┼───────────────────────┤
448 │14 │VWERASE │ ETB │
449 ├────────────────────┼────────────────────┼───────────────────────┤
450 │15 │VLNEXT │ SYN │
451 ├────────────────────┼────────────────────┼───────────────────────┤
452 │16-19 │Reserved │ │
453 └────────────────────┴────────────────────┴───────────────────────┘
454 Input Modes
456 The c_iflag field describes the basic terminal input control:
457 IGNBRK Ignore break condition.
459 BRKINT Signal interrupt on break.
462 IGNPAR Ignore characters with parity errors.
465 PARMRK Mark parity errors.
468 INPCK Enable input parity check.
471 ISTRIP Strip character.
474 INLCR Map NL to CR on input.
477 IGNCR Ignore CR.
480 ICRNL Map CR to NL on input.
483 IUCLC Map upper-case to lower-case on input.
486 IXON Enable start/stop output control.
489 IXANY Enable any character to restart output.
492 IXOFF Enable start/stop input control.
495 IMAXBEL Echo BEL on input line too long.
498 If IGNBRK is set, a break condition (a character framing error with
502 data all zeros) detected on input is ignored, that is, not put on the
503 input queue and therefore not read by any process. If IGNBRK is not set
504 and BRKINT is set, the break condition shall flush the input and output
505 queues and if the terminal is the controlling terminal of a foreground
506 process group, the break condition generates a single SIGINT signal to
507 that foreground process group. If neither IGNBRK nor BRKINT is set, a
508 break condition is read as a single '\0' (ASCII NULL) character, or if
509 PARMRK is set, as '\377', '\0', c, where '\377' is a single character
510 with value 377 octal (0xff hex, 255 decimal), '\0' is a single charac‐
511 ter with value 0, and c is the errored character received.
512 If IGNPAR is set, a byte with framing or parity errors (other than
515 break) is ignored.
516 If PARMRK is set, and IGNPAR is not set, a byte with a framing or par‐
519 ity error (other than break) is given to the application as the three-
520 character sequence: '\377', '\0', c, where '\377' is a single character
521 with value 377 octal (0xff hex, 255 decimal), '\0' is a single charac‐
522 ter with value 0, and c is the errored character received. To avoid
523 ambiguity in this case, if ISTRIP is not set, a valid character of
524 '\377' is given to the application as `\377.' If neither IGNPAR nor
525 PARMRK is set, a framing or parity error (other than break) is given to
526 the application as a single '\0' (ASCII NULL) character.
527 If INPCK is set, input parity checking is enabled. If INPCK is not set,
530 input parity checking is disabled. This allows output parity generation
531 without input parity errors. Note that whether input parity checking
532 is enabled or disabled is independent of whether parity detection is
533 enabled or disabled. If parity detection is enabled but input parity
534 checking is disabled, the hardware to which the terminal is connected
535 will recognize the parity bit, but the terminal special file will not
536 check whether this is set correctly or not.
537 If ISTRIP is set, valid input characters are first stripped to seven
540 bits, otherwise all eight bits are processed.
541 If INLCR is set, a received NL character is translated into a CR char‐
544 acter. If IGNCR is set, a received CR character is ignored (not
545 read). Otherwise, if ICRNL is set, a received CR character is trans‐
546 lated into a NL character.
547 If IUCLC is set, a received upper case, alphabetic character is trans‐
550 lated into the corresponding lower case character.
551 If IXON is set, start/stop output control is enabled. A received STOP
554 character suspends output and a received START character restarts out‐
555 put. The STOP and START characters will not be read, but will merely
556 perform flow control functions. If IXANY is set, any input character
557 restarts output that has been suspended.
558 If IXOFF is set, the system transmits a STOP character when the input
561 queue is nearly full, and a START character when enough input has been
562 read so that the input queue is nearly empty again.
563 If IMAXBEL is set, the ASCII BEL character is echoed if the input
566 stream overflows. Further input is not stored, but any input already
567 present in the input stream is not disturbed. If IMAXBEL is not set,
568 no BEL character is echoed, and all input present in the input queue is
569 discarded if the input stream overflows.
570 Output Modes
572 The c_oflag field specifies the system treatment of output:
573 OPOST Post-process output.
575 OLCUC Map lower case to upper on output.
578 ONLCR Map NL to CR-NL on output.
581 OCRNL Map CR to NL on output.
584 ONOCR No CR output at column 0.
587 ONLRET NL performs CR function.
590 OFILL Use fill characters for delay.
593 OFDEL Fill is DEL, else NULL.
596 NLDLY Select newline delays:
599 NL0
600 NL1
601 CRDLY Select carriage-return delays:
604 CR0
605 CR1
606 CR2
607 CR3
608 TABDLY Select horizontal tab delays or tab expansion:
611 TAB0
613 TAB1
616 TAB2
619 TAB3 Expand tabs to spaces
622 XTABS Expand tabs to spaces
625 BSDLY Select backspace delays:
629 BS0
630 BS1
631 VTDLY Select vertical tab delays:
634 VT0
635 VT1
636 FFDLY Select form feed delays:
639 FF0
640 FF1
641 If OPOST is set, output characters are post-processed as indicated by
645 the remaining flags; otherwise, characters are transmitted without
646 change.
647 If OLCUC is set, a lower case alphabetic character is transmitted as
650 the corresponding upper case character. This function is often used in
651 conjunction with IUCLC.
652 If ONLCR is set, the NL character is transmitted as the CR-NL character
655 pair. If OCRNL is set, the CR character is transmitted as the NL
656 character. If ONOCR is set, no CR character is transmitted when at
657 column 0 (first position). If ONRET is set, the NL character is
658 assumed to do the carriage-return function; the column pointer is set
659 to 0 and the delays specified for CR are used. Otherwise, the NL char‐
660 acter is assumed to do just the line-feed function; the column pointer
661 remains unchanged. The column pointer is also set to 0 if the CR char‐
662 acter is actually transmitted.
663 The delay bits specify how long transmission stops to allow for mechan‐
666 ical or other movement when certain characters are sent to the termi‐
667 nal. In all cases, a value of 0 indicates no delay. If OFILL is set,
668 fill characters are transmitted for delay instead of a timed delay.
669 This is useful for high baud rate terminals that need only a minimal
670 delay. If OFDEL is set, the fill character is DEL ; otherwise it is
671 NULL.
672 If a form-feed or vertical-tab delay is specified, it lasts for about 2
675 seconds.
676 Newline delay lasts about 0.10 seconds. If ONLRET is set, the carriage-
679 return delays are used instead of the newline delays. If OFILL is set,
680 two fill characters are transmitted.
681 Carriage-return delay type 1 is dependent on the current column posi‐
684 tion, type 2 is about 0.10 seconds, and type 3 is about 0.15 seconds.
685 If OFILL is set, delay type 1 transmits two fill characters, and type
686 2 transmits four fill characters.
687 Horizontal-tab delay type 1 is dependent on the current column posi‐
690 tion. Type 2 is about 0.10 seconds. Type 3 specifies that tabs are to
691 be expanded into spaces. If OFILL is set, two fill characters are
692 transmitted for any delay.
693 Backspace delay lasts about 0.05 seconds. If OFILL is set, one fill
696 character is transmitted.
697 The actual delays depend on line speed and system load.
700 Control Modes
702 The c_cflag field describes the hardware control of the terminal:
703 CBAUD Baud rate:
705 B0 Hang up
708 B50 50 baud
711 B75 75 baud
714 B110 110 baud
717 B134 134 baud
720 B150 150 baud
723 B200 200 baud
726 B300 300 baud
729 B600 600 baud
732 B1200 1200 baud
735 B1800 1800 baud
738 B2400 2400 baud
741 B4800 4800 baud
744 B9600 9600 baud
747 B19200 19200 baud
750 EXTA External A
753 B38400 38400 baud
756 EXTB External B
759 B57600 57600 baud
762 B76800 76800 baud
765 B115200 115200 baud
768 B153600 153600 baud
771 B230400 230400 baud
774 B307200 307200 baud
777 B460800 460800 baud
780 CSIZE Character size:
783 CS5 5 bits
786 CS6 6 bits
789 CS7 7 bits
792 CS8 8 bits
795 CSTOPB Send two stop bits, else one
798 CREAD Enable receiver
801 PARENB Parity enable
804 PARODD Odd parity, else even
807 HUPCL Hang up on last close
810 CLOCAL Local line, else dial-up
813 CIBAUD Input baud rate, if different from output rate
816 PAREXT Extended parity for mark and space parity
819 CRTSXOFF Enable inbound hardware flow control
822 CRTSCTS Enable outbound hardware flow control
825 CBAUDEXT Bit to indicate output speed > B38400
828 CIBAUDEXT Bit to indicate input speed > B38400
831 The CBAUD bits together with the CBAUDEXT bit specify the output baud
835 rate. To retrieve the output speed from the termios structure pointed
836 to by termios_p see the following code segment.
837 speed_t ospeed;
839 if (termios_p->c_cflag & CBAUDEXT)
840 ospeed = (termios_p->c_cflag & CBAUD) + CBAUD + 1;
841 else
842 ospeed = termios_p->c_cflag & CBAUD;
843 To store the output speed in the termios structure pointed to by
847 termios_p see the following code segment.
848 speed_t ospeed;
850 if (ospeed > CBAUD) {
851 termios_p->c_cflag |= CBAUDEXT;
852 ospeed -= (CBAUD + 1);
853 } else
854 termios_p->c_cflag &= ~CBAUDEXT;
855 termios_p->c_cflag =
856 (termios_p->c_cflag & ~CBAUD) | (ospeed & CBAUD);
857 The zero baud rate, B0, is used to hang up the connection. If B0 is
861 specified, the data-terminal-ready signal is not asserted. Normally,
862 this disconnects the line.
863 If the CIBAUDEXT or CIBAUD bits are not zero, they specify the input
866 baud rate, with the CBAUDEXT and CBAUD bits specifying the output baud
867 rate; otherwise, the output and input baud rates are both specified by
868 the CBAUDEXT and CBAUD bits. The values for the CIBAUD bits are the
869 same as the values for the CBAUD bits, shifted left IBSHIFT bits. For
870 any particular hardware, impossible speed changes are ignored. To
871 retrieve the input speed in the termios structure pointed to by
872 termios_p see the following code segment.
873 speed_t ispeed;
875 if (termios_p->c_cflag & CIBAUDEXT)
876 ispeed = ((termios_p->c_cflag & CIBAUD) >> IBSHIFT)
877 + (CIBAUD >> IBSHIFT) + 1;
878 else
879 ispeed = (termios_p->c_cflag & CIBAUD) >> IBSHIFT;
880 To store the input speed in the termios structure pointed to by
884 termios_p see the following code segment.
885 speed_t ispeed;
887 if (ispeed == 0) {
888 ispeed = termios_p->c_cflag & CBAUD;
889 if (termios_p->c_cflag & CBAUDEXT)
890 ispeed += (CBAUD + 1);
891 }
892 if ((ispeed << IBSHIFT) > CIBAUD) {
893 termios_p->c_cflag |= CIBAUDEXT;
894 ispeed -= ((CIBAUD >> IBSHIFT) + 1);
895 } else
896 termios_p->c_cflag &= ~CIBAUDEXT;
897 termios_p->c_cflag =
898 (termios_p->c_cflag & ~CIBAUD) |
899 ((ispeed << IBSHIFT) & CIBAUD);
900 The CSIZE bits specify the character size in bits for both transmission
904 and reception. This size does not include the parity bit, if any. If
905 CSTOPB is set, two stop bits are used; otherwise, one stop bit is used.
906 For example, at 110 baud, two stops bits are required.
907 If PARENB is set, parity generation and detection is enabled, and a
910 parity bit is added to each character. If parity is enabled, the PARODD
911 flag specifies odd parity if set; otherwise, even parity is used.
912 If CREAD is set, the receiver is enabled. Otherwise, no characters are
915 received.
916 If HUPCL is set, the line is disconnected when the last process with
919 the line open closes it or terminates. That is, the data-terminal-ready
920 signal is not asserted.
921 If CLOCAL is set, the line is assumed to be a local, direct connection
924 with no modem control; otherwise, modem control is assumed.
925 If CRTSXOFF is set, inbound hardware flow control is enabled.
928 If CRTSCTS is set, outbound hardware flow control is enabled.
931 The four possible combinations for the state of CRTSCTS and CRTSXOFF
934 bits and their interactions are described below.
935 Case A: CRTSCTS off, CRTSXOFF off. In this case the hardware flow
937 control is disabled.
938 Case B: CRTSCTS on, CRTSXOFF off. In this case only outbound hard‐
941 ware flow control is enabled. The state of CTS signal is
942 used to do outbound flow control. It is expected that output
943 will be suspended if CTS is low and resumed when CTS is
944 high.
945 Case C: CRTSCTS off, CRTSXOFF on. In this case only inbound hardware
948 flow control is enabled. The state of RTS signal is used to
949 do inbound flow control. It is expected that input will be
950 suspended if RTS is low and resumed when RTS is high.
951 Case D: CRTSCTS on, CRTSXOFF on. In this case both inbound and out‐
954 bound hardware flow control are enabled. Uses the state of
955 CTS signal to do outbound flow control and RTS signal to do
956 inbound flow control.
957 Local Modes
960 The c_lflag field of the argument structure is used by the line disci‐
961 pline to control terminal functions. The basic line discipline provides
962 the following:
963 ISIG Enable signals.
965 ICANON Canonical input (erase and kill processing).
968 XCASE Canonical upper/lower presentation.
971 ECHO Enable echo.
974 ECHOE Echo erase character as BS-SP-BS &.
977 ECHOK Echo NL after kill character.
980 ECHONL Echo NL .
983 NOFLSH Disable flush after interrupt or quit.
986 TOSTOP Send SIGTTOU for background output.
989 ECHOCTL Echo control characters as char, delete as ^?.
992 ECHOPRT Echo erase character as character erased.
995 ECHOKE BS-SP-BS erase entire line on line kill.
998 FLUSHO Output is being flushed.
1001 PENDIN Retype pending input at next read or input character.
1004 IEXTEN Enable extended (implementation-defined) functions.
1007 If ISIG is set, each input character is checked against the special
1011 control characters INTR, QUIT, SWTCH, SUSP, STATUS, and DSUSP. If an
1012 input character matches one of these control characters, the function
1013 associated with that character is performed. (Note: If SWTCH is set and
1014 the character matches, the character is simply discarded. No other
1015 action is taken.) If ISIG is not set, no checking is done. Thus, these
1016 special input functions are possible only if ISIG is set.
1017 If ICANON is set, canonical processing is enabled. This enables the
1020 erase and kill edit functions, and the assembly of input characters
1021 into lines delimited by NL-c, EOF, EOL, and EOL . If ICANON is not
1022 set, read requests are satisfied directly from the input queue. A read
1023 is not satisfied until at least MIN characters have been received or
1024 the timeout value TIME has expired between characters. This allows fast
1025 bursts of input to be read efficiently while still allowing single
1026 character input. The time value represents tenths of seconds.
1027 If XCASE is set and ICANON is set, an upper case letter is accepted on
1030 input if preceded by a backslash (\) character, and is output preceded
1031 by a backslash (\) character. In this mode, the following escape
1032 sequences are generated on output and accepted on input:
1033 ┌─────────────────────────────┬─────────────────────────────┐
1038 │ FOR: │ USE: │
1039 ├─────────────────────────────┼─────────────────────────────┤
1040 │` │\' │
1041 ├─────────────────────────────┼─────────────────────────────┤
1042 │| │\! │
1043 ├─────────────────────────────┼─────────────────────────────┤
1044 │∼ │\^ │
1045 ├─────────────────────────────┼─────────────────────────────┤
1046 │{ │\( │
1047 ├─────────────────────────────┼─────────────────────────────┤
1048 │} │\) │
1049 ├─────────────────────────────┼─────────────────────────────┤
1050 │\ │\\ │
1051 └─────────────────────────────┴─────────────────────────────┘
1052 For example, input A as \a, \n as \\n, and \N as \\\n.
1055 If ECHO is set, characters are echoed as received.
1058 When ICANON is set, the following echo functions are possible.
1061 o If ECHO and ECHOE are set, and ECHOPRT is not set, the
1063 ERASE and WERASE characters are echoed as one or more ASCII
1064 BS SP BS, which clears the last character(s) from a CRT
1065 screen.
1066 o If ECHO, ECHOPRT, and IEXTEN are set, the first ERASE and
1068 WERASE character in a sequence echoes as a backslash (\),
1069 followed by the characters being erased. Subsequent ERASE
1070 and WERASE characters echo the characters being erased, in
1071 reverse order. The next non-erase character causes a `/'
1072 (slash) to be typed before it is echoed. ECHOPRT should be
1073 used for hard copy terminals.
1074 o If ECHOKE and IEXTEN are set, the kill character is echoed
1076 by erasing each character on the line from the screen
1077 (using the mechanism selected by ECHOE and ECHOPRa).
1078 o If ECHOK is set, and ECHOKE is not set, the NL character is
1080 echoed after the kill character to emphasize that the line
1081 is deleted. Note that a `´ (escape) character or an LNEXT
1082 character preceding the erase or kill character removes any
1083 special function.
1084 o If ECHONL is set, the NL character is echoed even if ECHO
1086 is not set. This is useful for terminals set to local echo
1087 (so called half-duplex).
1088 If ECHOCTL and IEXTEN are set, all control characters (characters with
1091 codes between 0 and 37 octal) other than ASCII TAB, ASCII NL, the
1092 START character, and the STOP character, ASCII CR, and ASCII BS are
1093 echoed as ^ X, where X is the character given by adding 100 octal to
1094 the code of the control character (so that the character with octal
1095 code 1 is echoed as ^ A), and the ASCII DEL character, with code 177
1096 octal, is echoed as ^ ?.
1097 If NOFLSH is set, the normal flush of the input and output queues
1100 associated with the INTR, QUIT, and SUSP characters is not done. This
1101 bit should be set when restarting system calls that read from or write
1102 to a terminal (see sigaction(2)).
1103 If TOSTOP and IEXTEN are set, the signal SIGTTOU is sent to a process
1106 that tries to write to its controlling terminal if it is not in the
1107 foreground process group for that terminal. This signal normally stops
1108 the process. Otherwise, the output generated by that process is output
1109 to the current output stream. Processes that are blocking or ignoring
1110 SIGTTOU signals are excepted and allowed to produce output, if any.
1111 If FLUSHO and IEXTEN are set, data written to the terminal is dis‐
1114 carded. This bit is set when the FLUSH character is typed. A program
1115 can cancel the effect of typing the FLUSH character by clearing FLUSHO.
1116 If PENDIN and IEXTEN are set, any input that has not yet been read is
1119 reprinted when the next character arrives as input. PENDIN is then
1120 automatically cleared.
1121 If IEXTEN is set, the following implementation-defined functions are
1124 enabled: special characters ( WERASE, REPRINT, DISCARD, and LNEXT) and
1125 local flags ( TOSTOP, ECHOCTL, ECHOPRT, ECHOKE, FLUSHO, and PENDIN).
1126 Minimum and Timeout
1128 The MIN and TIME values were described previously, in the subsection,
1129 Non-canonical Mode Input Processing. The initial value of MIN is 1,
1130 and the initial value of TIME is 0.
1131 Terminal Size
1133 The number of lines and columns on the terminal's display is specified
1134 in the winsize structure defined by sys/termios.h and includes the
1135 following members:
1136 unsigned short ws_row; /* rows, in characters */
1138 unsigned short ws_col; /* columns, in characters */
1139 unsigned short ws_xpixel; /* horizontal size, in pixels */
1140 unsigned short ws_ypixel; /* vertical size, in pixels */
1141 Termio Structure
1144 The SunOS/SVR4 termio structure is used by some ioctls; it is defined
1145 by sys/termio.h and includes the following members:
1146 unsigned short c_iflag; /* input modes */
1148 unsigned short c_oflag; /* output modes */
1149 unsigned short c_cflag; /* control modes */
1150 unsigned short c_lflag; /* local modes */
1151 char c_line; /* line discipline */
1152 unsigned char c_cc[NCC]; /* control chars */
1153 The special control characters are defined by the array c_cc. The sym‐
1157 bolic name NCC is the size of the Control-character array and is also
1158 defined by termio.h. The relative positions, subscript names, and typi‐
1159 cal default values for each function are as follows:
1160 ┌────────────────────┬────────────────────┬────────────────────────┐
1165 │Relative Positions │ Subscript Names │ Typical Default Values │
1166 ├────────────────────┼────────────────────┼────────────────────────┤
1167 │0 │VINTR │ EXT │
1168 ├────────────────────┼────────────────────┼────────────────────────┤
1169 │1 │VQUIT │ FS │
1170 ├────────────────────┼────────────────────┼────────────────────────┤
1171 │2 │VERASE │ DEL │
1172 ├────────────────────┼────────────────────┼────────────────────────┤
1173 │3 │VKILL │ NAK │
1174 ├────────────────────┼────────────────────┼────────────────────────┤
1175 │4 │VEOF │ EOT │
1176 ├────────────────────┼────────────────────┼────────────────────────┤
1177 │5 │VEOL │ NUL │
1178 ├────────────────────┼────────────────────┼────────────────────────┤
1179 │6 │VEOL2 │ NUL │
1180 ├────────────────────┼────────────────────┼────────────────────────┤
1181 │7 │Reserved │ │
1182 └────────────────────┴────────────────────┴────────────────────────┘
1183 The MIN values is stored in the VMIN element of the c_cc array; the
1186 TIME value is stored in the VTIME element of the c_cc array. The
1187 VMIN element is the same element as the VEOF element; the VTIME ele‐
1188 ment is the same element as the VEOL element.
1189 The calls that use the termio structure only affect the flags and con‐
1192 trol characters that can be stored in the termio structure; all other
1193 flags and control characters are unaffected.
1194 Modem Lines
1196 On special files representing serial ports, modem control lines can be
1197 read. Control lines (if the underlying hardware supports it) may also
1198 be changed. Status lines are read-only. The following modem control and
1199 status lines may be supported by a device; they are defined by
1200 sys/termios.h:
1201 TIOCM_LE line enable
1203 TIOCM_DTR data terminal ready
1206 TIOCM_RTS request to send
1209 TIOCM_ST secondary transmit
1212 TIOCM_SR secondary receive
1215 TIOCM_CTS clear to send
1218 TIOCM_CAR carrier detect
1221 TIOCM_RNG ring
1224 TIOCM_DSR data set ready
1227 TIOCM_CD is a synonym for TIOCM_CAR, and TIOCM_RI is a synonym for
1231 TIOCM_RNG. Not all of these are necessarily supported by any particular
1232 device; check the manual page for the device in question.
1233 The software carrier mode can be enabled or disabled using the TIOC‐
1236 SSOFTCAR ioctl. If the software carrier flag for a line is off, the
1237 line pays attention to the hardware carrier detect (DCD) signal. The
1238 tty device associated with the line cannot be opened until DCD is
1239 asserted. If the software carrier flag is on, the line behaves as if
1240 DCD is always asserted.
1241 The software carrier flag is usually turned on for locally connected
1244 terminals or other devices, and is off for lines with modems.
1245 To be able to issue the TIOCGSOFTCAR and TIOCSSOFTCAR ioctl calls, the
1248 tty line should be opened with O_NDELAY so that the open(2) will not
1249 wait for the carrier.
1250 Default Values
1252 The initial termios values upon driver open is configurable. This is
1253 accomplished by setting the "ttymodes" property in the file /ker‐
1254 nel/drv/options.conf. Since this property is assigned during system
1255 initialization, any change to the "ttymodes" property will not take
1256 effect until the next reboot. The string value assigned to this prop‐
1257 erty should be in the same format as the output of the stty(1) command
1258 with the -g option.
1259 If this property is undefined, the following termios modes are in
1262 effect. The initial input control value is BRKINT, ICRNL, IXON, IMAX‐
1263 BEL. The initial output control value is OPOST, ONLCR, TAB3. The ini‐
1264 tial hardware control value is B9600, CS8, CREAD. The initial line-dis‐
1265 cipline control value is ISIG, ICANON, IEXTEN, ECHO, ECHOK, ECHOE,
1266 ECHOKE, ECHOCTL.
1267
1269 The ioctls supported by devices and STREAMS modules providing the
1270 termios(3C) interface are listed below. Some calls may not be supported
1271 by all devices or modules. The functionality provided by these calls
1272 is also available through the preferred function call interface speci‐
1273 fied on termios.
1274 TCGETS The argument is a pointer to a termios structure. The
1276 current terminal parameters are fetched and stored into
1277 that structure.
1278 TCSETS The argument is a pointer to a termios structure. The
1281 current terminal parameters are set from the values
1282 stored in that structure. The change is immediate.
1283 TCSETSW The argument is a pointer to a termios structure. The
1286 current terminal parameters are set from the values
1287 stored in that structure. The change occurs after all
1288 characters queued for output have been transmitted.
1289 This form should be used when changing parameters that
1290 affect output.
1291 TCSETSF The argument is a pointer to a termios structure. The
1294 current terminal parameters are set from the values
1295 stored in that structure. The change occurs after all
1296 characters queued for output have been transmitted; all
1297 characters queued for input are discarded and then the
1298 change occurs.
1299 TCGETA The argument is a pointer to a termio structure. The
1302 current terminal parameters are fetched, and those
1303 parameters that can be stored in a termio structure are
1304 stored into that structure.
1305 TCSETA The argument is a pointer to a termio structure. Those
1308 terminal parameters that can be stored in a termio
1309 structure are set from the values stored in that struc‐
1310 ture. The change is immediate.
1311 TCSETAW The argument is a pointer to a termio structure. Those
1314 terminal parameters that can be stored in a termio
1315 structure are set from the values stored in that struc‐
1316 ture. The change occurs after all characters queued for
1317 output have been transmitted. This form should be used
1318 when changing parameters that affect output.
1319 TCSETAF The argument is a pointer to a termio structure. Those
1322 terminal parameters that can be stored in a termio
1323 structure are set from the values stored in that struc‐
1324 ture. The change occurs after all characters queued for
1325 output have been transmitted; all characters queued for
1326 input are discarded and then the change occurs.
1327 TCSBRK The argument is an int value. Wait for the output to
1330 drain. If the argument is 0, then send a break (zero
1331 valued bits for 0.25 seconds).
1332 TCXONC Start/stop control. The argument is an int value. If
1335 the argument is 0, suspend output; if 1, restart sus‐
1336 pended output; if 2, suspend input; if 3, restart sus‐
1337 pended input.
1338 TCFLSH The argument is an int value. If the argument is 0,
1341 flush the input queue; if 1, flush the output queue; if
1342 2, flush both the input and output queues.
1343 TIOCGPGRP The argument is a pointer to a pid_t. Set the value of
1346 that pid_t to the process group ID of the foreground
1347 process group associated with the terminal. See
1348 termios(3C) for a description of TCGETPGRP.
1349 TIOCSPGRP The argument is a pointer to a pid_t. Associate the
1352 process group whose process group ID is specified by
1353 the value of that pid_t with the terminal. The new
1354 process group value must be in the range of valid
1355 process group ID values. Otherwise, the error EPERM
1356 is returned.
1357 TIOCGSID The argument is a pointer to a pid_t. The session ID of
1360 the terminal is fetched and stored in the pid_t.
1361 TIOCGWINSZ The argument is a pointer to a winsize structure. The
1364 terminal driver's notion of the terminal size is stored
1365 into that structure.
1366 TIOCSWINSZ The argument is a pointer to a winsize structure. The
1369 terminal driver's notion of the terminal size is set
1370 from the values specified in that structure. If the new
1371 sizes are different from the old sizes, a SIGWINCH sig‐
1372 nal is set to the process group of the terminal.
1373 TIOCMBIS The argument is a pointer to an int whose value is a
1376 mask containing modem control lines to be turned on.
1377 The control lines whose bits are set in the argument
1378 are turned on; no other control lines are affected.
1379 TIOCMBIC The argument is a pointer to an int whose value is a
1382 mask containing modem control lines to be turned off.
1383 The control lines whose bits are set in the argument
1384 are turned off; no other control lines are affected.
1385 TIOCMGET The argument is a pointer to an int. The current state
1388 of the modem status lines is fetched and stored in the
1389 int pointed to by the argument.
1390 TIOCMSET The argument is a pointer to an int containing a new
1393 set of modem control lines. The modem control lines are
1394 turned on or off, depending on whether the bit for that
1395 mode is set or clear.
1396 TIOCSPPS The argument is a pointer to an int that determines
1399 whether pulse-per-second event handling is to be
1400 enabled (non-zero) or disabled (zero). If a one-pulse-
1401 per-second reference clock is attached to the serial
1402 line's data carrier detect input, the local system
1403 clock will be calibrated to it. A clock with a high
1404 error, that is, a deviation of more than 25 microsec‐
1405 onds per tick, is ignored.
1406 TIOCGPPS The argument is a pointer to an int, in which the state
1409 of the even handling is returned. The int is set to a
1410 non-zero value if pulse-per-second (PPS) handling has
1411 been enabled. Otherwise, it is set to zero.
1412 TIOCGSOFTCAR The argument is a pointer to an int whose value is 1 or
1415 0, depending on whether the software carrier detect is
1416 turned on or off.
1417 TIOCSSOFTCAR The argument is a pointer to an int whose value is 1 or
1420 0. The value of the integer should be 0 to turn off
1421 software carrier, or 1 to turn it on.
1422 TIOCGPPSEV The argument is a pointer to a struct ppsclockev. This
1425 structure contains the following members:
1426 struct timeval tv;
1428 uint32_t serial;
1429 "tv" is the system clock timestamp when the event
1431 (pulse on the DCD pin) occurred. "serial" is the ordi‐
1432 nal of the event, which each consecutive event being
1433 assigned the next ordinal. The first event registered
1434 gets a "serial" value of 1. The TIOCGPPSEV returns the
1435 last event registered; multiple calls will persistently
1436 return the same event until a new one is registered. In
1437 addition to time stamping and saving the event, if it
1438 is of one-second period and of consistently high accu‐
1439 racy, the local system clock will automatically cali‐
1440 brate to it.
1441
1444 Files in or under /dev
1445
1447 stty(1), fork(2), getpgid(2), getsid(2), ioctl(2), setsid(2), sigac‐
1448 tion(2), signal(3C), tcsetpgrp(3C), termios(3C), signal.h(3HEAD),
1449 streamio(7I)
1450SunOS 5.11 14 Sep 2005 termio(7I)