NAME

newtty − a new terminal interface

SYNOPSIS

stty new

DESCRIPTION

This section describes a new terminal interface, which is available as a replacement for that described in tty(4). It is necessary to use this terminal interface to take advantage of the full process control power of csh(1), as it is not possible to generate the signals necessary to stop processes gracefully from a keyboard controlled by the discipline described in tty(4). This interface provides “better” editing functionality over terminal input than does tty(4) extracting its price in added complexity.

To enable the discipline in a program, one uses the TIOCSETD ioctl, e.g.:

#include <sgtty.h>
 int ldisc = NTTYDISC;
 ioctl(0, TIOCSETD, &ldisc);

Replacing TIOCSETD with TIOCGETD will yield in ldisc the current discipline, which will be either 0 (if tty(4) is being used), NETDISC if bk(4) is being used, or NTTYDISC.

The file /dev/tty is, in each process, a synonym for the 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. 

As for terminals in general: all of the low-speed asynchronous communications ports use, by default, the same general interface, no matter what hardware is involved.  That interface is described in tty(4). The interface described in bk(4) is used for networking applications, and whenever high-speed input must be presented to the machine. This newtty interface described here provides the features of tty(4) and also additional features required for the job control mechanisms provided by csh(1). It also provides input editing functions and options not found in tty(4); these functions are reminiscent of those provided on other systems such as TOPS-20.

N.B.: This line discipline is provided in support of the mechanisms of csh(1). Its default mode is highly compatible with the standard UNIX version 7 tty driver, tty(4), but programs which are written to require features of this driver are less portable than they would be if they could make do without them.

The remainder of this section discusses the common features of the interface; the presentation parallels that of tty(4).

When a terminal file is opened, it causes the process to wait until a connection is established.  In practice user’s programs seldom open these files; they are opened by init and become a user’s input and output file.  The very first terminal file open in a process becomes the control terminal for that process, and the system establishes a process group consisting initially of that single process, associating this group with the terminal.  The control terminal’s process group plays a special role in handling the quit, interrupt, and stop signals, as discussed below.  The control terminal is inherited by a child process during a fork, even if the control terminal is closed. The set of processes which are in the process group associated with the terminal receive certain signals together, as described below and also in kill(2).

By moving sets of related processes in and out of the terminals process group with setpgrp(2), shells can allow the user to arbitrate between these different jobs. The terminal driver aids this arbitration by sending a SIGTTIN signal to the process group of a process which attempts to read from its control terminal while it is not in the terminals process group. If the action for the SIGTTIN signal is SIG_IGN or SIG_HOLD, then no signal is sent; instead the process gets an end-of-file on the read. A signal SIGTTOU exists and has a similar function for output. The default, however, is to allow background processes to produce output.  They are stopped only if the local tty option bit TOSTOP is set. (If the process chooses to ignore or hold SIGTTOU signals while the TOSTOP bit is set, then the output is simply discarded; it is not clear that this is a reasonable thing to do, but it is hard to know what to do in this situation.)

A terminal associated with one of these files 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 the input limit is reached further characters are ignored and the system rings the terminal bell to warn that no more buffer space is available. 

Normally, terminal input is processed in units of lines.  This means that a program attempting to read will be suspended until an entire line has been typed.  Also, 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.  There are special modes, discussed below, that permit the program to read each character as typed without waiting for a full line, or to be informed by a SIGTINT interrupt whenever data is available to read. 

During input, erase and kill processing is normally done.  By default, either a ‘#’ or a backspace (control-H) character erases the last character typed, except that it will not erase beyond the beginning of a line or an EOT.  By default, either the character ‘@’ or the character NAK (control-U) kills the entire line up to the point where it was typed, but not beyond an EOT.  These characters operate on a keystroke basis independently of any backspacing or tabbing that may have been done.  Each of them may be entered literally by preceding it by ‘\’; the erase or kill character remains, but the ‘\’ disappears.  These characters may be changed to others.  The intention in providing two erase and two kill characters is that the characters ^H and ^U should always be available.  The default ‘#’ and ‘@’ characters are often eliminated so that these characters can be typed normally, or to provide a different erase or kill character which a particular user likes. 

When desired, all upper-case letters are mapped into the corresponding lower-case letter.  The upper-case letter may be generated by preceding it by ‘\’, and upper-case letters are printed preceded by ‘\’ on output.  In addition, the following escape sequences can be generated on output and accepted on input:

foruse
`\´
|\!
~\^
{\(
}\)

Besides ^H and ^U some other ASCII control characters have special meaning.  These characters are not passed to a reading program except in raw mode where they lose their special character, or when typed immediately after the literal next character, normally ^V.  Also, it is possible to change these characters from the default; see below. 

ETB (Control-W) erases the preceding word (but not any spaces before it).  A word is a sequence of non-blank characters (tabs count as “blank” here.) 

EOT (Control-D) may be used to generate an end of file from a terminal.  When an EOT is received, all the characters waiting to be read are immediately passed to the program, without waiting for a new-line, and the EOT is discarded.  Thus if there are no characters waiting, which is to say the EOT occurred at the beginning of a line, zero characters will be passed back, and this is the standard end-of-file indication. 

DEL (Rubout) is not passed to a program but generates an interrupt signal which is sent to all processes in the process group of the control terminal.  Normally each such process is forced to terminate, but arrangements may be made either to ignore the signal or to receive a trap to an agreed-upon location.  See signal(2).

ETX (Control-C) also generates an interrupt as a synonym for DEL.  Some users may make DEL an erase character, but ^C should normally work on all terminals, unless the user (impolitely) changes both interrupt characters. 

EM (Control-Z) is not passed to a program but generates a stop signal (SIGTSTOP) which is sent to all processes in the process group of the controlling terminal, normally suspending the current job, so that it may be placed in the background or another job may be run.  The job can later be continued or killed using facilities of the shell. 

SUB (Control-Y) generates a SIGTSTOP signal as ^Z does, but the signal is sent when a program tries to read the ^Y, rather than when it is typed. 

DC2 (Control-R) retypes the pending input on a new line.  (Retyping automagically occurs if characters which would normally be erased from the screen are fouled by program output.) 

US (Control-O) flushes the output to the terminal until any character is typed, or a program reads from the terminal.  Programs (such as the shell) which print prompts often clear the state set by ^O so that their prompt will appear. 

SYN (Control-V) is a causes the next character input to be taken literally.  It has no special function.  Any character may be input in this way, including ^V. 

FS (Control-\ or control-shift-L) generates the quit signal.  Its treatment is identical to the interrupt signal except that unless a receiving process has made other arrangements it will not only be terminated but a core image file will be generated. 

DC3 (Control-S) delays all printing on the terminal until something is typed in. 

DC1 (Control-Q) restarts printing after DC3 without generating any input to a program. 

When the carrier signal from the dataset drops (usually because the user has hung up his terminal) a hangup signal is sent to all processes with the terminal as control terminal.  Unless other arrangements have been made, this signal causes the processes to terminate.  If the hangup signal is ignored, any read returns with an end-of-file indication.  Thus programs that read a terminal and test for end-of-file on their input can terminate appropriately when hung up on. 

When one or more characters are written, they are actually transmitted to the terminal as soon as previously-written characters have finished typing.  Input characters are 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 always generated on output.  The EOT character is not transmitted (except in raw or cbreak mode) to prevent terminals that respond to it from hanging up. 

Several ioctl(2) calls apply to terminals. The standard calls are described in tty(4) and will not be repeated here. Additional functions provided by this interface use bits in a local mode word, described in <ioctl.h> as follows:

LCRTBS000001Backspace on erase rather than echoing erase
LPRTERA000002Printing terminal erase mode
LCRTERA000004Erase character echoes as backspace-space-backspace
LTILDE000010Convert ~ to ’ on output (for Hazeltine terminals)
LMDMBUF000020Stop/start output when carrier drops
LLITOUT000040Suppress output translations
LTOSTOP000100Send SIGTTYO for background output
LFLUSHO000200Output is being flushed
LNOHANG000400Don’t send hangup when carrier drops
LETXACK001000Diablo style buffer hacking (unimplemented)
LCRTKIL002000BS-space-BS erase entire line on line kill
LINTRUP004000Generate interrupt SIGTINT when input ready to read
LCTLECH010000Echo input control chars as ^X, delete as ^?
LPENDIN020000Retype pending input at next read or input character

The applicable ioctl functions are:

TIOCLBIS
arg is a (integer) mask which is the bits to be set in the local mode word.

TIOCLBIC
arg is a mask of bits to be cleared.

TIOCLSET
arg is a new mask to be placed in the local mode word.

TIOCLGET
arg is the address of a word which the current mask is placed in.

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 current terminal.

TIOCSPGRP
args is a word (typically a process id) which becomes the process group for the control terminal.

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. 

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, and terminals, but not (yet) for multiplexed channels.

The ltchars structure is defined by:

struct ltchars {
chart_suspc;/* stop process signal */
chart_dstopc;/* delayed stop process signal */
chart_rprntc;/* reprint line */
chart_flushc;/* flush output (toggles) */
chart_werasec;/* word erase */
chart_lnextc;/* literal next character */
chart_lerasec;/* local erase */
chart_lkill;/* local kill */
chart_lintr;/* local interrupt */
};

The default values for these characters are ^Z, ^Y, ^R, ^O, ^W, ^V, ^H, ^U and ^? (delete).  A value of -1 disables the character.

FILES

/dev/tty
/dev/tty*
/dev/console

SEE ALSO

getty(8), stty (1), signal(2), ioctl(2), bk(4), tty(4)

BUGS

The output flush character ^O incorrectly flushes input as well. 

7th Edition