--- name: "9term" section: "1" platform: "linux" package: "9term" version: "1.6.6-5" release: "Debian 2.1 (Slink)" platforms: ["linux"] url: "https://new.carta.tech/9term" --- # 9term(1) terminal emulator ## 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 **/etc/utmp** file. A corresponding **+ut** option prevents *9term* from placing an entry in **/etc/utmp**. 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)](/sh/1.md) 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 **.xsession** 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)](/xterm/1.md). ### 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)](/sh/1.md), [*rc*(1)](/rc/1.md), and [*es*(1)](/es/1.md)) 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 **/dev/tty**. ### Text windows Characters typed on the keyboard or written to **/dev/tty** 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)](/sam/1.md). ### 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 **/dev/tty** 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 **/dev/tty**. 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 **/dev/tty** 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)](/mail/1.md), 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 **p9TtyModes** 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, **ttyModes**, 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)](/keyboard/4.md)) scrolls forward half a window. A REVIEW key (scroll back half a window) may also be supported. The DEL character sends an **interrupt** 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. **Mark/extend** is useful for making a selection larger than will fit on the screen. **Mark** indicates one extreme of the selection while **extend** selects the text from the current mark to the include the current selection. **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 **/etc/utmp**. 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 - - **/lib/font/bit/\*** font directories ## SEE ALSO [*sh*(1)](/sh/1.md), [*rc*(1)](/rc/1.md), [*es*(1)](/es/1.md), [*sam*(1)](/sam/1.md), *9wm*(1), [*mail*(1)](/mail/1.md), *graphics*(3), *frame*(3), *layer*(3), *text*(3), [*keyboard*(4)](/keyboard/4.md).