| blob | 1306ed63b7afbf1e5f8cc4f605fd2d3ec8de0eb7 |
1 .TH TTY 4
2 .SH NAME
3 tty, termios \- terminals
4 .SH DESCRIPTION
5 The
6 .B tty
7 driver family takes care of all user input and output. It governs the
8 keyboard, the console, the serial lines, and pseudo ttys. Input on any of
9 these devices undergoes "input processing", and output undergoes "output
10 processing" according to the standard termios terminal interface.
11 .SS "Input processing"
12 Each terminal device has an input queue. This queue is used to store
13 preprocessed input characters, and to perform the backspacing and erase
14 functions. Some special characters like a newline make the contents of the
15 queue available to a process reading from the terminal. Characters up to
16 and including the newline, or another so-called "line break", may be read by
17 a process. The process need not read all characters at once. An input line
18 may be read byte by byte if one wants to. A line break just makes
19 characters available for reading, thats all.
20 .PP
21 When data is made available depends on whether the tty is in canonical mode
22 or not. In canonical mode the terminal processes input line by line. A
23 line ends with a newline
24 .RB ( NL ),
25 end-of-file
26 .RB ( EOF ),
27 or end-of-line
28 .RB ( EOL ).
29 Characters that have not been delimited by such a line break may be erased
30 one by one with the
31 .B ERASE
32 character or all at once with the
33 .B KILL
34 character. Once a line break is typed the characters become available to a
35 reading process and can no longer be erased. Once read they are removed
36 from the input queue. Several lines may be gathered in the input queue if
37 no reader is present to read them, but a new reader will only receive one
38 line. Two line breaks are never returned in one read call. The input queue
39 has a maximum length of
40 .B MAX_CANON
41 characters. Any more characters are discarded. One must use
42 .B ERASE
43 or
44 .B KILL
45 to make the terminal functioning again if the input queue fills up. If
46 nonblocking I/O is set then \-1 is returned with
47 .B errno
48 set to
49 .B EAGAIN
50 if the reader would otherwise be blocked.
51 .PP
52 In non-canonical mode (raw mode for short) all characters are immediately
53 available to the reader in principle. One may however tune the terminal to
54 bursty input with the
55 .B MIN
56 and
57 .B TIME
58 parameters, see the raw I/O parameters section below. In raw mode no
59 characters are discarded if the input queue threatens to overflow if the
60 device supports flow control.
61 .SS "Output processing"
62 Characters written to a terminal device may undergo output processing, which
63 is usually just inserting a carriage returns before newlines. A writer
64 may return before all characters are output if the characters can be stored
65 in the output buffers. If not then the writer may be blocked until space is
66 available. If non-blocking I/O is set then only the count of the number of
67 bytes that can be processed immediately is returned. If no characters can
68 be written at all then \-1 is returned with
69 .B errno
70 set to
71 .BR EAGAIN .
72 .SS "Special characters"
73 Some characters have special functions in some of the terminal modes. These
74 characters are as follows, with the MINIX 3 defaults shown in parentheses:
75 .TP 5
76 .BR INTR " (^?)"
77 Special input character that is recognized if
78 .B ISIG
79 is set. (For
80 .B ISIG
81 and other flags see the various modes sections below.) It causes a
82 .B SIGINT
83 signal to be sent to all processes in the terminal process group. (See the
84 section on session leaders below.)
85 .TP
86 .BR QUIT " (^\e)"
87 Special input character if
88 .B ISIG
89 is set. Causes a
90 .B SIGQUIT
91 signal to be sent to the terminal process group.
92 .TP
93 .BR ERASE " (^H)"
94 Special input character if
95 .B ICANON
96 is set. Erases the last character in the current line.
97 .TP
98 .BR KILL " (^U)"
99 Special input character if
100 .B ICANON
101 is set. Erases the entire line.
102 .TP
103 .BR EOF " (^D)"
104 Special input character if
105 .B ICANON
106 is set. It is a line break character that is not itself returned to a
107 reader. If EOF is typed with no input present then the read returns zero,
108 which normally causes the reader to assume that end-of-file is reached.
109 .TP
110 .BR CR " (^M)"
111 Special input character if
112 .B IGNCR
113 or
114 .B ICRNL
115 is set. It is a carriage return ('\er'). If
116 .B IGNCR
117 is set then
118 .B CR
119 is discarded. If
120 .B ICRNL
121 is set and
122 .B IGNCR
123 is not set then
124 .B CR
125 is changed into an
126 .B NL
127 and has the same function as
128 .BR NL.
129 .TP
130 .BR NL " (^J)"
131 Special input character if
132 .B ICANON
133 is set. It is both a newline ('\en') and a line break.
134 .br
135 Special output character if
136 .B OPOST
137 and
138 .B ONLCR
139 are set. A
140 .B CR NL
141 sequence is output instead of just
142 .BR NL .
143 (MINIX 3 specific, but almost mandatory on any UNIX-like system.)
144 .TP
145 .BR TAB " (^I)"
146 Special character on output if
147 .B OPOST
148 and
149 .B XTABS
150 are set. It is transformed into the number of spaces necessary to reach a
151 column position that is a multiple of eight. (Only needed for terminals
152 without hardware tabs.)
153 .TP
154 .BR EOL " (undefined)"
155 Special input character if
156 .B ICANON
157 is set. It is an additional line break.
158 .TP
159 .BR SUSP " (^Z)"
160 Special input character if job control is implemented and
161 .B ISIG
162 is set. It causes a
163 .B SIGTSTP
164 signal to be send to the terminal process group. (MINIX 3 does not have job
165 control.)
166 .TP
167 .BR STOP " (^S)"
168 Special input character if
169 .B IXON
170 is set. It suspends terminal output and is then discarded.
171 .TP
172 .BR START " (^Q)"
173 Special output character if
174 .B IXON
175 is set. It starts terminal output if suspended and is then discarded. If
176 .B IXANY
177 is also set then any other character also starts terminal output, but they
178 are not discarded.
179 .TP
180 .BR REPRINT " (^R)"
181 Special input character if
182 .B IEXTEN
183 and
184 .B ECHO
185 are set. Reprints the input queue from the last line break onwards. A
186 reprint also happens automatically if the echoed input has been messed up by
187 other output and
188 .B ERASE
189 is typed.
190 .TP
191 .BR LNEXT " (^V)"
192 Special input character if
193 .B IEXTEN
194 is set. It is the "literal next" character that causes the next character
195 to be input without any special processing.
196 .TP
197 .BR DISCARD " (^O)"
198 Special input character if
199 .B IEXTEN
200 is set. Causes output to be discarded until it is typed again. (Implemented
201 only under Minix-vmd.)
202 .PP
203 All of these characters except
204 .BR CR ,
205 .B NL
206 and
207 .B TAB
208 may be changed or disabled under MINIX 3. (Changes to
209 .B START
210 and
211 .B STOP
212 may be ignored under other termios implementations.) The
213 .B REPRINT
214 and
215 .B LNEXT
216 characters are MINIX 3 extensions that are commonly present in other
217 implementations. \s-2POSIX\s+2 is unclear on whether
218 .BR IEXTEN,
219 .BR IGNCR
220 and
221 .BR ICRNL
222 should be active in non-canonical mode, but under MINIX 3 they are.
223 .SS "Terminal attributes"
224 The attributes of a terminal, such as whether the mode should be canonical or
225 non-canonical, are controlled by routines that use the
226 .B termios
227 structure as defined in
228 .BR <termios.h> :
229 .PP
230 .RS
231 .nf
232 .ta +4n +10n +15n
233 struct termios {
234 tcflag_t c_iflag; /* input modes */
235 tcflag_t c_oflag; /* output modes */
236 tcflag_t c_cflag; /* control modes */
237 tcflag_t c_lflag; /* local modes */
238 speed_t c_ispeed; /* input speed */
239 speed_t c_ospeed; /* output speed */
240 cc_t c_cc[NCCS]; /* control characters */
241 };
242 .fi
243 .RE
244 .PP
245 The types
246 .BR tcflag ,
247 .B speed_t
248 and
249 .B cc_t
250 are defined in
251 .B <termios.h>
252 as unsigned integral types.
253 .SS "Input Modes"
254 The
255 .B c_iflag
256 field contains the following single bit flags that control input processing:
257 .TP 5
258 .B ICRNL
259 Map
260 .B CR
261 to
262 .B NL
263 on input.
264 .TP
265 .B IGNCR
266 Ignore
267 .B CR
268 on input. This flag overrides
269 .BR ICRNL .
270 .TP
271 .B INLCR
272 Map
273 .B NL
274 to
275 .B CR
276 on input. This is done after the
277 .B IGNCR
278 check.
279 .TP
280 .B IXON
281 Enable start/stop output control.
282 .TP
283 .B IXOFF
284 Enable start/stop input control. (Not implemented.)
285 .TP
286 .B IXANY
287 Allow any character to restart output. (MINIX 3 specific.)
288 .TP
289 .B ISTRIP
290 Strip characters to seven bits.
291 .TP
292 .B IGNPAR
293 Ignore characters with parity errors. (Not implemented.)
294 .TP
295 .B INPCK
296 Enable input parity checking. (Not implemented.)
297 .TP
298 .B PARMRK
299 Mark parity errors by preceding the faulty character with '\e377', '\e0'.
300 The character '\e377' is preceded by another '\e377' to avoid ambiguity.
301 (Not implemented.)
302 .TP
303 .B BRKINT
304 Send the signal
305 .B SIGINT
306 to the terminal process group when receiving a break condition. (Not
307 implemented.)
308 .TP
309 .B IGNBRK
310 Ignore break condition. If neither
311 .B BRKINT
312 or
313 .B IGNBRK
314 is set a break is input as a single '\e0', or if
315 .B PARMRK
316 is set as '\e377', '\e0', '\e0'.
317 (Breaks are always ignored.)
318 .TP
319 .B SCANCODES
320 Send input as keyboard scancodes rather than processed ASCII characters. This
321 flag only applies to consoles; to check whether the flag is supported use the
322 .B tcgetattr
323 function after setting it and test whether
324 .B c_iflag
325 still contains the
326 .B SCANCODES
327 flag. Scancodes are provided directly and without any processing. As a
328 consequence, the
329 .B ISTRIP
330 ,
331 .B IGNCR
332 ,
333 .B ICRNL
334 ,
335 .B INLCR
336 ,
337 .B ICANON
338 and
339 .B IEXTEN
340 flags no longer influence input if this flag is specified. However, they may
341 still influence echoing if enabled. (MINIX 3 specific.)
342 .SS "Output Modes"
343 The
344 .B c_oflag
345 field contains the following single bit flags that control output processing:
346 .TP
347 .B OPOST
348 Perform output processing. This flag is the "main switch" on output
349 processing. All other flags are MINIX 3 specific.
350 .TP
351 .B ONLCR
352 Transform an
353 .B NL
354 to a
355 .B CR NL
356 sequence on output. Note that a key labeled "RETURN" or "ENTER" usually
357 sends a
358 .BR CR .
359 In line oriented mode this is normally transformed into
360 .B NL
361 by
362 .BR ICRNL .
363 .B NL
364 is the normal UNIX line delimiter ('\en'). On output an
365 .B NL
366 is transformed into the
367 .B CR NL
368 sequence that is necessary to reach the first column of the next line.
369 (This is a common output processing function for UNIX-like systems, but not
370 always separately switchable by an
371 .B ONLCR
372 flag.)
373 .TP
374 .B XTABS
375 Transform a
376 .B TAB
377 into the number of spaces necessary to reach a column position that is a
378 multiple of eight.
379 .TP
380 .B ONOEOT
381 Discard
382 .B EOT
383 (^D) characters. (Minix-vmd only.)
384 .SS "Control Modes"
385 The
386 .B c_cflag
387 field contains the following single bit flags and bit field for basic
388 hardware control:
389 .TP
390 .B CLOCAL
391 Ignore modem status lines.
392 .TP
393 .B CREAD
394 Enable receiver. (The receiver is always enabled.)
395 .TP
396 .B CSIZE
397 Number of bits per byte.
398 .B CSIZE
399 masks off the values
400 .BR CS5 ,
401 .BR CS6 ,
402 .BR CS7
403 and
404 .BR CS8
405 that indicate that 5, 6, 7 or 8 bits are used.
406 .TP
407 .B CSTOPB
408 Send two stop bits instead of one. Two stop bits are normally used at 110
409 baud or less.
410 .TP
411 .B PARENB
412 Enable parity generation.
413 .TP
414 .B PARODD
415 Generate odd parity if parity is generated, otherwise even parity.
416 .TP
417 .B HUPCL
418 Drop the modem control lines on the last close of the terminal line. (Not
419 implemented.)
420 .SS "Local Modes"
421 The
422 .B c_lflag
423 field contains the following single bit flags that control various functions:
424 .TP
425 .B ECHO
426 Enable echoing of input characters. Most input characters are echoed as
427 they are. Control characters are echoed as
428 .BI "^" X
429 where
430 .I X
431 is the letter used to say that the control character is
432 .BI CTRL\- X\fR.
433 The
434 .BR CR ,
435 .BR NL
436 and
437 .BR TAB
438 characters are echoed with their normal effect unless they are escaped by
439 .BR LNEXT .
440 .TP
441 .B ECHOE
442 If
443 .B ICANON
444 and
445 .B ECHO
446 are set then echo
447 .B ERASE
448 and
449 .B KILL
450 as one or more backspace-space-backspace sequences to wipe out the last
451 character or the entire line, otherwise they are echoed as they are.
452 .TP
453 .B ECHOK
454 If
455 .B ICANON
456 and
457 .B ECHO
458 are set and
459 .B ECHOE
460 is not set then output an
461 .B NL
462 after the
463 .B KILL
464 character. (For hardcopy terminals it is best to unset
465 .B ECHOE
466 and to set
467 .BR ECHOK .)
468 .TP
469 .B ECHONL
470 Echo
471 .B NL
472 even if
473 .B ECHO
474 is not set, but
475 .B ICANON
476 is set.
477 .TP
478 .B ICANON
479 Canonical input. This enables line oriented input and erase and kill
480 processing.
481 .TP
482 .B IEXTEN
483 Enable implementation defined input extensions.
484 .TP
485 .B ISIG
486 Enable the signal characters
487 .BR INTR ,
488 .BR QUIT
489 and
490 .BR SUSP .
491 .TP
492 .B NOFLSH
493 Disable the flushing of the input and output queues that is normally done if
494 a signal is sent.
495 .TP
496 .B TOSTOP
497 Send a
498 .B SIGTTOU
499 signal if job control is implemented and a background process tries to
500 write. (MINIX 3 has no job control.)
501 .SS "Input and output speed"
502 The input and output speed are encoded into the
503 .B c_ispeed
504 and
505 .B c_ospeed
506 fields.
507 .B <termios.h>
508 defines the symbols
509 .BR B0 ,
510 .BR B50 ,
511 .BR B75 ,
512 .BR B110 ,
513 .BR B134 ,
514 .BR B150 ,
515 .BR B200 ,
516 .BR B300 ,
517 .BR B600 ,
518 .BR B1200 ,
519 .BR B1800 ,
520 .BR B2400 ,
521 .BR B4800 ,
522 .BR B9600 ,
523 .BR B19200 ,
524 .BR B38400 ,
525 .BR B57600
526 and
527 .BR B115200
528 as values used to indicate the given baud rates. The zero baud rate,
529 .BR B0 ,
530 if used for the input speed causes the input speed to be equal to the
531 output speed. Setting the output speed to zero hangs up the line. One
532 should use the functions
533 .BR cfgetispeed() ,
534 .BR cfgetospeed() ,
535 .BR cfsetispeed()
536 and
537 .BR cfsetospeed()
538 to get or set a speed, because the
539 .B c_ispeed
540 and
541 .B c_ospeed
542 fields may not be visible under other implementations. (The
543 .B c_ispeed
544 and
545 .B c_ospeed
546 fields and the
547 .B B57600
548 and
549 .B B115200
550 symbols are MINIX 3 specific.)
551 .SS "Special characters"
552 The
553 .B c_cc
554 array contains the special characters that can be modified. The array has
555 length
556 .B NCCS
557 and is subscripted by the symbols
558 .BR VEOF ,
559 .BR VEOL ,
560 .BR VERASE ,
561 .BR VINTR ,
562 .BR VKILL ,
563 .BR VMIN ,
564 .BR VQUIT ,
565 .BR VTIME ,
566 .BR VSUSP ,
567 .BR VSTART ,
568 .BR VSTOP ,
569 .BR VREPRINT ,
570 .BR VLNEXT
571 and
572 .BR VDISCARD .
573 All these symbols are defined in
574 .BR <termios.h> .
575 Some implementations may give the same values to the
576 .B VMIN
577 and
578 .B VTIME
579 subscripts and the
580 .B VEOF
581 and
582 .B VEOL
583 subscripts respectively, and may ignore changes to
584 .B START
585 and
586 .BR STOP .
587 (Under MINIX 3 all special characters have their own
588 .I c_cc
589 slot and can all be modified.)
590 .SS "Raw I/O Parameters"
591 The
592 .B MIN
593 and
594 .B TIME
595 parameters can be used to adjust a raw connection to bursty input.
596 .B MIN
597 represents a minimum number of bytes that must be received before a read
598 call returns.
599 .B TIME
600 is a timer of 0.1 second granularity that can be used to time out a read.
601 Setting either of these parameters to zero has special meaning, which leads
602 to the following four possibilities:
603 .TP 5
604 .B "MIN > 0, TIME > 0"
605 .B TIME
606 is an inter-byte timer that is started (and restarted) when a byte is
607 received. A read succeeds when either the minimum number of characters
608 is received or the timer expires. Note that the timer starts
609 .B after
610 the first character, so the read returns at least one byte.
611 .TP
612 .B "MIN > 0, TIME = 0"
613 Now the timer is disabled, and a reader blocks indefinitely until at least
614 .B MIN
615 characters are received.
616 .TP
617 .B "MIN = 0, TIME > 0"
618 .B TIME
619 is now a read timer that is started when a read is executed. The read will
620 return if the read timer expires or if at least one byte is input. (Note
621 that a value of zero may be returned to the reader.)
622 .TP
623 .B "MIN = 0, TIME = 0"
624 The bytes currently available are returned. Zero is returned if no bytes
625 are available.
626 .SS "User Level Functions"
627 Termios attributes are set or examined, and special functions can be
628 performed by using the functions described in
629 .BR termios (3).
630 .SS "Session Leaders and Process Groups"
631 With the use of the
632 .B setsid()
633 function can a process become a session leader. A session leader forms a
634 process group with a process group id equal to the process id of the session
635 leader. If a session leader opens a terminal device file then this terminal
636 becomes the controlling tty of the session leader. Unless the terminal is
637 already the controlling tty of another process, or unless the
638 .B O_NOCTTY
639 flag is used to prevent the allocation of a controlling tty. The process
640 group of the session leader is now remembered as the terminal process group
641 for signals sent by the terminal driver. All the children and grandchildren
642 of the session leader inherit the controlling terminal and process group
643 until they themselves use
644 .BR setsid() .
645 .PP
646 The controlling tty becomes inaccessible to the children of the session
647 leader when the session leader exits, and a hangup signal is sent to all
648 the members of the process group. The input and output queues are flushed
649 on the last close of a terminal and all attributes are reset to the default
650 state.
651 .PP
652 A special device
653 .B /dev/tty
654 is a synonym for the controlling tty of a process. It allows a process to
655 reach the terminal even when standard input, output and error are
656 redirected. Opening this device can also be used as a test to see if a
657 process has a controlling tty or not.
658 .PP
659 For MINIX 3 a special write-only device
660 .B /dev/log
661 exists for processes that want to write messages to the system console.
662 Unlike the console this device is still accessible when a session leader
663 exits.
664 .PP
665 Minix-vmd also has a
666 .B /dev/log
667 device, but this device is read-write. All messages written to the log
668 device or to the console when X11 is active can be read from
669 .BR /dev/log .
670 The system tries to preserve the log buffer over a reboot so that panic
671 messages reappear in the log if the system happens to crash.
672 .SS "Pseudo Terminals"
673 Pseudo ttys allow a process such as a remote login daemon to set up a
674 terminal for a remote login session. The login session uses a device like
675 .B /dev/ttyp0
676 for input and output, and the remote login daemon uses the device
677 .B /dev/ptyp0
678 to supply input to or take output from the login session and transfer this
679 to or from the originating system. So the character flow may be: Local
680 user input sent to the remote system is written to
681 .B /dev/ptyp0
682 by the remote login daemon, undergoes input processing and appears on
683 .B /dev/ttyp0
684 as input to the login session. Output from the login session to
685 .B /dev/ttyp0
686 undergoes output processing, is read from
687 .B /dev/ptyp0
688 by the remote login daemon and is send over to the local system to be
689 displayed for the user. (So there are only four data streams to worry about
690 in a pseudo terminal.)
691 .PP
692 A pseudo terminal can be allocated by trying to open all the controlling
693 devices
694 .BI /dev/pty nn
695 one by one until it succeeds. Further opens will fail once a pty is open.
696 The process should now fork, the child should become session leader, open
697 the tty side of the pty and start a login session.
698 .PP
699 If the tty side is eventually closed down then reads from the pty side will
700 return zero and writes return \-1 with
701 .B errno
702 set to
703 .BR EIO .
704 If the pty side is closed first then a
705 .B SIGHUP
706 signal is sent to the session leader and further reads from the tty side
707 return zero and writes return \-1 with
708 .B errno
709 set to
710 .BR EIO .
711 (Special note: A line erase may cause up to three times the size of the
712 tty input queue to be sent to the pty reader as backspace overstrikes. Some
713 of this output may get lost if the pty reader cannot accept it all at once
714 in a single read call.)
715 .SH FILES
716 The list below shows all devices that MINIX 3 and Minix-vmd have. Not all of
717 these devices are configured in by default, as indicated by the numbers
718 (i/j/k, l/m/n) that tell the minimum, default and maximum possible number of
719 these devices for MINIX 3 (i/j/k) and Minix-vmd (l/m/n).
720 .TP 20
721 .B /dev/console
722 System console.
723 .TP
724 .B /dev/ttyc[1-7]
725 Virtual consoles. (0/1/7, 0/1/7)
726 .TP
727 .BR /dev/log
728 Console log device.
729 .TP
730 .B /dev/tty0[0-3]
731 Serial lines. (0/2/2, 4/4/4)
732 .TP
733 .B /dev/tty[p-w][0-f]
734 Pseudo ttys. (0/0/64, 1/32/128)
735 .TP
736 .B /dev/pty[p-w][0-f]
737 Associated pseudo tty controllers.
738 .SH "SEE ALSO"
739 .BR stty (1),
740 .BR termios (3),
741 .BR setsid (2),
742 .BR read (2),
743 .BR write (2).
744 .SH BUGS
745 A fair number of flags are not implemented under MINIX 3 (yet). Luckily they
746 are very limited utility and only apply to RS-232, not to the user interface.
747 .SH AUTHOR
748 Kees J. Bot (kjb@cs.vu.nl)