![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tty.4 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / man / man4|
Return to tty.4 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / man / man4 |
1.1 root 1: .\" Copyright (c) 1983 Regents of the University of California.
2: .\" All rights reserved. The Berkeley software License Agreement
3: .\" specifies the terms and conditions for redistribution.
4: .\"
5: .\" @(#)tty.4 6.8 (Berkeley) 2/24/89
6: .\"
7: .TH TTY 4 "February 24, 1989"
8: .UC 4
9: .SH NAME
10: tty \- general terminal interface
11: .SH SYNOPSIS
12: .B #include <sgtty.h>
13: .SH DESCRIPTION
14: This section describes
15: both a particular special file
16: .B /dev/tty
17: and the terminal drivers used for conversational computing.
18: .LP
19: .B Line disciplines.
20: .PP
21: The system provides different
22: .I "line disciplines"
23: for controlling communications lines.
24: In this version of the system there are two disciplines available for use
25: with terminals:
26: .IP "old" 8
27: The old (Version 7) terminal driver. This is sometimes used when using the
28: standard shell
29: .IR sh (1).
30: .IP "new"
31: The standard Berkeley terminal driver, with features for job control;
32: this must be used when using
33: .IR csh (1).
34: .LP
35: Line discipline switching is accomplished with the TIOCSETD
36: .IR ioctl :
37: .IP
38: .B "int ldisc = LDISC;"
39: .br
40: .B "ioctl(f, TIOCSETD, &ldisc);"
41: .LP
42: where LDISC is OTTYDISC for the standard tty driver
43: and NTTYDISC for the ``new'' driver.
44: The standard (currently old) tty driver is discipline 0 by convention.
45: Other disciplines may exist for special purposes, such as use of communications
46: lines for network connections.
47: The current line discipline can be obtained with the TIOCGETD
48: .IR ioctl .
49: Pending input is discarded when the line discipline is changed.
50: .PP
51: All of the low-speed asynchronous
52: communications ports can use any
53: of the available line disciplines, no matter what
54: hardware is involved.
55: The remainder of this section discusses the
56: \*(lqold\*(rq and \*(lqnew\*(rq disciplines.
57: .LP
58: .B "The control terminal."
59: .LP
60: When a terminal file is opened, it causes the process to wait until a
61: connection is established. In practice, user programs seldom open
62: these files; they are opened by
63: .IR getty (8)
64: or
65: .IR rlogind (8C)
66: and become a user's standard input and output file.
67: .PP
68: If a process which has no control terminal opens a terminal file, then
69: that terminal file becomes the control terminal for that process.
70: The control terminal is thereafter inherited by a child process during a
71: .IR fork (2),
72: even if the control terminal is closed.
73: .LP
74: The file
75: .B /dev/tty
76: is, in each process, a synonym for a
77: .I "control terminal"
78: associated with that process. It is useful for programs that wish to
79: be sure of writing messages on the terminal
80: no matter how output has been redirected.
81: It can also be used for programs that demand a file name
82: for output, when typed output is desired
83: and it is tiresome to find out which terminal
84: is currently in use.
85: .LP
86: A process can remove the association it has with its controlling
87: terminal by opening the file
88: .B /dev/tty
89: and issuing an
90: .IP
91: .B "ioctl(f, TIOCNOTTY, 0);"
92: .LP
93: This is often desirable in server processes.
94: .LP
95: .B "Process groups."
96: .LP
97: Command processors such as
98: .IR csh (1)
99: can arbitrate the terminal between different
100: .I jobs
101: by placing related jobs in a single process group and associating this
102: process group with the terminal. A terminal's associated process group
103: may be set using the TIOCSPGRP
104: .IR ioctl (2):
105: .IP
106: .B "ioctl(fildes, TIOCSPGRP, &pgrp);"
107: .LP
108: or examined using TIOCGPGRP, which returns the current
109: process group in
110: .IR pgrp .
111: The new terminal driver aids in this arbitration by restricting access
112: to the terminal by processes which are not in the current process group;
113: see
114: .B "Job access control"
115: below.
116: .LP
117: .B "Modes."
118: .PP
119: The terminal drivers have three major modes, characterized by the
120: amount of processing on the input and output characters:
121: .IP cooked 10
122: The normal mode. In this mode lines of input are collected and input editing
123: is done. The edited line is made available when it is completed by
124: a newline,
125: or when the \fIt_brkc\fP character (normally undefined)
126: or \fIt_eofc\fP character (normally an EOT, control-D, hereafter ^D)
127: is entered.
128: A carriage return is usually made synonymous with newline in this mode,
129: and replaced with a newline whenever it is typed.
130: All driver functions
131: (input editing, interrupt generation,
132: output processing such as delay generation and tab expansion, etc.)
133: are available in this mode.
134: .IP CBREAK 10
135: This mode eliminates the character, word, and line editing input facilities,
136: making the input character available to the user program as it is typed.
137: Flow control, literal-next and interrupt processing are still done in this mode.
138: Output processing is done.
139: .IP RAW 10
140: This mode eliminates all input processing and makes all input characters
141: available as they are typed; no output processing is done either.
142: .PP
143: The style of input processing can also be very different when
144: the terminal is put in non-blocking I/O mode; see
145: the FNDELAY flag described in
146: .IR fcntl (2).
147: In this case a
148: .IR read (2)
149: from the control terminal will never block, but rather
150: return an error indication (EWOULDBLOCK) if there is no
151: input available.
152: .PP
153: A process may also request that a SIGIO signal be sent it whenever input
154: is present and also whenever output queues fall below the low-water mark.
155: To enable this mode the FASYNC flag should be set using
156: .IR fcntl (2).
157: .LP
158: .B "Input editing."
159: .LP
160: A UNIX terminal ordinarily operates in full-duplex mode.
161: Characters may be typed at any time,
162: even while output is occurring, and are only lost when the
163: system's character input buffers become completely
164: choked, which is rare,
165: or when the user has accumulated the maximum allowed number of
166: input characters that have not yet been read by some program.
167: Currently this limit is 256 characters.
168: In RAW mode, the terminal driver
169: throws away all input and output without notice when the limit is reached.
170: In CBREAK or cooked mode it refuses to accept any further input and,
171: if in the new line discipline, rings the terminal bell.
172: .PP
173: Input characters are normally accepted in either even or odd parity
174: with the parity bit being stripped off before the character is given to
175: the program. By clearing either the EVEN or ODD bit in the flags word
176: it is possible to have input characters with that parity discarded (see the
177: \fBSummary\fR below.)
178: .PP
179: In all of the line disciplines, it is possible to simulate terminal
180: input using the TIOCSTI
181: .IR ioctl ,
182: which takes, as its third argument,
183: the address of a character. The system pretends that this character
184: was typed on the argument terminal, which must be the control terminal except
185: for the super-user (this call is not in standard version 7 UNIX).
186: .PP
187: Input characters are normally echoed by putting them in an output queue
188: as they arrive. This may be disabled by clearing the ECHO bit in the
189: flags word using the
190: .IR stty (3C)
191: call or the TIOCSETN or TIOCSETP
192: .IR ioctl s
193: (see the \fBSummary\fR below).
194: .PP
195: In cooked mode, terminal input is processed in units of lines.
196: A program attempting
197: to read will normally be suspended until an entire line has been
198: received
199: (but see the description of SIGTTIN in \fBJob access control\fR
200: and of FIONREAD in
201: \fBSummary\fR, both below.)
202: No matter how many characters are requested
203: in the read call, at most one line will be returned.
204: It is not, however, necessary to read a whole line at
205: once; any number of characters may be
206: requested in a read, even one, without losing information.
207: .PP
208: During input, line editing is normally done, with the erase character
209: .I sg_erase
210: (by default, DELETE)
211: logically erasing the last character typed and the
212: .I sg_kill
213: character (default, ^U: control-U)
214: logically erasing the entire current input line.
215: These characters
216: never erase beyond the beginning of the current input line or an eof.
217: These characters may be entered literally by
218: preceding them with `\e\|'; the `\e\|' will normally be erased when the
219: character is typed.
220: .PP
221: The drivers normally treat either a carriage return or a newline character
222: as terminating an input line, replacing the return with a newline and echoing
223: a return and a line feed.
224: If the CRMOD bit is cleared in the local mode word then the processing
225: for carriage return is disabled, and it is simply echoed as a return,
226: and does not terminate cooked mode input.
227: .PP
228: In the new driver there is a literal-next character (normally ^V)
229: which can be typed
230: in both cooked and CBREAK mode preceding
231: .I any
232: character to prevent its special meaning to the terminal handler.
233: This is to be preferred to the
234: use of `\e\|' escaping erase and kill characters, but `\e\|' is
235: retained with its old function in the new line discipline.
236: .PP
237: The new terminal driver also provides two other editing characters in
238: normal mode. The word-erase character, normally ^W, erases the preceding
239: word, but not any spaces before it. For the purposes of ^W, a word
240: is defined as a sequence of non-blank characters, with tabs counted as
241: blanks.
242: Finally, the reprint character, normally ^R, retypes the pending input beginning
243: on a new line. Retyping occurs automatically in cooked mode if characters
244: which would normally be erased from the screen are fouled by program output.
245: .LP
246: .B "Input echoing and redisplay"
247: .LP
248: The terminal driver has several modes (not present in standard UNIX
249: Version 7 systems) for handling the echoing of
250: terminal input, controlled by bits in a local mode word.
251: .LP
252: .I "Hardcopy terminals."
253: When a hardcopy terminal is in use, the LPRTERA bit is normally set in
254: the local mode word. Characters which are logically erased are
255: then printed out backwards preceded by `\e\|' and followed by `/' in this mode.
256: .LP
257: .I "CRT terminals."
258: When a CRT terminal is in use, the LCRTBS bit is normally set in the local
259: mode word. The terminal driver then echoes the proper number of erase
260: characters when input is erased; in the normal case where the erase
261: character is a ^H this causes the cursor of the terminal to back up
262: to where it was before the logically erased character was typed.
263: If the input has become fouled due to interspersed asynchronous output,
264: the input is automatically retyped.
265: .LP
266: .I "Erasing characters from a CRT."
267: When a CRT terminal is in use, the LCRTERA bit may be set to cause
268: input to be erased from the screen with a \*(lqbackspace-space-backspace\*(rq
269: sequence when character or word deleting sequences are used.
270: A LCRTKIL bit may be set as well, causing the input to
271: be erased in this manner on line kill sequences as well.
272: .LP
273: .I "Echoing of control characters."
274: If the LCTLECH bit is set in the local state word, then non-printing (control)
275: characters are normally echoed as ^X (for some X)
276: rather than being echoed unmodified; delete is echoed as ^?.
277: .LP
278: The normal modes for use on CRT terminals are speed dependent.
279: At speeds less than 1200 baud, the LCRTERA and LCRTKILL processing
280: is painfully slow, and
281: .IR stty (1)
282: normally just sets LCRTBS and LCTLECH; at
283: speeds of 1200 baud or greater all of these bits are normally set.
284: .IR Stty (1)
285: summarizes these option settings and the use of the new terminal
286: driver as
287: \*(lqnewcrt.\*(rq
288: .LP
289: .B "Output processing."
290: .PP
291: When one or more
292: characters are written, they are actually transmitted
293: to the terminal as soon as previously-written characters
294: have finished typing.
295: (As noted above, input characters are normally
296: echoed by putting them in the output queue
297: as they arrive.)
298: When a process produces characters more rapidly than they can be typed,
299: it will be suspended when its output queue exceeds some limit.
300: When the queue has drained down to some threshold
301: the program is resumed.
302: Even parity is normally generated on output.
303: The EOT character is not transmitted in cooked mode to prevent terminals
304: that respond to it from hanging up; programs using RAW or CBREAK mode
305: should be careful.
306: .PP
307: The terminal drivers provide necessary processing for cooked and CBREAK mode
308: output including delay generation for certain special characters and parity
309: generation. Delays are available after backspaces ^H, form feeds ^L,
310: carriage returns ^M, tabs ^I and newlines ^J. The driver will also optionally
311: expand tabs into spaces, where the tab stops are assumed to be set every
312: eight columns, and optionally convert newlines to carriage returns
313: followed by newline. These functions are controlled by bits in the tty
314: flags word; see \fBSummary\fR below.
315: .PP
316: The terminal drivers provide for mapping between upper and lower case
317: on terminals lacking lower case, and for other special processing on
318: deficient terminals.
319: .PP
320: Finally, in the new terminal driver, there is a output flush character,
321: normally ^O, which sets the LFLUSHO bit in the local mode word, causing
322: subsequent output to be flushed until it is cleared by a program or more
323: input is typed. This character has effect in both cooked and CBREAK modes
324: and causes pending input to be retyped if there is any pending input.
325: An
326: .I ioctl
327: to flush the characters in the input or output queues, TIOCFLUSH,
328: is also available.
329: .LP
330: .B "Upper case terminals and Hazeltines"
331: .PP
332: If the LCASE bit is set in the tty flags, then
333: all upper-case letters are mapped into
334: the corresponding lower-case letter.
335: The upper-case letter may be generated by preceding
336: it by `\\'.
337: Upper case letters are preceded by a `\e\|' when output.
338: In addition, the following escape sequences can be generated
339: on output and accepted on input:
340: .PP
341: .nf
342: for \` | ~ { }
343: use \e\|\' \e\|! \e\|^ \e\|( \e\|)
344: .fi
345: .PP
346: To deal with Hazeltine terminals, which do not understand that ~ has
347: been made into an ASCII character, the LTILDE bit may be set in the local
348: mode word; in this case the character
349: ~ will be replaced with the character \` on output.
350: .LP
351: .B "Flow control."
352: .PP
353: There are two characters (the stop character, normally ^S, and the
354: start character, normally ^Q) which cause output to be suspended and
355: resumed respectively. Extra stop characters typed when output
356: is already stopped have no effect, unless the start and stop characters
357: are made the same, in which case output resumes.
358: .PP
359: A bit in the flags word may be set to put the terminal into TANDEM mode.
360: In this mode the system produces a stop character (default ^S) when
361: the input queue is in danger of overflowing, and a start character (default
362: ^Q) when the input has drained sufficiently. This mode is useful
363: when the terminal is actually another machine that obeys those
364: conventions.
365: .LP
366: .B "Line control and breaks."
367: .LP
368: There are several
369: .I ioctl
370: calls available to control the state of the terminal line.
371: The TIOCSBRK
372: .I ioctl
373: will set the break bit in the hardware interface
374: causing a break condition to exist; this can be cleared (usually after a delay
375: with
376: .IR sleep (3))
377: by TIOCCBRK.
378: Break conditions in the input are reflected as a null character in RAW mode
379: or as the interrupt character in cooked or CBREAK mode.
380: The TIOCCDTR
381: .I ioctl
382: will clear the data terminal ready condition; it can
383: be set again by TIOCSDTR.
384: .PP
385: When the carrier signal from the dataset drops (usually
386: because the user has hung up his terminal) a
387: SIGHUP hangup signal is sent to the processes in the distinguished
388: process group of the terminal; this usually causes them to terminate.
389: The SIGHUP can be suppressed by setting the LNOHANG bit in the local
390: state word of the driver.
391: Access to the terminal by other processes is then normally revoked,
392: so any further reads will fail, and programs that read a terminal and test for
393: end-of-file on their input will terminate appropriately.
394: .PP
395: It is possible to ask that the phone line be hung up on the last close
396: with the TIOCHPCL
397: .IR ioctl ;
398: this is normally done on the outgoing lines and dialups.
399: .LP
400: .B "Interrupt characters."
401: .PP
402: There are several characters that generate interrupts in cooked and CBREAK
403: mode; all are sent to the processes in the control group of the terminal,
404: as if a TIOCGPGRP
405: .I ioctl
406: were done to get the process group and then a
407: .IR killpg (2)
408: system call were done,
409: except that these characters also flush pending input and output when
410: typed at a terminal
411: (\fI\z'a\`'la\fR TIOCFLUSH).
412: The characters shown here are the defaults; the field names in the structures
413: (given below)
414: are also shown.
415: The characters may be changed.
416: .IP ^C
417: \fBt_intrc\fR (ETX) generates a SIGINT signal.
418: This is the normal way to stop a process which is no longer interesting,
419: or to regain control in an interactive program.
420: .IP ^\e
421: \fBt_quitc\fR (FS) generates a SIGQUIT signal.
422: This is used to cause a program to terminate and produce a core image,
423: if possible,
424: in the file
425: .B core
426: in the current directory.
427: .IP ^Z
428: \fBt_suspc\fR (EM) generates a SIGTSTP signal, which is used to suspend
429: the current process group.
430: .IP ^Y
431: \fBt_dsuspc\fR (SUB) generates a SIGTSTP signal as ^Z does, but the
432: signal is sent when a program attempts to read the ^Y, rather than when
433: it is typed.
434: .LP
435: .B "Job access control."
436: .PP
437: When using the new terminal driver,
438: if a process which is not in the distinguished process group of its
439: control terminal attempts to read from that terminal its process group is
440: sent a SIGTTIN signal. This signal normally causes the members of
441: that process group to stop.
442: If, however, the process is ignoring SIGTTIN, has SIGTTIN blocked,
443: or is in the middle of process creation using
444: .IR vfork (2)),
445: the read will return \-1 and set
446: .I errno
447: to EIO.
448: .PP
449: When using the new terminal driver with the LTOSTOP bit set in the local
450: modes, a process is prohibited from writing on its control terminal if it is
451: not in the distinguished process group for that terminal.
452: Processes which are holding or ignoring SIGTTOU signals
453: or which are in the middle of a
454: .IR vfork (2)
455: are excepted and allowed to produce output.
456: .LP
457: .B "Terminal/window sizes."
458: .LP
459: In order to accommodate terminals and workstations with variable-sized
460: windows, the terminal driver provides a mechanism for obtaining and setting
461: the current terminal size.
462: The driver does not use this information internally, but only stores it
463: and provides a uniform access mechanism.
464: When the size is changed, a SIGWINCH signal is sent to the terminal's process
465: group so that knowledgeable programs may detect size changes.
466: This facility was added in 4.3BSD and is not available in earlier
467: versions of the system.
468: .LP
469: .B "Summary of modes."
470: .LP
471: Unfortunately, due to the evolution of the terminal driver,
472: there are 4 different structures which contain various portions of the
473: driver data. The first of these (\fBsgttyb\fR)
474: contains that part of the information
475: largely common between version 6 and version 7 UNIX systems.
476: The second contains additional control characters added in version 7.
477: The third is a word of local state added in 4BSD,
478: and the fourth is another structure of special characters added for the
479: new driver. In the future a single structure may be made available
480: to programs which need to access all this information; most programs
481: need not concern themselves with all this state.
482: .de Ul
483: .ie t \\$1\l'|0\(ul'
484: .el \fI\\$1\fP
485: ..
486: .LP
487: .Ul "Basic modes: sgtty."
488: .PP
489: The basic
490: .IR ioctl s
491: use the structure
492: defined in
493: .IR <sgtty.h> :
494: .PP
495: .ta .5i 1i
496: .nf
497: .ft 3
498: struct sgttyb {
499: char sg_ispeed;
500: char sg_ospeed;
501: char sg_erase;
502: char sg_kill;
503: short sg_flags;
504: };
505: .ft R
506: .fi
507: .PP
508: The
509: .I sg_ispeed
510: and
511: .I sg_ospeed
512: fields describe the input and output speeds of the
513: device according to the following table,
514: which corresponds to the DEC DH-11 interface.
515: If other hardware is used,
516: impossible speed changes are ignored.
517: Symbolic values in the table are as defined in
518: .IR <sgtty.h> .
519: .PP
520: .nf
521: .ta \w'B9600 'u +5n
522: B0 0 (hang up dataphone)
523: B50 1 50 baud
524: B75 2 75 baud
525: B110 3 110 baud
526: B134 4 134.5 baud
527: B150 5 150 baud
528: B200 6 200 baud
529: B300 7 300 baud
530: B600 8 600 baud
531: B1200 9 1200 baud
532: B1800 10 1800 baud
533: B2400 11 2400 baud
534: B4800 12 4800 baud
535: B9600 13 9600 baud
536: EXTA 14 External A
537: EXTB 15 External B
538: .fi
539: .DT
540: .PP
541: Code conversion and line control required for
542: IBM 2741's (134.5 baud)
543: must be implemented by the user's
544: program.
545: The half-duplex line discipline
546: required for the 202 dataset (1200 baud)
547: is not supplied; full-duplex 212 datasets work fine.
548: .PP
549: The
550: .I sg_erase
551: and
552: .I sg_kill
553: fields of the argument structure
554: specify the erase and kill characters respectively.
555: (Defaults are DELETE and ^U.)
556: .PP
557: The
558: .I sg_flags
559: field of the argument structure
560: contains several bits that determine the
561: system's treatment of the terminal:
562: .PP
563: .ta \w'ALLDELAY 'u +\w'0100000 'u
564: .nf
565: ALLDELAY 0177400 Delay algorithm selection
566: BSDELAY 0100000 Select backspace delays (not implemented):
567: BS0 0
568: BS1 0100000
569: VTDELAY 0040000 Select form-feed and vertical-tab delays:
570: FF0 0
571: FF1 0040000
572: CRDELAY 0030000 Select carriage-return delays:
573: CR0 0
574: CR1 0010000
575: CR2 0020000
576: CR3 0030000
577: TBDELAY 0006000 Select tab delays:
578: TAB0 0
579: TAB1 0002000
580: TAB2 0004000
581: XTABS 0006000
582: NLDELAY 0001400 Select new-line delays:
583: NL0 0
584: NL1 0000400
585: NL2 0001000
586: NL3 0001400
587: EVENP 0000200 Even parity allowed on input
588: ODDP 0000100 Odd parity allowed on input
589: RAW 0000040 Raw mode: wake up on all characters, 8-bit interface
590: CRMOD 0000020 Map CR into LF; output LF as CR-LF
591: ECHO 0000010 Echo (full duplex)
592: LCASE 0000004 Map upper case to lower on input and lower to upper on output
593: CBREAK 0000002 Return each character as soon as typed
594: TANDEM 0000001 Automatic flow control
595: .DT
596: .fi
597: .PP
598: The delay bits specify how long
599: transmission stops to allow for mechanical or other movement
600: when certain characters are sent to the terminal.
601: In all cases a value of 0 indicates no delay.
602: .PP
603: Backspace delays are currently ignored but might
604: be used for Terminet 300's.
605: .PP
606: If a form-feed/vertical tab delay is specified,
607: it lasts for about 2 seconds.
608: .PP
609: Carriage-return delay type 1 lasts about .08 seconds
610: and is suitable for the Terminet 300.
611: Delay type 2 lasts about .16 seconds and is suitable
612: for the VT05 and the TI 700.
613: Delay type 3 is suitable for the concept-100 and pads lines
614: to be at least 9 characters at 9600 baud.
615: .PP
616: New-line delay type 1 is dependent on the current column
617: and is tuned for Teletype model 37's.
618: Type 2 is useful for the VT05 and is about .10 seconds.
619: Type 3 is unimplemented and is 0.
620: .PP
621: Tab delay type 1 is dependent on the amount of movement
622: and is tuned to the Teletype model
623: 37.
624: Type 3, called XTABS,
625: is not a delay at all but causes tabs to be replaced
626: by the appropriate number of spaces on output.
627: .PP
628: The flags for even and odd parity control parity checking on input
629: and generation on output in cooked and CBREAK mode
630: (unless LPASS8 is enabled, see below).
631: Even parity is generated on output unless ODDP is set and EVENP
632: is clear, in which case odd parity is generated.
633: Input characters with the wrong parity, as determined by EVENP and
634: ODDP, are ignored in cooked and CBREAK mode.
635: .PP
636: RAW
637: disables all processing save output flushing with LFLUSHO;
638: full 8 bits of input are given as soon as
639: it is available; all 8 bits are passed on output.
640: A break condition in the input is reported as a null character.
641: If the input queue overflows in raw mode all data in the input and output
642: queues are discarded; this applies to both new and old drivers.
643: .PP
644: CRMOD causes input carriage returns to be turned into
645: new-lines, and output and echoed new-lines to be output as a carriage return
646: followed by a line feed.
647: .PP
648: CBREAK is a sort of half-cooked (rare?) mode.
649: Programs can read each character as soon as typed, instead
650: of waiting for a full line;
651: all processing is done except the input editing:
652: character and word erase and line kill, input reprint,
653: and the special treatment of \e and EOT are disabled.
654: .PP
655: TANDEM mode causes the system to produce
656: a stop character (default ^S) whenever the input
657: queue is in danger of overflowing, and a start character
658: (default ^Q)
659: when the input queue has drained sufficiently.
660: It is useful for flow control when the `terminal'
661: is really another computer which understands the conventions.
662: .LP
663: .B Note:
664: The same ``stop'' and ``start'' characters are used for both directions
665: of flow control; the
666: .I t_stopc
667: character is accepted on input as the character that stops output and is
668: produced on output as the character to stop input, and the
669: .I t_startc
670: character is accepted on input as the character that restarts output and is
671: produced on output as the character to restart input.
672: .LP
673: .Ul "Basic ioctls"
674: .PP
675: A large number of
676: .IR ioctl (2)
677: calls apply to terminals. Some have the general form:
678: .PP
679: .B #include <sgtty.h>
680: .PP
681: .B ioctl(fildes, code, arg)
682: .br
683: .B struct sgttyb *arg;
684: .PP
685: The applicable codes are:
686: .IP TIOCGETP 15
687: Fetch the basic parameters associated with the terminal, and store
688: in the pointed-to \fIsgttyb\fR structure.
689: .IP TIOCSETP
690: Set the parameters according to the pointed-to \fIsgttyb\fR structure.
691: The interface delays until output is quiescent,
692: then throws away any unread characters,
693: before changing the modes.
694: .IP TIOCSETN
695: Set the parameters like TIOCSETP but do not delay or flush input.
696: Input is not preserved, however, when changing to or from RAW.
697: .PP
698: With the following codes
699: .I arg
700: is ignored.
701: .IP TIOCEXCL 15
702: Set \*(lqexclusive-use\*(rq mode:
703: no further opens are permitted until the file has been closed.
704: .IP TIOCNXCL
705: Turn off \*(lqexclusive-use\*(rq mode.
706: .IP TIOCHPCL
707: When the file is closed for the last time,
708: hang up the terminal.
709: This is useful when the line is associated
710: with an ACU used to place outgoing calls.
711: .PP
712: With the following codes
713: .I arg
714: is a pointer to an
715: .BR int .
716: .IP TIOCGETD 15
717: .I arg
718: is a pointer to an
719: .B int
720: into which is placed the current line discipline number.
721: .IP TIOCSETD
722: .I arg
723: is a pointer to an
724: .B int
725: whose value becomes the current line discipline number.
726: .IP TIOCFLUSH
727: If the
728: .B int
729: pointed to by
730: .I arg
731: has a zero value, all characters waiting in input or output queues are flushed.
732: Otherwise, the value of the
733: .B int
734: is for the FREAD and FWRITE bits defined in
735: .BR <sys/file.h> ;
736: if the FREAD bit is set, all characters waiting in input queues are flushed,
737: and if the FWRITE bit is set, all characters waiting in output queues are
738: flushed.
739: .LP
740: The remaining calls are not available in vanilla version 7 UNIX.
741: In cases where arguments are required, they are described; \fIarg\fR
742: should otherwise be given as 0.
743: .IP TIOCSTI 15
744: the argument points to a character which the system
745: pretends had been typed on the terminal.
746: .IP TIOCSBRK 15
747: the break bit is set in the terminal.
748: .IP TIOCCBRK
749: the break bit is cleared.
750: .IP TIOCSDTR
751: data terminal ready is set.
752: .IP TIOCCDTR
753: data terminal ready is cleared.
754: .IP TIOCSTOP 15
755: output is stopped as if the ``stop'' character had been typed.
756: .IP TIOCSTART
757: output is restarted as if the ``start'' character had been typed.
758: .IP TIOCGPGRP
759: .I arg
760: is a pointer to an
761: .B int
762: into which is placed the process group ID of the process group
763: for which this terminal is the control terminal.
764: .IP TIOCSPGRP
765: .I arg
766: is a pointer to an
767: .B int
768: which is the value to which the process group ID
769: for this terminal will be set.
770: .IP TIOCOUTQ
771: returns in the
772: .B int
773: pointed to by
774: .I arg
775: the number of characters queued for output to the terminal.
776: .IP FIONREAD
777: returns in the
778: .B int
779: pointed to by
780: .I arg
781: the number of characters immediately readable from the argument descriptor.
782: This works for files, pipes, and terminals.
783: .PP
784: .Ul Tchars
785: .PP
786: The second structure associated with each terminal specifies
787: characters that are special in both the old and new terminal interfaces:
788: The following structure is defined in
789: .IR <sys/ioctl.h> ,
790: which is automatically included in
791: .IR <sgtty.h> :
792: .PP
793: .nf
794: .ft 3
795: .ta .5i 1i 2i
796: struct tchars {
797: char t_intrc; /* interrupt */
798: char t_quitc; /* quit */
799: char t_startc; /* start output */
800: char t_stopc; /* stop output */
801: char t_eofc; /* end-of-file */
802: char t_brkc; /* input delimiter (like nl) */
803: };
804: .DT
805: .fi
806: .ft R
807: .PP
808: The default values for these characters are
809: ^C, ^\e\|, ^Q, ^S, ^D, and \-1.
810: A character value of \-1
811: eliminates the effect of that character.
812: The
813: .I t_brkc
814: character, by default \-1,
815: acts like a new-line in that it terminates a `line,'
816: is echoed, and is passed to the program.
817: The `stop' and `start' characters may be the same,
818: to produce a toggle effect.
819: It is probably counterproductive to make
820: other special characters (including erase and kill)
821: identical.
822: The applicable
823: .I ioctl
824: calls are:
825: .IP TIOCGETC 12
826: Get the special characters and put them in the specified structure.
827: .IP TIOCSETC 12
828: Set the special characters to those given in the structure.
829: .LP
830: .Ul "Local mode"
831: .PP
832: The third structure associated with each terminal is a local mode word.
833: The bits of the local mode word are:
834: .sp
835: .nf
836: LCRTBS 000001 Backspace on erase rather than echoing erase
837: LPRTERA 000002 Printing terminal erase mode
838: LCRTERA 000004 Erase character echoes as backspace-space-backspace
839: LTILDE 000010 Convert ~ to \` on output (for Hazeltine terminals)
840: LMDMBUF 000020 Stop/start output when carrier drops
841: LLITOUT 000040 Suppress output translations
842: LTOSTOP 000100 Send SIGTTOU for background output
843: LFLUSHO 000200 Output is being flushed
844: LNOHANG 000400 Don't send hangup when carrier drops
845: LETXACK 001000 Diablo style buffer hacking (unimplemented)
846: LCRTKIL 002000 BS-space-BS erase entire line on line kill
847: LPASS8 004000 Pass all 8 bits through on input, in any mode
848: LCTLECH 010000 Echo input control chars as ^X, delete as ^?
849: LPENDIN 020000 Retype pending input at next read or input character
850: LDECCTQ 040000 Only ^Q restarts output after ^S, like DEC systems
851: LNOFLSH 100000 Inhibit flushing of pending I/O when an interrupt character is typed.
852: .fi
853: .sp
854: The applicable
855: .I ioctl
856: functions are:
857: .IP TIOCLBIS 15
858: .I arg
859: is a pointer to an
860: .B int
861: whose value is a mask containing the bits to be set in the local mode word.
862: .IP TIOCLBIC
863: .I arg
864: is a pointer to an
865: .B int
866: whose value is a mask containing the bits to be cleared in the local mode word.
867: .IP TIOCLSET
868: .I arg
869: is a pointer to an
870: .B int
871: whose value is stored in the local mode word.
872: .IP TIOCLGET
873: .I arg
874: is a pointer to an
875: .B int
876: into which the current local mode word is placed.
877: .LP
878: .Ul "Local special chars"
879: .PP
880: The
881: final control structure associated with each terminal is the
882: .I ltchars
883: structure which defines control characters
884: for the new terminal driver.
885: Its structure is:
886: .nf
887: .sp
888: .ta .5i 1i 2i
889: .ft B
890: struct ltchars {
891: char t_suspc; /* stop process signal */
892: char t_dsuspc; /* delayed stop process signal */
893: char t_rprntc; /* reprint line */
894: char t_flushc; /* flush output (toggles) */
895: char t_werasc; /* word erase */
896: char t_lnextc; /* literal next character */
897: };
898: .ft R
899: .fi
900: .sp
901: The default values for these characters are ^Z, ^Y, ^R, ^O, ^W, and ^V.
902: A value of \-1 disables the character.
903: .PP
904: The applicable \fIioctl\fR functions are:
905: .IP TIOCSLTC 12
906: .I arg
907: is a pointer to an
908: .I ltchars
909: structure which defines the new local special characters.
910: .IP TIOCGLTC 12
911: .I arg
912: is a pointer to an
913: .I ltchars
914: structure into which is placed the current set of local special characters.
915: .LP
916: .Ul "Window/terminal sizes"
917: .PP
918: Each terminal has provision for storage of the current terminal or window
919: size in a
920: .I winsize
921: structure, with format:
922: .nf
923: .sp
924: .ft B
925: .ta .5i +\w'unsigned short\ \ \ \ 'u +\w'ws_ypixel;\ \ \ \ \ 'u
926: struct winsize {
927: unsigned short ws_row; /* rows, in characters */
928: unsigned short ws_col; /* columns, in characters */
929: unsigned short ws_xpixel; /* horizontal size, pixels */
930: unsigned short ws_ypixel; /* vertical size, pixels */
931: };
932: .ft R
933: .fi
934: .LP
935: A value of 0 in any field is interpreted as ``undefined;''
936: the entire structure is zeroed on final close.
937: .PP
938: The applicable \fIioctl\fP functions are:
939: .IP TIOCGWINSZ
940: .I arg
941: is a pointer to a
942: .B "struct winsize"
943: into which will be placed the current terminal or window size information.
944: .IP TIOCSWINSZ
945: .I arg
946: is a pointer to a
947: .B "struct winsize"
948: which will be used to set the current terminal or window size information.
949: If the new information is different than the old information,
950: a SIGWINCH signal will be sent to the terminal's process group.
951: .SH FILES
952: /dev/tty
953: .br
954: /dev/tty*
955: .br
956: /dev/console
957: .SH SEE ALSO
958: csh(1),
959: stty(1),
960: tset(1),
961: ioctl(2),
962: sigvec(2),
963: stty(3C),
964: getty(8)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.