![[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] / 43BSDTahoe / man / man4|
Return to tty.4 CVS log | Up to [CSRG BSD Unix] / 43BSDTahoe / 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.7 (Berkeley) 5/19/86
6: .\"
7: .TH TTY 4 "May 19, 1986"
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: .B "Terminal/window sizes."
457: In order to accommodate terminals and workstations with variable-sized
458: windows, the terminal driver provides a mechanism for obtaining and setting
459: the current terminal size.
460: The driver does not use this information internally, but only stores it
461: and provides a uniform access mechanism.
462: When the size is changed, a SIGWINCH signal is sent to the terminal's process
463: group so that knowledgeable programs may detect size changes.
464: This facility was added in 4.3BSD and is not available in earlier
465: versions of the system.
466: .LP
467: .B "Summary of modes."
468: .LP
469: Unfortunately, due to the evolution of the terminal driver,
470: there are 4 different structures which contain various portions of the
471: driver data. The first of these (\fBsgttyb\fR)
472: contains that part of the information
473: largely common between version 6 and version 7 UNIX systems.
474: The second contains additional control characters added in version 7.
475: The third is a word of local state added in 4BSD,
476: and the fourth is another structure of special characters added for the
477: new driver. In the future a single structure may be made available
478: to programs which need to access all this information; most programs
479: need not concern themselves with all this state.
480: .de Ul
481: .ie t \\$1\l'|0\(ul'
482: .el \fI\\$1\fP
483: ..
484: .LP
485: .Ul "Basic modes: sgtty."
486: .PP
487: The basic
488: .IR ioctl s
489: use the structure
490: defined in
491: .IR <sgtty.h> :
492: .PP
493: .ta .5i 1i
494: .nf
495: .ft 3
496: struct sgttyb {
497: char sg_ispeed;
498: char sg_ospeed;
499: char sg_erase;
500: char sg_kill;
501: short sg_flags;
502: };
503: .ft R
504: .fi
505: .PP
506: The
507: .I sg_ispeed
508: and
509: .I sg_ospeed
510: fields describe the input and output speeds of the
511: device according to the following table,
512: which corresponds to the DEC DH-11 interface.
513: If other hardware is used,
514: impossible speed changes are ignored.
515: Symbolic values in the table are as defined in
516: .IR <sgtty.h> .
517: .PP
518: .nf
519: .ta \w'B9600 'u +5n
520: B0 0 (hang up dataphone)
521: B50 1 50 baud
522: B75 2 75 baud
523: B110 3 110 baud
524: B134 4 134.5 baud
525: B150 5 150 baud
526: B200 6 200 baud
527: B300 7 300 baud
528: B600 8 600 baud
529: B1200 9 1200 baud
530: B1800 10 1800 baud
531: B2400 11 2400 baud
532: B4800 12 4800 baud
533: B9600 13 9600 baud
534: EXTA 14 External A
535: EXTB 15 External B
536: .fi
537: .DT
538: .PP
539: Code conversion and line control required for
540: IBM 2741's (134.5 baud)
541: must be implemented by the user's
542: program.
543: The half-duplex line discipline
544: required for the 202 dataset (1200 baud)
545: is not supplied; full-duplex 212 datasets work fine.
546: .PP
547: The
548: .I sg_erase
549: and
550: .I sg_kill
551: fields of the argument structure
552: specify the erase and kill characters respectively.
553: (Defaults are DELETE and ^U.)
554: .PP
555: The
556: .I sg_flags
557: field of the argument structure
558: contains several bits that determine the
559: system's treatment of the terminal:
560: .PP
561: .ta \w'ALLDELAY 'u +\w'0100000 'u
562: .nf
563: ALLDELAY 0177400 Delay algorithm selection
564: BSDELAY 0100000 Select backspace delays (not implemented):
565: BS0 0
566: BS1 0100000
567: VTDELAY 0040000 Select form-feed and vertical-tab delays:
568: FF0 0
569: FF1 0040000
570: CRDELAY 0030000 Select carriage-return delays:
571: CR0 0
572: CR1 0010000
573: CR2 0020000
574: CR3 0030000
575: TBDELAY 0006000 Select tab delays:
576: TAB0 0
577: TAB1 0002000
578: TAB2 0004000
579: XTABS 0006000
580: NLDELAY 0001400 Select new-line delays:
581: NL0 0
582: NL1 0000400
583: NL2 0001000
584: NL3 0001400
585: EVENP 0000200 Even parity allowed on input
586: ODDP 0000100 Odd parity allowed on input
587: RAW 0000040 Raw mode: wake up on all characters, 8-bit interface
588: CRMOD 0000020 Map CR into LF; output LF as CR-LF
589: ECHO 0000010 Echo (full duplex)
590: LCASE 0000004 Map upper case to lower on input and lower to upper on output
591: CBREAK 0000002 Return each character as soon as typed
592: TANDEM 0000001 Automatic flow control
593: .DT
594: .fi
595: .PP
596: The delay bits specify how long
597: transmission stops to allow for mechanical or other movement
598: when certain characters are sent to the terminal.
599: In all cases a value of 0 indicates no delay.
600: .PP
601: Backspace delays are currently ignored but might
602: be used for Terminet 300's.
603: .PP
604: If a form-feed/vertical tab delay is specified,
605: it lasts for about 2 seconds.
606: .PP
607: Carriage-return delay type 1 lasts about .08 seconds
608: and is suitable for the Terminet 300.
609: Delay type 2 lasts about .16 seconds and is suitable
610: for the VT05 and the TI 700.
611: Delay type 3 is suitable for the concept-100 and pads lines
612: to be at least 9 characters at 9600 baud.
613: .PP
614: New-line delay type 1 is dependent on the current column
615: and is tuned for Teletype model 37's.
616: Type 2 is useful for the VT05 and is about .10 seconds.
617: Type 3 is unimplemented and is 0.
618: .PP
619: Tab delay type 1 is dependent on the amount of movement
620: and is tuned to the Teletype model
621: 37.
622: Type 3, called XTABS,
623: is not a delay at all but causes tabs to be replaced
624: by the appropriate number of spaces on output.
625: .PP
626: The flags for even and odd parity control parity checking on input
627: and generation on output in cooked and CBREAK mode
628: (unless LPASS8 is enabled, see below).
629: Even parity is generated on output unless ODDP is set and EVENP
630: is clear, in which case odd parity is generated.
631: Input characters with the wrong parity, as determined by EVENP and
632: ODDP, are ignored in cooked and CBREAK mode.
633: .PP
634: RAW
635: disables all processing save output flushing with LFLUSHO;
636: full 8 bits of input are given as soon as
637: it is available; all 8 bits are passed on output.
638: A break condition in the input is reported as a null character.
639: If the input queue overflows in raw mode all data in the input and output
640: queues are discarded; this applies to both new and old drivers.
641: .PP
642: CRMOD causes input carriage returns to be turned into
643: new-lines, and output and echoed new-lines to be output as a carriage return
644: followed by a line feed.
645: .PP
646: CBREAK is a sort of half-cooked (rare?) mode.
647: Programs can read each character as soon as typed, instead
648: of waiting for a full line;
649: all processing is done except the input editing:
650: character and word erase and line kill, input reprint,
651: and the special treatment of \e and EOT are disabled.
652: .PP
653: TANDEM mode causes the system to produce
654: a stop character (default ^S) whenever the input
655: queue is in danger of overflowing, and a start character
656: (default ^Q)
657: when the input queue has drained sufficiently.
658: It is useful for flow control when the `terminal'
659: is really another computer which understands the conventions.
660: .LP
661: .B Note:
662: The same ``stop'' and ``start'' characters are used for both directions
663: of flow control; the
664: .I t_stopc
665: character is accepted on input as the character that stops output and is
666: produced on output as the character to stop input, and the
667: .I t_startc
668: character is accepted on input as the character that restarts output and is
669: produced on output as the character to restart input.
670: .LP
671: .Ul "Basic ioctls"
672: .PP
673: A large number of
674: .IR ioctl (2)
675: calls apply to terminals. Some have the general form:
676: .PP
677: .B #include <sgtty.h>
678: .PP
679: .B ioctl(fildes, code, arg)
680: .br
681: .B struct sgttyb *arg;
682: .PP
683: The applicable codes are:
684: .IP TIOCGETP 15
685: Fetch the basic parameters associated with the terminal, and store
686: in the pointed-to \fIsgttyb\fR structure.
687: .IP TIOCSETP
688: Set the parameters according to the pointed-to \fIsgttyb\fR structure.
689: The interface delays until output is quiescent,
690: then throws away any unread characters,
691: before changing the modes.
692: .IP TIOCSETN
693: Set the parameters like TIOCSETP but do not delay or flush input.
694: Input is not preserved, however, when changing to or from RAW.
695: .PP
696: With the following codes
697: .I arg
698: is ignored.
699: .IP TIOCEXCL 15
700: Set \*(lqexclusive-use\*(rq mode:
701: no further opens are permitted until the file has been closed.
702: .IP TIOCNXCL
703: Turn off \*(lqexclusive-use\*(rq mode.
704: .IP TIOCHPCL
705: When the file is closed for the last time,
706: hang up the terminal.
707: This is useful when the line is associated
708: with an ACU used to place outgoing calls.
709: .PP
710: With the following codes
711: .I arg
712: is a pointer to an
713: .BR int .
714: .IP TIOCGETD 15
715: .I arg
716: is a pointer to an
717: .B int
718: into which is placed the current line discipline number.
719: .IP TIOCSETD
720: .I arg
721: is a pointer to an
722: .B int
723: whose value becomes the current line discipline number.
724: .IP TIOCFLUSH
725: If the
726: .B int
727: pointed to by
728: .I arg
729: has a zero value, all characters waiting in input or output queues are flushed.
730: Otherwise, the value of the
731: .B int
732: is for the FREAD and FWRITE bits defined in
733: .BR <sys/file.h> ;
734: if the FREAD bit is set, all characters waiting in input queues are flushed,
735: and if the FWRITE bit is set, all characters waiting in output queues are
736: flushed.
737: .LP
738: The remaining calls are not available in vanilla version 7 UNIX.
739: In cases where arguments are required, they are described; \fIarg\fR
740: should otherwise be given as 0.
741: .IP TIOCSTI 15
742: the argument points to a character which the system
743: pretends had been typed on the terminal.
744: .IP TIOCSBRK 15
745: the break bit is set in the terminal.
746: .IP TIOCCBRK
747: the break bit is cleared.
748: .IP TIOCSDTR
749: data terminal ready is set.
750: .IP TIOCCDTR
751: data terminal ready is cleared.
752: .IP TIOCSTOP 15
753: output is stopped as if the ``stop'' character had been typed.
754: .IP TIOCSTART
755: output is restarted as if the ``start'' character had been typed.
756: .IP TIOCGPGRP
757: .I arg
758: is a pointer to an
759: .B int
760: into which is placed the process group ID of the process group
761: for which this terminal is the control terminal.
762: .IP TIOCSPGRP
763: .I arg
764: is a pointer to an
765: .B int
766: which is the value to which the process group ID
767: for this terminal will be set.
768: .IP TIOCOUTQ
769: returns in the
770: .B int
771: pointed to by
772: .I arg
773: the number of characters queued for output to the terminal.
774: .IP FIONREAD
775: returns in the
776: .B int
777: pointed to by
778: .I arg
779: the number of characters immediately readable from the argument descriptor.
780: This works for files, pipes, and terminals.
781: .PP
782: .Ul Tchars
783: .PP
784: The second structure associated with each terminal specifies
785: characters that are special in both the old and new terminal interfaces:
786: The following structure is defined in
787: .IR <sys/ioctl.h> ,
788: which is automatically included in
789: .IR <sgtty.h> :
790: .PP
791: .nf
792: .ft 3
793: .ta .5i 1i 2i
794: struct tchars {
795: char t_intrc; /* interrupt */
796: char t_quitc; /* quit */
797: char t_startc; /* start output */
798: char t_stopc; /* stop output */
799: char t_eofc; /* end-of-file */
800: char t_brkc; /* input delimiter (like nl) */
801: };
802: .DT
803: .fi
804: .ft R
805: .PP
806: The default values for these characters are
807: ^C, ^\e\|, ^Q, ^S, ^D, and \-1.
808: A character value of \-1
809: eliminates the effect of that character.
810: The
811: .I t_brkc
812: character, by default \-1,
813: acts like a new-line in that it terminates a `line,'
814: is echoed, and is passed to the program.
815: The `stop' and `start' characters may be the same,
816: to produce a toggle effect.
817: It is probably counterproductive to make
818: other special characters (including erase and kill)
819: identical.
820: The applicable
821: .I ioctl
822: calls are:
823: .IP TIOCGETC 12
824: Get the special characters and put them in the specified structure.
825: .IP TIOCSETC 12
826: Set the special characters to those given in the structure.
827: .LP
828: .Ul "Local mode"
829: .PP
830: The third structure associated with each terminal is a local mode word.
831: The bits of the local mode word are:
832: .sp
833: .nf
834: LCRTBS 000001 Backspace on erase rather than echoing erase
835: LPRTERA 000002 Printing terminal erase mode
836: LCRTERA 000004 Erase character echoes as backspace-space-backspace
837: LTILDE 000010 Convert ~ to \` on output (for Hazeltine terminals)
838: LMDMBUF 000020 Stop/start output when carrier drops
839: LLITOUT 000040 Suppress output translations
840: LTOSTOP 000100 Send SIGTTOU for background output
841: LFLUSHO 000200 Output is being flushed
842: LNOHANG 000400 Don't send hangup when carrier drops
843: LETXACK 001000 Diablo style buffer hacking (unimplemented)
844: LCRTKIL 002000 BS-space-BS erase entire line on line kill
845: LPASS8 004000 Pass all 8 bits through on input, in any mode
846: LCTLECH 010000 Echo input control chars as ^X, delete as ^?
847: LPENDIN 020000 Retype pending input at next read or input character
848: LDECCTQ 040000 Only ^Q restarts output after ^S, like DEC systems
849: LNOFLSH 100000 Inhibit flushing of pending I/O when an interrupt character is typed.
850: .fi
851: .sp
852: The applicable
853: .I ioctl
854: functions are:
855: .IP TIOCLBIS 15
856: .I arg
857: is a pointer to an
858: .B int
859: whose value is a mask containing the bits to be set in the local mode word.
860: .IP TIOCLBIC
861: .I arg
862: is a pointer to an
863: .B int
864: whose value is a mask containing the bits to be cleared in the local mode word.
865: .IP TIOCLSET
866: .I arg
867: is a pointer to an
868: .B int
869: whose value is stored in the local mode word.
870: .IP TIOCLGET
871: .I arg
872: is a pointer to an
873: .B int
874: into which the current local mode word is placed.
875: .LP
876: .Ul "Local special chars"
877: .PP
878: The
879: final control structure associated with each terminal is the
880: .I ltchars
881: structure which defines control characters
882: for the new terminal driver.
883: Its structure is:
884: .nf
885: .sp
886: .ta .5i 1i 2i
887: .ft B
888: struct ltchars {
889: char t_suspc; /* stop process signal */
890: char t_dsuspc; /* delayed stop process signal */
891: char t_rprntc; /* reprint line */
892: char t_flushc; /* flush output (toggles) */
893: char t_werasc; /* word erase */
894: char t_lnextc; /* literal next character */
895: };
896: .ft R
897: .fi
898: .sp
899: The default values for these characters are ^Z, ^Y, ^R, ^O, ^W, and ^V.
900: A value of \-1 disables the character.
901: .PP
902: The applicable \fIioctl\fR functions are:
903: .IP TIOCSLTC 12
904: .I arg
905: is a pointer to an
906: .I ltchars
907: structure which defines the new local special characters.
908: .IP TIOCGLTC 12
909: .I arg
910: is a pointer to an
911: .I ltchars
912: structure into which is placed the current set of local special characters.
913: .LP
914: .Ul "Window/terminal sizes"
915: .PP
916: Each terminal has provision for storage of the current terminal or window
917: size in a
918: .I winsize
919: structure, with format:
920: .nf
921: .sp
922: .ft B
923: .ta .5i +\w'unsigned short\ \ \ \ 'u +\w'ws_ypixel;\ \ \ \ \ 'u
924: struct winsize {
925: unsigned short ws_row; /* rows, in characters */
926: unsigned short ws_col; /* columns, in characters */
927: unsigned short ws_xpixel; /* horizontal size, pixels */
928: unsigned short ws_ypixel; /* vertical size, pixels */
929: };
930: .ft R
931: .fi
932: .LP
933: A value of 0 in any field is interpreted as ``undefined;''
934: the entire structure is zeroed on final close.
935: .PP
936: The applicable \fIioctl\fP functions are:
937: .IP TIOCGWINSZ
938: .I arg
939: is a pointer to a
940: .B "struct winsize"
941: into which will be placed the current terminal or window size information.
942: .IP TIOCSWINSZ
943: .I arg
944: is a pointer to a
945: .B "struct winsize"
946: which will be used to set the current terminal or window size information.
947: If the new information is different than the old information,
948: a SIGWINCH signal will be sent to the terminal's process group.
949: .SH FILES
950: /dev/tty
951: .br
952: /dev/tty*
953: .br
954: /dev/console
955: .SH SEE ALSO
956: csh(1),
957: stty(1),
958: tset(1),
959: ioctl(2),
960: sigvec(2),
961: stty(3C),
962: getty(8)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.