1 TERMIO(7I) Ioctl Requests TERMIO(7I)
2
3
4
5 NAME
6 termio - general terminal interface
7
8 SYNOPSIS
9 #include <termio.h>
10
11 ioctl(int fildes, int request, struct termio *arg);
12
13
14 ioctl(int fildes, int request, int arg);
15
16
17 #include <termios.h>
18
19 ioctl(int fildes, int request, struct termios *arg);
20
21
22 DESCRIPTION
23 This release supports a general interface for asynchronous
24 communications ports that is hardware-independent. The user interface
25 to this 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
28 subsystem which are relevant with both user interfaces.
29
30
31 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
37 terminal plays a special role in handling quit and interrupt signals,
38 as 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
42
43 A terminal associated with one of these files ordinarily operates in
44 full-duplex mode. Characters may be typed at any time, even while
45 output is occurring, and are only lost when the character input buffers
46 of the system become completely full, which is rare. For example, the
47 number of characters in the line discipline buffer may exceed
48 {MAX_CANON} and IMAXBEL (see below) is not set, or the user may
49 accumulate { MAX_INPUT} number of input characters that have not yet
50 been read by some program. When the input limit is reached, all the
51 characters saved in the buffer up to that point are thrown away without
52 notice.
53
54 Session Management (Job Control)
55 A control terminal will distinguish one of the process groups in the
56 session associated with it to be the foreground process group. All
57 other process groups in the session are designated as background
58 process groups. This foreground process group plays a special role in
59 handling signal-generating input characters, as discussed below. By
60 default, when a controlling terminal is allocated, the controlling
61 process's process group is assigned as foreground process group.
62
63
64 Background process groups in the controlling process's session are
65 subject to a job control line discipline when they attempt to access
66 their controlling terminal. Process groups can be sent signals that
67 will cause them to stop, unless they have made other arrangements. An
68 exception is made for members of orphaned process groups.
69
70
71 An orphaned process group is one where the process group (see
72 getpgid(2)) has no members with a parent in a different process group
73 but sharing the same controlling terminal. When a member of an orphaned
74 process group attempts to access its controlling terminal, EIO is
75 returned because there would be no way to restart the process if it
76 were stopped on one of these signals.
77
78
79 If a member of a background process group attempts to read its
80 controlling terminal, its process group will be sent a SIGTTIN signal,
81 which will normally cause the members of that process group to stop.
82 If, however, the process is ignoring or holding SIGTTIN, or is a member
83 of an orphaned process group, the read will fail with errno set to
84 EIO, and no signal is sent.
85
86
87 If a member of a background process group attempts to write its
88 controlling terminal and the TOSTOP bit is set in the c_lflag field,
89 its process group is sent a SIGTTOU signal, which will normally cause
90 the members of that process group to stop. If, however, the process is
91 ignoring or holding SIGTTOU, the write will succeed. If the process is
92 not ignoring or holding SIGTTOU and is a member of an orphaned process
93 group, the write will fail with errno set to EIO, and no signal will
94 be sent.
95
96
97 If TOSTOP is set and a member of a background process group attempts
98 to ioctl its controlling terminal, and that ioctl will modify terminal
99 parameters (for example, TCSETA, TCSETAW, TCSETAF, or TIOCSPGRP), its
100 process group will be sent a SIGTTOU signal, which will normally cause
101 the members of that process group to stop. If, however, the process is
102 ignoring or holding SIGTTOU, the ioctl will succeed. If the process is
103 not ignoring or holding SIGTTOU and is a member of an orphaned process
104 group, the write will fail with errno set to EIO, and no signal will
105 be sent.
106
107 Canonical Mode Input Processing
108 Normally, terminal input is processed in units of lines. A line is
109 delimited by a newline (ASCII LF) character, an end-of-file (ASCII EOT)
110 character, or an end-of-line character. This means that a program
111 attempting to read will block until an entire line has been typed.
112 Also, no matter how many characters are requested in the read call, at
113 most one line will be returned. It is not necessary, however, to read
114 a whole line at once; any number of characters may be requested in a
115 read, even one, without losing information.
116
117
118 During input, erase, erase2, and kill processing is normally done. The
119 ERASE and ERASE2 character (by default, the character DEL for ERASE and
120 Control-h for ERASE2) erases the last character typed. The WERASE
121 character (the character Control-w) erases the last "word" typed in
122 the current input line (but not any preceding spaces or tabs). A "word"
123 is defined as a sequence of non-blank characters, with tabs counted as
124 blanks. None of ERASE or ERASE2 or WERASE will erase beyond the
125 beginning of the line. The KILL character (by default, the character
126 NAK) kills (deletes) the entire input line, and optionally outputs a
127 newline character. All these characters operate on a key stroke basis,
128 independent of any backspacing or tabbing that may have been done. The
129 REPRINT character (the character Control-r) prints a newline followed
130 by all characters that have not been read. Reprinting also occurs
131 automatically if characters that would normally be erased from the
132 screen are fouled by program output. The characters are reprinted as if
133 they were being echoed; consequencely, if ECHO is not set, they are not
134 printed.
135
136
137 The ERASE, ERASE2, and KILL characters may be entered literally by
138 preceding them with the escape character. In this case, the escape
139 character is not read. The erase, erase2, and kill characters may be
140 changed.
141
142 Non-canonical Mode Input Processing
143 In non-canonical mode input processing, input characters are not
144 assembled into lines, and erase and kill processing does not occur. The
145 MIN and TIME values are used to determine how to process the characters
146 received.
147
148
149 MIN represents the minimum number of characters that should be received
150 when the read is satisfied (that is, when the characters are returned
151 to the user). TIME is a timer of 0.10-second granularity that is used
152 to timeout bursty and short-term data transmissions. The four possible
153 values for MIN and TIME and their interactions are described below.
154
155 Case A: MIN > 0, TIME > 0
156 In this case, TIME serves as an
157 intercharacter timer and is activated
158 after the first character is received.
159 Since it is an intercharacter timer, it is
160 reset after a character is received. The
161 interaction between MIN and TIME is as
162 follows: as soon as one character is
163 received, the intercharacter timer is
164 started. If MIN characters are received
165 before the intercharacter timer expires
166 (note that the timer is reset upon receipt
167 of each character), the read is satisfied.
168 If the timer expires before MIN characters
169 are received, the characters received to
170 that point are returned to the user. Note
171 that if TIME expires, at least one
172 character will be returned because the
173 timer would not have been enabled unless a
174 character was received. In this case (MIN
175 > 0, TIME > 0), the read sleeps until the
176 MIN and TIME mechanisms are activated by
177 the receipt of the first character. If
178 the number of characters read is less than
179 the number of characters available, the
180 timer is not reactivated and the
181 subsequent read is satisfied immediately.
182
183
184 Case B: MIN > 0, TIME = 0
185 In this case, since the value of TIME is
186 zero, the timer plays no role and only MIN
187 is significant. A pending read is not
188 satisfied until MIN characters are
189 received (the pending read sleeps until
190 MIN characters are received). A program
191 that uses this case to read record based
192 terminal I/O may block indefinitely in the
193 read operation.
194
195
196 Case C: MIN = 0, TIME > 0
197 In this case, since MIN = 0, TIME no
198 longer represents an intercharacter timer:
199 it now serves as a read timer that is
200 activated as soon as a read is done. A
201 read is satisfied as soon as a single
202 character is received or the read timer
203 expires. Note that, in this case, if the
204 timer expires, no character is returned.
205 If the timer does not expire, the only way
206 the read can be satisfied is if a
207 character is received. In this case, the
208 read will not block indefinitely waiting
209 for a character; if no character is
210 received within TIME *.10 seconds after
211 the read is initiated, the read returns
212 with zero characters.
213
214
215 Case D: MIN = 0, TIME = 0
216 In this case, return is immediate. The
217 minimum of either the number of characters
218 requested or the number of characters
219 currently available is returned without
220 waiting for more characters to be input.
221
222
223 Comparing Different Cases of MIN, TIME Interaction
224 Some points to note about MIN and TIME :
225
226 o In the following explanations, note that the interactions of
227 MIN and TIME are not symmetric. For example, when MIN > 0
228 and TIME = 0, TIME has no effect. However, in the opposite
229 case, where MIN = 0 and TIME > 0, both MIN and TIME play
230 a role in that MIN is satisfied with the receipt of a single
231 character.
232
233 o Also note that in case A (MIN > 0, TIME > 0), TIME
234 represents an intercharacter timer, whereas in case C ( MIN
235 = 0, TIME > 0), TIME represents a read timer.
236
237
238 These two points highlight the dual purpose of the MIN/TIME feature.
239 Cases A and B, where MIN > 0, exist to handle burst mode activity (for
240 example, file transfer programs), where a program would like to process
241 at least MIN characters at a time. In case A, the intercharacter timer
242 is activated by a user as a safety measure; in case B, the timer is
243 turned off.
244
245
246 Cases C and D exist to handle single character, timed transfers. These
247 cases are readily adaptable to screen-based applications that need to
248 know if a character is present in the input queue before refreshing the
249 screen. In case C, the read is timed, whereas in case D, it is not.
250
251
252 Another important note is that MIN is always just a minimum. It does
253 not denote a record length. For example, if a program does a read of 20
254 bytes, MIN is 10, and 25 characters are present, then 20 characters
255 will be returned to the user.
256
257 Writing Characters
258 When one or more characters are written, they are transmitted to the
259 terminal as soon as previously written characters have finished typing.
260 Input characters are echoed as they are typed if echoing has been
261 enabled. If a process produces characters more rapidly than they can be
262 typed, it will be suspended when its output queue exceeds some limit.
263 When the queue is drained down to some threshold, the program is
264 resumed.
265
266 Special Characters
267 Certain characters have special functions on input. These functions and
268 their default character values are summarized as follows:
269
270 INTR
271 (Control-c or ASCII ETX) generates a SIGINT signal. SIGINT
272 is sent to all foreground processes associated with the
273 controlling terminal. Normally, each such process is forced
274 to terminate, but arrangements may be made either to ignore
275 the signal or to receive a trap to an agreed upon location.
276 (See signal.h(3HEAD)).
277
278
279 QUIT
280 (Control-| or ASCII FS) generates a SIGQUIT signal. Its
281 treatment is identical to the interrupt signal except that,
282 unless a receiving process has made other arrangements, it
283 will not only be terminated but a core image file (called
284 core) will be created in the current working directory.
285
286
287 ERASE
288 (DEL) erases the preceding character. It does not erase
289 beyond the start of a line, as delimited by a NL, EOF, EOL,
290 or EOL2 character.
291
292
293 ERASE2
294 (Control-h or ASCII BS) erases the preceding character, with
295 behaviour identical to that of ERASE.
296
297
298 WERASE
299 (Control-w or ASCII ETX) erases the preceding "word". It
300 does not erase beyond the start of a line, as delimited by a
301 NL, EOF, EOL, or EOL2 character.
302
303
304 KILL
305 (Control-u or ASCII NAK) deletes the entire line, as
306 delimited by a NL, EOF, EOL, or EOL2 character.
307
308
309 REPRINT
310 (Control-r or ASCII DC2) reprints all characters, preceded
311 by a newline, that have not been read.
312
313
314 EOF
315 (Control-d or ASCII EOT) may be used to generate an end-of-
316 file from a terminal. When received, all the characters
317 waiting to be read are immediately passed to the program,
318 without waiting for a newline, and the EOF is discarded.
319 Thus, if no characters are waiting (that is, the EOF
320 occurred at the beginning of a line) zero characters are
321 passed back, which is the standard end-of-file indication.
322 Unless escaped, the EOF character is not echoed. Because EOT
323 is the default EOF character, this prevents terminals that
324 respond to EOT from hanging up.
325
326
327 NL
328 (ASCII LF) is the normal line delimiter. It cannot be
329 changed or escaped.
330
331
332 EOL
333 (ASCII NULL) is an additional line delimiter, like NL . It
334 is not normally used.
335
336
337 EOL2
338 is another additional line delimiter.
339
340
341 SWTCH
342 (Control-z or ASCII EM) Header file symbols related to this
343 special character are present for compatibility purposes
344 only and the kernel takes no special action on matching
345 SWTCH (except to discard the character).
346
347
348 SUSP
349 (Control-z or ASCII SUB) generates a SIGTSTP signal.
350 SIGTSTP stops all processes in the foreground process group
351 for that terminal.
352
353
354 DSUSP
355 (Control-y or ASCII EM). It generates a SIGTSTP signal as
356 SUSP does, but the signal is sent when a process in the
357 foreground process group attempts to read the DSUSP
358 character, rather than when it is typed.
359
360
361 STOP
362 (Control-s or ASCII DC3) can be used to suspend output
363 temporarily. It is useful with CRT terminals to prevent
364 output from disappearing before it can be read. While output
365 is suspended, STOP characters are ignored and not read.
366
367
368 START
369 (Control-q or ASCII DC1) is used to resume output. Output
370 has been suspended by a STOP character. While output is not
371 suspended, START characters are ignored and not read.
372
373
374 DISCARD
375 (Control-o or ASCII SI) causes subsequent output to be
376 discarded. Output is discarded until another DISCARD
377 character is typed, more input arrives, or the condition is
378 cleared by a program.
379
380
381 STATUS
382 (Control-t or ASCII DC4) generates a SIGINFO signal.
383 Processes with a handler will output status information when
384 they receive SIGINFO, for example, dd(1M). If a process does
385 not have a SIGINFO handler, the signal will be ignored.
386
387
388 LNEXT
389 (Control-v or ASCII SYN) causes the special meaning of the
390 next character to be ignored. This works for all the
391 special characters mentioned above. It allows characters to
392 be input that would otherwise be interpreted by the system
393 (for example KILL, QUIT). The character values for INTR,
394 QUIT, ERASE, ERASE2, WERASE, KILL, REPRINT, EOF, EOL, EOL2,
395 SWTCH, SUSP, DSUSP, STOP, START, DISCARD, STATUS, and LNEXT
396 may be changed to suit individual tastes. If the value of a
397 special control character is _POSIX_VDISABLE (0), the
398 function of that special control character is disabled. The
399 ERASE, ERASE2, KILL, and EOF characters may be escaped by a
400 preceding backslash (\) character, in which case no special
401 function is done. Any of the special characters may be
402 preceded by the LNEXT character, in which case no special
403 function is done.
404
405
406 Modem Disconnect
407 When a modem disconnect is detected, a SIGHUP signal is sent to the
408 terminal's controlling process. Unless other arrangements have been
409 made, these signals cause the process to terminate. If SIGHUP is
410 ignored or caught, any subsequent read returns with an end-of-file
411 indication until the terminal is closed.
412
413
414 If the controlling process is not in the foreground process group of
415 the terminal, a SIGTSTP is sent to the terminal's foreground process
416 group. Unless other arrangements have been made, these signals cause
417 the processes to stop.
418
419
420 Processes in background process groups that attempt to access the
421 controlling terminal after modem disconnect while the terminal is still
422 allocated to the session will receive appropriate SIGTTOU and SIGTTIN
423 signals. Unless other arrangements have been made, this signal causes
424 the processes to stop.
425
426
427 The controlling terminal will remain in this state until it is
428 reinitialized with a successful open by the controlling process, or
429 deallocated by the controlling process.
430
431 Terminal Parameters
432 The parameters that control the behavior of devices and modules
433 providing the termios interface are specified by the termios structure
434 defined by termios.h. Several ioctl(2) system calls that fetch or
435 change these parameters use this structure that contains the following
436 members:
437
438 tcflag_t c_iflag; /* input modes */
439 tcflag_t c_oflag; /* output modes */
440 tcflag_t c_cflag; /* control modes */
441 tcflag_t c_lflag; /* local modes */
442 cc_t c_cc[NCCS]; /* control chars */
443
444
445
446 The special control characters are defined by the array c_cc. The
447 symbolic name NCCS is the size of the Control-character array and is
448 also defined by <termios.h>. The relative positions, subscript names,
449 and typical default values for each function are as follows:
450
451
452
453
454 +------------------+----------------+-----------------------+
455 |Relative Position | Subscript Name | Typical Default Value |
456 +------------------+----------------+-----------------------+
457 |0 | VINTR | ETX |
458 +------------------+----------------+-----------------------+
459 |1 | VQUIT | FS |
460 +------------------+----------------+-----------------------+
461 |2 | VERASE | DEL |
462 +------------------+----------------+-----------------------+
463 |3 | VKILL | NAK |
464 +------------------+----------------+-----------------------+
465 |4 | VEOF | EOT |
466 +------------------+----------------+-----------------------+
467 |5 | VEOL | NUL |
468 +------------------+----------------+-----------------------+
469 |6 | VEOL2 | NUL |
470 +------------------+----------------+-----------------------+
471 |7 | VWSTCH | NUL |
472 +------------------+----------------+-----------------------+
473 |8 | VSTART | NUL |
474 +------------------+----------------+-----------------------+
475 |9 | VSTOP | DC3 |
476 +------------------+----------------+-----------------------+
477 |10 | VSUSP | SUB |
478 +------------------+----------------+-----------------------+
479 |11 | VDSUSP | EM |
480 +------------------+----------------+-----------------------+
481 |12 | VREPRINT | DC2 |
482 +------------------+----------------+-----------------------+
483 |13 | VDISCARD | SI |
484 +------------------+----------------+-----------------------+
485 |14 | VWERASE | ETB |
486 +------------------+----------------+-----------------------+
487 |15 | VLNEXT | SYN |
488 +------------------+----------------+-----------------------+
489 |16 | VSTATUS | DC4 |
490 +------------------+----------------+-----------------------+
491 |17 | VERASE2 | BS |
492 +------------------+----------------+-----------------------+
493 |18-19 | Reserved | |
494 +------------------+----------------+-----------------------+
495
496 Input Modes
497 The c_iflag field describes the basic terminal input control:
498
499 IGNBRK
500 Ignore break condition.
501
502
503 BRKINT
504 Signal interrupt on break.
505
506
507 IGNPAR
508 Ignore characters with parity errors.
509
510
511 PARMRK
512 Mark parity errors.
513
514
515 INPCK
516 Enable input parity check.
517
518
519 ISTRIP
520 Strip character.
521
522
523 INLCR
524 Map NL to CR on input.
525
526
527 IGNCR
528 Ignore CR.
529
530
531 ICRNL
532 Map CR to NL on input.
533
534
535 IUCLC
536 Map upper-case to lower-case on input.
537
538
539 IXON
540 Enable start/stop output control.
541
542
543 IXANY
544 Enable any character to restart output.
545
546
547 IXOFF
548 Enable start/stop input control.
549
550
551 IMAXBEL
552 Echo BEL on input line too long.
553
554
555
556 If IGNBRK is set, a break condition (a character framing error with
557 data all zeros) detected on input is ignored, that is, not put on the
558 input queue and therefore not read by any process. If IGNBRK is not set
559 and BRKINT is set, the break condition shall flush the input and output
560 queues and if the terminal is the controlling terminal of a foreground
561 process group, the break condition generates a single SIGINT signal to
562 that foreground process group. If neither IGNBRK nor BRKINT is set, a
563 break condition is read as a single '\0' (ASCII NULL) character, or if
564 PARMRK is set, as '\377', '\0', c, where '\377' is a single character
565 with value 377 octal (0xff hex, 255 decimal), '\0' is a single
566 character with value 0, and c is the errored character received.
567
568
569 If IGNPAR is set, a byte with framing or parity errors (other than
570 break) is ignored.
571
572
573 If PARMRK is set, and IGNPAR is not set, a byte with a framing or
574 parity error (other than break) is given to the application as the
575 three-character sequence: '\377', '\0', c, where '\377' is a single
576 character with value 377 octal (0xff hex, 255 decimal), '\0' is a
577 single character with value 0, and c is the errored character received.
578 To avoid ambiguity in this case, if ISTRIP is not set, a valid
579 character of '\377' is given to the application as `\377.' If neither
580 IGNPAR nor PARMRK is set, a framing or parity error (other than break)
581 is given to the application as a single '\0' (ASCII NULL) character.
582
583
584 If INPCK is set, input parity checking is enabled. If INPCK is not set,
585 input parity checking is disabled. This allows output parity generation
586 without input parity errors. Note that whether input parity checking
587 is enabled or disabled is independent of whether parity detection is
588 enabled or disabled. If parity detection is enabled but input parity
589 checking is disabled, the hardware to which the terminal is connected
590 will recognize the parity bit, but the terminal special file will not
591 check whether this is set correctly or not.
592
593
594 If ISTRIP is set, valid input characters are first stripped to seven
595 bits, otherwise all eight bits are processed.
596
597
598 If INLCR is set, a received NL character is translated into a CR
599 character. If IGNCR is set, a received CR character is ignored (not
600 read). Otherwise, if ICRNL is set, a received CR character is
601 translated into a NL character.
602
603
604 If IUCLC is set, a received upper case, alphabetic character is
605 translated into the corresponding lower case character.
606
607
608 If IXON is set, start/stop output control is enabled. A received STOP
609 character suspends output and a received START character restarts
610 output. The STOP and START characters will not be read, but will merely
611 perform flow control functions. If IXANY is set, any input character
612 restarts output that has been suspended.
613
614
615 If IXOFF is set, the system transmits a STOP character when the input
616 queue is nearly full, and a START character when enough input has been
617 read so that the input queue is nearly empty again.
618
619
620 If IMAXBEL is set, the ASCII BEL character is echoed if the input
621 stream overflows. Further input is not stored, but any input already
622 present in the input stream is not disturbed. If IMAXBEL is not set,
623 no BEL character is echoed, and all input present in the input queue is
624 discarded if the input stream overflows.
625
626 Output Modes
627 The c_oflag field specifies the system treatment of output:
628
629 OPOST
630 Post-process output.
631
632
633 OLCUC
634 Map lower case to upper on output.
635
636
637 ONLCR
638 Map NL to CR-NL on output.
639
640
641 OCRNL
642 Map CR to NL on output.
643
644
645 ONOCR
646 No CR output at column 0.
647
648
649 ONLRET
650 NL performs CR function.
651
652
653 OFILL
654 Use fill characters for delay.
655
656
657 OFDEL
658 Fill is DEL, else NULL.
659
660
661 NLDLY
662 Select newline delays:
663 NL0
664 NL1
665
666
667 CRDLY
668 Select carriage-return delays:
669 CR0
670 CR1
671 CR2
672 CR3
673
674
675 TABDLY
676 Select horizontal tab delays or tab expansion:
677
678 TAB0
679
680
681
682 TAB1
683
684
685
686 TAB2
687
688
689
690 TAB3
691 Expand tabs to spaces
692
693
694 XTABS
695 Expand tabs to spaces
696
697
698
699 BSDLY
700 Select backspace delays:
701 BS0
702 BS1
703
704
705 VTDLY
706 Select vertical tab delays:
707 VT0
708 VT1
709
710
711 FFDLY
712 Select form feed delays:
713 FF0
714 FF1
715
716
717
718 If OPOST is set, output characters are post-processed as indicated by
719 the remaining flags; otherwise, characters are transmitted without
720 change.
721
722
723 If OLCUC is set, a lower case alphabetic character is transmitted as
724 the corresponding upper case character. This function is often used in
725 conjunction with IUCLC.
726
727
728 If ONLCR is set, the NL character is transmitted as the CR-NL character
729 pair. If OCRNL is set, the CR character is transmitted as the NL
730 character. If ONOCR is set, no CR character is transmitted when at
731 column 0 (first position). If ONRET is set, the NL character is
732 assumed to do the carriage-return function; the column pointer is set
733 to 0 and the delays specified for CR are used. Otherwise, the NL
734 character is assumed to do just the line-feed function; the column
735 pointer remains unchanged. The column pointer is also set to 0 if the
736 CR character is actually transmitted.
737
738
739 The delay bits specify how long transmission stops to allow for
740 mechanical or other movement when certain characters are sent to the
741 terminal. In all cases, a value of 0 indicates no delay. If OFILL is
742 set, fill characters are transmitted for delay instead of a timed
743 delay. This is useful for high baud rate terminals that need only a
744 minimal delay. If OFDEL is set, the fill character is DEL ; otherwise
745 it is NULL.
746
747
748 If a form-feed or vertical-tab delay is specified, it lasts for about 2
749 seconds.
750
751
752 Newline delay lasts about 0.10 seconds. If ONLRET is set, the carriage-
753 return delays are used instead of the newline delays. If OFILL is set,
754 two fill characters are transmitted.
755
756
757 Carriage-return delay type 1 is dependent on the current column
758 position, type 2 is about 0.10 seconds, and type 3 is about 0.15
759 seconds. If OFILL is set, delay type 1 transmits two fill characters,
760 and type 2 transmits four fill characters.
761
762
763 Horizontal-tab delay type 1 is dependent on the current column
764 position. Type 2 is about 0.10 seconds. Type 3 specifies that tabs are
765 to be expanded into spaces. If OFILL is set, two fill characters are
766 transmitted for any delay.
767
768
769 Backspace delay lasts about 0.05 seconds. If OFILL is set, one fill
770 character is transmitted.
771
772
773 The actual delays depend on line speed and system load.
774
775 Control Modes
776 The c_cflag field describes the hardware control of the terminal:
777
778 CBAUD
779 Baud rate:
780
781
782 B0
783 Hang up
784
785
786 B50
787 50 baud
788
789
790 B75
791 75 baud
792
793
794 B110
795 110 baud
796
797
798 B134
799 134 baud
800
801
802 B150
803 150 baud
804
805
806 B200
807 200 baud
808
809
810 B300
811 300 baud
812
813
814 B600
815 600 baud
816
817
818 B1200
819 1200 baud
820
821
822 B1800
823 1800 baud
824
825
826 B2400
827 2400 baud
828
829
830 B4800
831 4800 baud
832
833
834 B9600
835 9600 baud
836
837
838 B19200
839 19200 baud
840
841
842 EXTA
843 External A
844
845
846 B38400
847 38400 baud
848
849
850 EXTB
851 External B
852
853
854 B57600
855 57600 baud
856
857
858 B76800
859 76800 baud
860
861
862 B115200
863 115200 baud
864
865
866 B153600
867 153600 baud
868
869
870 B230400
871 230400 baud
872
873
874 B307200
875 307200 baud
876
877
878 B460800
879 460800 baud
880
881
882 CSIZE
883 Character size:
884
885
886 CS5
887 5 bits
888
889
890 CS6
891 6 bits
892
893
894 CS7
895 7 bits
896
897
898 CS8
899 8 bits
900
901
902 CSTOPB
903 Send two stop bits, else one
904
905
906 CREAD
907 Enable receiver
908
909
910 PARENB
911 Parity enable
912
913
914 PARODD
915 Odd parity, else even
916
917
918 HUPCL
919 Hang up on last close
920
921
922 CLOCAL
923 Local line, else dial-up
924
925
926 CIBAUD
927 Input baud rate, if different from output rate
928
929
930 PAREXT
931 Extended parity for mark and space parity
932
933
934 CRTSXOFF
935 Enable inbound hardware flow control
936
937
938 CRTSCTS
939 Enable outbound hardware flow control
940
941
942 CBAUDEXT
943 Bit to indicate output speed > B38400
944
945
946 CIBAUDEXT
947 Bit to indicate input speed > B38400
948
949
950
951 The CBAUD bits together with the CBAUDEXT bit specify the output baud
952 rate. To retrieve the output speed from the termios structure pointed
953 to by termios_p see the following code segment.
954
955 speed_t ospeed;
956 if (termios_p->c_cflag & CBAUDEXT)
957 ospeed = (termios_p->c_cflag & CBAUD) + CBAUD + 1;
958 else
959 ospeed = termios_p->c_cflag & CBAUD;
960
961
962
963 To store the output speed in the termios structure pointed to by
964 termios_p see the following code segment.
965
966 speed_t ospeed;
967 if (ospeed > CBAUD) {
968 termios_p->c_cflag |= CBAUDEXT;
969 ospeed -= (CBAUD + 1);
970 } else
971 termios_p->c_cflag &= ~CBAUDEXT;
972 termios_p->c_cflag =
973 (termios_p->c_cflag & ~CBAUD) | (ospeed & CBAUD);
974
975
976
977 The zero baud rate, B0, is used to hang up the connection. If B0 is
978 specified, the data-terminal-ready signal is not asserted. Normally,
979 this disconnects the line.
980
981
982 If the CIBAUDEXT or CIBAUD bits are not zero, they specify the input
983 baud rate, with the CBAUDEXT and CBAUD bits specifying the output baud
984 rate; otherwise, the output and input baud rates are both specified by
985 the CBAUDEXT and CBAUD bits. The values for the CIBAUD bits are the
986 same as the values for the CBAUD bits, shifted left IBSHIFT bits. For
987 any particular hardware, impossible speed changes are ignored. To
988 retrieve the input speed in the termios structure pointed to by
989 termios_p see the following code segment.
990
991 speed_t ispeed;
992 if (termios_p->c_cflag & CIBAUDEXT)
993 ispeed = ((termios_p->c_cflag & CIBAUD) >> IBSHIFT)
994 + (CIBAUD >> IBSHIFT) + 1;
995 else
996 ispeed = (termios_p->c_cflag & CIBAUD) >> IBSHIFT;
997
998
999
1000 To store the input speed in the termios structure pointed to by
1001 termios_p see the following code segment.
1002
1003 speed_t ispeed;
1004 if (ispeed == 0) {
1005 ispeed = termios_p->c_cflag & CBAUD;
1006 if (termios_p->c_cflag & CBAUDEXT)
1007 ispeed += (CBAUD + 1);
1008 }
1009 if ((ispeed << IBSHIFT) > CIBAUD) {
1010 termios_p->c_cflag |= CIBAUDEXT;
1011 ispeed -= ((CIBAUD >> IBSHIFT) + 1);
1012 } else
1013 termios_p->c_cflag &= ~CIBAUDEXT;
1014 termios_p->c_cflag =
1015 (termios_p->c_cflag & ~CIBAUD) |
1016 ((ispeed << IBSHIFT) & CIBAUD);
1017
1018
1019
1020 The CSIZE bits specify the character size in bits for both transmission
1021 and reception. This size does not include the parity bit, if any. If
1022 CSTOPB is set, two stop bits are used; otherwise, one stop bit is used.
1023 For example, at 110 baud, two stops bits are required.
1024
1025
1026 If PARENB is set, parity generation and detection is enabled, and a
1027 parity bit is added to each character. If parity is enabled, the PARODD
1028 flag specifies odd parity if set; otherwise, even parity is used.
1029
1030
1031 If CREAD is set, the receiver is enabled. Otherwise, no characters are
1032 received.
1033
1034
1035 If HUPCL is set, the line is disconnected when the last process with
1036 the line open closes it or terminates. That is, the data-terminal-ready
1037 signal is not asserted.
1038
1039
1040 If CLOCAL is set, the line is assumed to be a local, direct connection
1041 with no modem control; otherwise, modem control is assumed.
1042
1043
1044 If CRTSXOFF is set, inbound hardware flow control is enabled.
1045
1046
1047 If CRTSCTS is set, outbound hardware flow control is enabled.
1048
1049
1050 The four possible combinations for the state of CRTSCTS and CRTSXOFF
1051 bits and their interactions are described below.
1052
1053 Case A:
1054 CRTSCTS off, CRTSXOFF off. In this case the hardware flow
1055 control is disabled.
1056
1057
1058 Case B:
1059 CRTSCTS on, CRTSXOFF off. In this case only outbound
1060 hardware flow control is enabled. The state of CTS signal is
1061 used to do outbound flow control. It is expected that output
1062 will be suspended if CTS is low and resumed when CTS is
1063 high.
1064
1065
1066 Case C:
1067 CRTSCTS off, CRTSXOFF on. In this case only inbound hardware
1068 flow control is enabled. The state of RTS signal is used to
1069 do inbound flow control. It is expected that input will be
1070 suspended if RTS is low and resumed when RTS is high.
1071
1072
1073 Case D:
1074 CRTSCTS on, CRTSXOFF on. In this case both inbound and
1075 outbound hardware flow control are enabled. Uses the state
1076 of CTS signal to do outbound flow control and RTS signal to
1077 do inbound flow control.
1078
1079
1080 Local Modes
1081 The c_lflag field of the argument structure is used by the line
1082 discipline to control terminal functions. The basic line discipline
1083 provides the following:
1084
1085 ISIG
1086 Enable signals.
1087
1088
1089 ICANON
1090 Canonical input (erase and kill processing).
1091
1092
1093 XCASE
1094 Canonical upper/lower presentation.
1095
1096
1097 ECHO
1098 Enable echo.
1099
1100
1101 ECHOE
1102 Echo erase character as BS-SP-BS &.
1103
1104
1105 ECHOK
1106 Echo NL after kill character.
1107
1108
1109 ECHONL
1110 Echo NL .
1111
1112
1113 NOFLSH
1114 Disable flush after interrupt or quit.
1115
1116
1117 TOSTOP
1118 Send SIGTTOU for background output.
1119
1120
1121 ECHOCTL
1122 Echo control characters as char, delete as ^?.
1123
1124
1125 ECHOPRT
1126 Echo erase character as character erased.
1127
1128
1129 ECHOKE
1130 BS-SP-BS erase entire line on line kill.
1131
1132
1133 FLUSHO
1134 Output is being flushed.
1135
1136
1137 PENDIN
1138 Retype pending input at next read or input character.
1139
1140
1141 IEXTEN
1142 Enable extended (implementation-defined) functions.
1143
1144
1145
1146 If ISIG is set, each input character is checked against the special
1147 control characters INTR, QUIT, SWTCH, SUSP, STATUS, and DSUSP. If an
1148 input character matches one of these control characters, the function
1149 associated with that character is performed. (Note: If SWTCH is set and
1150 the character matches, the character is simply discarded. No other
1151 action is taken.) If ISIG is not set, no checking is done. Thus, these
1152 special input functions are possible only if ISIG is set.
1153
1154
1155 If ICANON is set, canonical processing is enabled. This enables the
1156 erase and kill edit functions, and the assembly of input characters
1157 into lines delimited by NL-c, EOF, EOL, and EOL . If ICANON is not
1158 set, read requests are satisfied directly from the input queue. A read
1159 is not satisfied until at least MIN characters have been received or
1160 the timeout value TIME has expired between characters. This allows fast
1161 bursts of input to be read efficiently while still allowing single
1162 character input. The time value represents tenths of seconds.
1163
1164
1165 If XCASE is set and ICANON is set, an upper case letter is accepted on
1166 input if preceded by a backslash (\) character, and is output preceded
1167 by a backslash (\) character. In this mode, the following escape
1168 sequences are generated on output and accepted on input:
1169
1170
1171
1172
1173 +-----+------+
1174 |FOR: | USE: |
1175 +-----+------+
1176 |` | \' |
1177 +-----+------+
1178 || | \! |
1179 +-----+------+
1180 |~ | \^ |
1181 +-----+------+
1182 |{ | \( |
1183 +-----+------+
1184 |} | \) |
1185 +-----+------+
1186 |\ | \\ |
1187 +-----+------+
1188
1189
1190 For example, input A as \a, \n as \\n, and \N as \\\n.
1191
1192
1193 If ECHO is set, characters are echoed as received.
1194
1195
1196 When ICANON is set, the following echo functions are possible.
1197
1198 o If ECHO and ECHOE are set, and ECHOPRT is not set, the
1199 ERASE, ERASE2, and WERASE characters are echoed as one or
1200 more ASCII BS SP BS, which clears the last character(s) from
1201 a CRT screen.
1202
1203 o If ECHO, ECHOPRT, and IEXTEN are set, the first ERASE,
1204 ERASE2, and WERASE character in a sequence echoes as a
1205 backslash (\), followed by the characters being erased.
1206 Subsequent ERASE and WERASE characters echo the characters
1207 being erased, in reverse order. The next non-erase character
1208 causes a `/' (slash) to be typed before it is echoed.
1209 ECHOPRT should be used for hard copy terminals.
1210
1211 o If ECHOKE and IEXTEN are set, the kill character is echoed
1212 by erasing each character on the line from the screen
1213 (using the mechanism selected by ECHOE and ECHOPRa).
1214
1215 o If ECHOK is set, and ECHOKE is not set, the NL character is
1216 echoed after the kill character to emphasize that the line
1217 is deleted. Note that a `' (escape) character or an LNEXT
1218 character preceding the erase or kill character removes any
1219 special function.
1220
1221 o If ECHONL is set, the NL character is echoed even if ECHO
1222 is not set. This is useful for terminals set to local echo
1223 (so called half-duplex).
1224
1225
1226 If ECHOCTL and IEXTEN are set, all control characters (characters with
1227 codes between 0 and 37 octal) other than ASCII TAB, ASCII NL, the
1228 START character, and the STOP character, ASCII CR, and ASCII BS are
1229 echoed as ^ X, where X is the character given by adding 100 octal to
1230 the code of the control character (so that the character with octal
1231 code 1 is echoed as ^ A), and the ASCII DEL character, with code 177
1232 octal, is echoed as ^ ?.
1233
1234
1235 If NOFLSH is set, the normal flush of the input and output queues
1236 associated with the INTR, QUIT, STATUS, and SUSP characters is not
1237 done. This bit should be set when restarting system calls that read
1238 from or write to a terminal (see sigaction(2)).
1239
1240
1241 If TOSTOP and IEXTEN are set, the signal SIGTTOU is sent to a process
1242 that tries to write to its controlling terminal if it is not in the
1243 foreground process group for that terminal. This signal normally stops
1244 the process. Otherwise, the output generated by that process is output
1245 to the current output stream. Processes that are blocking or ignoring
1246 SIGTTOU signals are excepted and allowed to produce output, if any.
1247
1248
1249 If FLUSHO and IEXTEN are set, data written to the terminal is
1250 discarded. This bit is set when the FLUSH character is typed. A program
1251 can cancel the effect of typing the FLUSH character by clearing FLUSHO.
1252
1253
1254 If PENDIN and IEXTEN are set, any input that has not yet been read is
1255 reprinted when the next character arrives as input. PENDIN is then
1256 automatically cleared.
1257
1258
1259 If IEXTEN is set, the following implementation-defined functions are
1260 enabled: special characters ( WERASE, REPRINT, DISCARD, and LNEXT) and
1261 local flags ( TOSTOP, ECHOCTL, ECHOPRT, ECHOKE, FLUSHO, and PENDIN).
1262
1263 Minimum and Timeout
1264 The MIN and TIME values were described previously, in the subsection,
1265 Non-canonical Mode Input Processing. The initial value of MIN is 1, and
1266 the initial value of TIME is 0.
1267
1268 Terminal Size
1269 The number of lines and columns on the terminal's display is specified
1270 in the winsize structure defined by sys/termios.h and includes the
1271 following members:
1272
1273 unsigned short ws_row; /* rows, in characters */
1274 unsigned shortws_col; /* columns, in characters */
1275 unsigned shortws_xpixel; /* horizontal size, in pixels */
1276 unsigned shortws_ypixel; /* vertical size, in pixels */
1277
1278
1279 Termio Structure
1280 The SunOS/SVR4 termio structure is used by some ioctls; it is defined
1281 by sys/termio.h and includes the following members:
1282
1283 unsigned shortc_iflag; /* input modes */
1284 unsigned shortc_oflag; /* output modes */
1285 unsigned shortc_cflag; /* control modes */
1286 unsigned short c_lflag; /* local modes */
1287 char c_line; /* line discipline */
1288 unsigned char c_cc[NCC]; /* control chars */
1289
1290
1291
1292 The special control characters are defined by the array c_cc. The
1293 symbolic name NCC is the size of the Control-character array and is
1294 also defined by termio.h. The relative positions, subscript names, and
1295 typical default values for each function are as follows:
1296
1297
1298
1299
1300 +-------------------+-----------------+------------------------+
1301 |Relative Positions | Subscript Names | Typical Default Values |
1302 +-------------------+-----------------+------------------------+
1303 |0 | VINTR | EXT |
1304 +-------------------+-----------------+------------------------+
1305 |1 | VQUIT | FS |
1306 +-------------------+-----------------+------------------------+
1307 |2 | VERASE | DEL |
1308 +-------------------+-----------------+------------------------+
1309 |3 | VKILL | NAK |
1310 +-------------------+-----------------+------------------------+
1311 |4 | VEOF | EOT |
1312 +-------------------+-----------------+------------------------+
1313 |5 | VEOL | NUL |
1314 +-------------------+-----------------+------------------------+
1315 |6 | VEOL2 | NUL |
1316 +-------------------+-----------------+------------------------+
1317 |7 | Reserved | |
1318 +-------------------+-----------------+------------------------+
1319
1320
1321 The MIN values is stored in the VMIN element of the c_cc array; the
1322 TIME value is stored in the VTIME element of the c_cc array. The VMIN
1323 element is the same element as the VEOF element; the VTIME element is
1324 the same element as the VEOL element.
1325
1326
1327 The calls that use the termio structure only affect the flags and
1328 control characters that can be stored in the termio structure; all
1329 other flags and control characters are unaffected.
1330
1331 Modem Lines
1332 On special files representing serial ports, modem control lines can be
1333 read. Control lines (if the underlying hardware supports it) may also
1334 be changed. Status lines are read-only. The following modem control
1335 and status lines may be supported by a device; they are defined by
1336 sys/termios.h:
1337
1338 TIOCM_LE
1339 line enable
1340
1341
1342 TIOCM_DTR
1343 data terminal ready
1344
1345
1346 TIOCM_RTS
1347 request to send
1348
1349
1350 TIOCM_ST
1351 secondary transmit
1352
1353
1354 TIOCM_SR
1355 secondary receive
1356
1357
1358 TIOCM_CTS
1359 clear to send
1360
1361
1362 TIOCM_CAR
1363 carrier detect
1364
1365
1366 TIOCM_RNG
1367 ring
1368
1369
1370 TIOCM_DSR
1371 data set ready
1372
1373
1374
1375 TIOCM_CD is a synonym for TIOCM_CAR, and TIOCM_RI is a synonym for
1376 TIOCM_RNG. Not all of these are necessarily supported by any particular
1377 device; check the manual page for the device in question.
1378
1379
1380 The software carrier mode can be enabled or disabled using the
1381 TIOCSSOFTCAR ioctl. If the software carrier flag for a line is off, the
1382 line pays attention to the hardware carrier detect (DCD) signal. The
1383 tty device associated with the line cannot be opened until DCD is
1384 asserted. If the software carrier flag is on, the line behaves as if
1385 DCD is always asserted.
1386
1387
1388 The software carrier flag is usually turned on for locally connected
1389 terminals or other devices, and is off for lines with modems.
1390
1391
1392 To be able to issue the TIOCGSOFTCAR and TIOCSSOFTCAR ioctl calls, the
1393 tty line should be opened with O_NDELAY so that the open(2) will not
1394 wait for the carrier.
1395
1396 Default Values
1397 The initial termios values upon driver open is configurable. This is
1398 accomplished by setting the "ttymodes" property in the file
1399 /kernel/drv/options.conf. Since this property is assigned during system
1400 initialization, any change to the "ttymodes" property will not take
1401 effect until the next reboot. The string value assigned to this
1402 property should be in the same format as the output of the stty(1)
1403 command with the -g option.
1404
1405
1406 If this property is undefined, the following termios modes are in
1407 effect. The initial input control value is BRKINT, ICRNL, IXON,
1408 IMAXBEL. The initial output control value is OPOST, ONLCR, TAB3. The
1409 initial hardware control value is B9600, CS8, CREAD. The initial line-
1410 discipline control value is ISIG, ICANON, IEXTEN, ECHO, ECHOK, ECHOE,
1411 ECHOKE, ECHOCTL.
1412
1413 IOCTLS
1414 The ioctls supported by devices and STREAMS modules providing the
1415 termios(3C) interface are listed below. Some calls may not be supported
1416 by all devices or modules. The functionality provided by these calls
1417 is also available through the preferred function call interface
1418 specified on termios.
1419
1420 TCGETS
1421 The argument is a pointer to a termios structure. The
1422 current terminal parameters are fetched and stored into
1423 that structure.
1424
1425
1426 TCSETS
1427 The argument is a pointer to a termios structure. The
1428 current terminal parameters are set from the values
1429 stored in that structure. The change is immediate.
1430
1431
1432 TCSETSW
1433 The argument is a pointer to a termios structure. The
1434 current terminal parameters are set from the values
1435 stored in that structure. The change occurs after all
1436 characters queued for output have been transmitted.
1437 This form should be used when changing parameters that
1438 affect output.
1439
1440
1441 TCSETSF
1442 The argument is a pointer to a termios structure. The
1443 current terminal parameters are set from the values
1444 stored in that structure. The change occurs after all
1445 characters queued for output have been transmitted; all
1446 characters queued for input are discarded and then the
1447 change occurs.
1448
1449
1450 TCGETA
1451 The argument is a pointer to a termio structure. The
1452 current terminal parameters are fetched, and those
1453 parameters that can be stored in a termio structure are
1454 stored into that structure.
1455
1456
1457 TCSETA
1458 The argument is a pointer to a termio structure. Those
1459 terminal parameters that can be stored in a termio
1460 structure are set from the values stored in that
1461 structure. The change is immediate.
1462
1463
1464 TCSETAW
1465 The argument is a pointer to a termio structure. Those
1466 terminal parameters that can be stored in a termio
1467 structure are set from the values stored in that
1468 structure. The change occurs after all characters
1469 queued for output have been transmitted. This form
1470 should be used when changing parameters that affect
1471 output.
1472
1473
1474 TCSETAF
1475 The argument is a pointer to a termio structure. Those
1476 terminal parameters that can be stored in a termio
1477 structure are set from the values stored in that
1478 structure. The change occurs after all characters
1479 queued for output have been transmitted; all characters
1480 queued for input are discarded and then the change
1481 occurs.
1482
1483
1484 TCSBRK
1485 The argument is an int value. Wait for the output to
1486 drain. If the argument is 0, then send a break (zero
1487 valued bits for 0.25 seconds).
1488
1489
1490 TCXONC
1491 Start/stop control. The argument is an int value. If
1492 the argument is 0, suspend output; if 1, restart
1493 suspended output; if 2, suspend input; if 3, restart
1494 suspended input.
1495
1496
1497 TCFLSH
1498 The argument is an int value. If the argument is 0,
1499 flush the input queue; if 1, flush the output queue; if
1500 2, flush both the input and output queues.
1501
1502
1503 TIOCGPGRP
1504 The argument is a pointer to a pid_t. Set the value of
1505 that pid_t to the process group ID of the foreground
1506 process group associated with the terminal. See
1507 termios(3C) for a description of TCGETPGRP.
1508
1509
1510 TIOCSPGRP
1511 The argument is a pointer to a pid_t. Associate the
1512 process group whose process group ID is specified by
1513 the value of that pid_t with the terminal. The new
1514 process group value must be in the range of valid
1515 process group ID values. Otherwise, the error EPERM
1516 is returned.
1517
1518
1519 TIOCGSID
1520 The argument is a pointer to a pid_t. The session ID of
1521 the terminal is fetched and stored in the pid_t.
1522
1523
1524 TIOCGWINSZ
1525 The argument is a pointer to a winsize structure. The
1526 terminal driver's notion of the terminal size is stored
1527 into that structure.
1528
1529
1530 TIOCSWINSZ
1531 The argument is a pointer to a winsize structure. The
1532 terminal driver's notion of the terminal size is set
1533 from the values specified in that structure. If the
1534 new sizes are different from the old sizes, a SIGWINCH
1535 signal is set to the process group of the terminal.
1536
1537
1538 TIOCMBIS
1539 The argument is a pointer to an int whose value is a
1540 mask containing modem control lines to be turned on.
1541 The control lines whose bits are set in the argument
1542 are turned on; no other control lines are affected.
1543
1544
1545 TIOCMBIC
1546 The argument is a pointer to an int whose value is a
1547 mask containing modem control lines to be turned off.
1548 The control lines whose bits are set in the argument
1549 are turned off; no other control lines are affected.
1550
1551
1552 TIOCMGET
1553 The argument is a pointer to an int. The current state
1554 of the modem status lines is fetched and stored in the
1555 int pointed to by the argument.
1556
1557
1558 TIOCMSET
1559 The argument is a pointer to an int containing a new
1560 set of modem control lines. The modem control lines are
1561 turned on or off, depending on whether the bit for that
1562 mode is set or clear.
1563
1564
1565 TIOCSPPS
1566 The argument is a pointer to an int that determines
1567 whether pulse-per-second event handling is to be
1568 enabled (non-zero) or disabled (zero). If a one-pulse-
1569 per-second reference clock is attached to the serial
1570 line's data carrier detect input, the local system
1571 clock will be calibrated to it. A clock with a high
1572 error, that is, a deviation of more than 25
1573 microseconds per tick, is ignored.
1574
1575
1576 TIOCGPPS
1577 The argument is a pointer to an int, in which the state
1578 of the even handling is returned. The int is set to a
1579 non-zero value if pulse-per-second (PPS) handling has
1580 been enabled. Otherwise, it is set to zero.
1581
1582
1583 TIOCGSOFTCAR
1584 The argument is a pointer to an int whose value is 1 or
1585 0, depending on whether the software carrier detect is
1586 turned on or off.
1587
1588
1589 TIOCSSOFTCAR
1590 The argument is a pointer to an int whose value is 1 or
1591 0. The value of the integer should be 0 to turn off
1592 software carrier, or 1 to turn it on.
1593
1594
1595 TIOCGPPSEV
1596 The argument is a pointer to a struct ppsclockev. This
1597 structure contains the following members:
1598
1599 struct timeval tv;
1600 uint32_t serial;
1601
1602 "tv" is the system clock timestamp when the event
1603 (pulse on the DCD pin) occurred. "serial" is the
1604 ordinal of the event, which each consecutive event
1605 being assigned the next ordinal. The first event
1606 registered gets a "serial" value of 1. The TIOCGPPSEV
1607 returns the last event registered; multiple calls will
1608 persistently return the same event until a new one is
1609 registered. In addition to time stamping and saving the
1610 event, if it is of one-second period and of
1611 consistently high accuracy, the local system clock will
1612 automatically calibrate to it.
1613
1614
1615 FILES
1616 Files in or under /dev
1617
1618 SEE ALSO
1619 stty(1), fork(2), getpgid(2), getsid(2), ioctl(2), setsid(2),
1620 sigaction(2), signal(3C), tcsetpgrp(3C), termios(3C), signal.h(3HEAD),
1621 streamio(7I)
1622
1623
1624
1625 December 30, 2016 TERMIO(7I)
|
1 TERMIO(7I) Ioctl Requests TERMIO(7I)
2
3 NAME
4 termio - general terminal interface
5
6 SYNOPSIS
7 #include <termio.h>
8
9 ioctl(int fildes, int request, struct termio *arg);
10
11 ioctl(int fildes, int request, int arg);
12
13 #include <termios.h>
14
15 ioctl(int fildes, int request, struct termios *arg);
16
17 DESCRIPTION
18 This release supports a general interface for asynchronous communications
19 ports that is hardware-independent. The user interface to this
20 functionality is using function calls (the preferred interface) described
21 in termios(3C) or ioctl() commands described in this section. This
22 section also discusses the common features of the terminal subsystem
23 which are relevant with both user interfaces.
24
25 When a terminal file is opened, it normally causes the process to wait
26 until a connection is established. In practice, user programs seldom
27 open terminal files; they are opened by the system and become a user's
28 standard input, output, and error files. The first terminal file opened
29 by the session leader that is not already associated with a session
30 becomes the controlling terminal for that session. The controlling
31 terminal plays a special role in handling quit and interrupt signals, as
32 discussed below. The controlling terminal is inherited by a child
33 process during a fork(2). A process can break this association by
34 changing its session using setsid(2).
35
36 A terminal associated with one of these files ordinarily operates in
37 full-duplex mode. Characters may be typed at any time, even while output
38 is occurring, and are only lost when the character input buffers of the
39 system become completely full, which is rare. For example, the number of
40 characters in the line discipline buffer may exceed {MAX_CANON} and
41 IMAXBEL (see below) is not set, or the user may accumulate {MAX_INPUT}
42 number of input characters that have not yet been read by some program.
43 When the input limit is reached, all the characters saved in the buffer
44 up to that point are thrown away without notice.
45
46 Session Management (Job Control)
47 A control terminal will distinguish one of the process groups in the
48 session associated with it to be the foreground process group. All other
49 process groups in the session are designated as background process
50 groups. This foreground process group plays a special role in handling
51 signal-generating input characters, as discussed below. By default, when
52 a controlling terminal is allocated, the controlling process's process
53 group is assigned as foreground process group.
54
55 Background process groups in the controlling process's session are
56 subject to a job control line discipline when they attempt to access
57 their controlling terminal. Process groups can be sent signals that will
58 cause them to stop, unless they have made other arrangements. An
59 exception is made for members of orphaned process groups.
60
61 An orphaned process group is one where the process group (see getpgid(2))
62 has no members with a parent in a different process group but sharing the
63 same controlling terminal. When a member of an orphaned process group
64 attempts to access its controlling terminal, EIO is returned because
65 there would be no way to restart the process if it were stopped on one of
66 these signals.
67
68 If a member of a background process group attempts to read its
69 controlling terminal, its process group will be sent a SIGTTIN signal,
70 which will normally cause the members of that process group to stop. If,
71 however, the process is ignoring or holding SIGTTIN, or is a member of an
72 orphaned process group, the read will fail with errno set to EIO, and no
73 signal is sent.
74
75 If a member of a background process group attempts to write its
76 controlling terminal and the TOSTOP bit is set in the c_lflag field, its
77 process group is sent a SIGTTOU signal, which will normally cause the
78 members of that process group to stop. If, however, the process is
79 ignoring or holding SIGTTOU, the write will succeed. If the process is
80 not ignoring or holding SIGTTOU and is a member of an orphaned process
81 group, the write will fail with errno set to EIO, and no signal will be
82 sent.
83
84 If TOSTOP is set and a member of a background process group attempts to
85 ioctl() its controlling terminal, and that ioctl() will modify terminal
86 parameters (for example, TCSETA, TCSETAW, TCSETAF, or TIOCSPGRP), its
87 process group will be sent a SIGTTOU signal, which will normally cause
88 the members of that process group to stop. If, however, the process is
89 ignoring or holding SIGTTOU, the ioctl will succeed. If the process is
90 not ignoring or holding SIGTTOU and is a member of an orphaned process
91 group, the write will fail with errno set to EIO, and no signal will be
92 sent.
93
94 Canonical Mode Input Processing
95 Normally, terminal input is processed in units of lines. A line is
96 delimited by a newline (ASCII LF) character, an end-of-file (ASCII EOT)
97 character, or an end-of-line character. This means that a program
98 attempting to read will block until an entire line has been typed. Also,
99 no matter how many characters are requested in the read call, at most one
100 line will be returned. It is not necessary, however, to read a whole
101 line at once; any number of characters may be requested in a read, even
102 one, without losing information.
103
104 During input, erase, erase2, and kill processing is normally done. The
105 ERASE and ERASE2 character (by default, the character DEL for ERASE and
106 Control-h for ERASE2) erases the last character typed. The WERASE
107 character (the character Control-w) erases the last "word" typed in the
108 current input line (but not any preceding spaces or tabs). A "word" is
109 defined as a sequence of non-blank characters, with tabs counted as
110 blanks. None of ERASE or ERASE2 or WERASE will erase beyond the
111 beginning of the line. The KILL character (by default, the character
112 NAK) kills (deletes) the entire input line, and optionally outputs a
113 newline character. All these characters operate on a key stroke basis,
114 independent of any backspacing or tabbing that may have been done. The
115 REPRINT character (the character Control-r) prints a newline followed by
116 all characters that have not been read. Reprinting also occurs
117 automatically if characters that would normally be erased from the screen
118 are fouled by program output. The characters are reprinted as if they
119 were being echoed; consequencely, if ECHO is not set, they are not
120 printed.
121
122 The ERASE, ERASE2, and KILL characters may be entered literally by
123 preceding them with the escape character. In this case, the escape
124 character is not read. The erase, erase2, and kill characters may be
125 changed.
126
127 Non-canonical Mode Input Processing
128 In non-canonical mode input processing, input characters are not
129 assembled into lines, and erase and kill processing does not occur. The
130 MIN and TIME values are used to determine how to process the characters
131 received.
132
133 MIN represents the minimum number of characters that should be received
134 when the read is satisfied (that is, when the characters are returned to
135 the user). TIME is a timer of 0.10-second granularity that is used to
136 timeout bursty and short-term data transmissions. The four possible
137 values for MIN and TIME and their interactions are described below.
138
139 Case A: MIN > 0, TIME > 0 In this case, TIME serves as an intercharacter
140 timer and is activated after the first
141 character is received. Since it is an
142 intercharacter timer, it is reset after a
143 character is received. The interaction
144 between MIN and TIME is as follows: as soon as
145 one character is received, the intercharacter
146 timer is started. If MIN characters are
147 received before the intercharacter timer
148 expires (note that the timer is reset upon
149 receipt of each character), the read is
150 satisfied. If the timer expires before MIN
151 characters are received, the characters
152 received to that point are returned to the
153 user. Note that if TIME expires, at least one
154 character will be returned because the timer
155 would not have been enabled unless a character
156 was received. In this case (MIN > 0, TIME >
157 0), the read sleeps until the MIN and TIME
158 mechanisms are activated by the receipt of the
159 first character. If the number of characters
160 read is less than the number of characters
161 available, the timer is not reactivated and
162 the subsequent read is satisfied immediately.
163
164 Case B: MIN > 0, TIME = 0 In this case, since the value of TIME is zero,
165 the timer plays no role and only MIN is
166 significant. A pending read is not satisfied
167 until MIN characters are received (the pending
168 read sleeps until MIN characters are
169 received). A program that uses this case to
170 read record based terminal I/O may block
171 indefinitely in the read operation.
172
173 Case C: MIN = 0, TIME > 0 In this case, since MIN 0, TIME no longer
174 represents an intercharacter timer: it now
175 serves as a read timer that is activated as
176 soon as a read(2) is done. A read is
177 satisfied as soon as a single character is
178 received or the read timer expires. Note
179 that, in this case, if the timer expires, no
180 character is returned. If the timer does not
181 expire, the only way the read can be satisfied
182 is if a character is received. In this case,
183 the read will not block indefinitely waiting
184 for a character; if no character is received
185 within TIME *.10 seconds after the read is
186 initiated, the read returns with zero
187 characters.
188
189 Case D: MIN = 0, TIME = 0 In this case, return is immediate. The
190 minimum of either the number of characters
191 requested or the number of characters
192 currently available is returned without
193 waiting for more characters to be input.
194
195 Comparing Different Cases of MIN, TIME Interaction
196 Some points to note about MIN and TIME:
197
198 o In the following explanations, note that the interactions of MIN
199 and TIME are not symmetric. For example, when MIN > 0 and TIME =
200 0, TIME has no effect. However, in the opposite case, where MIN =
201 0 and TIME > 0, both MIN and TIME play a role in that MIN is
202 satisfied with the receipt of a single character.
203
204 o Also note that in case A (MIN > 0, TIME > 0), TIME represents an
205 intercharacter timer, whereas in case C (MIN = 0, TIME > 0), TIME
206 represents a read timer.
207
208 These two points highlight the dual purpose of the MIN/TIME feature.
209 Cases A and B, where MIN > 0, exist to handle burst mode activity (for
210 example, file transfer programs), where a program would like to process
211 at least MIN characters at a time. In case A, the inteercharacter timer
212 is activated by a user as a safety measure; in case B, the timer is
213 turned off.
214
215 Cases C and D exist to handle single character, timed transfers. These
216 cases are readily adaptable to screen-based applications that need to
217 know if a character is present in the input queue before refreshing the
218 screen. In case C, the read is timed, whereas in case D, it is not.
219
220 Another important note is that MIN is always just a minimum. It does not
221 denote a record length. For example, if a program does a read of 20
222 bytes, MIN is 10, and 25 characters are present, then 20 characters will
223 be returned to the user.
224
225 Writing Characters
226 When one or more characters are written, they are transmitted to the
227 terminal as soon as previously written characters have finished typing.
228 nputt characters are echoed as they are typed if echoing has been
229 enabled. If a process produces characters more rapidly than they can be
230 typed, it will be suspended when its output queue exceeds some limit.
231 When the queue is drained down to some threshold, the program is resumed.
232
233 Special Characters
234 Certain characters have special functions on input. These functions and
235 their default character values are summarized as follows:
236
237 INTR (Control-c or ASCII ETX) generates a SIGINT signal. SIGINT is
238 sent to all foreground processes associated with the controlling
239 terminal. Normally, each such process is forced to terminate,
240 but arrangements may be made either to ignore the signal or to
241 receive a trap to an agreed upon location. (See
242 signal.h(3HEAD)).
243
244 QUIT (Control-| or ASCII FS) generates a SIGQUIT signal. Its
245 treatment is identical to the interrupt signal except that,
246 unless a receiving process has made other arrangements, it will
247 not only be terminated but a core image file (called core) will
248 be created in the current working directory.
249
250 ERASE (DEL) erases the preceding character. It does not erase beyond
251 the start of a line, as delimited by a NL, EOF, EOL, or EOL2
252 character.
253
254 ERASE2 (Control-h or ASCII BS) erases the preceding character, with
255 behaviour identical to that of ERASE.
256
257 WERASE (Control-w or ASCII ETX) erases the preceding "word". It does
258 not erase beyond the start of a line, as delimited by a NL, EOF,
259 EOL, or EOL2 character.
260
261 KILL (Control-u or ASCII NAK) deletes the entire line, as delimited
262 by a NL, EOF, EOL, or EOL2 character.
263
264 REPRINT (Control-r or ASCII DC2) reprints all characters, preceded by a
265 newline, that have not been read.
266
267 EOF (Control-d or ASCII EOT) may be used to generate an end-of-file
268 from a terminal. When received, all the characters waiting to
269 be read are immediately passed to the program, without waiting
270 for a newline, and the EOF is discarded. Thus, if no characters
271 are waiting (that is, the EOF occurred at the beginning of a
272 line) zero characters are passed back, which is the standard
273 end-of-file indication. Unless escaped, the EOF character is
274 not echoed. Because EOT is the default EOF character, this
275 prevents terminals that respond to EOT from hanging up.
276
277 NL (ASCII LF) is the normal line delimiter. It cannot be changed
278 or escaped.
279
280 EOL (ASCII NULL) is an additional line delimiter, like NL. It is
281 not normally used.
282
283 EOL2 is another additional line delimiter.
284
285 SWTCH (Control-z or ASCII EM) Header file symbols related to this
286 special character are present for compatibility purposes only
287 and the kernel takes no special action on matching SWTCH (except
288 to discard the character).
289
290 SUSP (Control-z or ASCII SUB) generates a SIGTSTP signal. SIGTSTP
291 stops all processes in the foreground process group for that
292 terminal.
293
294 DSUSP (Control-y or ASCII EM). It generates a SIGTSTP signal as SUSP
295 does, but the signal is sent when a process in the foreground
296 process group attempts to read the DSUSP character, rather than
297 when it is typed.
298
299 STOP (Control-s or ASCII DC3) can be used to suspend output
300 temporarily. It is useful with CRT terminals to prevent output
301 from disappearing before it can be read. While output is
302 suspended, STOP characters are ignored and not read.
303
304 START (Control-q or ASCII DC1) is used to resume output. Output has
305 been suspended by a STOP character. While output is not
306 suspended, START characters are ignored and not read.
307
308 DISCARD (Control-o or ASCII SI) causes subsequent output to be
309 discarded. Output is discarded until another DISCARD character
310 is typed, more input arrives, or the condition is cleared by a
311 program.
312
313 STATUS (Control-t or ASCII DC4) generates a SIGINFO signal. Processes
314 with a handler will output status information when they receive
315 SIGINFO, for example, dd(1M). If a process does not have a
316 SIGINFO handler, the signal will be ignored.
317
318 LNEXT (Control-v or ASCII SYN) causes the special meaning of the next
319 character to be ignored. This works for all the special
320 characters mentioned above. It allows characters to be input
321 that would otherwise be interpreted by the system (for example
322 KILL, QUIT). The character values for INTR, QUIT, ERASE,
323 ERASE2, WERASE, KILL, REPRINT, EOF, EOL, EOL2, SWTCH, SUSP,
324 DSUSP, STOP, START, DISCARD, STATUS, and LNEXT may be changed to
325 suit individual tastes. If the value of a special control
326 character is _POSIX_VDISABLE (0), the function of that special
327 control character is disabled. The ERASE, ERASE2, KILL, and EOF
328 characters may be escaped by a preceding backslash (\)
329 character, in which case no special function is done. Any of
330 the special characters may be preceded by the LNEXT character,
331 in which case no special function is done.
332
333 Modem Disconnect
334 When a modem disconnect is detected, a SIGHUP signal is sent to the
335 terminal's controlling process. Unless other arrangements have been
336 made, these signals cause the process to terminate. If SIGHUP is ignored
337 or caught, any subsequent read returns with an end-of-file indication
338 until the terminal is closed.
339
340 If the controlling process is not in the foreground process group of the
341 terminal, a SIGTSTP is sent to the terminal's foreground process group.
342 Unless other arrangements have been made, these signals cause the
343 processes to stop.
344
345 Processes in background process groups that attempt to access the
346 controlling terminal after modem disconnect while the terminal is still
347 allocated to the session will receive appropriate SIGTTOU and SIGTTIN
348 signals. Unless other arrangements have been made, this signal causes
349 the processes to stop.
350
351 The controlling terminal will remain in this state until it is
352 reinitialized ithh a successful open by the controlling process, or
353 deallocated by the controlling process.
354
355 Terminal Parameters
356 The parameters that control the behavior of devices and modules providing
357 the termios interface are specified by the termios structure defined by
358 <termios.h>. Several ioctl(2) system calls that fetch or change these
359 parameters use this structure that contains the following members:
360
361 tcflag_t c_iflag; /* input modes */
362 tcflag_t c_oflag; /* output modes */
363 tcflag_t c_cflag; /* control modes */
364 tcflag_t c_lflag; /* local modes */
365 cc_t c_cc[NCCS]; /* control chars */
366
367 The special control characters are defined by the array c_cc. The
368 symbolic name NCCS is the size of the Control-character array and is also
369 defined by <termios.h>. The relative positions, subscript names, and
370 typical default values for each function are as follows:
371
372 Relative Position Subscript Name Typical Default Value
373 0 VINTR ETX
374 1 VQUIT FS
375 2 VERASE DEL
376 3 VKILL NAK
377 4 VEOF EOT
378 5 VEOL NUL
379 6 VEOL2 NUL
380 7 VWSTCH NUL
381 8 VSTART NUL
382 9 VSTOP DC3
383 10 VSUSP SUB
384 11 VDSUSP EM
385 12 VREPRINT DC2
386 13 VDISCARD SI
387 14 VWERASE ETB
388 15 VLNEXT SYN
389 16 VSTATUS DC4
390 17 VERASE2 BS
391 18-19 Reserved
392
393 Input Modes
394 The c_iflag field describes the basic terminal input control:
395
396 IGNBRK Ignore break condition.
397 BRKINT Signal interrupt on break.
398 IGNPAR Ignore characters with parity errors.
399 PARMRK Mark parity errors.
400 INPCK Enable input parity check.
401 ISTRIP Strip character.
402 INLCR Map NL to CR on input.
403 IGNCR Ignore CR.
404 ICRNL Map CR to NL on input.
405 IUCLC Map upper-case to lower-case on input.
406 IXON Enable start/stop output control.
407 IXANY Enable any character to restart output.
408 IXOFF Enable start/stop input control.
409 IMAXBEL Echo BEL on input line too long.
410
411 If IGNBRK is set, a break condition (a character framing error with data
412 all zeros) detected on input is ignored, that is, not put on the input
413 queue and therefore not read by any process. If IGNBRK is not set and
414 BRKINT is set, the break condition shall flush the input and output
415 queues and if the terminal is the controlling terminal of a foreground
416 process group, the break condition generates a single SIGINT signal to
417 that foreground process group. If neither IGNBRK nor BRKINT is set, a
418 break condition is read as a single `\0' (ASCII NULL) character, or if
419 PARMRK is set, as `\377', `\0', c, where `\377' is a single character
420 with value 377 octal (0xff hex, 255 decimal), `\0' is a single character
421 with value 0, and c is the errored character received.
422
423 If IGNPAR is set, a byte with framing or parity errors (other than break)
424 is ignored.
425
426 If PARMRK is set, and IGNPAR is not set, a byte with a framing or parity
427 error (other than break) is given to the application as the three-
428 character sequence: `\377', `\0', c, where `\377' is a single character
429 with value 377 octal (0xff hex, 255 decimal), `\0' is a single character
430 with value 0, and c is the errored character received. To avoid
431 ambiguity in this case, if ISTRIP is not set, a valid character of `\377'
432 is given to the application as `\377'. If neither IGNPAR nor PARMRK is
433 set, a framing or parity error (other than break) is given to the
434 application as a single `\0' (ASCII NULL) character.
435
436 If INPCK is set, input parity checking is enabled. If INPCK is not set,
437 input parity checking is disabled. This allows output parity generation
438 without input parity errors. Note that whether input parity checking is
439 enabled or disabled is independent of whether parity detection is enabled
440 or disabled. If parity detection is enabled but input parity checking is
441 disabled, the hardware to which the terminal is connected will recognize
442 the parity bit, but the terminal special file will not check whether this
443 is set correctly or not.
444
445 If ISTRIP is set, valid input characters are first stripped to seven
446 bits, otherwise all eight bits are processed.
447
448 If INLCR is set, a received NL character is translated into a CR
449 character. If IGNCR is set, a received CR character is ignored (not
450 read). Otherwise, if ICRNL is set, a received CR character is translated
451 into a NL character.
452
453 If IUCLC is set, a received upper case, alphabetic character is
454 translated into the corresponding lower case character.
455
456 If IXON is set, start/stop output control is enabled. A received STOP
457 character suspends output and a received START character restarts output.
458 The STOP and START characters will not be read, but will merely perform
459 flow control functions. If IXANY is set, any input character restarts
460 output that has been suspended.
461
462 If IXOFF is set, the system transmits a STOP character when the input
463 queue is nearly full, and a START character when enough input has been
464 read so that the input queue is nearly empty again.
465
466 If IMAXBEL is set, the ASCII BEL character is echoed if the input stream
467 overflows. Further input is not stored, but any input already present in
468 the input stream is not disturbed. If IMAXBEL is not set, no BEL
469 character is echoed, and all input present in the input queue is
470 discarded if the input stream overflows.
471
472 Output Modes
473 The c_oflag field specifies the system treatment of output:
474
475 OPOST Post-process output.
476 OLCUC Map lower case to upper on output.
477 ONLCR Map NL to CR-NL on output.
478 OCRNL Map CR to NL on output.
479 ONOCR No CR output at column 0.
480 ONLRET NL performs CR function.
481 OFILL Use fill characters for delay.
482 OFDEL Fill is DEL, else INULL.
483 NLDLY Select newline delays:
484 NL0
485 NL1
486 CRDLY Select carriage-return delays:
487 CR0
488 CR1
489 CR2
490 CR3
491 TABDLY Select horizontal tab delays or tab expansion:
492 TAB0
493 TAB1
494 TAB2
495 TAB3 Expand tabs to spaces
496 XTABS Expand tabs to spaces
497 BSDLY Select backspace delays:
498 BS0
499 BS1
500 VTDLY Select vertical tab delays:
501 VT0
502 VT1
503 FFDLY Select form feed delays:
504 FF0
505 FF1
506
507 If OPOST is set, output characters are post-processed as indicated by the
508 remaining flags; otherwise, characters are transmitted without change.
509
510 If OLCUC is set, a lower case alphabetic character is transmitted as the
511 corresponding upper case character. This function is often used in
512 conjunction with IUCLC.
513
514 If ONLCR is set, the NL character is transmitted as the CR-NL character
515 pair. If OCRNL is set, the CR character is transmitted as the NL
516 character. If ONOCR is set, no CR character is transmitted when at
517 column 0 (first position). If ONRET is set, the NL character is assumed
518 to do the carriage-return function; the column pointer is set to 0 and
519 the delays specified for CR are used. Otherwise, the NL character is
520 assumed to do just the line-feed function; the column pointer remains
521 unchanged. The column pointer is also set to 0 if the CR character is
522 actually transmitted.
523
524 The delay bits specify how long transmission stops to allow for
525 mechanical or other movement when certain characters are sent to the
526 terminal. In all cases, a value of 0 indicates no delay. If OFILL is
527 set, fill characters are transmitted for delay instead of a timed delay.
528 This is useful for high baud rate terminals that need only a minimal
529 delay. If OFDEL is set, the fill character is DEL; otherwise it is NULL.
530
531 If a form-feed or vertical-tab delay is specified, it lasts for about 2
532 seconds.
533
534 Newline delay lasts about 0.10 seconds. If ONLRET is set, the carriage-
535 return delays are used instead of the newline delays. If OFILL is set,
536 two fill characters are transmitted.
537
538 Carriage-return delay type 1 is dependent on the current column position,
539 type 2 is about 0.10 seconds, and type 3 is about 0.15 seconds. If OFILL
540 is set, delay type 1 transmits two fill characters, and type 2 transmits
541 four fill characters.
542
543 Horizontal-tab delay type 1 is dependent on the current column position.
544 Type 2 is about 0.10 seconds. Type 3 specifies that tabs are to be
545 expanded into spaces. If OFILL is set, two fill characters are
546 transmitted for any delay.
547
548 Backspace delay lasts about 0.05 seconds. If OFILL is set, one fill
549 character is transmitted.
550
551 The actual delays depend on line speed and system load.
552
553 Control Modes
554 The c_cflag field describes the hardware control of the terminal:
555
556 CBAUD Baud rate:
557 B0 Hang up
558 B50 50 baud
559 B75 75 baud
560 B110 110 baud
561 B134 134 baud
562 B150 150 baud
563 B200 200 baud
564 B300 300 baud
565 B600 600 baud
566 B1200 1200 baud
567 B1800 1800 baud
568 B2400 2400 baud
569 B4800 4800 baud
570 B9600 9600 baud
571 B19200 19200 baud
572 EXTA External A
573 B38400 38400 baud
574 EXTB External B
575 B57600 57600 baud
576 B76800 76800 baud
577 B115200 115200 baud
578 B153600 153600 baud
579 B230400 230400 baud
580 B307200 307200 baud
581 B460800 460800 baud
582
583 CSIZE Character size:
584 CS5 5 bits
585 CS6 6 bits
586 CS7 7 bits
587 CS8 8 bits
588 CSTOPB Send two stop bits, else one
589 CREAD Enable receiver
590 PARENB Parity enable
591 PARODD Odd parity, else even
592 HUPCL Hang up on last close
593 CLOCAL Local line, else dial-up
594 CIBAUD Input baud rate, if different from output rate
595 PAREXT Extended parity for mark and space parity
596 CRTSXOFF Enable inbound hardware flow control
597 CRTSCTS Enable outbound hardware flow control
598 CBAUDEXT Bit to indicate output speed > B38400
599 CIBAUDEXT Bit to indicate input speed > B38400
600
601 The CBAUD bits together with the CBAUDEXT bit specify the output baud
602 rate. To retrieve the output speed from the termios structure pointed to
603 by termios_p see the following code segment.
604
605 speed_t ospeed;
606 if (termios_p->c_cflag & CBAUDEXT)
607 ospeed = (termios_p->c_cflag & CBAUD) + CBAUD + 1;
608 else
609 ospeed = termios_p->c_cflag & CBAUD;
610
611 To store the output speed in the termios structure pointed to by
612 termios_p see the following code segment.
613
614 speed_t ospeed;
615 if (ospeed > CBAUD) {
616 termios_p->c_cflag |= CBAUDEXT;
617 ospeed -= (CBAUD + 1);
618 } else {
619 termios_p->c_cflag &= ~CBAUDEXT;
620 }
621 termios_p->c_cflag =
622 (termios_p->c_cflag & ~CBAUD) | (ospeed & CBAUD);
623
624 The zero baud rate, B0, is used to hang up the connection. If B0 is
625 specified, the data-terminal-ready signal is not asserted. Normally,
626 this disconnects the line.
627
628 If the CIBAUDEXT or CIBAUD bits are not zero, they specify the input baud
629 rate, with the CBAUDEXT and CBAUD bits specifying the output baud rate;
630 otherwise, the output and input baud rates are both specified by the
631 CBAUDEXT and CBAUD bits. The values for the CIBAUD bits are the same as
632 the values for the CBAUD bits, shifted left IBSHIFT bits. For any
633 particular hardware, impossible speed changes are ignored. To retrieve
634 the input speed in the termios structure pointed to by termios_p see the
635 following code segment.
636
637 speed_t ispeed;
638 if (termios_p->c_cflag & CIBAUDEXT) {
639 ispeed = ((termios_p->c_cflag & CIBAUD) >> IBSHIFT)
640 + (CIBAUD >> IBSHIFT) + 1;
641 } else {
642 ispeed = (termios_p->c_cflag & CIBAUD) >> IBSHIFT;
643 }
644
645 To store the input speed in the termios structure pointed to by termios_p
646 see the following code segment.
647
648 speed_t ispeed;
649 if (ispeed == 0) {
650 ispeed = termios_p->c_cflag & CBAUD;
651 if (termios_p->c_cflag & CBAUDEXT)
652 ispeed += (CBAUD + 1);
653 }
654 if ((ispeed << IBSHIFT) > CIBAUD) {
655 termios_p->c_cflag |= CIBAUDEXT;
656 ispeed -= ((CIBAUD >> IBSHIFT) + 1);
657 } else {
658 termios_p->c_cflag &= ~CIBAUDEXT;
659 }
660 termios_p->c_cflag =
661 (termios_p->c_cflag & ~CIBAUD) | ((ispeed << IBSHIFT) & CIBAUD);
662
663 The CSIZE bits specify the character size in bits for both transmission
664 and reception. This size does not include the parity bit, if any. If
665 CSTOPB is set, two stop bits are used; otherwise, one stop bit is used.
666 For example, at 110 baud, two stops bits are required.
667
668 If PARENB is set, parity generation and detection is enabled, and a
669 parity bit is added to each character. If parity is enabled, the PARODD
670 flag specifies odd parity if set; otherwise, even parity is used.
671
672 If CREAD is set, the receiver is enabled. Otherwise, no characters are
673 received.
674
675 If HUPCL is set, the line is disconnected when the last process with the
676 line open closes it or terminates. That is, the data-terminal-ready
677 signal is not asserted.
678
679 If CLOCAL is set, the line is assumed to be a local, direct connection
680 with no modem control; otherwise, modem control is assumed.
681
682 If CRTSXOFF is set, inbound hardware flow control is enabled.
683
684 If CRTSCTS is set, outbound hardware flow control is enabled.
685
686 The four possible combinations for the state of CRTSCTS and CRTSXOFF bits
687 and their interactions are described below.
688
689 Case A: CRTSCTS off, CRTSXOFF off. In this case the hardware flow
690 control is disabled.
691
692 Case B: CRTSCTS on, CRTSXOFF off. In this case only outbound hardware
693 flow control is enabled. The state of CTS signal is used to do
694 outbound flow control. It is expected that output will be
695 suspended if CTS is low and resumed when CTS is high.
696
697 Case C: CRTSCTS off, CRTSXOFF on. In this case only inbound hardware
698 flow control is enabled. The state of RTS signal is used to do
699 inbound flow control. It is expected that input will be
700 suspended if RTS is low and resumed when RTS is high.
701
702 Case D: CRTSCTS on, CRTSXOFF on. In this case both inbound and outbound
703 hardware flow control are enabled. Uses the state of CTS signal
704 to do outbound flow control and RTS signal to do inbound flow
705 control.
706
707 Local Modes
708 The c_lflag field of the argument structure is used by the line
709 discipline to control terminal functions. The basic line discipline
710 provides the following:
711
712 ISIG Enable signals.
713 ICANON Canonical input (erase and kill processing).
714 XCASE Canonical upper/lower presentation.
715 ECHO Enable echo.
716 ECHOE Echo erase character as BS-SP-BS &.
717 ECHOK Echo NL after kill character.
718 ECHONL Echo NL.
719 NOFLSH Disable flush after interrupt or quit.
720 TOSTOP Send
721 SIGTTOU for background output.
722 ECHOCTL Echo control characters as char, delete as ^?.
723 ECHOPRT Echo erase character as character erased.
724 ECHOKE BS-SP-BS erase entire line on line kill.
725 FLUSHO Output is being flushed.
726 PENDIN Retype pending input at next read or input character.
727 IEXTEN Enable extended (implementation-defined) functions.
728
729 If ISIG is set, each input character is checked against the special
730 control characters INTR, QUIT, SWTCH, SUSP, STATUS, and DSUSP. If an
731 input character matches one of these control characters, the function
732 associated with that character is performed. (Note: If SWTCH is set and
733 the character matches, the character is simply discarded. No other
734 action is taken.) If ISIG is not set, no checking is done. Thus, these
735 special input functions are possible only if ISIG is set.
736
737 If ICANON is set, canonical processing is enabled. This enables the
738 erase and kill edit functions, and the assembly of input characters into
739 lines delimited by NL-c, EOF, EOL, and EOL. If ICANON is not set, read
740 requests are satisfied directly from the input queue. A read is not
741 satisfied until at least MIN characters have been received or the timeout
742 value TIME has expired between characters. This allows fast bursts of
743 input to be read efficiently while still allowing single character input.
744 The time value represents tenths of seconds.
745
746 If XCASE is set and ICANON is set, an upper case letter is accepted on
747 input if preceded by a backslash `\' character, and is output preceded by
748 a backslash `\' character. In this mode, the following escape sequences
749 are generated on output and accepted on input:
750
751 FOR: USE:
752 ` \'
753 | \!
754 ~ \^
755 { \(
756 } \)
757 \ \\
758
759 For example, input A as \a, \n as \\n, and \N as \\\n.
760
761 If ECHO is set, characters are echoed as received.
762
763 When ICANON is set, the following echo functions are possible.
764
765 o If ECHO and ECHOE are set, and ECHOPRT is not set, the ERASE,
766 ERASE2, and WERASE characters are echoed as one or more ASCII
767 BS SP BS, which clears the last character(s) from a CRT screen.
768
769 o If ECHO, ECHOPRT, and IEXTEN are set, the first ERASE, ERASE2,
770 and WERASE character in a sequence echoes as a backslash `\',
771 followed by the characters being erased. Subsequent ERASE and
772 WERASE characters echo the characters being erased, in reverse
773 order. The next non-erase character causes a `/' (slash) to be
774 typed before it is echoed. ECHOPRT should be used for hard
775 copy terminals.
776
777 o If ECHOKE and IEXTEN are set, the kill character is echoed by
778 erasing each character on the line from the screen (using the
779 mechanism selected by ECHOE and ECHOPR).
780
781 o If ECHOK is set, and ECHOKE is not set, the NL character is
782 echoed after the kill character to emphasize that the line is
783 deleted. Note that a `\' (escape) character or an LNEXT
784 character preceding the erase or kill character removes any
785 special function.
786
787 o If ECHONL is set, the NL character is echoed even if ECHO is
788 not set. This is useful for terminals set to local echo (so
789 called half-duplex).
790
791 If ECHOCTL and IEXTEN are set, all control characters (characters with
792 codes between 0 and 37 octal) other than ASCII TAB, ASCII NL, the START
793 character, and the STOP character, ASCII CR, and ASCII BS are echoed as
794 ^X, where X is the character given by adding `100' octal to the code of
795 the control character (so that the character with octal code `1' is
796 echoed as ^A), and the ASCII DEL character, with code `177' octal, is
797 echoed as ^?.
798
799 If NOFLSH is set, the normal flush of the input and output queues
800 associated with the INTR, QUIT, STATUS, and SUSP characters is not done.
801 This bit should be set when restarting system calls that read from or
802 write to a terminal (see sigaction(2)).
803
804 If TOSTOP and IEXTEN are set, the signal SIGTTOU is sent to a process
805 that tries to write to its controlling terminal if it is not in the
806 foreground process group for that terminal. This signal normally stops
807 the process. Otherwise, the output generated by that process is output
808 to the current output stream. Processes that are blocking or ignoring
809 SIGTTOU signals are excepted and allowed to produce output, if any.
810
811 If FLUSHO and IEXTEN are set, data written to the terminal is discarded.
812 This bit is set when the FLUSH character is typed. A program can cancel
813 the effect of typing the FLUSH character by clearing FLUSHO.
814
815 If PENDIN and IEXTEN are set, any input that has not yet been read is
816 reprinted when the next character arrives as input. PENDIN is then
817 automatically cleared.
818
819 If IEXTEN is set, the following implementation-defined functions are
820 enabled: special characters ( WERASE, REPRINT, DISCARD, and LNEXT) and
821 local flags ( TOSTOP, ECHOCTL, ECHOPRT, ECHOKE, FLUSHO, and PENDIN).
822
823 Minimum and Timeout
824 The MIN and TIME values were described previously, in the subsection,
825 Non-canonical Mode Input Processing. The initial value of MIN is 1, and
826 the initial value of TIME is 0.
827
828 Terminal Size
829 The number of lines and columns on the terminal's display is specified in
830 the winsize structure defined by <sys/termios.h> and includes the
831 following members:
832
833 unsigned short ws_row; /* rows, in characters */
834 unsigned short ws_col; /* columns, in characters */
835 unsigned short ws_xpixel; /* horizontal size, in pixels */
836 unsigned short ws_ypixel; /* vertical size, in pixels */
837
838 Termio Structure
839 The SunOS/SVR4 termio structure is used by some ioctl()s; it is defined
840 by <sys/termio.h> and includes the following members:
841
842 unsigned short c_iflag; /* input modes */
843 unsigned short c_oflag; /* output modes */
844 unsigned short c_cflag; /* control modes */
845 unsigned short c_lflag; /* local modes */
846 char c_line; /* line discipline */
847 unsigned char c_cc[NCC]; /* control chars */
848
849 The special control characters are defined by the array c_cc. The
850 symbolic name NCC is the size of the Control-character array and is also
851 defined by <termio.h>. The relative positions, subscript names, and
852 typical default values for each function are as follows:
853
854 Relative Positions Subscript Names Typical Default Values
855 0 VINTR EXT
856 1 VQUIT FS
857 2 VERASE DEL
858 3 VKILL NAK
859 4 VEOF EOT
860 5 VEOL NUL
861 6 VEOL2 NUL
862 7 Reserved
863
864 The MIN values is stored in the VMIN element of the c_cc array; the TIME
865 value is stored in the VTIME element of the c_cc array. The VMIN element
866 is the same element as the VEOF element; the VTIME element is the same
867 element as the VEOL element.
868
869 The calls that use the termio structure only affect the flags and control
870 characters that can be stored in the termio structure; all other flags
871 and control characters are unaffected.
872
873 Modem Lines
874 On special files representing serial ports, modem control lines can be
875 read. Control lines (if the underlying hardware supports it) may also be
876 changed. Status lines are read-only. The following modem control and
877 status lines may be supported by a device; they are defined by
878 <sys/termios.h>:
879
880 TIOCM_LE line enable
881 TIOCM_DTR data terminal ready
882 TIOCM_RTS request to send
883 TIOCM_ST secondary transmit
884 TIOCM_SR secondary receive
885 TIOCM_CTS clear to send
886 TIOCM_CAR carrier detect
887 TIOCM_RNG ring
888 TIOCM_DSR data set ready
889
890 TIOCM_CD is a synonym for TIOCM_CAR, and TIOCM_RI is a synonym for
891 TIOCM_RNG. Not all of these are necessarily supported by any particular
892 device; check the manual page for the device in question.
893
894 The software carrier mode can be enabled or disabled using the
895 TIOCSSOFTCAR ioctl(). If the software carrier flag for a line is off,
896 the line pays attention to the hardware carrier detect (DCD) signal. The
897 tty device associated with the line cannot be opened until DCD is
898 asserted. If the software carrier flag is on, the line behaves as if DCD
899 is always asserted.
900
901 The software carrier flag is usually turned on for locally connected
902 terminals or other devices, and is off for lines with modems.
903
904 To be able to issue the TIOCGSOFTCAR and TIOCSSOFTCAR ioctl() calls, the
905 tty line should be opened with O_NDELAY so that the open(2) will not wait
906 for the carrier.
907
908 Default Values
909 The initial termios values upon driver open is configurable. This is
910 accomplished by setting the "ttymodes" property in the file
911 /kernel/drv/options.conf. Since this property is assigned during system
912 initialization, any change to the "ttymodes" property will not take
913 effect until the next reboot. The string value assigned to this property
914 should be in the same format as the output of the stty(1) command with
915 the -g option.
916
917 If this property is undefined, the following termios modes are in effect.
918 The initial input control value is BRKINT, ICRNL, IXON, IMAXBEL. The
919 initial output control value is OPOST, ONLCR, TAB3. The initial hardware
920 control value is B9600, CS8, CREAD. The initial line-discipline control
921 value is ISIG, ICANON, IEXTEN, ECHO, ECHOK, ECHOE, ECHOKE, ECHOCTL.
922
923 IOCTLS
924 The ioctl()s supported by devices and STREAMS modules providing the
925 termios(3C) interface are listed below. Some calls may not be supported
926 by all devices or modules. The functionality provided by these calls is
927 also available through the preferred function call interface specified on
928 termios.
929
930 TCGETS The argument is a pointer to a termios structure. The
931 current terminal parameters are fetched and stored into
932 that structure.
933
934 TCSETS The argument is a pointer to a termios structure. The
935 current terminal parameters are set from the values stored
936 in that structure. The change is immediate.
937
938 TCSETSW The argument is a pointer to a termios structure. The
939 current terminal parameters are set from the values stored
940 in that structure. The change occurs after all characters
941 queued for output have been transmitted. This form should
942 be used when changing parameters that affect output.
943
944 TCSETSF The argument is a pointer to a termios structure. The
945 current terminal parameters are set from the values stored
946 in that structure. The change occurs after all characters
947 queued for output have been transmitted; all characters
948 queued for input are discarded and then the change occurs.
949
950 TCGETA The argument is a pointer to a termio structure. The
951 current terminal parameters are fetched, and those
952 parameters that can be stored in a termio structure are
953 stored into that structure.
954
955 TCSETA The argument is a pointer to a termio structure. Those
956 terminal parameters that can be stored in a termio
957 structure are set from the values stored in that structure.
958 The change is immediate.
959
960 TCSETAW The argument is a pointer to a termio structure. Those
961 terminal parameters that can be stored in a termio
962 structure are set from the values stored in that structure.
963 The change occurs after all characters queued for output
964 have been transmitted. This form should be used when
965 changing parameters that affect output.
966
967 TCSETAF The argument is a pointer to a termio structure. Those
968 terminal parameters that can be stored in a termio
969 structure are set from the values stored in that structure.
970 The change occurs after all characters queued for output
971 have been transmitted; all characters queued for input are
972 discarded and then the change occurs.
973
974 TCSBRK The argument is an int value. Wait for the output to
975 drain. If the argument is 0, then send a break (zero
976 valued bits for 0.25 seconds).
977
978 TCXONC Start/stop control. The argument is an int value. If the
979 argument is 0, suspend output; if 1, restart suspended
980 output; if 2, suspend input; if 3, restart suspended input.
981
982 TCFLSH The argument is an int value. If the argument is 0, flush
983 the input queue; if 1, flush the output queue; if 2, flush
984 both the input and output queues.
985
986 TIOCGPGRP The argument is a pointer to a pid_t. Set the value of
987 that pid_t to the process group ID of the foreground
988 process group associated with the terminal. See
989 termios(3C) for a description of TCGETPGRP.
990
991 TIOCSPGRP The argument is a pointer to a pid_t. Associate the
992 process group whose process group ID is specified by the
993 value of that pid_t with the terminal. The new process
994 group value must be in the range of valid process group ID
995 values. Otherwise, the error EPERM is returned.
996
997 TIOCGSID The argument is a pointer to a pid_t. The session ID of
998 the terminal is fetched and stored in the pid_t.
999
1000 TIOCGWINSZ The argument is a pointer to a winsize structure. The
1001 terminal driver's notion of the terminal size is stored
1002 into that structure.
1003
1004 TIOCSWINSZ The argument is a pointer to a winsize structure. The
1005 terminal driver's notion of the terminal size is set from
1006 the values specified in that structure. If the new sizes
1007 are different from the old sizes, a SIGWINCH signal is set
1008 to the process group of the terminal.
1009
1010 TIOCMBIS The argument is a pointer to an int whose value is a mask
1011 containing modem control lines to be turned on. The
1012 control lines whose bits are set in the argument are turned
1013 on; no other control lines are affected.
1014
1015 TIOCMBIC The argument is a pointer to an int whose value is a mask
1016 containing modem control lines to be turned off. The
1017 control lines whose bits are set in the argument are turned
1018 off; no other control lines are affected.
1019
1020 TIOCMGET The argument is a pointer to an int. The current state of
1021 the modem status lines is fetched and stored in the int
1022 pointed to by the argument.
1023
1024 TIOCMSET The argument is a pointer to an int containing a new set of
1025 modem control lines. The modem control lines are turned on
1026 or off, depending on whether the bit for that mode is set
1027 or clear.
1028
1029 TIOCSPPS The argument is a pointer to an int that determines whether
1030 pulse-per-second event handling is to be enabled (non-zero)
1031 or disabled (zero). If a one-pulse-per-second reference
1032 clock is attached to the serial line's data carrier detect
1033 input, the local system clock will be calibrated to it. A
1034 clock with a high error, that is, a deviation of more than
1035 25 microseconds per tick, is ignored.
1036
1037 TIOCGPPS The argument is a pointer to an int, in which the state of
1038 the even handling is returned. The int is set to a non-
1039 zero value if pulse-per-second (PPS) handling has been
1040 enabled. Otherwise, it is set to zero.
1041
1042 TIOCGSOFTCAR The argument is a pointer to an int whose value is 1 or 0,
1043 depending on whether the software carrier detect is turned
1044 on or off.
1045
1046 TIOCSSOFTCAR The argument is a pointer to an int whose value is 1 or 0.
1047 The value of the integer should be 0 to turn off software
1048 carrier, or 1 to turn it on.
1049
1050 TIOCGPPSEV The argument is a pointer to a struct ppsclockev. This
1051 structure contains the following members:
1052
1053 struct timeval tv;
1054 uint32_t serial;
1055
1056 tv is the system clock timestamp when the event (pulse on
1057 the DCD pin) occurred. serial is the ordinal of the event,
1058 which each consecutive event being assigned the next
1059 ordinal. The first event registered gets a serial value of
1060 1. The TIOCGPPSEV returns the last event registered;
1061 multiple calls will persistently return the same event
1062 until a new one is registered. In addition to time
1063 stamping and saving the event, if it is of one-second
1064 period and of consistently high accuracy, the local system
1065 clock will automatically calibrate to it.
1066
1067 FILES
1068 Files in or under /dev
1069
1070 SEE ALSO
1071 stty(1), fork(2), getpgid(2), getsid(2), ioctl(2), setsid(2),
1072 sigaction(2), signal(3C), tcsetpgrp(3C), termios(3C), signal.h(3HEAD),
1073 streamio(7I)
1074
1075 illumos March 17, 2019 illumos
|