9TERM(1) 9TERM(1)
NAME
9term - terminal windows
SYNOPSIS
9term [ -asc ] [ -f font ] [ cmd ... ]
DESCRIPTION
9term is a terminal window program for the X Window System,
providing an interface similar to that used on Plan 9.
Command
The 9term command starts a new window.
The -a flag causes button 2 to send the selection immedi-
ately, like acme. Otherwise button 2 brings up a menu,
described below.
The -s option has no effect. It formerly set the scrolling
mode, and is recognized to avoid breaking scripts that cre-
ate new windows. See below for a description of scrolling
behavior.
The -c option starts the window in forced cooked mode,
described below.
The font argument to -f names a font used to display text,
both in 9term's menus and as a default for any programs run-
ning in its windows; it also establishes the environment
variable $font. If -f is not given, 9term uses the imported
value of $font if set; otherwise it uses the graphics system
default. (See font(7) for a full discussion of font syn-
taxes.)
9term runs the given command in the window, or $SHELL if no
command is given.
Text windows
Characters typed on the keyboard collect in the window to
form a long, continuous document.
There is always some selected text, a contiguous string
marked on the screen by reversing its color. If the
selected text is a null string, it is indicated by a hair-
line cursor between two characters. The selected text may
be edited by mousing and typing. Text is selected by point-
ing and clicking button 1 to make a null-string selection,
or by pointing, then sweeping with button 1 pressed. Text
may also be selected by double-clicking: just inside a
matched delimiter-pair with one of {[(<`'" on the left and
}])>`'" on the right, it selects all text within the pair;
Page 1 Plan 9 (printed 12/22/24)
9TERM(1) 9TERM(1)
at the beginning or end of a line, it selects the line;
within or at the edge of an alphanumeric word, it selects
the word.
Characters typed on the keyboard replace the selected text;
if this text is not empty, it is placed in a snarf buffer
common to all windows but distinct from that of sam(1).
Programs access the text in the window at a single point
maintained automatically by 9term. The output point is the
location in the text where the next character written by a
program to the terminal will appear; afterwards, the output
point is the null string beyond the new character. The out-
put point is also the location in the text of the next char-
acter that will be read (directly from the text in the win-
dow, not from an intervening buffer) by a program. Since
Unix does not make it possible to know when a program is
reading the terminal, lines are sent as they are completed
(when the user types a newline character).
In general there is text in the window after the output
point, usually placed there by typing but occasionally by
the editing operations described below. A pending read of
the terminal will block until the text after the output
point contains a newline, whereupon the read may acquire the
text, up to and including the newline. After the read, as
described above, the output point will be at the beginning
of the next line of text. In normal circumstances, there-
fore, typed text is delivered to programs a line at a time.
Changes made by typing or editing before the text is read
will not be seen by the program reading it. Because of the
Unix issues mentioned above, a line of text is only editable
until it is completed with a newline character, or when hold
mode (see below) is enabled.
Even when there are newlines in the output text, 9term will
not honor reads if the window is in hold mode, which is
indicated by a white cursor and blue text and border. The
ESC character toggles hold mode. Some programs automati-
cally turn on hold mode to simplify the editing of multi-
line text; type ESC when done to allow mail to read the
text.
An EOT character (control-D) behaves exactly like newline
except that it is not delivered to a program when read.
Thus on an empty line an EOT serves to deliver an end-of-
file indication: the read will return zero characters. The
BS character (control-H) erases the character before the
selected text. The ETB character (control-W) erases any
nonalphanumeric characters, then the alphanumeric word just
before the selected text. `Alphanumeric' here means non-
blanks and non-punctuation. The NAK character (control-U)
Page 2 Plan 9 (printed 12/22/24)
9TERM(1) 9TERM(1)
erases the text after the output point, and not yet read by
a program, but not more than one line. All these characters
are typed on the keyboard and hence replace the selected
text; for example, typing a BS with a word selected places
the word in the snarf buffer, removes it from the screen,
and erases the character before the word.
An ACK character (control-F) or Insert character triggers
file name completion for the preceding string (see
complete(3)).
Text may be moved vertically within the window. A scroll
bar on the left of the window shows in its clear portion
what fragment of the total output text is visible on the
screen, and in its grey part what is above or below view; it
measures characters, not lines. Mousing inside the scroll
bar moves text: clicking button 1 with the mouse pointing
inside the scroll bar brings the line at the top of the win-
dow to the cursor's vertical location; button 3 takes the
line at the cursor to the top of the window; button 2,
treating the scroll bar as a ruler, jumps to the indicated
portion of the stored text. Holding a button pressed in the
scroll bar will cause the text to scroll continuously until
the button is released.
Typing down-arrow scrolls forward one third of a window, and
up-arrow scrolls back. Typing page-down scrolls forward two
thirds of a window, and page-up scrolls back. Typing Home
scrolls to the top of the window; typing End scrolls to the
end.
The DEL character sends an `interrupt' note to all processes
in the window's process group. Unlike the other characters,
the DEL and arrow keys do not affect the selected text. The
left (right) arrow key moves the selection to one character
before (after) the current selection.
9term relies on the kernel's terminal processing to handle
EOT, so the terminal must be set up with EOT as the ``eof''
character. 9term runs stty(1) to establish this when the
terminal is created.
9term always treats the DEL keystroke as an interrupt
request. In response it sends the terminal's current inter-
rupt character (which need not be DEL).
Written output to a window is appended to the end of the
window. The window scrolls to display the new output only
if the end of the window was visible before the write.
9term changes behavior according to the terminal settings of
the running programs. Most programs run with echo enabled.
Page 3 Plan 9 (printed 12/22/24)
9TERM(1) 9TERM(1)
In this mode, 9term displays and allows editing of the
input. Some programs, typically those reading passwords,
run with echo disabled. In this mode, 9term passes keys-
trokes through directly, without echoing them or buffering
until a newline character. These heuristics work well in
many cases, but there are a few common ones where they fall
short. First, programs using the GNU readline library typi-
cally disable terminal echo and perform echoing themselves.
The most common example is the shell bash(1). Disabling the
use of readline with ``set +o emacs'' [sic] usually restores
the desired behavior. Second, remote terminal programs such
as ssh(1) typically run with echo disabled, relying on the
remote system to echo characters as desired. Plan 9's ssh
has a -C flag to disable this, leaving the terminal in
``cooked'' mode. For similar situations on Unix, 9term's
button 2 menu has an entry to toggle the forced use of
cooked mode, despite the terminal settings. In such cases,
it is useful to run ``stty -echo'' on the remote system to
avoid seeing your input twice.
Editing operations are selected from a menu on button 2.
The cut operation deletes the selected text from the screen
and puts it in the snarf buffer; snarf copies the selected
text to the buffer without deleting it; paste replaces the
selected text with the contents of the buffer; and send
copies the snarf buffer to just after the output point,
adding a final newline if missing. Paste will sometimes and
send will always place text after the output point; the text
so placed will behave exactly as described above. Therefore
when pasting text containing newlines after the output
point, it may be prudent to turn on hold mode first.
The plumb menu item sends the contents of the selection (not
the snarf buffer) to the plumber (see plumb(1)). If the
selection is empty, it sends the white-space-delimited text
containing the selection (typing cursor). A typical use of
this feature is to tell the editor to find the source of an
error by plumbing the file and line information in a
compiler's diagnostic.
For systems without a three-button mouse, the keyboard modi-
fier keys can be used to modify the effect of the main mouse
button. On Unix systems, the Control key changes the main
button to button 2, and the Alt key changes it to button 3.
On Mac systems, the Option key changes the main button to
button 2, and the Command key changes it to button 3. Also
on Mac systems, the usual keyboard shortcuts Command-C, -V,
and -X invoke copy, paste, and cut, as in other programs.
Each 9term listens for connections on a Unix socket. When a
client connects, the 9term writes the window contents to the
client and then hangs up. 9term installs the name of this
Page 4 Plan 9 (printed 12/22/24)
9TERM(1) 9TERM(1)
socket in the environment as $text9term before running cmd.
SOURCE
/usr/local/plan9/src/cmd/9term
BUGS
There should be a program to toggle the current window's
hold mode.
Not a 9term bug: when running bash(1) in ``set +o emacs''
mode, its handling of interrupts is broken. In response to
DEL, bash processes the interrupt but then silently discards
the next character typed.
Unix makes everything harder.
SEE ALSO
wintext(1)
Page 5 Plan 9 (printed 12/22/24)