1 \cfg{man-identity}{pterm}{1}{2004-03-24}{PuTTY tool suite}{PuTTY tool suite}
3 \H{pterm-manpage} Man page for pterm
5 \S{pterm-manpage-name} NAME
7 pterm \- yet another X terminal emulator
9 \S{pterm-manpage-synopsis} SYNOPSIS
14 \S{pterm-manpage-description} DESCRIPTION
16 \cw{pterm} is a terminal emulator for X. It is based on a port of
17 the terminal emulation engine in the Windows SSH client PuTTY.
19 \S{pterm-manpage-options} OPTIONS
21 The command-line options supported by \cw{pterm} are:
23 \dt \cw{\-e} \e{command} [ \e{arguments} ]
25 \dd Specify a command to be executed in the new terminal. Everything on
26 the command line after this option will be passed straight to the
27 \cw{execvp} system call; so if you need the command to redirect its
28 input or output, you will have to use \cw{sh}:
32 \c pterm -e sh -c 'mycommand < inputfile'
36 \dt \cw{\-\-display} \e{display\-name}
38 \dd Specify the X display on which to open \cw{pterm}. (Note this
39 option has a double minus sign, even though none of the others do.
40 This is because this option is supplied automatically by GTK.
43 \dt \cw{\-name} \e{name}
45 \dd Specify the name under which \cw{pterm} looks up X resources.
46 Normally it will look them up as (for example) \cw{pterm.Font}. If
47 you specify \q{\cw{\-name xyz}}, it will look them up as
48 \cw{xyz.Font} instead. This allows you to set up several different
49 sets of defaults and choose between them.
51 \dt \cw{\-fn} \e{font-name}
53 \dd Specify the font to use for normal text displayed in the terminal.
55 \dt \cw{\-fb} \e{font-name}
57 \dd Specify the font to use for bold text displayed in the terminal. If
58 the \cw{BoldAsColour} resource is set to 1 (the default), bold text
59 will be displayed in different colours instead of a different font,
60 so this option will be ignored. If \cw{BoldAsColour} is set to 0 or 2
61 and you do not specify a bold font, \cw{pterm} will overprint the
62 normal font to make it look bolder.
64 \dt \cw{\-fw} \e{font-name}
66 \dd Specify the font to use for double-width characters (typically
67 Chinese, Japanese and Korean text) displayed in the terminal.
69 \dt \cw{\-fwb} \e{font-name}
71 \dd Specify the font to use for bold double-width characters
72 (typically Chinese, Japanese and Korean text). Like \cw{-fb}, this
73 will be ignored unless the \cw{BoldAsColour} resource is set to 0 or 2.
75 \dt \cw{\-geometry} \e{geometry}
77 \dd Specify the size of the terminal, in rows and columns of text. See
78 \e{X(7)} for more information on the syntax of geometry
81 \dt \cw{\-sl} \e{lines}
83 \dd Specify the number of lines of scrollback to save off the top of the
86 \dt \cw{\-fg} \e{colour}
88 \dd Specify the foreground colour to use for normal text.
90 \dt \cw{\-bg} \e{colour}
92 \dd Specify the background colour to use for normal text.
94 \dt \cw{\-bfg} \e{colour}
96 \dd Specify the foreground colour to use for bold text, if the
97 \cw{BoldAsColour} resource is set to 1 (the default) or 2.
99 \dt \cw{\-bbg} \e{colour}
101 \dd Specify the foreground colour to use for bold reverse-video text, if
102 the \cw{BoldAsColour} resource is set to 1 (the default) or 2. (This
103 colour is best thought of as the bold version of the background
104 colour; so it only appears when text is displayed \e{in} the
107 \dt \cw{\-cfg} \e{colour}
109 \dd Specify the foreground colour to use for text covered by the cursor.
111 \dt \cw{\-cbg} \e{colour}
113 \dd Specify the background colour to use for text covered by the cursor.
114 In other words, this is the main colour of the cursor.
116 \dt \cw{\-title} \e{title}
118 \dd Specify the initial title of the terminal window. (This can be
119 changed under control of the server.)
121 \dt \cw{\-ut\-} or \cw{+ut}
123 \dd Tells \cw{pterm} not to record your login in the \cw{utmp},
124 \cw{wtmp} and \cw{lastlog} system log files; so you will not show
125 up on \cw{finger} or \cw{who} listings, for example.
129 \dd Tells \cw{pterm} to record your login in \cw{utmp}, \cw{wtmp} and
130 \cw{lastlog}: this is the opposite of \cw{\-ut\-}. This is the
131 default option: you will probably only need to specify it explicitly
132 if you have changed the default using the \cw{StampUtmp} resource.
134 \dt \cw{\-ls\-} or \cw{+ls}
136 \dd Tells \cw{pterm} not to execute your shell as a login shell.
140 \dd Tells \cw{pterm} to execute your shell as a login shell: this is
141 the opposite of \cw{\-ls\-}. This is the default option: you will
142 probably only need to specify it explicitly if you have changed the
143 default using the \cw{LoginShell} resource.
145 \dt \cw{\-sb\-} or \cw{+sb}
147 \dd Tells \cw{pterm} not to display a scroll bar.
151 \dd Tells \cw{pterm} to display a scroll bar: this is the opposite of
152 \cw{\-sb\-}. This is the default option: you will probably only need
153 to specify it explicitly if you have changed the default using the
154 \cw{ScrollBar} resource.
156 \dt \cw{\-log} \e{filename}
158 \dd This option makes \cw{pterm} log all the terminal output to a file
159 as well as displaying it in the terminal.
161 \dt \cw{\-cs} \e{charset}
163 \dd This option specifies the character set in which \cw{pterm} should
164 assume the session is operating. This character set will be used to
165 interpret all the data received from the session, and all input you
166 type or paste into \cw{pterm} will be converted into this character
167 set before being sent to the session.
169 \lcont{ Any character set name which is valid in a MIME header (and
170 supported by \cw{pterm}) should be valid here (examples are
171 \q{\cw{ISO-8859-1}}, \q{\cw{windows-1252}} or \q{\cw{UTF-8}}). Also,
172 any character encoding which is valid in an X logical font
173 description should be valid (\q{\cw{ibm-cp437}}, for example).
175 \cw{pterm}'s default behaviour is to use the same character encoding
176 as its primary font. If you supply a Unicode (\cw{iso10646-1}) font,
177 it will default to the UTF-8 character set.
179 Character set names are case-insensitive.
184 \dd Tells \cw{pterm} to enable NetHack keypad mode, in which the
185 numeric keypad generates the NetHack \c{hjklyubn} direction keys.
186 This enables you to play NetHack with the numeric keypad without
187 having to use the NetHack \c{number_pad} option (which requires you
188 to press \q{\cw{n}} before any repeat count). So you can move with
189 the numeric keypad, and enter repeat counts with the normal number
192 \dt \cw{\-xrm} \e{resource-string}
194 \dd This option specifies an X resource string. Useful for setting
195 resources which do not have their own command-line options. For
200 \c pterm -xrm 'ScrollbarOnLeft: 1'
204 \dt \cw{\-help}, \cw{\-\-help}
206 \dd Display a message summarizing the available options.
210 \dd Display the fingerprints of the PuTTY PGP Master Keys, to aid
211 in verifying new files released by the PuTTY team.
213 \S{pterm-manpage-x-resources} X RESOURCES
215 \cw{pterm} can be more completely configured by means of X
216 resources. All of these resources are of the form \cw{pterm.FOO} for
217 some \cw{FOO}; you can make \cw{pterm} look them up under another
218 name, such as \cw{xyz.FOO}, by specifying the command-line option
221 \dt \cw{pterm.CloseOnExit}
223 \dd This option should be set to 0, 1 or 2; the default is 2. It
224 controls what \cw{pterm} does when the process running inside it
225 terminates. When set to 2 (the default), \cw{pterm} will close its
226 window as soon as the process inside it terminates. When set to 0,
227 \cw{pterm} will print the process's exit status, and the window
228 will remain present until a key is pressed (allowing you to inspect
229 the scrollback, and copy and paste text out of it).
233 When this setting is set to 1, \cw{pterm} will close
234 immediately if the process exits cleanly (with an exit status of
235 zero), but the window will stay around if the process exits with a
236 non-zero code or on a signal. This enables you to see what went
237 wrong if the process suffers an error, but not to have to bother
238 closing the window in normal circumstances.
242 \dt \cw{pterm.WarnOnClose}
244 \dd This option should be set to either 0 or 1; the default is 1.
245 When set to 1, \cw{pterm} will ask for confirmation before closing
246 its window when you press the close button.
248 \dt \cw{pterm.TerminalType}
250 \dd This controls the value set in the \cw{TERM} environment
251 variable inside the new terminal. The default is \q{\cw{xterm}}.
253 \dt \cw{pterm.BackspaceIsDelete}
255 \dd This option should be set to either 0 or 1; the default is 1.
256 When set to 0, the ordinary Backspace key generates the Backspace
257 character (\cw{^H}); when set to 1, it generates the Delete
258 character (\cw{^?}). Whichever one you set, the terminal device
259 inside \cw{pterm} will be set up to expect it.
261 \dt \cw{pterm.RXVTHomeEnd}
263 \dd This option should be set to either 0 or 1; the default is 0. When
264 it is set to 1, the Home and End keys generate the control sequences
265 they would generate in the \cw{rxvt} terminal emulator, instead of
266 the more usual ones generated by other emulators.
268 \dt \cw{pterm.LinuxFunctionKeys}
270 \dd This option can be set to any number between 0 and 5 inclusive;
271 the default is 0. The modes vary the control sequences sent by the
272 function keys; for more complete documentation, it is probably
273 simplest to try each option in \q{\cw{pterm \-e cat}}, and press the
274 keys to see what they generate.
276 \dt \cw{pterm.NoApplicationKeys}
278 \dd This option should be set to either 0 or 1; the default is 0. When
279 set to 1, it stops the server from ever switching the numeric keypad
280 into application mode (where the keys send function-key-like
281 sequences instead of numbers or arrow keys). You probably only need
282 this if some application is making a nuisance of itself.
284 \dt \cw{pterm.NoApplicationCursors}
286 \dd This option should be set to either 0 or 1; the default is 0. When
287 set to 1, it stops the server from ever switching the cursor keys
288 into application mode (where the keys send slightly different
289 sequences). You probably only need this if some application is
290 making a nuisance of itself.
292 \dt \cw{pterm.NoMouseReporting}
294 \dd This option should be set to either 0 or 1; the default is 0. When
295 set to 1, it stops the server from ever enabling mouse reporting
296 mode (where mouse clicks are sent to the application instead of
297 controlling cut and paste).
299 \dt \cw{pterm.NoRemoteResize}
301 \dd This option should be set to either 0 or 1; the default is 0. When
302 set to 1, it stops the server from being able to remotely control
303 the size of the \cw{pterm} window.
305 \dt \cw{pterm.NoAltScreen}
307 \dd This option should be set to either 0 or 1; the default is 0. When
308 set to 1, it stops the server from using the \q{alternate screen}
309 terminal feature, which lets full-screen applications leave the
310 screen exactly the way they found it.
312 \dt \cw{pterm.NoRemoteWinTitle}
314 \dd This option should be set to either 0 or 1; the default is 0. When
315 set to 1, it stops the server from remotely controlling the title of
316 the \cw{pterm} window.
318 \dt \cw{pterm.NoRemoteQTitle}
320 \dd This option should be set to either 0 or 1; the default is 1. When
321 set to 1, it stops the server from remotely requesting the title of
322 the \cw{pterm} window.
325 This feature is a \e{POTENTIAL SECURITY HAZARD}. If a malicious
326 application can write data to your terminal (for example, if you
327 merely \cw{cat} a file owned by someone else on the server
328 machine), it can change your window title (unless you have disabled
329 this using the \cw{NoRemoteWinTitle} resource) and then use this
330 service to have the new window title sent back to the server as if
331 typed at the keyboard. This allows an attacker to fake keypresses
332 and potentially cause your server-side applications to do things you
333 didn't want. Therefore this feature is disabled by default, and we
334 recommend you do not turn it on unless you \e{really} know what
338 \dt \cw{pterm.NoDBackspace}
340 \dd This option should be set to either 0 or 1; the default is 0.
341 When set to 1, it disables the normal action of the Delete (\cw{^?})
342 character when sent from the server to the terminal, which is to
343 move the cursor left by one space and erase the character now under
346 \dt \cw{pterm.ApplicationCursorKeys}
348 \dd This option should be set to either 0 or 1; the default is 0. When
349 set to 1, the default initial state of the cursor keys are
350 application mode (where the keys send function-key-like sequences
351 instead of numbers or arrow keys). When set to 0, the default state
354 \dt \cw{pterm.ApplicationKeypad}
356 \dd This option should be set to either 0 or 1; the default is 0. When
357 set to 1, the default initial state of the numeric keypad is
358 application mode (where the keys send function-key-like sequences
359 instead of numbers or arrow keys). When set to 0, the default state
362 \dt \cw{pterm.NetHackKeypad}
364 \dd This option should be set to either 0 or 1; the default is 0. When
365 set to 1, the numeric keypad operates in NetHack mode. This is
366 equivalent to the \cw{\-nethack} command-line option.
368 \dt \cw{pterm.Answerback}
370 \dd This option controls the string which the terminal sends in
371 response to receiving the \cw{^E} character (\q{tell me about
372 yourself}). By default this string is \q{\cw{PuTTY}}.
374 \dt \cw{pterm.HideMousePtr}
376 \dd This option should be set to either 0 or 1; the default is 0. When
377 it is set to 1, the mouse pointer will disappear if it is over the
378 \cw{pterm} window and you press a key. It will reappear as soon as
381 \dt \cw{pterm.WindowBorder}
383 \dd This option controls the number of pixels of space between the text
384 in the \cw{pterm} window and the window frame. The default is 1.
385 You can increase this value, but decreasing it to 0 is not
386 recommended because it can cause the window manager's size hints to
389 \dt \cw{pterm.CurType}
391 \dd This option should be set to either 0, 1 or 2; the default is 0.
392 When set to 0, the text cursor displayed in the window is a
393 rectangular block. When set to 1, the cursor is an underline; when
394 set to 2, it is a vertical line.
396 \dt \cw{pterm.BlinkCur}
398 \dd This option should be set to either 0 or 1; the default is 0. When
399 it is set to 1, the text cursor will blink when the window is active.
403 \dd This option should be set to either 0 or 2 (yes, 2); the default
404 is 0. When it is set to 2, \cw{pterm} will respond to a bell
405 character (\cw{^G}) by flashing the window instead of beeping.
407 \dt \cw{pterm.BellOverload}
409 \dd This option should be set to either 0 or 1; the default is 0. When
410 it is set to 1, \cw{pterm} will watch out for large numbers of
411 bells arriving in a short time and will temporarily disable the bell
412 until they stop. The idea is that if you \cw{cat} a binary file,
413 the frantic beeping will mostly be silenced by this feature and will
417 The bell overload mode is activated by receiving N bells in time T;
418 after a further time S without any bells, overload mode will turn
421 Bell overload mode is always deactivated by any keypress in the
422 terminal. This means it can respond to large unexpected streams of
423 data, but does not interfere with ordinary command-line activities
424 that generate beeps (such as filename completion).
427 \dt \cw{pterm.BellOverloadN}
429 \dd This option counts the number of bell characters which will activate
430 bell overload if they are received within a length of time T. The
433 \dt \cw{pterm.BellOverloadT}
435 \dd This option specifies the time period in which receiving N or more
436 bells will activate bell overload mode. It is measured in
437 microseconds, so (for example) set it to 1000000 for one second. The
438 default is 2000000 (two seconds).
440 \dt \cw{pterm.BellOverloadS}
442 \dd This option specifies the time period of silence required to turn
443 off bell overload mode. It is measured in microseconds, so (for
444 example) set it to 1000000 for one second. The default is 5000000
445 (five seconds of silence).
447 \dt \cw{pterm.ScrollbackLines}
449 \dd This option specifies how many lines of scrollback to save above the
450 visible terminal screen. The default is 200. This resource is
451 equivalent to the \cw{\-sl} command-line option.
453 \dt \cw{pterm.DECOriginMode}
455 \dd This option should be set to either 0 or 1; the default is 0. It
456 specifies the default state of DEC Origin Mode. (If you don't know
457 what that means, you probably don't need to mess with it.)
459 \dt \cw{pterm.AutoWrapMode}
461 \dd This option should be set to either 0 or 1; the default is 1. It
462 specifies the default state of auto wrap mode. When set to 1, very
463 long lines will wrap over to the next line on the terminal; when set
464 to 0, long lines will be squashed against the right-hand edge of the
467 \dt \cw{pterm.LFImpliesCR}
469 \dd This option should be set to either 0 or 1; the default is 0. When
470 set to 1, the terminal will return the cursor to the left side of
471 the screen when it receives a line feed character.
473 \dt \cw{pterm.WinTitle}
475 \dd This resource is the same as the \cw{\-T} command-line option:
476 it controls the initial title of the window. The default is
479 \dt \cw{pterm.TermWidth}
481 \dd This resource is the same as the width part of the \cw{\-geometry}
482 command-line option: it controls the number of columns of text in
483 the window. The default is 80.
485 \dt \cw{pterm.TermHeight}
487 \dd This resource is the same as the width part of the \cw{\-geometry}
488 command-line option: it controls the number of columns of text in
489 the window. The defaults is 24.
493 \dd This resource is the same as the \cw{\-fn} command-line option: it
494 controls the font used to display normal text. The default is
497 \dt \cw{pterm.BoldFont}
499 \dd This resource is the same as the \cw{\-fb} command-line option: it
500 controls the font used to display bold text when \cw{BoldAsColour}
501 is set to 0 or 2. The default is unset (the font will be bolded by
502 printing it twice at a one-pixel offset).
504 \dt \cw{pterm.WideFont}
506 \dd This resource is the same as the \cw{\-fw} command-line option: it
507 controls the font used to display double-width characters. The
508 default is unset (double-width characters cannot be displayed).
510 \dt \cw{pterm.WideBoldFont}
512 \dd This resource is the same as the \cw{\-fwb} command-line option: it
513 controls the font used to display double-width characters in bold,
514 when \cw{BoldAsColour} is set to 0 or 2. The default is unset
515 (double-width characters are displayed in bold by printing them
516 twice at a one-pixel offset).
518 \dt \cw{pterm.ShadowBoldOffset}
520 \dd This resource can be set to an integer; the default is \-1. It
521 specifies the offset at which text is overprinted when using
522 \q{shadow bold} mode. The default (1) means that the text will be
523 printed in the normal place, and also one character to the right;
524 this seems to work well for most X bitmap fonts, which have a blank
525 line of pixels down the right-hand side. For some fonts, you may
526 need to set this to \-1, so that the text is overprinted one pixel
527 to the left; for really large fonts, you may want to set it higher
528 than 1 (in one direction or the other).
530 \dt \cw{pterm.BoldAsColour}
532 \dd This option should be set to either 0, 1, or 2; the default is 1.
533 It specifies how bold text should be displayed. When set to 1, bold
534 text is shown by displaying it in a brighter colour; when set to 0,
535 bold text is shown by displaying it in a heavier font; when set to 2,
536 both effects happen at once (a heavy font \e{and} a brighter colour).
538 \dt \cw{pterm.Colour0}, \cw{pterm.Colour1}, ..., \cw{pterm.Colour21}
540 \dd These options control the various colours used to display text
541 in the \cw{pterm} window. Each one should be specified as a triple
542 of decimal numbers giving red, green and blue values: so that black
543 is \q{\cw{0,0,0}}, white is \q{\cw{255,255,255}}, red is
544 \q{\cw{255,0,0}} and so on.
548 Colours 0 and 1 specify the foreground colour and its bold
549 equivalent (the \cw{\-fg} and \cw{\-bfg} command-line options).
550 Colours 2 and 3 specify the background colour and its bold
551 equivalent (the \cw{\-bg} and \cw{\-bbg} command-line options).
552 Colours 4 and 5 specify the text and block colours used for the
553 cursor (the \cw{\-cfg} and \cw{\-cbg} command-line options). Each
554 even number from 6 to 20 inclusive specifies the colour to be used
555 for one of the ANSI primary colour specifications (black, red,
556 green, yellow, blue, magenta, cyan, white, in that order); the odd
557 numbers from 7 to 21 inclusive specify the bold version of each
558 colour, in the same order. The defaults are:
560 \c pterm.Colour0: 187,187,187
561 \c pterm.Colour1: 255,255,255
562 \c pterm.Colour2: 0,0,0
563 \c pterm.Colour3: 85,85,85
564 \c pterm.Colour4: 0,0,0
565 \c pterm.Colour5: 0,255,0
566 \c pterm.Colour6: 0,0,0
567 \c pterm.Colour7: 85,85,85
568 \c pterm.Colour8: 187,0,0
569 \c pterm.Colour9: 255,85,85
570 \c pterm.Colour10: 0,187,0
571 \c pterm.Colour11: 85,255,85
572 \c pterm.Colour12: 187,187,0
573 \c pterm.Colour13: 255,255,85
574 \c pterm.Colour14: 0,0,187
575 \c pterm.Colour15: 85,85,255
576 \c pterm.Colour16: 187,0,187
577 \c pterm.Colour17: 255,85,255
578 \c pterm.Colour18: 0,187,187
579 \c pterm.Colour19: 85,255,255
580 \c pterm.Colour20: 187,187,187
581 \c pterm.Colour21: 255,255,255
585 \dt \cw{pterm.RectSelect}
587 \dd This option should be set to either 0 or 1; the default is 0. When
588 set to 0, dragging the mouse over several lines selects to the end
589 of each line and from the beginning of the next; when set to 1,
590 dragging the mouse over several lines selects a rectangular region.
591 In each case, holding down Alt while dragging gives the other
594 \dt \cw{pterm.MouseOverride}
596 \dd This option should be set to either 0 or 1; the default is 1. When
597 set to 1, if the application requests mouse tracking (so that mouse
598 clicks are sent to it instead of doing selection), holding down
599 Shift will revert the mouse to normal selection. When set to 0,
600 mouse tracking completely disables selection.
602 \dt \cw{pterm.Printer}
604 \dd This option is unset by default. If you set it, then
605 server-controlled printing is enabled: the server can send control
606 sequences to request data to be sent to a printer. That data will be
607 piped into the command you specify here; so you might want to set it
608 to \q{\cw{lpr}}, for example, or \q{\cw{lpr \-Pmyprinter}}.
610 \dt \cw{pterm.ScrollBar}
612 \dd This option should be set to either 0 or 1; the default is 1. When
613 set to 0, the scrollbar is hidden (although Shift-PageUp and
614 Shift-PageDown still work). This is the same as the \cw{\-sb}
617 \dt \cw{pterm.ScrollbarOnLeft}
619 \dd This option should be set to either 0 or 1; the default is 0. When
620 set to 1, the scrollbar will be displayed on the left of the
621 terminal instead of on the right.
623 \dt \cw{pterm.ScrollOnKey}
625 \dd This option should be set to either 0 or 1; the default is 0. When
626 set to 1, any keypress causes the position of the scrollback to be
627 reset to the very bottom.
629 \dt \cw{pterm.ScrollOnDisp}
631 \dd This option should be set to either 0 or 1; the default is 1. When
632 set to 1, any activity in the display causes the position of the
633 scrollback to be reset to the very bottom.
635 \dt \cw{pterm.LineCodePage}
637 \dd This option specifies the character set to be used for the session.
638 This is the same as the \cw{\-cs} command-line option.
640 \dt \cw{pterm.NoRemoteCharset}
642 \dd This option disables the terminal's ability to change its character
643 set when it receives escape sequences telling it to. You might need
644 to do this to interoperate with programs which incorrectly change
645 the character set to something they think is sensible.
649 \dd This option should be set to either 0 or 1; the default is 1. When
650 set to 1, the various control sequences that erase parts of the
651 terminal display will erase in whatever the current background
652 colour is; when set to 0, they will erase in black always.
654 \dt \cw{pterm.BlinkText}
656 \dd This option should be set to either 0 or 1; the default is 0. When
657 set to 1, text specified as blinking by the server will actually
658 blink on and off; when set to 0, \cw{pterm} will use the less
659 distracting approach of making the text's background colour bold.
661 \dt \cw{pterm.StampUtmp}
663 \dd This option should be set to either 0 or 1; the default is 1. When
664 set to 1, \cw{pterm} will log the login in the various system log
665 files. This resource is equivalent to the \cw{\-ut} command-line
668 \dt \cw{pterm.LoginShell}
670 \dd This option should be set to either 0 or 1; the default is 1. When
671 set to 1, \cw{pterm} will execute your shell as a login shell. This
672 resource is equivalent to the \cw{\-ls} command-line option.
674 \S{pterm-manpage-bugs} BUGS
676 Most of the X resources have silly names. (Historical reasons from