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