TTY(4) COMMAND REFERENCE TTY(4) NAME tty - general terminal interface for UTek workstations SYNOPSIS #include <sgtty.h> DESCRIPTION This section describes both a particular special file /dev/tty and the terminal drivers used for conversational computing. The specific characteristics of a particular terminal driver are given in a separate manual page. The serial port driver for the UTek workstations is comm(4). Line Disciplines The system provides different line disciplines for controlling communications lines. In this version of the system there are three disciplines available: old The old (standard) terminal driver. This is used when using the standard shell sh(1sh) and for compatibility with other standard UNIXr Version 7 systems. new A newer terminal driver, with features for job control; this must be used when using csh(1csh). Line discipline switching is accomplished with the TIOCSETD ioctl: int ldisc = LDISC; ioctl(fd, TIOCSETD, &ldisc); where LDISC is OTTYDISC for the standard tty driver, NTTYDISC for the new driver, and NETLDISC for the networking discipline. The standard (currently old) tty driver is discipline 0 by convention. The current line discipline can be obtained with the TIOCGETD ioctl. Pending input is discarded when the line discipline is changed. All low-speed asynchronous communications ports can use any of the available line disciplines, no matter what hardware is involved. The remainder of this section discusses the old and new disciplines. The Control Terminal When a terminal file is opened, it causes the process to wait until a connection is established. In practice, user programs seldom open these files; they are opened by init(8) and become a user's standard input and output file. Printed 5/19/88 1
TTY(4) COMMAND REFERENCE TTY(4) If a process which has no control terminal opens a terminal file, then that terminal file becomes the control terminal for that process. The control terminal is thereafter inherited by a child process during a fork(2), even if the control terminal is closed. The file /dev/tty is, in each process, a synonym for a control terminal associated with that process. It is useful for programs that wish to be sure of writing messages on the terminal no matter how output has been redirected; it can also be used for programs that demand a file name for output, when typed output is desired and it is tiresome to find out which terminal is currently in use. The association between a process and its control terminal can be broken by the TIOCNOTTY ioctl(2). TIOCNOTTY does not close any existing file descriptors. Therefore, you can place the ioctl and still read and write from the file. But you no longer have a control terminal. Note that TIOCNOTTY has no effect if the tty you apply it to is not the control terminal. A common use of TIOCNOTTY follows: if((fd = open ("/dev/tty",O_WRONLY)) >= 0){ ioctl (fd, TIOCNOTTY, NULL); close(fd); } TIOCNOTTY sets the process group to zero. The next time you open a terminal file, that file becomes the control terminal. This new association can be prevented by first setting the process group to some non-zero value. For example, setpgrp(getpid()); Process Groups Command processors such as csh(1csh) can arbitrate the terminal between different jobs by placing related jobs in a single process group and associating this process group with the terminal. A terminals-associated process group may be set using the TIOCSPGRP ioctl(2): ioctl(fildes, TIOCSPGRP, &pgrp) or examined using TIOCGPGRP rather than TIOCSPGRP, returning the current process group in pgrp. The new terminal driver aids in this arbitration by restricting access to the Printed 5/19/88 2
TTY(4) COMMAND REFERENCE TTY(4) terminal by processes which are not in the current process group; see Job Access Control. Modes The terminal drivers have three major modes, characterized by the amount of processing on the input and output characters: cooked The normal mode. In this mode lines of input are collected and input editing is done. The edited line is made available when it is completed by a newline or when an EOT (control-D, hereafter ^D) is entered. A carriage return is usually made synonymous with newline in this mode, and replaced with a newline whenever it is typed. All driver functions (input editing, interrupt generation, output processing such as delay generation and tab expansion, etc.) are available in this mode. CBREAK This mode eliminates the character, word, and line editing input facilities, making the input character available to the user program as it is typed. Flow control, literal-next and interrupt processing are still done in this mode. Output processing is done. RAW This mode eliminates all input processing and makes all input characters available as they are typed; no output processing is done either. The style of input processing can also be very different when the terminal is put in non-blocking i/o mode; see fcntl(2). In this case a read(2) from the control terminal will never block, but rather return an error indication (EWOULDBLOCK) if there is no input available. A process may also request a SIGIO signal be sent it whenever input is present. To enable this mode the FASYNC flag should be set using fcntl(2). Input Editing A UTek terminal ordinarily operates in full-duplex mode. Characters may be typed at any time, even while output is occurring, and are only lost when the system's character input buffers become completely choked, which is rare, or when the user has accumulated the maximum allowed number of input characters that have not yet been read by some program. Currently this limit is 256 characters. When this limit is reached, no more input is accepted and the terminal bell is rung. Printed 5/19/88 3
TTY(4) COMMAND REFERENCE TTY(4) Input characters are normally accepted in either even or odd parity with the parity bit being stripped off before the character is given to the program. By clearing either the EVEN or ODD bit in the flags word it is possible to have input characters with that parity discarded (see the sections Basic ioctl and Basic Modes: sgtty.) In all of the line disciplines, it is possible to simulate terminal input using the TIOCSTI ioctl, which takes, as its third argument, the address of a character. The system pretends that this character was typed on the argument terminal, which must be the control terminal except for the superuser (this call is not in standard UNIXr Version 7). Input characters are normally echoed by putting them in an output queue as they arrive; this may be disabled by clearing the ECHO bit in the flags word using the TIOCSETN or TIOCSETP ioctls (see the Summary section). In cooked mode, terminal input is processed in units of lines. A program attempting to read will normally be suspended until an entire line has been received (but see the description of SIGTTIN in Job Access Control above and FIONREAD in the section Basic ioctl.) No matter how many characters are requested in the read call, at most one line will be returned. It is not, however, necessary to read a whole line at once; any number of characters may be requested in a read, even one, without losing information. During input, line editing is normally done with the character ^H logically erasing the last character typed and the character ^U logically erasing the entire current input line. These characters never erase beyond the beginning of the current input line or a ^D. These characters may be entered literally by preceding them with ^V. The drivers normally treat either a carriage return or a newline character as terminating an input line, replacing the return with a newline and echoing a return and a line feed. If the CRMOD bit is cleared in the local mode word then the processing for carriage return is disabled, and it is simply echoed as a return, and does not terminate cooked mode input. In both old and new driver there is a literal-next character (default ^V) which can be typed in both cooked and CBREAK mode preceding any character to prevent its special meaning. The new terminal driver also provides two other editing characters in normal mode. The word-erase character, normally ^W, erases the preceding word, but not any spaces before it. For the purposes of ^W, a word is defined as a Printed 5/19/88 4
TTY(4) COMMAND REFERENCE TTY(4) sequence of non-blank characters, with tabs counted as blanks. Finally, the reprint character, normally ^R, retypes the pending input beginning on a new line. Input Echoing and Redisplay When a kill character is typed it is echoed, followed by a new-line. The new terminal driver has several modes for handling the echoing of terminal input, controlled by bits in a local mode word. Hard Copy Terminals. When a hardcopy terminal is in use, the LPRTERA bit is normally set in the local mode word. Characters which are logically erased are then printed out backwards preceded by \ and followed by / in this mode. Crt Terminals. When a CRT terminal is in use, the LCRTBS bit is normally set in the local mode word. The terminal driver then echoes the proper number of erase characters when input is erased; in the normal case where the erase character is a ^H this causes the cursor of the terminal to back up to where it was before the logically erased character was typed. Erasing Characters From a CRT. When a CRT terminal is in use, the LCRTERA bit may be set to cause input to be erased from the screen with a backspace- space-backspace sequence when character or word deleting sequences are used. A LCRTKIL bit may be set as well, causing the input to be erased in this manner on line kill sequences as well. Echoing of Control Characters. If the LCTLECH bit is set in the local state word, then non-printing (control) characters are normally echoed as ^X (for some X) rather than being echoed unmodified; delete is echoed as ^?. The normal modes for using the new terminal driver on CRT terminals are speed dependent. At speeds less than 1200 baud, the LCRTERA and LCRTKILL processing is painfully slow, so stty(1) normally just sets LCRTBS and LCTLECH; at speeds of 1200 baud or greater all of these bits are normally set. The command stty(1) summarizes these option settings and the use of the new terminal driver as newcrt. Output Processing Printed 5/19/88 5
TTY(4) COMMAND REFERENCE TTY(4) When one or more characters are written, they are actually transmitted to the terminal as soon as previously-written characters have finished typing. (As noted previously, input characters are normally echoed by putting them in the output queue as they arrive.) When a process produces characters more rapidly than they can be typed, it will be suspended when its output queue exceeds some limit. When the queue has drained down to some threshold the program is resumed. Even parity is normally generated on output. The terminal drivers provide necessary processing for cooked and CBREAK mode output including delay generation for certain special characters and parity generation. Delays are available after backspaces ^H, form feeds ^L, carriage returns ^M, tabs ^I and newlines ^J. The driver will also optionally expand tabs into spaces, where the tab stops are assumed to be set every eight columns. These functions are controlled by bits in the tty flags word; see the Summary section. Finally, in the new terminal driver, there is a output flush character, normally ^O, which sets the LFLUSHO bit in the local mode word, causing subsequent output to be flushed until it is cleared by a program or more input is typed. This character has effect in both cooked and CBREAK modes and causes pending input to be retyped if there is any pending input. An ioctl to flush the characters in the input and output queues, TIOCFLUSH, is also available. Hazeltine Terminals To deal with Hazeltine terminals, which do not understand that ~ (tilde) has been made into an ASCII character, the LTILDE bit may be set in the local mode word when using the new terminal driver; in this case the character ~ will be replaced with the character ` on output. Flow Control There are two characters (the stop character, normally ^S, and the start character, normally ^Q) which cause output to be suspended and resumed respectively. Extra stop characters typed when output is already stopped have no effect. A bit in the flags word may be set to put the terminal into TANDEM mode. In this mode the system produces a stop character (default ^S) when the input queue is in danger of overflowing, and a start character (default ^Q) when the input has drained sufficiently. This mode is useful when the terminal is actually another machine that obeys the conventions. Printed 5/19/88 6
TTY(4) COMMAND REFERENCE TTY(4) Line Control and Breaks There are several ioctl calls available to control the state of the terminal line. The TIOCSBRK ioctl will set the break bit in the hardware interface causing a break condition to exist; this can be cleared (usually after a delay with sleep(3c) by TIOCCBRK. Break conditions in the input are reflected as a null character in RAW mode or as the interrupt character in cooked or CBREAK mode. The TIOCCDTR ioctl will clear the data terminal ready condition; it can be set again by TIOCSDTR. When the carrier signal from the dataset drops (usually because the user has hung up his terminal) a SIGHUP hangup signal is sent to the processes in the distinguished process group of the terminal; this usually causes them to terminate (the SIGHUP can be suppressed by setting the LNOHANG bit in the local state word of the driver.) Access to the terminal by other processes is then normally revoked, so any further reads will fail, and programs that read a terminal and test for end-of-file on their input will terminate appropriately. When using an ACU it is possible to ask that the phone line be hung up on the last close with the TIOCHPCL ioctl; this is normally done on the outgoing line. Interrupt Characters There are several characters that generate interrupts in cooked and CBREAK mode; all are sent the processes in the control group of the terminal, as if a TIOCGPGRP ioctl were done to get the process group and then a killpg(2) system call were done, except that these characters also flush pending input and output when typed at a terminal (a la TIOCFLUSH). The characters shown here are the defaults; the field names in the structures (given below) are also shown. The characters may be changed, although this is not often done. ^C tintrc (Delete) generates a SIGINT signal. This is the normal way to stop a process which is no longer interesting, or to regain control in an interactive program. ^\ tquitc (FS) generates a SIGQUIT signal. This is used to cause a program to terminate and produce a core image, if possible, in the file core in the current directory. ^Z tsuspc (SUB) generates a SIGTSTP signal, which is used to suspend the current process group. Printed 5/19/88 7
TTY(4) COMMAND REFERENCE TTY(4) ^Y tdsuspc (EM) generates a SIGTSTP signal as ^Z does, but the signal is sent when a program attempts to read the ^Y, rather than when it is typed. Job Access Control When using the new terminal driver, if a process which is not in the distinguished process group of its control terminal attempts to read from that terminal its process group is sent a SIGTTIN signal. This signal normally causes the members of that process group to stop. If, however, the process is ignoring SIGTTIN, has SIGTTIN blocked, is an orphan process, or is in the middle of process creation using vfork(2), it is instead returned an end-of-file. (An orphan process is a process whose parent has exited and has been inherited by the init(8) process.) Under older systems these processes would typically have had their input files reset to /dev/null, so this is a compatible change. When using the new terminal driver with the LTOSTOP bit set in the local modes, a process is prohibited from writing on its control terminal if it is not in the distinguished process group for that terminal. Processes which are holding or ignoring SIGTTOU signals, which are orphans, or which are in the middle of a vfork(2) are excepted and allowed to produce output. Window Management The driver stores the terminal's current window size in terms of pixels and characters. The driver doesn't actively interpret the information; it merely provides a convenient storage place for the information. The window size may be set with the TIOCSWINSZ ioctl(2) and is returned by the TIOCGWINSZ ioctl. The terminal's default window size is normally initialized by tset(1). The driver sends a SIGWINCH signal to its associated process group whenever the window size is changed. This facility is used, for example, by the Berkeley windows package to notify the pager more(1) and the screen editor vi(1) that the screen must be redrawn. Summary of Modes Unfortunately, due to the evolution of the terminal driver, there are 4 different structures which contain various portions of the driver data. The first of these (sgttyb) contains that part of the information largely common between UNIXr Version 6 and Version 7 systems. The second contains additional control characters added in version 7. The third is a word of local state peculiar to the new terminal Printed 5/19/88 8
TTY(4) COMMAND REFERENCE TTY(4) driver, and the fourth is another structure of special characters added for the new driver. In the future a single structure may be made available to programs which need to access all this information; most programs need not concern themselves with all this state. Basic Modes: sgtty. The basic ioctls use the structure defined in <sgtty.h>: struct sgttyb { char sg_ispeed; /* input speed */ char sg_ospeed; /* output speed */ char sg_erase; /* erase character */ char sg_kill; /* kill character */ short sg_flags; /* mode flags */ }; The sg_ispeed and sg_ospeed fields describe the input and output speeds of the device according to the following table. NOTE: due to hardware limitations, sg_ispeed and sg_ospeed must be the same. Symbolic values in the table are as defined in <sys/ttydev.h>. B0 0 (hang up dataphone) B50 1 50 baud B75 2 75 baud B110 3 110 baud B134 4 134.5 baud B150 5 150 baud B200 6 200 baud B300 7 300 baud B600 8 600 baud B1200 9 1200 baud B1800 10 1800 baud B2400 11 2400 baud B4800 12 4800 baud B9600 13 9600 baud EXTA 14 19200 baud EXTB 15 External B In the current configuration, only 110, 150, 300 and 1200 baud are really supported on dial-up lines. Code conversion and line control required for IBM 2741's (134.5 baud) must be implemented by the user's program. The half-duplex line discipline required for the 202 dataset (1200 baud) is not supplied; full-duplex 212 datasets work fine. The sg_erase and sg_kill fields of the argument structure specify the erase and kill characters respectively. (Defaults are ^H and ^U.) Printed 5/19/88 9
TTY(4) COMMAND REFERENCE TTY(4) The sg_flags field of the argument structure contains several bits that determine the system's treatment of the terminal: ALLDELAY 0x0000FF00 Delay algorithm selection BSDELAY 0x00008000 Select backspace delays (not implemented): BS0 0x00000000 BS1 0x00008000 VTDELAY 0x00004000 Select form-feed and vertical-tab delays: FF0 0x00000000 FF1 0x00004000 CRDELAY 0x00003000 Select carriage-return delays: CR0 0x00000000 CR1 0x00001000 CR2 0x00002000 CR3 0x00003000 TBDELAY 0x00000C00 Select tab delays: TAB0 0x00000000 TAB1 0x00000400 TAB2 0x00000800 XTABS 0x00000C00 NLDELAY 0x00000300 Select new-line delays: NL0 0x00000000 NL1 0x00000100 NL2 0x00000200 NL3 0x00000300 EVENP 0x00000080 Even parity allowed on input (most terminals) ODDP 0x00000040 Odd parity allowed on input RAW 0x00000020 Raw mode: wake up on all characters, 8-bit interface CRMOD 0x00000010 Map CR into LF; echo LF or CR as CR-LF ECHO 0x00000008 Echo (full duplex) LCASE 0x00000004 Map upper case to lower on input CBREAK 0x00000002 Return each character as soon as typed TANDEM 0x00000001 Automatic flow control The delay bits specify how long transmission stops to allow for mechanical or other movement when certain characters are sent to the terminal. In all cases a value of 0 indicates no delay. Backspace delays are currently ignored but might be used for Terminet 300's. If a form-feed/vertical tab delay is specified, it lasts for about 2 seconds. Carriage-return delay type 1 lasts about 0.08 seconds and is suitable for the Terminet 300. Delay type 2 lasts about 0.16 seconds and is suitable for the VT05 and the TI 700. Delay type 3 is suitable for the concept-100 and pads lines to be at least 9 characters at 9600 baud. Printed 5/19/88 10
TTY(4) COMMAND REFERENCE TTY(4) New-line delay type 1 (about 0.12 seconds) is dependent on the current column and is tuned for Teletype model 37's. Type 2 is useful for the VT05 and is about 0.10 seconds. Type 3 is unimplemented and is 0. Tab delay type 1 is about 0.1 seconds and and is tuned to the Teletype model 37. Type 2 is not implemented. Type 3, called XTABS, is not a delay at all but causes tabs to be replaced by the appropriate number of spaces on output. Input characters with the wrong parity, as determined by bits 200 and 100, are ignored in cooked and CBREAK mode. RAW disables all processing save output flushing with LFLUSHO; full 8 bits of input are given as soon as it is available; all 8 bits are passed on output. A break condition in the input is reported as a null character. If the input queue overflows in raw mode it is discarded; this applies to both new and old drivers. CRMOD causes input carriage returns to be turned into new- lines; input of either CR or LF causes LF-CR both to be echoed (for terminals with a new-line function). CBREAK is a sort of half-cooked (rare?) mode. Programs can read each character as soon as typed, instead of waiting for a full line; all processing is done except the input editing: character and word erase and line kill, input reprint, and the special treatment of \ or EOT are disabled. TANDEM mode causes the system to produce a stop character (default is ^S) whenever the input queue is in danger of overflowing, and a start character (default is ^Q) when the input queue has drained sufficiently. It is useful for flow control when the `terminal' is really another computer which understands the conventions. DODTR and DOCTS provide a hardware flow control mechanism. DODTR works much like TANDEM in that when the buffer approaches being full, the DTR line is deasserted; when the buffer is emptied DTR is reasserted. DOCTS causes the USART to transmit or not depending on the state of the CTS pin. Basic ioctls In addition to the TIOCSETD and TIOCGETD disciplines discussed in the Line Disciplines section a large number of other ioctl(2) calls apply to terminals, and have the general form: #include <sgtty.h> Printed 5/19/88 11
TTY(4) COMMAND REFERENCE TTY(4) ioctl(fildes, code, arg) struct sgttyb *arg; The applicable codes are: TIOCEXCL Set exclusive-use mode: no further opens are permitted until the file has been closed. TIOCGETP Fetch the basic parameters associated with the terminal, and store in the pointed-to sgttyb structure. TIOCHPCL When the file is closed for the last time, hang up the terminal. This is useful when the line is associated with an ACU used to place outgoing calls. TIOCNXCL Turn off exclusive-use mode. TIOCSETP Set the parameters according to the pointed-to sgttyb structure. The interface delays until output is quiescent, then throws away any unread characters, before changing the modes. TIOCSETN Set the parameters like TIOCSETP but do not delay or flush input. Input is not preserved, however, when changing to or from RAW. TIOCSTART Simulates the use of <CTRL-Q>. TIOCSTOP Simulates the use of <CTRL-S>. TIOCNOTTY Breaks the association between a process and its control terminal. The remaining calls are not available in vanilla UNIXr Version 7. In cases where arguments are required, they are described; arg should otherwise be given as 0. TIOCSTI the argument is the address of a character which the system pretends was typed on the terminal. TIOCSBRK the break bit is set in the terminal. TIOCCBRK the break bit is cleared. TIOCSDTR data terminal ready is set. TIOCCDTR data terminal ready is cleared. TIOCGPGRP arg is the address of a word into which is placed the process group number of the control terminal. Printed 5/19/88 12
TTY(4) COMMAND REFERENCE TTY(4) TIOCSPGRP arg is the address of a word (typically a process id) which becomes the process group for the control terminal. FIONREAD returns in the long integer whose address is arg the number of immediately readable characters from the argument unit. This works for files, pipes, terminals, and sockets. The following call uses a different structure than do the previous calls: #include <sys/file.h> ioctl(filedes, code, arg) int *arg; TIOCFLUSH Flush all characters waiting in input and/or output queues, based on whether FREAD (input), FWRITE (output) or both have been set in the word pointed to by arg. If that word is 0, both input and output queues will be flushed. This last feature is provided for compatibility with 4.1c BSD. Tchars The second structure associated with each terminal specifies characters that are special in both the old and new terminal interfaces: The following structure is defined in <sys/ioctl.h>, which is automatically included in <sgtty.h>: struct tchars { char t_intrc; /* interrupt */ char t_quitc; /* quit */ char t_startc; /* start output */ char t_stopc; /* stop output */ char t_eofc; /* end-of-file */ char t_brkc; /* input delimiter (like nl) */ }; The default values for these characters are ^?, ^\, ^Q, ^S, ^D, and -1. A character value of -1 eliminates the effect of that character. The t_brkc character, by default -1, acts like a new-line in that it terminates a line, is echoed, and is passed to the program. The stop and start characters may be the same, to produce a toggle effect. It is probably counterproductive to make other special characters (including erase and kill) identical. Applicable ioctl calls are: TIOCGETC Get the special characters and put them in the specified structure. Printed 5/19/88 13
TTY(4) COMMAND REFERENCE TTY(4) TIOCSETC Set the special characters to those given in the structure. Local Mode The third structure associated with each terminal is a local mode word; except for the LNOHANG bit, this word is interpreted only when the new driver is in use. The bits of the local mode word are: LCRTBS 0x0001 Backspace on erase rather than echoing erase LPRTERA 0x0002 Printing terminal erase mode LCRTERA 0x0004 Erase character echoes as BS-space-BS LTILDE 0x0008 Convert ~ to ` on output (Hazeltine terminals) LMDMBUF 0x0010 Stop/start output when carrier drops LLITOUT 0x0020 Suppress output translations LTOSTOP 0x0040 Send SIGTTOU for background output LFLUSHO 0x0080 Output is being flushed LNOHANG 0x0100 Don't send hangup when carrier drops LDODTR 0x0200 Automatic flow control using DTR LCRTKIL 0x0400 BS-space-BS erase entire line on line kill LDOCTS 0x0800 Transmission conditional on CTS LCTLECH 0x1000 Echo input control chars as ^X, delete as ^? LPENDIN 0x2000 Retype pending input at next read or input LDECCTQ 0x4000 Only ^Q restarts output after ^S, like DEC LNOFLSH 0x8000 Don't flush output on interrupt/suspend The applicable ioctl functions are: TIOCLBIS arg is the address of a mask which is the bits to be set in the local mode word. TIOCLBIC arg is the address of a mask of bits to be cleared in the local mode word. TIOCLSET arg is the address of a mask to be placed in the local mode word. TIOCLGET arg is the address of a word into which the current mask is placed. Local Special chars The final structure associated with each terminal is the ltchars structure, defined in <sys/ttychars.h>, which defines interrupt characters for the new terminal driver; its structure follows: struct ltchars { char t_suspc; /* stop process signal */ char t_dsuspc; /* delayed stop process signal */ char t_rprntc; /* reprint line */ char t_flushc; /* flush output (toggles) */ char t_werasc; /* word erase */ char t_lnextc; /* literal next character */ Printed 5/19/88 14
TTY(4) COMMAND REFERENCE TTY(4) }; The default values for these characters are ^Z, ^Y, ^R, ^O, ^W, and ^V. A value of -1 disables the character. The applicable ioctl functions are TIOCSLTC args is the address of a ltchars structure which defines the new local special characters. TIOCGLTC args is the address of a ltchars structure into which is placed the current set of local special characters. FILES /dev/tty /dev/tty* /dev/console CAVEATS Half-duplex terminals are not supported. SEE ALSO csh(1csh), stty(1), ioctl(2), sigvec(2), comm(4), getty(8), and init(8). Printed 5/19/88 15
%%index%% na:216,106; sy:322,284; de:606,2443;3337,2420;6045,2748;9081,3393;12762,2813;15863,2957;19108,3157;22553,3319;26160,2345;28793,2210;31291,2821;34400,2443;37131,2910;40329,2774;43391,572; fi:43963,152; ca:44115,125; se:44240,269; %%index%%000000000262