1 ba19f6b5 2004-04-19 devnull .TH 9TERM 1
3 c8b6342d 2005-01-13 devnull 9term \- terminal windows
4 ba19f6b5 2004-04-19 devnull .SH SYNOPSIS
17 ba19f6b5 2004-04-19 devnull .SH DESCRIPTION
19 ba19f6b5 2004-04-19 devnull is a terminal window program for the X Window System,
20 ba19f6b5 2004-04-19 devnull providing an interface similar to that used on Plan 9.
21 c8b6342d 2005-01-13 devnull .SS Command
24 ba19f6b5 2004-04-19 devnull command starts a new window.
28 ba19f6b5 2004-04-19 devnull flag causes button 2 to send the selection immediately, like acme.
29 ba19f6b5 2004-04-19 devnull Otherwise button 2 brings up a menu, described below.
33 ba19f6b5 2004-04-19 devnull option initializes windows so that text scrolls;
34 ba19f6b5 2004-04-19 devnull the default is not to scroll.
38 ba19f6b5 2004-04-19 devnull argument to
40 ba19f6b5 2004-04-19 devnull names a font used to display text, both in
41 ba19f6b5 2004-04-19 devnull .IR 9term 's
43 ba19f6b5 2004-04-19 devnull and as a default for any programs running in its windows; it also
44 ba19f6b5 2004-04-19 devnull establishes the
45 ba19f6b5 2004-04-19 devnull environment variable
46 ba19f6b5 2004-04-19 devnull .BR $font .
49 ba19f6b5 2004-04-19 devnull is not given,
51 ba19f6b5 2004-04-19 devnull uses the imported value of
53 ba19f6b5 2004-04-19 devnull if set; otherwise it uses the graphics system default.
56 ba19f6b5 2004-04-19 devnull runs the given command in the window, or
57 ba19f6b5 2004-04-19 devnull .B $SHELL
58 ba19f6b5 2004-04-19 devnull if no command is given.
59 ba19f6b5 2004-04-19 devnull .SS Text windows
60 ba19f6b5 2004-04-19 devnull Characters typed on the keyboard
61 ba19f6b5 2004-04-19 devnull collect in the window to form
62 ba19f6b5 2004-04-19 devnull a long, continuous document.
64 ba19f6b5 2004-04-19 devnull There is always some
65 ba19f6b5 2004-04-19 devnull .I selected
66 ba19f6b5 2004-04-19 devnull .IR text ,
67 ba19f6b5 2004-04-19 devnull a contiguous string marked on the screen by reversing its color.
68 ba19f6b5 2004-04-19 devnull If the selected text is a null string, it is indicated by a hairline cursor
69 ba19f6b5 2004-04-19 devnull between two characters.
70 ba19f6b5 2004-04-19 devnull The selected text
71 ba19f6b5 2004-04-19 devnull may be edited by mousing and typing.
72 ba19f6b5 2004-04-19 devnull Text is selected by pointing and clicking button 1
73 ba19f6b5 2004-04-19 devnull to make a null-string selection, or by pointing,
74 ba19f6b5 2004-04-19 devnull then sweeping with button 1 pressed.
75 ba19f6b5 2004-04-19 devnull Text may also be selected by double-clicking:
76 ba19f6b5 2004-04-19 devnull just inside a matched delimiter-pair
77 ba19f6b5 2004-04-19 devnull with one of
78 ba19f6b5 2004-04-19 devnull .B {[(<`'"
79 ba19f6b5 2004-04-19 devnull on the left and
80 ba19f6b5 2004-04-19 devnull .B }])>`'"
81 ba19f6b5 2004-04-19 devnull on the right, it selects all text within
82 ba19f6b5 2004-04-19 devnull the pair; at the beginning
83 ba19f6b5 2004-04-19 devnull or end of a line, it selects the line; within or at the edge of an alphanumeric word,
84 ba19f6b5 2004-04-19 devnull it selects the word.
86 ba19f6b5 2004-04-19 devnull Characters typed on the keyboard replace the selected text;
87 ba19f6b5 2004-04-19 devnull if this text is not empty, it is placed in a
88 ba19f6b5 2004-04-19 devnull .I snarf buffer
89 ba19f6b5 2004-04-19 devnull common to all windows but distinct from that of
90 ba19f6b5 2004-04-19 devnull .IR sam (1).
92 ba19f6b5 2004-04-19 devnull Programs access the text in the window at a single point
93 ba19f6b5 2004-04-19 devnull maintained automatically by
94 ba19f6b5 2004-04-19 devnull .IR 9term .
96 ba19f6b5 2004-04-19 devnull .I output point
97 ba19f6b5 2004-04-19 devnull is the location in the text where the next character written by
98 ba19f6b5 2004-04-19 devnull a program to the terminal
99 ba19f6b5 2004-04-19 devnull will appear; afterwards, the output point is the null string
100 ba19f6b5 2004-04-19 devnull beyond the new character.
101 ba19f6b5 2004-04-19 devnull The output point is also the location in the text of the next character
102 ba19f6b5 2004-04-19 devnull that will be read (directly from the text in the window,
103 ba19f6b5 2004-04-19 devnull not from an intervening buffer)
104 ba19f6b5 2004-04-19 devnull by a program.
105 ba19f6b5 2004-04-19 devnull Since Unix does not make it possible to know when a program
106 ba19f6b5 2004-04-19 devnull is reading the terminal, lines are sent as they are completed
107 ba19f6b5 2004-04-19 devnull (when the user types a newline character).
109 ba19f6b5 2004-04-19 devnull In general there is text in the window after the output point,
110 ba19f6b5 2004-04-19 devnull usually placed there by typing but occasionally by the editing
111 ba19f6b5 2004-04-19 devnull operations described below.
112 ba19f6b5 2004-04-19 devnull A pending read of the terminal
113 ba19f6b5 2004-04-19 devnull will block until the text after the output point contains
114 ba19f6b5 2004-04-19 devnull a newline, whereupon the read may
115 ba19f6b5 2004-04-19 devnull acquire the text, up to and including the newline.
116 ba19f6b5 2004-04-19 devnull After the read, as described above, the output point will be at
117 ba19f6b5 2004-04-19 devnull the beginning of the next line of text.
118 ba19f6b5 2004-04-19 devnull In normal circumstances, therefore, typed text is delivered
119 ba19f6b5 2004-04-19 devnull to programs a line at a time.
120 ba19f6b5 2004-04-19 devnull Changes made by typing or editing before the text is read will not
121 ba19f6b5 2004-04-19 devnull be seen by the program reading it.
122 ba19f6b5 2004-04-19 devnull Because of the Unix issues mentioned above, a line of text is only editable
123 ba19f6b5 2004-04-19 devnull until it is completed with a newline character, or when hold mode
124 ba19f6b5 2004-04-19 devnull (see below) is enabled.
126 ba19f6b5 2004-04-19 devnull Even when there are newlines in the output text,
127 ba19f6b5 2004-04-19 devnull .I 9term
128 ba19f6b5 2004-04-19 devnull will not honor reads if the window is in
130 ba19f6b5 2004-04-19 devnull .IR mode ,
131 ba19f6b5 2004-04-19 devnull which is indicated by a white cursor and blue text and border.
132 ba19f6b5 2004-04-19 devnull The ESC character toggles hold mode.
133 ba19f6b5 2004-04-19 devnull Some programs
134 ba19f6b5 2004-04-19 devnull automatically turn on hold mode to simplify the editing of multi-line text;
135 ba19f6b5 2004-04-19 devnull type ESC when done to allow
137 ba19f6b5 2004-04-19 devnull to read the text.
139 ba19f6b5 2004-04-19 devnull An EOT character (control-D) behaves exactly like newline except
140 ba19f6b5 2004-04-19 devnull that it is not delivered to a program when read.
141 ba19f6b5 2004-04-19 devnull Thus on an empty line an EOT serves to deliver an end-of-file indication:
142 ba19f6b5 2004-04-19 devnull the read will return zero characters.
143 c8b6342d 2005-01-13 devnull .\" Like newlines, unread EOTs may be successfully edited out of the text.
144 ba19f6b5 2004-04-19 devnull The BS character (control-H) erases the character before the selected text.
145 ba19f6b5 2004-04-19 devnull The ETB character (control-W) erases any nonalphanumeric characters, then
146 ba19f6b5 2004-04-19 devnull the alphanumeric word just before the selected text.
147 ba19f6b5 2004-04-19 devnull `Alphanumeric' here means non-blanks and non-punctuation.
148 ba19f6b5 2004-04-19 devnull The NAK character (control-U) erases the text after the output point,
149 ba19f6b5 2004-04-19 devnull and not yet read by a program, but not more than one line.
150 ba19f6b5 2004-04-19 devnull All these characters are typed on the keyboard and hence replace
151 ba19f6b5 2004-04-19 devnull the selected text; for example, typing a BS with a word selected
152 ba19f6b5 2004-04-19 devnull places the word in the snarf buffer, removes it from the screen,
153 ba19f6b5 2004-04-19 devnull and erases the character before the word.
155 ba19f6b5 2004-04-19 devnull An ACK character (control-F) or Insert character triggers file name completion
156 ba19f6b5 2004-04-19 devnull for the preceding string (see
157 ba19f6b5 2004-04-19 devnull .IR complete (3)).
159 ba19f6b5 2004-04-19 devnull Text may be moved vertically within the window.
160 ba19f6b5 2004-04-19 devnull A scroll bar on the left of the window shows in its clear portion what fragment of the
161 ba19f6b5 2004-04-19 devnull total output text is visible on the screen, and in its gray part what
162 ba19f6b5 2004-04-19 devnull is above or below view;
163 ba19f6b5 2004-04-19 devnull it measures characters, not lines.
164 ba19f6b5 2004-04-19 devnull Mousing inside the scroll bar moves text:
165 ba19f6b5 2004-04-19 devnull clicking button 1 with the mouse pointing inside the scroll bar
166 ba19f6b5 2004-04-19 devnull brings the line at the top of the
167 ba19f6b5 2004-04-19 devnull window to the cursor's vertical location;
168 ba19f6b5 2004-04-19 devnull button 3 takes the line at the cursor to the top of the window;
169 ba19f6b5 2004-04-19 devnull button 2, treating the scroll bar as a ruler, jumps to the indicated portion
170 ba19f6b5 2004-04-19 devnull of the stored text.
171 ba19f6b5 2004-04-19 devnull Holding a button pressed in the scroll bar will cause the text
172 ba19f6b5 2004-04-19 devnull to scroll continuously until the button is released.
174 ba19f6b5 2004-04-19 devnull Typing down-arrow scrolls forward
175 ba19f6b5 2004-04-19 devnull one third of a window, and up-arrow scrolls back.
176 ba19f6b5 2004-04-19 devnull Typing page-down scrolls forward
177 ba19f6b5 2004-04-19 devnull two thirds of a window, and page-up scrolls back.
178 ba19f6b5 2004-04-19 devnull Typing Home scrolls to the top of the window;
179 ba19f6b5 2004-04-19 devnull typing End scrolls to the end.
181 ba19f6b5 2004-04-19 devnull The DEL character sends an
182 ba19f6b5 2004-04-19 devnull .L interrupt
183 ba19f6b5 2004-04-19 devnull note to all processes in the window's process group.
184 ba19f6b5 2004-04-19 devnull Unlike the other characters, the DEL and arrow
185 ba19f6b5 2004-04-19 devnull keys do not affect the selected text.
186 ba19f6b5 2004-04-19 devnull The left (right) arrow key moves the selection to one character
187 ba19f6b5 2004-04-19 devnull before (after) the current selection.
189 ba19f6b5 2004-04-19 devnull .I 9term
190 ba19f6b5 2004-04-19 devnull relies on the kernel's terminal processing to handle
191 ba19f6b5 2004-04-19 devnull EOT and DEL, so the terminal must be set up with EOT
192 ba19f6b5 2004-04-19 devnull as the ``eof'' character and DEL as the ``intr'' character.
193 c8b6342d 2005-01-13 devnull .I 9term
195 c8b6342d 2005-01-13 devnull .IR stty (1)
196 c8b6342d 2005-01-13 devnull to establish this when the terminal is created.
198 ba19f6b5 2004-04-19 devnull Normally, written output to a window blocks when
199 ba19f6b5 2004-04-19 devnull the text reaches the end of the screen and the terminal
200 ba19f6b5 2004-04-19 devnull buffer fills;
201 ba19f6b5 2004-04-19 devnull a button 2 menu item toggles scrolling.
203 ba19f6b5 2004-04-19 devnull .I 9term
204 ba19f6b5 2004-04-19 devnull changes behavior according to
205 ba19f6b5 2004-04-19 devnull the terminal settings of the running programs.
206 ba19f6b5 2004-04-19 devnull Most programs run with echo enabled.
207 ba19f6b5 2004-04-19 devnull In this mode,
208 ba19f6b5 2004-04-19 devnull .I 9term
209 c8b6342d 2005-01-13 devnull displays and allows editing of the input.
210 ba19f6b5 2004-04-19 devnull Some programs, typically those reading passwords,
211 ba19f6b5 2004-04-19 devnull run with echo disabled.
212 ba19f6b5 2004-04-19 devnull In this mode,
213 ba19f6b5 2004-04-19 devnull .I 9term
214 ba19f6b5 2004-04-19 devnull passes keystrokes through directly, without
215 ba19f6b5 2004-04-19 devnull echoing them or buffering until a newline character.
216 ba19f6b5 2004-04-19 devnull These heuristics work well in many cases, but there
217 ba19f6b5 2004-04-19 devnull are a few common ones where they fall short.
218 ba19f6b5 2004-04-19 devnull First, programs using the GNU readline library typically
219 ba19f6b5 2004-04-19 devnull disable terminal echo and perform echoing themselves.
220 ba19f6b5 2004-04-19 devnull The most common example is the shell
221 ba19f6b5 2004-04-19 devnull .IR bash (1).
222 ba19f6b5 2004-04-19 devnull Disabling the use of readline with
223 ba19f6b5 2004-04-19 devnull .RB `` "set +o emacs" ''
224 ba19f6b5 2004-04-19 devnull .RI [ sic ]
225 ba19f6b5 2004-04-19 devnull usually restores the desired behavior.
226 ba19f6b5 2004-04-19 devnull Second, remote terminal programs such as
227 ba19f6b5 2004-04-19 devnull .IR ssh (1)
228 ba19f6b5 2004-04-19 devnull typically run with echo disabled, relying on the
229 ba19f6b5 2004-04-19 devnull remote system to echo characters as desired.
230 ba19f6b5 2004-04-19 devnull Plan 9's
234 ba19f6b5 2004-04-19 devnull flag to disable this, leaving the terminal in ``cooked'' mode.
235 ba19f6b5 2004-04-19 devnull For similar situations on Unix,
236 ba19f6b5 2004-04-19 devnull .IR 9term 's
237 ba19f6b5 2004-04-19 devnull button 2 menu has an entry to toggle the forced use of
238 ba19f6b5 2004-04-19 devnull cooked mode, despite the terminal settings.
239 ba19f6b5 2004-04-19 devnull In such cases, it is useful to run
240 ba19f6b5 2004-04-19 devnull .RB `` "stty -echo" ''
241 ba19f6b5 2004-04-19 devnull on the remote system to avoid seeing your input twice.
243 ba19f6b5 2004-04-19 devnull Editing operations are selected from a menu on button 2.
246 ba19f6b5 2004-04-19 devnull operation deletes the selected text
247 ba19f6b5 2004-04-19 devnull from the screen and puts it in the snarf buffer;
248 ba19f6b5 2004-04-19 devnull .B snarf
249 ba19f6b5 2004-04-19 devnull copies the selected text to the buffer without deleting it;
250 ba19f6b5 2004-04-19 devnull .B paste
251 ba19f6b5 2004-04-19 devnull replaces the selected text with the contents of the buffer;
254 ba19f6b5 2004-04-19 devnull copies the snarf buffer to just after the output point, adding a final newline
255 ba19f6b5 2004-04-19 devnull if missing.
256 ba19f6b5 2004-04-19 devnull .B Paste
257 ba19f6b5 2004-04-19 devnull will sometimes and
259 ba19f6b5 2004-04-19 devnull will always place text after the output point; the text so placed
260 ba19f6b5 2004-04-19 devnull will behave exactly as described above. Therefore when pasting
261 ba19f6b5 2004-04-19 devnull text containing newlines after the output point, it may be prudent
262 ba19f6b5 2004-04-19 devnull to turn on hold mode first.
265 ba19f6b5 2004-04-19 devnull .B plumb
266 ba19f6b5 2004-04-19 devnull menu item sends the contents of the selection (not the snarf buffer) to the
267 058b0118 2005-01-03 devnull .I plumber
269 058b0118 2005-01-03 devnull .IR plumb (1)).
270 ba19f6b5 2004-04-19 devnull If the selection is empty, it sends the white-space-delimited text
271 ba19f6b5 2004-04-19 devnull containing the selection (typing cursor).
272 ba19f6b5 2004-04-19 devnull A typical use of this feature is to tell the editor to find the source of an error
273 ba19f6b5 2004-04-19 devnull by plumbing the file and line information in a compiler's diagnostic.
276 c8b6342d 2005-01-13 devnull .I 9term
277 c8b6342d 2005-01-13 devnull listens for connections on a Unix socket.
278 c8b6342d 2005-01-13 devnull When a client connects, the
279 c8b6342d 2005-01-13 devnull .I 9term
280 c8b6342d 2005-01-13 devnull writes the window contents to the client and then hangs up.
281 c8b6342d 2005-01-13 devnull .I 9term
282 c8b6342d 2005-01-13 devnull installs the name of this socket in the environment as
283 c8b6342d 2005-01-13 devnull .B $text9term
284 c8b6342d 2005-01-13 devnull before running
285 c8b6342d 2005-01-13 devnull .IR cmd .
286 ba19f6b5 2004-04-19 devnull .SH SOURCE
287 c3674de4 2005-01-11 devnull .B \*9/src/cmd/9term
288 ba19f6b5 2004-04-19 devnull .SH BUGS
289 ba19f6b5 2004-04-19 devnull There should be a program to toggle the current window's hold mode.
292 76164c00 2005-02-08 devnull .IR 9term
294 76164c00 2005-02-08 devnull when running
295 76164c00 2005-02-08 devnull .IR bash (1)
297 76164c00 2005-02-08 devnull .RB `` "set +o emacs" ''
298 76164c00 2005-02-08 devnull mode, its handling of interrupts is broken.
299 76164c00 2005-02-08 devnull In response to DEL,
301 76164c00 2005-02-08 devnull processes the interrupt but then silently discards the next
302 76164c00 2005-02-08 devnull character typed.
304 ba19f6b5 2004-04-19 devnull Unix makes everything harder.
305 c8b6342d 2005-01-13 devnull .SH SEE ALSO
306 c8b6342d 2005-01-13 devnull .IR wintext (1)
