diff options
Diffstat (limited to 'pkg/language/doc/stty.hlp')
| -rw-r--r-- | pkg/language/doc/stty.hlp | 589 |
1 files changed, 589 insertions, 0 deletions
diff --git a/pkg/language/doc/stty.hlp b/pkg/language/doc/stty.hlp new file mode 100644 index 00000000..8556a43b --- /dev/null +++ b/pkg/language/doc/stty.hlp @@ -0,0 +1,589 @@ +.help stty Feb88 language +.ih +NAME +stty -- set/show terminal characteristics +.ih +USAGE +stty [terminal] +.ih +PARAMETERS +.ls terminal +The logical name of the terminal to be used, i.e., the name of the device +given in the \fIdev$termcap\fR file. +.le +.ls 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. +.le +.ls 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. +.le +.ls nlines = 24 +The logical height of the screen in characters. +.le +.ls show = no +Show the current terminal driver settings. The \fIshow\fR function is +automatically enabled if \fIstty\fR is called with no arguments. +.le +.ls all = no +Show all terminal driver settings, including those which are not currently +in use. Setting \fIall\fR automatically sets \fIshow\fR. +.le +.ls 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. +.le +.ls resize = no +Recompute the terminal screen size parameters, \fBttyncols\fR and +\fBttynlines\fR, 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. +.le +.ls clear = no +Clear the function(s) which follow on the command line, e.g., +"clear ucasein ucaseout" is equivalent to "ucasein=no ucaseout=no". +.le +.ls 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. +.le +.ls ucaseout = no +Map terminal output to upper case. +.le +.ls login = "home$ttyin.log" [off] +Log all input from the terminal to the named text file. +.le +.ls logio = "home$ttyio.log" [off] +Log all terminal i/o to the named text file. May not be used if either +\fIlogin\fR or \fIlogout\fR mode is in effect, and vice versa. +.le +.ls logout = "home$ttyout.log" [off] +Log all output to the terminal to the named text file. +.le +.ls 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 \fIlogin\fR +mode in effect, e.g., to test or demo software. +.le +.ls verify = no +If \fIverify\fR is enabled during \fIplayback\fR 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, \fIq\fR to terminate +playback mode, or \fIg\fR to continue execution with \fIverify\fR mode +disabled. Typing any other key causes a help line to be printed. +.le +.ls delay = 500 (msec) +If \fIverify\fR is disabled during \fIplayback\fR mode the terminal driver +will pause for \fIdelay\fR milliseconds before executing each logfile command. +.le + +.ih +DESCRIPTION +The \fIstty\fR task is used to set or display the terminal device +characteristics and VOS terminal driver options. +Without arguments, \fIstty\fR prints the current characteristics of the +terminal. The default terminal type can be changed by setting \fIttyname\fR. +The terminal characteristics \fIncols\fR, \fInlines\fR or \fIbaud\fR, +may be changed by typing new values explicitly on the command line. + +The most common use of \fIstty\fR 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 \fBtermcap\fR file; +if the named terminal is a graphics terminal, there must also be an entry +in the \fBgraphcap\fR file. + +To find out about the current terminal settings, type + +.ks +.nf + cl> stty +or + cl> stty all +.fi +.ke + +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. + +.ih 4 1 +Case Conversions +The \fBucasein\fR 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 \fBucaseout\fR will cause all +terminal output to be mapped to upper case. Preceding either or both of +these option keywords by \fBclear\fR causes the options to be cleared. + +.ks +.nf + ^ shift next character to upper case + ^+ shift lock (caps lock) + ^- clear shift lock + ^^ the character ^ +.fi +.ke + +Case shifting is disabled in raw mode, e.g., while in cursor mode, and in +\fBeparam\fR. 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 \fIucasein\fR 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 \fIucasein\fR mode is in effect, terminating cursor mode and +returning a lowercase key to the applications program. + +.ih +Recording Terminal I/O +The terminal driver options \fBlogio\fR, \fBlogout\fR, and \fBlogin\fR +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 \fItermcap\fR and +\fIgraphcap\fR 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 \fIlanguage.logging\fR +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: + +.ks +.nf + \\ \ + \^ ^ + ^@ 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 +.fi +.ke + +These special escape sequences, plus any ordinary characters, constitute the +\fIdata\fR recorded in the logfile. The following additional escape +sequences are used to record information about the logging session itself in +the logfile. + +.ks +.nf + \# 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 +.fi +.ke + +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 \fBplayback\fR +facility described in the next section. + +.ih +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 \fIall\fR 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 \fBplayback scripts\fR 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: + +.ks +.nf + cl> stty login [= logfilename] + <execute an arbitrary sequence of commands> + cl> stty clear login # or stty reset + cl> stty playback [= logfilename] +.fi +.ke + +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 \fBstty\fR 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 \fBdelay\fR 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 +\fBverify\fR option. In verify mode, the following keystrokes may be +entered to continue execution: + +.ks +.nf + space, return continue execution + 'g' go: turn verify mode off and continue + 'q' quit: terminate playback mode +.fi +.ke + +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 \fBverify\fR or +\fBdelay\fR options may be overridden by control directives embedded in the +playback text, as we shall see in the next section. + +.ih +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 \fBcontrol_directive\fR refers to one of the following: + +.ks +.nf + %V+ turn verify on + %V- turn verify off + %NNN set \fBdelay\fR to NNN milliseconds +.fi +.ke + +For example, + +.ks +.nf + dir\{%5000 + [list the current directory]\}\n +.fi +.ke + +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): + +.ks +.nf + cl> dir + [list the current directory]<> +.fi +.ke + +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 \fIverify\fR or \fIdelay\fR 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 \fIverify\fR (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 \fBrecord oriented\fR, +and that a control directive refers to the input record with which it is +associated. An input record is a single \fIlogical\fR 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. + +.ih +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 +\fIeparam\fR and \fIpage\fR, which are keystroke driven, and any program +which reads the \fBgraphics cursor\fR, 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, \fBverify\fR +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. + +.ih +Cursor Reads in Playback Mode +A typical Tektronix style cursor read will look something like the following, +as recorded in an \fBstty login\fR script file following a recording session: + +.ks +.nf + K + 3 + ) + ' + * + \r +.fi +.ke + +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). + +.ks +.nf + K3)'*\r +or + K 3 ) ' * \r +or + K + 3)'* + \r +etc. +.fi +.ke + +To set the values of the \fIverify\fR or \fIdelay\fR 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 \fBstatus line\fR, +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. + +.ks +.nf + :####\r + \{%5000 + This is a status line comment\} + ^U\177 +.fi +.ke + +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. + +.ih +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 \fIimplot\fR task in the PLOT package (the PLOT package must already +be loaded). + +.ks +.nf + \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 +.fi +.ke + +.ih +EXAMPLES +1. Show the current terminal type and attributes. + +.nf + cl> stty + Terminal=vt640, ncols=80, nlines=24, 9600 baud + ucasein=no, ucaseout=no, logio=off +.fi + +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. + +.nf + cl> stty reset + cl> stty playback=demo +.fi +.ih +BUGS +1. Note that, when working with a terminal which supports runtime querying +of the screen size, the screen size is queried when the \fBstty resize\fR +command is executed, rather than when the terminal screen actually changes size. +Hence, the screen size parameters printed by a command such as \fBstty show\fR +will not necessarily reflect the actual screen size. \fBstty resize show\fR +queries the terminal for the screen size, hence should always be correct. +The screen size is automatically queried whenever the \fIpage\fR or \fIhelp\fR +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 \fBstty\fR will hang. Typing a carriage +return causes execution to resume, after which the error should be corrected. +.ih +SEE ALSO +language.logging, fio$zfiott.x, etc$sttyco.x +.endhelp |