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