stty: Set/show terminal characteristics

Package: language

Usage

stty [terminal]

Parameters

terminal: The logical name of the terminal to be used, i.e., the name of the device given in the dev$termcap file.

baud = 9600: Set to some nonzero value to inform the VOS of the baud rate; the software does not automatically sense the baud rate. The baud rate must be known to accurately generate delays.

ncols = 80: The logical width of the screen in characters; may be set to some value less than the physical width to produce more readable output on very high resolution terminals.

nlines = 24: The logical height of the screen in characters.

show = no: Show the current terminal driver settings. The show function is automatically enabled if stty is called with no arguments.

all = no: Show all terminal driver settings, including those which are not currently in use. Setting all automatically sets show.

reset = no: Reset the terminal driver settings to their default (login time) values. Note that the terminal driver is not a task in the normal sense but is always active, and once a parameter is set the new value is retained indefinitely.

resize = no: Recompute the terminal screen size parameters, ttyncols and ttynlines, and update their values in the environment. If the terminal supports runtime querying of the screen size it will be queried (allowing the screen size to change dynamically at runtime), otherwise the values from the termcap entry for the terminal will be used.

clear = no: Clear the function(s) which follow on the command line, e.g., "clear ucasein ucaseout" is equivalent to "ucasein=no ucaseout=no".

ucasein = no: Map terminal input to lower case, e.g., when working on an old monocase terminal, or on a modern terminal with the shiftlock key on.

ucaseout = no: Map terminal output to upper case.

login = "home$ttyin.log" [off]: Log all input from the terminal to the named text file.

logio = "home$ttyio.log" [off]: Log all terminal i/o to the named text file. May not be used if either login or logout mode is in effect, and vice versa.

logout = "home$ttyout.log" [off]: Log all output to the terminal to the named text file.

playback = "home$ttyin.log" [off]: Divert terminal driver input to the named "stty login" style text file, i.e., take input from a file instead of from the terminal. The effect is to exactly repeat a previous terminal session executed with login mode in effect, e.g., to test or demo software.

verify = no: If verify is enabled during playback mode the terminal driver will read a key from the keyboard before executing each command in the logfile. Tap the space bar to execute the command, q to terminate playback mode, or g to continue execution with verify mode disabled. Typing any other key causes a help line to be printed.

delay = 500 (msec): If verify is disabled during playback mode the terminal driver will pause for delay milliseconds before executing each logfile command.

Description

The stty task is used to set or display the terminal device characteristics and VOS terminal driver options. Without arguments, stty prints the current characteristics of the terminal. The default terminal type can be changed by setting ttyname. The terminal characteristics ncols, nlines or baud, may be changed by typing new values explicitly on the command line.

The most common use of stty is to inform IRAF of the type of terminal being used, e.g.,

cl> stty vt100

would set the terminal type to "vt100". An error message will be printed unless an entry for the named terminal is present in the termcap file; if the named terminal is a graphics terminal, there must also be an entry in the graphcap file.

To find out about the current terminal settings, type

cl> stty

or

cl> stty all

A limited number of terminal driver options may also be set. In particular, the VOS terminal driver (not to be confused with the host operating system terminal driver, a lower level facility) implements facilities for case conversion upon input or output, and for logging all i/o to the terminal and playing back a terminal session logged in a file.

Case conversions

The ucasein option, if set, will cause all upper case terminal input to be mapped to lower case (e.g., when working from an old monocase terminal). In this mode, individual upper case characters may be input by preceding them with the escape character ^, e.g., "^MAKEFILE" equates to "Makefile". The full set of ^ escapes is summarized below. The option ucaseout will cause all terminal output to be mapped to upper case. Preceding either or both of these option keywords by clear causes the options to be cleared.

^       shift next character to upper case
^+      shift lock (caps lock)
^-      clear shift lock
^^      the character ^

Case shifting is disabled in raw mode, e.g., while in cursor mode, and in eparam. All standard IRAF software, however, will sense that ucase mode is set before entering raw mode, and will behave as expected. Ucase mode is also disabled by the STDGRAPH kernel whenever the graphics workstation is activated.

Note that ^ is also the history meta-character, hence ^^ must be used when in ucasein mode to pass a single ^ to the CL history mechanism. In cursor mode, upper case keystrokes are intercepted by cursor mode unless escaped with a backslash. Escaped keystrokes are mapped to lower case by cursor mode if ucasein mode is in effect, terminating cursor mode and returning a lowercase key to the applications program.

Recording terminal i/o

The terminal driver options logio, logout, and login may be used to log, respectively, all terminal i/o, all output to the terminal, or all input from the terminal. The logfile names are "home$ttyin.log", "home$ttyout.log", or "home$ttyio.log", unless a different logfile name is specified by the user. All logfiles are standard textfiles containing only printable characters.

Terminal i/o logging is especially useful for debugging termcap and graphcap entries for new terminals. All IRAF terminal i/o is logged, including raw mode i/o and graphics output. Terminal i/o from foreign tasks or OS escapes is not logged since these tasks bypass the VOS to talk directly to the user terminal.

Each sequence of characters read from or written to the terminal (via a zgettt or zputtt call to the driver) appears as one logical line of text in the logfile, delimited by the data character \n (newline). When reading from a terminal in raw mode, each input character will appear on a separate line in the logfile with no newline, since only a single data character is read at a time during raw mode input. All control characters embedded in the data, including newline terminators, are rendered into printable form. Long lines are broken near the right margin, adding an escaped newline and indenting continuation lines 4 spaces.

Terminal i/o logging is intended primarily for debugging purposes, rather than for logging user commands; the IRAF command language provides a more user friendly facility for command logging (see the language.logging manpage for further information on the CL command logging facilities). All unprintable ASCII codes are rendered in the logfile in a printable form intended to eliminate any ambiguity regarding the exact sequence of characters sent to or received from the terminal. In addition to the standard escape sequences \n, \t, \r, etc., the following special escape sequences are used:

\\              \
\^              ^
^@              NUL (ascii 000)
^[A-Z]          ctrl/a - ctrl/z (ascii 001 - 032)
^[              ESC (ascii 033)
^\              FS  (ascii 034)
^]              GS  (ascii 035)
^^              RS  (ascii 036)
^_              US  (ascii 037)
\s              blank (ascii 040)
\<newline>      long i/o record continued on next line

These special escape sequences, plus any ordinary characters, constitute the data recorded in the logfile. The following additional escape sequences are used to record information about the logging session itself in the logfile.

\#              rest of line is a comment
\T              terminal device name at log time
\G              stdgraph device name at log time
\O              timestamp written at start of log session

Any whitespace (unescaped blanks, tabs, or newlines) appearing in the logfile is put there only to make the file more readable, and is not considered data. Blocks of text may be enclosed in a logfile delimited by escaped curly brackets, i.e., "\{ ... \}". This is used for the playback facility described in the next section.

Playback of terminal sessions

The terminal driver has the capability not only of recording terminal i/o in a file, but of taking input from a logfile to repeat a sequence of commands previously entered by the user with terminal input logging enabled. Note that we are not talking about simply playing back recorded output, but of actually executing an arbitrary sequence of commands formerly entered by the user. This is different from executing a sequence of commands entered into, for example, a CL script, because all input is recorded, including not only the commands, but also all responses to parameter queries, all rawmode keystroke input, and all graphics cursor input occurring interactively during execution of the recorded commands. These playback scripts are useful for preparing automated demos or tutorials of complex software, and for preparing scripts to be used to automatically test software.

The basic sequence used to record and later playback a terminal session is as follows:

cl> stty login [= logfilename]
        <execute an arbitrary sequence of commands>
cl> stty clear login                    # or stty reset
cl> stty playback [= logfilename]

Naturally, the playback script must be executed in the same context as when the script was generated, i.e., one must ensure that all necessary packages have been loaded, that the current directory has been set to the proper value if it matters, and so on. It is not necessary to execute a playback script on the same type of video terminal or graphics terminal as was used when the script was recorded; since only the terminal input is being recorded, playback scripts are device independent and may be played back on any terminal.

If desired the commands necessary to establish the starting context may be recorded as part of the script. If the script is going to be repeatedly executed it may also be desirable to include commands at the end of the recording session to clean up, e.g., deleting any temporary files created during the recording session. If anything has changed which causes a command to abort during execution of a playback script, normal terminal input is automatically restored, aborting the script. Note that if the "stty playback" command gets into the playback script for some reason, e.g., because the "stty reset" (or "stty login=no" etc.) was omitted, then the script will repeat indefinitely. This may or may not be what was desired.

Two stty command line arguments are provided for controlling the execution of a playback script. By default, when a script is played back the terminal driver will pause for delay milliseconds after echoing the command to be executed, to give the user watching the playback a chance to read the command. Aside from this programmed delay, execution is fully automated. For example,

cl> stty play=filename delay=2000

would playback the file "filename", with a delay of 2 seconds following echo of each line of recorded input text.

Alternatively, the user may request that the driver pause and wait for the user to type a key before executing each logged command (i.e., before returning each input line of text to the application). This is called the verify option. In verify mode, the following keystrokes may be entered to continue execution:

space, return           continue execution
'g'                        go: turn verify mode off and continue
'q'                        quit: terminate playback mode

Verify mode is automatically disabled during raw mode input since the input consists of single characters and an inordinate number of verification keystrokes would be required from the user. Either of the verify or delay options may be overridden by control directives embedded in the playback text, as we shall see in the next section.

Customizing playback scripts

Although playback scripts may be and often are generated and played back without ever looking at or modifying the actual playback script, there are cases where it may be desirable to do so. For example, when generating a script to be used as a demo or tutorial, it may be desirable to insert explanatory text into the script to be printed out on the terminal when the script is played back, to explain to the person running the script what is going on. Likewise, it may be desirable to control the verify and delay options at a granularity finer than the entire script.

Explanatory text and/or playback control directives may be inserted into the script using the following construct:

"\{" [<control_directives>] [<text>] "\}"

where control_directive refers to one of the following:

%V+             turn verify on
%V-             turn verify off
%NNN            set delay to NNN milliseconds

For example,

dir\{%5000
[list the current directory]\}\n

would cause the following to be output, followed after a 5 second delay by a listing of the current directory (the "<>" is not printed, but shows where the cursor will be during the 5 second pause):

cl> dir
[list the current directory]<>

Note that the newline following the "\{%5000" in the above example is textual data, and will be output to the terminal along with whatever follows, up until the closing brace, i.e., "\}". The amount of text to be output may be arbitrarily large; there is a builtin limit (currently 4096 characters), but it is unlikely that this limit will ever be exceedd, since no more than one pageful of text should ever be output in a single call.

Normally, a %V or %NNN control directive refers only to the input record with which the enclosing \{...\} control block is associated. The global value of verify or delay is temporarily overridden for the current record. If desired, the global value may instead be permanently modified by adding a ! after the %, e.g.,

\{%!V-%3000...\}

would permanently disable verify (unless a %V+ or %!V+ directive follows later in the script) then output the text "..." followed by a 3 second delay.

To know where to insert the control directives into a script, it is important to understand that input from the script is record oriented, and that a control directive refers to the input record with which it is associated. An input record is a single logical line of text in the input file. Note that a logical line of text may span multiple physical lines, if the newlines are escaped or present as textual data within a control directive. The position of the control directive within the input record determines where the explanatory text will be positioned relative to the input text, when both are echoed to the terminal. Any programmed delay or pause will always occur after echoing the full record on the terminal.

Raw mode playback

When a program is executing which reads from the terminal in raw mode, each character is read from the terminal as soon as it is typed, and input characters are not echoed to the terminal unless the application explicitly does the echoing. Examples of programs which use raw mode input are eparam and page, which are keystroke driven, and any program which reads the graphics cursor, since a graphics cursor read uses raw mode input.

Playback works much the same for raw input mode as for line input mode, except that during raw mode input the input records normally consist of single characters, rather than entire lines of text. By default, verify is turned off while reading from the terminal in raw mode, to avoid having the user verify each individual character. Also, the terminal driver will not echo text read from the playback file in raw mode, since the text would not have been echoed if playback were not in effect.

Cursor reads in playback mode

A typical Tektronix style cursor read will look something like the following, as recorded in an stty login script file following a recording session:

K
3
)
'
*
\r

This six character sequence consists of the key value of the cursor read (K), followed by the [x,y] cursor coordinate encoded as four ascii characters ("3)'*" in this case), followed by the "GIN mode terminator" character or characters, normally a single CR (\r). Of course, if the terminal is not a Tektronix compatible terminal (e.g., DEC-Regis), the details will differ from this example.

The single character per line format of a cursor read reflects the fact that each input record is a single character when reading from the terminal in raw mode. For the purposes of playback, however, such a sequence may be reformatted on a single line if desired, to improve the readability of a script (the extra whitespace in the second example is ignored, since if a space were data it would appear as \s).

        K3)'*\r
or
        K 3 ) ' * \r
or
        K
        3)'*
        \r
etc.

To set the values of the verify or delay parameters for a cursor read one may insert the \{...\} sequence anywhere before the \r delimiter is returned to the application, e.g.,

K3)'*\r\{%V+\}

would do, since the sequence shown forms one logical input record in the playback file, and the control directive included will be processed before any input data characters from the record are returned to the application. If the multi-line form of a cursor read is used, the control directive may be tacked onto any of the records K through \r in the example.

Output of explanatory text in an interactive graphics session is a little more tricky, since if one is not careful the text will come out while in graphics mode, causing it to be rendered as random lines drawn all over the screen. A safe technique for outputting comments during playback of a graphics session is to output the text to the status line, taking care of course to output only a single line of text at once (since multiple lines written to the status line would rapidly flash by, leaving only the last line visible on the screen). We can do this by taking advantage of the : command sequence, which can be used to put the terminal temporarily into status line output mode.

:####\r
\{%5000
This is a status line comment\}
^U\177

For example, insertion of the above sequence between any two cursor reads in a recorded interactive graphics session would cause the text "This is a status line comment" to be written to the status line, with normal execution of the script occurring after a 5 second delay followed by erasure of the status line and exit from status line mode (due to the ctrl/u and rubout inserted as data after the colon cursor read).

While executing an interactive graphics session via playback, cursor values are read from the playback script instead of from the terminal, hence the user never sees the actual cursor crosshairs on the screen. To give the user some idea of what is going on, the key values of successive cursor mode keystrokes are echoed in ascii down the left side of the screen, starting at the upper left. The keystroke value is also echoed at the position of the cursor, to indicate where the cursor crosshairs would have been in an actual interactive session.

Sample playback script

We conclude with an example of a complete playback script which can be entered into a file and played back to demonstrate some of the features of the implot task in the PLOT package (the PLOT package must already be loaded).

\O=NOAO/IRAF V2.6 iraf@pavo Fri 20:09:21 01-Jan-88
\T=gterm40
\G=gterm
\n
imheader\sdev$pix\slo+\suser-\n\{%3000
[Print image header]\}
\n
implot\sdev$pix\n
J3..8\r J3-,)\r J3+)9\r K3)'*\r J3((0\r l3&';\r
:####\r
\{%5000
[use key `o' to overplot]\}
^U\177
o3&';\r
K3&';\r K3%*(\r K3#,3\r l3!.?\r
:####\r
\{%5000
[key `X' expands the plot in x]\}
^U\177
X3!.?\r
qXXXX\r
stty\sreset\n

Examples

1. Show the current terminal type and attributes.

cl> stty
Terminal=vt640, ncols=80, nlines=24, 9600 baud
ucasein=no, ucaseout=no, logio=off

2. Tell the system that the terminal is a vt100.

cl> stty vt100

3. Set the baud rate of the current terminal to 9600 baud.

cl> stty baud=9600

4. Set the width of the screen to 80 columns, e.g., to get short menus on a workstation where the physical number of columns may be much greater than 80.

cl> stty ncols=80

5. Set the terminal type to 4012 and set ucasein and ucaseout modes.

cl> stty 4012 ucasein ucaseout

6. Clear the ucasein and ucaseout modes.

cl> stty clear ucasein ucaseout

7. Record a terminal session in the default logfile (home$ttyio.log).

cl> stty logio

8. Record input from the terminal in the file "demo".

cl> stty login=demo

9. Terminate logging and playback the terminal session recorded in this file.

cl> stty reset
cl> stty playback=demo

Bugs

1. Note that, when working with a terminal which supports runtime querying of the screen size, the screen size is queried when the stty resize command is executed, rather than when the terminal screen actually changes size. Hence, the screen size parameters printed by a command such as stty show will not necessarily reflect the actual screen size. stty resize show queries the terminal for the screen size, hence should always be correct. The screen size is automatically queried whenever the page or help tasks are run.

2. The terminal screen size is determined by querying the terminal for the screen size, and reading the response back (this technique has the advantage that it works remotely over IPC and network connections, and is host system independent). If the terminal does not respond for some reason, e.g., because the terminal type has been set improperly and the terminal does not support the query function, then stty will hang. Typing a carriage return causes execution to resume, after which the error should be corrected.