9TERM(1)

NAME
9term, label, wloc - terminal emulator

SYNOPSIS
9term [ -s ] [ -p9font fontfile ] [ -unix ] [ -9 ] [ -ls ] [ -ut ] [ -label label ] [ -high highwater ] [ -low lowwater ] [ -9wm ] [ -e cmd ... ]

label name

wloc

DESCRIPTION
9term is a terminal emulator for the X Window System. It provides a terminal window similar to an 8½ window.

  Commands
The 9term command starts a new instance of a terminal window.

The -s option creates a scrolling window; by default scrolling is inhibited. A +s option forces the window not to scroll.

The -unix option starts 9term in Unix mode; normally it starts in Plan 9 mode (see below). The -9 option starts 9term in Plan 9 mode.

The fontfile argument to the -p9font option names a fontfile used to display text, both in 9term's menus and on the window. It also establishes the environment variable font with this value, so any programs running in its windows may use the same font. If fontfile cannot be used as a valid libXg font file (see font(4)), then 9term will attempt to use an X font by the same name. If -p9font is not given, 9term imports a default font from the underlying graphics server. If that fails 9term will attempt to use the default X font, see graphics(3).

The -ls option make the window a login window (prepends a `-' to cmd). The option +ls attempt to do the opposite. The default is not to create a login window.

The -ut option causes 9term to place an entry in the file. A corresponding +ut option prevents 9term from placing an entry in The default is not to create a utmp entry.

The -label command gives the new 9term window the initial label of label. The default label is 9term.

The -e option tells 9term to run the command cmd in the window with the following arguments. This must be the final option on the command line. If no command is specified, 9term runs the program specified by the environment variable SHELL in the window, if this is unset, then 9term runs sh(1) in the window.

The -high and -low options set the maximum and minimum amount of characters kept by 9term. At any one time the actual number of characters stored may slightly exceed the highwater mark.

The -9wm option allows 9term to work more harmoniously with 9wm when started before the window manager may have completed its initialisation, such as in a user's file. It causes 9term to refrain from placing a border around the text content of the window and instead allows the window manager this task.

The label command changes a window's identifying name.

The wloc command prints the coordinates of the instance of 9term in which it is executed and is used to construct a geometry argument for X programs. It relies on the environment variable WINDOWID which 9term places in the environment in a manner similar to xterm(1).

  Window control
Each window behaves as a separate terminal with at least one process associated with it. When a window is created, a new process (usually a shell; see sh(1), rc(1), and es(1)) is established and bound to the window as a process group leader of a new process group. Initially, each window acts as a simple terminal that displays character text; the standard input and output of its processes are attached to

  Text windows
Characters typed on the keyboard or written to 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 colour. If the selected text is a null string, it is indicated by a hairline cursor between two characters. The selected text may be edited by mousing and typing. Text is selected by pointing and clicking button 1 to make a null-string selection, or by pointing, then sweeping with button 1 depressed. 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; 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).

  The Output Point
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 will appear; afterwards, the output point is the null string beyond the new character. The output point is also the location in the text of the next character that will be read (directly from the text in the window, not from an intervening buffer) by a program from When such a read will occur is, however, mostly under control of 9term and the user.

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 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, since 9term will not send characters until there is a newline after the output point. After the read, as described above, the output point will be at the beginning of the next line of text. In normal circumstances, therefore, typed text is delivered to programs a line at a time. Changes made by typing or editing before the text is read will be seen by the program reading it. Lines are sent when a newline is typed by the user, thus there may only be at most a single line of text after the output point waiting to be sent.

Even when there are newlines in the output text, 9term will not honour reads if the window is in hold mode, which is indicated by a white cursor and border. The ESC character toggles hold mode. Some programs, such as mail(1), may benefit from hold mode to simplify the editing of multi-line text; type ESC when done to allow mail to read the text. Hold mode is disabled when the terminal is in cbreak/raw mode, for example, when using rlogin. When the terminal is in this mode, changes to the last line will not be `seen' by the program running in the window since characters typed are sent immediately.

  Terminal modes
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. Like newlines, unread EOTs may be successfully edited out of the text. 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) 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.

The characters listed above are the default characters for the Plan 9 mode of 9term. The initial value of this set may be changed with the X resource and may be useful for keyboards which have no backspace key (such as DEC keyboards). Such a change is static for the life of a 9term. A corresponding resource, may be used to set the initial Unix mode characters. Such characters may be altered over the life of a 9term.

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 gray 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 window 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. Also, a VIEW key (possibly with a different label; see keyboard(4)) scrolls forward half a window. A REVIEW key (scroll back half a window) may also be supported.

The DEL character sends an signal to all processes in the window's process group. Alone among characters, the DEL and VIEW keys do not snarf the selected text.

Normally written output to a window does not block when the text reaches the end of the screen. In this respect 9term differs from an 8½ window. A button 2 menu item toggles scrolling.

  Cutting, Pasting and Snarfing Text
Other 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. Scroll/noscroll toggles scroll mode.

Button 3 menu items are used to search forwards and backwards in the window, and access the hold and view features of 9term when running in Unix mode. Selecting fwd (bkwd) searches forward (backward) in the window from the current cursor position for the next (previous) occurrence of the currently selected text. If no text is currently selected then 9term searches the window for the string currently in the snarf buffer. Selecting suspend is equivalent to typing the hold key. When the terminal is in hold mode this menu item will change to resume. Selecting view or review is equivalent to pressing the VIEW or REVIEW key. The last button 3 menu item toggles between Plan 9 and Unix modes.

X DEFAULTS
LibXg understands all of the resources mentioned in graphics(3) including p9font, composeMod, and scrollForwardR, as well as

scroll (class Scroll)
    Specifies whether or not the window should scroll. The default is ``false.''

login (class Login)
    Specifies whether or not the shell to be run in the window should be started as a login shell. The default is ``false.''

utmp (class Utmp)
    Specifies whether or not 9term should try to record the user's terminal in The default is ``false.''

label (class Label)
    Specifies an initial label for the window that may be used by a window manager when displaying this application. The default is ``9term.''

kbdMode (class KbdMode)
    Specifies the initial label keyboard mode. The default is ``plan9.''

ttyModes (class TtyModes)
    Specifies a string containing terminal setting keywords and the characters to which they may be bound. These are the characters initially to be used in Unix mode. Allowable keywords include: intr, quit, erase, kill, eof, eol, eol2, swtch, start, stop, susp, dsusp, rprnt, flush, weras, and lnext. Control characters may be specified as ^char (e.g. ^c or ^u) and ^? may be used to indicate DELETE. This is very useful for overriding the default terminal settings without having to do a stty every time a 9term is started.

p9TtyModes (class P9TtyModes)
    Specifies a string of the same format as above indicating the characters to be used in Plan 9 mode.

highwater (class Highwater)
    Specifies the maximum number of characters of output 9term should save. At any one time 9term may slightly exceed this limit. The default is 50 000.

lowwater (class Lowwater)
    Specifies the low water mark for 9term. 9term truncates the saved output to this many characters when the number of saved characters exceeds the high water mark. The default is 40 000.

9wm (class 9Wm)
    Specifies whether or not 9term should refrain from placing a border around the the text inside its window. The default is ``false.''

beep (class Beep)
    Specifies the modes for which 9term should sound an audible bell when confronted with the BEL character (control-G). Permissible values are ``plan9'' and ``unix'' corresponding to the two keyboard modes. Both may be specified. The default is ``none''.

FILES

font directories

SEE ALSO
sh(1), rc(1), es(1), sam(1), 9wm(1), mail(1), graphics(3), frame(3), layer(3), text(3), keyboard(4).