9TERM(1)                     General Commands Manual                    9TERM(1)

       9term - terminal windows

       9term [ -asc ] [ -f font ] [ cmd ...  ]

       9term is a terminal window program for the X Window System, providing an
       interface similar to that used on Plan 9.

       The 9term command starts a new window.

       The -a flag causes button 2 to send the selection immediately, 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 create 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 running 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

       9term runs the given command in the window, or $SHELL if no command is

   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 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 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; 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 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.  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, therefore, 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 automatically 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) 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 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.  Holding a button pressed in the
       scroll bar will cause the text to scroll continuously until the button is

       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 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 interrupt 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.  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
       keystrokes 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 typically 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

       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.

       The look menu item searches forward for the contents of the selection
       within the window. If a match is found, it becomes the new selection and
       the window scrolls to display it. The search wraps around to the
       beginning of the windows if the end of the window is reached.

       For systems without a three-button mouse, the keyboard modifier 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 socket in the environment as
       $text9term before running cmd.


       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.