pterm(1) PuTTY tool suite pterm(1)

NAME

pterm - yet another X terminal emulator

SYNOPSIS

pterm [ options ]

DESCRIPTION

pterm is a terminal emulator for X. It is based on a port of the
terminal emulation engine in the Windows SSH client PuTTY.

OPTIONS

The command-line options supported by pterm are:

-e command [ arguments ]
Specify a command to be executed in the new terminal.
Everything on the command line after this option will be
passed straight to the execvp system call; so if you need the
command to redirect its input or output, you will have to use
sh:

pterm -e sh -c 'mycommand < inputfile'

--display display-name
Specify the X display on which to open pterm. (Note this
option has a double minus sign, even though none of the others
do. This is because this option is supplied automatically by
GTK. Sorry.)

-name name
Specify the name under which pterm looks up X resources.
Normally it will look them up as (for example) pterm.Font. If
you specify `-name xyz', it will look them up as xyz.Font
instead. This allows you to set up several different sets of
defaults and choose between them.

-fn font-name
Specify the font to use for normal text displayed in the
terminal. For example, -fn fixed, -fn "Monospace 12".

-fb font-name
Specify the font to use for bold text displayed in the
terminal. If the BoldAsColour resource is set to 1 (the
default), bold text will be displayed in different colours
instead of a different font, so this option will be ignored.
If BoldAsColour is set to 0 or 2 and you do not specify a bold
font, pterm will overprint the normal font to make it look
bolder.

-fw font-name
Specify the font to use for double-width characters (typically
Chinese, Japanese and Korean text) displayed in the terminal.

-fwb font-name
Specify the font to use for bold double-width characters
(typically Chinese, Japanese and Korean text). Like -fb, this
will be ignored unless the BoldAsColour resource is set to 0
or 2.

-geometry geometry
Specify the size of the terminal, in rows and columns of text.
See X(7) for more information on the syntax of geometry
specifications.

-sl lines
Specify the number of lines of scrollback to save off the top
of the terminal.

-fg colour
Specify the foreground colour to use for normal text.

-bg colour
Specify the background colour to use for normal text.

-bfg colour
Specify the foreground colour to use for bold text, if the
BoldAsColour resource is set to 1 (the default) or 2.

-bbg colour
Specify the foreground colour to use for bold reverse-video
text, if the BoldAsColour resource is set to 1 (the default)
or 2. (This colour is best thought of as the bold version of
the background colour; so it only appears when text is
displayed in the background colour.)

-cfg colour
Specify the foreground colour to use for text covered by the
cursor.

-cbg colour
Specify the background colour to use for text covered by the
cursor. In other words, this is the main colour of the cursor.

-title title
Specify the initial title of the terminal window. (This can be
changed under control of the server.)

-ut- or +ut
Tells pterm not to record your login in the utmp, wtmp and
lastlog system log files; so you will not show up on finger or
who listings, for example.

-ut Tells pterm to record your login in utmp, wtmp and lastlog:
this is the opposite of -ut-. This is the default option: you
will probably only need to specify it explicitly if you have
changed the default using the StampUtmp resource.

-ls- or +ls
Tells pterm not to execute your shell as a login shell.

-ls Tells pterm to execute your shell as a login shell: this is
the opposite of -ls-. This is the default option: you will
probably only need to specify it explicitly if you have
changed the default using the LoginShell resource.

-sb- or +sb
Tells pterm not to display a scroll bar.

-sb Tells pterm to display a scroll bar: this is the opposite of
-sb-. This is the default option: you will probably only need
to specify it explicitly if you have changed the default using
the ScrollBar resource.

-log logfile, -sessionlog logfile
This option makes pterm log all the terminal output to a file
as well as displaying it in the terminal.

-cs charset
This option specifies the character set in which pterm should
assume the session is operating. This character set will be
used to interpret all the data received from the session, and
all input you type or paste into pterm will be converted into
this character set before being sent to the session.

Any character set name which is valid in a MIME header (and
supported by pterm) should be valid here (examples are
`ISO-8859-1', `windows-1252' or `UTF-8'). Also, any character
encoding which is valid in an X logical font description
should be valid (`ibm-cp437', for example).

pterm's default behaviour is to use the same character
encoding as its primary font. If you supply a Unicode
(iso10646-1) font, it will default to the UTF-8 character set.

Character set names are case-insensitive.

-nethack
Tells pterm to enable NetHack keypad mode, in which the
numeric keypad generates the NetHack hjklyubn direction keys.
This enables you to play NetHack with the numeric keypad
without having to use the NetHack number_pad option (which
requires you to press `n' before any repeat count). So you can
move with the numeric keypad, and enter repeat counts with the
normal number keys.

-xrm resource-string
This option specifies an X resource string. Useful for setting
resources which do not have their own command-line options.
For example:

pterm -xrm 'ScrollbarOnLeft: 1'

-help, --help
Display a message summarizing the available options.

-pgpfp Display the fingerprints of the PuTTY PGP Master Keys, to aid
in verifying new files released by the PuTTY team.

X RESOURCES

pterm can be more completely configured by means of X resources. All
of these resources are of the form pterm.FOO for some FOO; you can
make pterm look them up under another name, such as xyz.FOO, by
specifying the command-line option `-name xyz'.

pterm.CloseOnExit
This option should be set to 0, 1 or 2; the default is 2. It
controls what pterm does when the process running inside it
terminates. When set to 2 (the default), pterm will close its
window as soon as the process inside it terminates. When set
to 0, pterm will print the process's exit status, and the
window will remain present until a key is pressed (allowing
you to inspect the scrollback, and copy and paste text out of
it).

When this setting is set to 1, pterm will close immediately if
the process exits cleanly (with an exit status of zero), but
the window will stay around if the process exits with a non-
zero code or on a signal. This enables you to see what went
wrong if the process suffers an error, but not to have to
bother closing the window in normal circumstances.

pterm.WarnOnClose
This option should be set to either 0 or 1; the default is 1.
When set to 1, pterm will ask for confirmation before closing
its window when you press the close button.

pterm.TerminalType
This controls the value set in the TERM environment variable
inside the new terminal. The default is `xterm'.

pterm.BackspaceIsDelete
This option should be set to either 0 or 1; the default is 1.
When set to 0, the ordinary Backspace key generates the
Backspace character (^H); when set to 1, it generates the
Delete character (^?). Whichever one you set, the terminal
device inside pterm will be set up to expect it.

pterm.RXVTHomeEnd
This option should be set to either 0 or 1; the default is 0.
When it is set to 1, the Home and End keys generate the
control sequences they would generate in the rxvt terminal
emulator, instead of the more usual ones generated by other
emulators.

pterm.LinuxFunctionKeys
This option can be set to any number between 0 and 5
inclusive; the default is 0. The modes vary the control
sequences sent by the function keys; for more complete
documentation, it is probably simplest to try each option in
`pterm -e cat', and press the keys to see what they generate.

pterm.NoApplicationKeys
This option should be set to either 0 or 1; the default is 0.
When set to 1, it stops the server from ever switching the
numeric keypad into application mode (where the keys send
function-key-like sequences instead of numbers or arrow keys).
You probably only need this if some application is making a
nuisance of itself.

pterm.NoApplicationCursors
This option should be set to either 0 or 1; the default is 0.
When set to 1, it stops the server from ever switching the
cursor keys into application mode (where the keys send
slightly different sequences). You probably only need this if
some application is making a nuisance of itself.

pterm.NoMouseReporting
This option should be set to either 0 or 1; the default is 0.
When set to 1, it stops the server from ever enabling mouse
reporting mode (where mouse clicks are sent to the application
instead of controlling cut and paste).

pterm.NoRemoteResize
This option should be set to either 0 or 1; the default is 0.
When set to 1, it stops the server from being able to remotely
control the size of the pterm window.

pterm.NoAltScreen
This option should be set to either 0 or 1; the default is 0.
When set to 1, it stops the server from using the `alternate
screen' terminal feature, which lets full-screen applications
leave the screen exactly the way they found it.

pterm.NoRemoteWinTitle
This option should be set to either 0 or 1; the default is 0.
When set to 1, it stops the server from remotely controlling
the title of the pterm window.

pterm.NoRemoteQTitle
This option should be set to either 0 or 1; the default is 1.
When set to 1, it stops the server from remotely requesting
the title of the pterm window.

This feature is a POTENTIAL SECURITY HAZARD. If a malicious
application can write data to your terminal (for example, if
you merely cat a file owned by someone else on the server
machine), it can change your window title (unless you have
disabled this using the NoRemoteWinTitle resource) and then
use this service to have the new window title sent back to the
server as if typed at the keyboard. This allows an attacker to
fake keypresses and potentially cause your server-side
applications to do things you didn't want. Therefore this
feature is disabled by default, and we recommend you do not
turn it on unless you really know what you are doing.

pterm.NoDBackspace
This option should be set to either 0 or 1; the default is 0.
When set to 1, it disables the normal action of the Delete
(^?) character when sent from the server to the terminal,
which is to move the cursor left by one space and erase the
character now under it.

pterm.ApplicationCursorKeys
This option should be set to either 0 or 1; the default is 0.
When set to 1, the default initial state of the cursor keys
are application mode (where the keys send function-key-like
sequences instead of numbers or arrow keys). When set to 0,
the default state is the normal one.

pterm.ApplicationKeypad
This option should be set to either 0 or 1; the default is 0.
When set to 1, the default initial state of the numeric keypad
is application mode (where the keys send function-key-like
sequences instead of numbers or arrow keys). When set to 0,
the default state is the normal one.

pterm.NetHackKeypad
This option should be set to either 0 or 1; the default is 0.
When set to 1, the numeric keypad operates in NetHack mode.
This is equivalent to the -nethack command-line option.

pterm.Answerback
This option controls the string which the terminal sends in
response to receiving the ^E character (`tell me about
yourself'). By default this string is `PuTTY'.

pterm.HideMousePtr
This option should be set to either 0 or 1; the default is 0.
When it is set to 1, the mouse pointer will disappear if it is
over the pterm window and you press a key. It will reappear as
soon as you move it.

pterm.WindowBorder
This option controls the number of pixels of space between the
text in the pterm window and the window frame. The default is
1. You can increase this value, but decreasing it to 0 is not
recommended because it can cause the window manager's size
hints to work incorrectly.

pterm.CurType
This option should be set to either 0, 1 or 2; the default is
0. When set to 0, the text cursor displayed in the window is a
rectangular block. When set to 1, the cursor is an underline;
when set to 2, it is a vertical line.

pterm.BlinkCur
This option should be set to either 0 or 1; the default is 0.
When it is set to 1, the text cursor will blink when the
window is active.

pterm.Beep
This option should be set to either 0 or 2 (yes, 2); the
default is 0. When it is set to 2, pterm will respond to a
bell character (^G) by flashing the window instead of beeping.

pterm.BellOverload
This option should be set to either 0 or 1; the default is 0.
When it is set to 1, pterm will watch out for large numbers of
bells arriving in a short time and will temporarily disable
the bell until they stop. The idea is that if you cat a binary
file, the frantic beeping will mostly be silenced by this
feature and will not drive you crazy.

The bell overload mode is activated by receiving N bells in
time T; after a further time S without any bells, overload
mode will turn itself off again.

Bell overload mode is always deactivated by any keypress in
the terminal. This means it can respond to large unexpected
streams of data, but does not interfere with ordinary command-
line activities that generate beeps (such as filename
completion).

pterm.BellOverloadN
This option counts the number of bell characters which will
activate bell overload if they are received within a length of
time T. The default is 5.

pterm.BellOverloadT
This option specifies the time period in which receiving N or
more bells will activate bell overload mode. It is measured in
microseconds, so (for example) set it to 1000000 for one
second. The default is 2000000 (two seconds).

pterm.BellOverloadS
This option specifies the time period of silence required to
turn off bell overload mode. It is measured in microseconds,
so (for example) set it to 1000000 for one second. The default
is 5000000 (five seconds of silence).

pterm.ScrollbackLines
This option specifies how many lines of scrollback to save
above the visible terminal screen. The default is 200. This
resource is equivalent to the -sl command-line option.

pterm.DECOriginMode
This option should be set to either 0 or 1; the default is 0.
It specifies the default state of DEC Origin Mode. (If you
don't know what that means, you probably don't need to mess
with it.)

pterm.AutoWrapMode
This option should be set to either 0 or 1; the default is 1.
It specifies the default state of auto wrap mode. When set to
1, very long lines will wrap over to the next line on the
terminal; when set to 0, long lines will be squashed against
the right-hand edge of the screen.

pterm.LFImpliesCR
This option should be set to either 0 or 1; the default is 0.
When set to 1, the terminal will return the cursor to the left
side of the screen when it receives a line feed character.

pterm.WinTitle
This resource is the same as the -T command-line option: it
controls the initial title of the window. The default is
`pterm'.

pterm.TermWidth
This resource is the same as the width part of the -geometry
command-line option: it controls the number of columns of text
in the window. The default is 80.

pterm.TermHeight
This resource is the same as the width part of the -geometry
command-line option: it controls the number of columns of text
in the window. The defaults is 24.

pterm.Font
This resource is the same as the -fn command-line option: it
controls the font used to display normal text. The default is
`fixed'.

pterm.BoldFont
This resource is the same as the -fb command-line option: it
controls the font used to display bold text when BoldAsColour
is set to 0 or 2. The default is unset (the font will be
bolded by printing it twice at a one-pixel offset).

pterm.WideFont
This resource is the same as the -fw command-line option: it
controls the font used to display double-width characters. The
default is unset (double-width characters cannot be
displayed).

pterm.WideBoldFont
This resource is the same as the -fwb command-line option: it
controls the font used to display double-width characters in
bold, when BoldAsColour is set to 0 or 2. The default is unset
(double-width characters are displayed in bold by printing
them twice at a one-pixel offset).

pterm.ShadowBoldOffset
This resource can be set to an integer; the default is -1. It
specifies the offset at which text is overprinted when using
`shadow bold' mode. The default (1) means that the text will
be printed in the normal place, and also one character to the
right; this seems to work well for most X bitmap fonts, which
have a blank line of pixels down the right-hand side. For some
fonts, you may need to set this to -1, so that the text is
overprinted one pixel to the left; for really large fonts, you
may want to set it higher than 1 (in one direction or the
other).

pterm.BoldAsColour
This option should be set to either 0, 1, or 2; the default is
1. It specifies how bold text should be displayed. When set to
1, bold text is shown by displaying it in a brighter colour;
when set to 0, bold text is shown by displaying it in a
heavier font; when set to 2, both effects happen at once (a
heavy font and a brighter colour).

pterm.Colour0, pterm.Colour1, ..., pterm.Colour21
These options control the various colours used to display text
in the pterm window. Each one should be specified as a triple
of decimal numbers giving red, green and blue values: so that
black is `0,0,0', white is `255,255,255', red is `255,0,0' and
so on.

Colours 0 and 1 specify the foreground colour and its bold
equivalent (the -fg and -bfg command-line options). Colours 2
and 3 specify the background colour and its bold equivalent
(the -bg and -bbg command-line options). Colours 4 and 5
specify the text and block colours used for the cursor (the
-cfg and -cbg command-line options). Each even number from 6
to 20 inclusive specifies the colour to be used for one of the
ANSI primary colour specifications (black, red, green, yellow,
blue, magenta, cyan, white, in that order); the odd numbers
from 7 to 21 inclusive specify the bold version of each
colour, in the same order. The defaults are:

pterm.Colour0: 187,187,187
pterm.Colour1: 255,255,255
pterm.Colour2: 0,0,0
pterm.Colour3: 85,85,85
pterm.Colour4: 0,0,0
pterm.Colour5: 0,255,0
pterm.Colour6: 0,0,0
pterm.Colour7: 85,85,85
pterm.Colour8: 187,0,0
pterm.Colour9: 255,85,85
pterm.Colour10: 0,187,0
pterm.Colour11: 85,255,85
pterm.Colour12: 187,187,0
pterm.Colour13: 255,255,85
pterm.Colour14: 0,0,187
pterm.Colour15: 85,85,255
pterm.Colour16: 187,0,187
pterm.Colour17: 255,85,255
pterm.Colour18: 0,187,187
pterm.Colour19: 85,255,255
pterm.Colour20: 187,187,187
pterm.Colour21: 255,255,255

pterm.RectSelect
This option should be set to either 0 or 1; the default is 0.
When set to 0, dragging the mouse over several lines selects
to the end of each line and from the beginning of the next;
when set to 1, dragging the mouse over several lines selects a
rectangular region. In each case, holding down Alt while
dragging gives the other behaviour.

pterm.MouseOverride
This option should be set to either 0 or 1; the default is 1.
When set to 1, if the application requests mouse tracking (so
that mouse clicks are sent to it instead of doing selection),
holding down Shift will revert the mouse to normal selection.
When set to 0, mouse tracking completely disables selection.

pterm.Printer
This option is unset by default. If you set it, then server-
controlled printing is enabled: the server can send control
sequences to request data to be sent to a printer. That data
will be piped into the command you specify here; so you might
want to set it to `lpr', for example, or `lpr -Pmyprinter'.

pterm.ScrollBar
This option should be set to either 0 or 1; the default is 1.
When set to 0, the scrollbar is hidden (although Shift-PageUp
and Shift-PageDown still work). This is the same as the -sb
command-line option.

pterm.ScrollbarOnLeft
This option should be set to either 0 or 1; the default is 0.
When set to 1, the scrollbar will be displayed on the left of
the terminal instead of on the right.

pterm.ScrollOnKey
This option should be set to either 0 or 1; the default is 0.
When set to 1, any keypress causes the position of the
scrollback to be reset to the very bottom.

pterm.ScrollOnDisp
This option should be set to either 0 or 1; the default is 1.
When set to 1, any activity in the display causes the position
of the scrollback to be reset to the very bottom.

pterm.LineCodePage
This option specifies the character set to be used for the
session. This is the same as the -cs command-line option.

pterm.NoRemoteCharset
This option disables the terminal's ability to change its
character set when it receives escape sequences telling it to.
You might need to do this to interoperate with programs which
incorrectly change the character set to something they think
is sensible.

pterm.BCE
This option should be set to either 0 or 1; the default is 1.
When set to 1, the various control sequences that erase parts
of the terminal display will erase in whatever the current
background colour is; when set to 0, they will erase in black
always.

pterm.BlinkText
This option should be set to either 0 or 1; the default is 0.
When set to 1, text specified as blinking by the server will
actually blink on and off; when set to 0, pterm will use the
less distracting approach of making the text's background
colour bold.

pterm.StampUtmp
This option should be set to either 0 or 1; the default is 1.
When set to 1, pterm will log the login in the various system
log files. This resource is equivalent to the -ut command-line
option.

pterm.LoginShell
This option should be set to either 0 or 1; the default is 1.
When set to 1, pterm will execute your shell as a login shell.
This resource is equivalent to the -ls command-line option.

BUGS

Most of the X resources have silly names. (Historical reasons from
PuTTY, mostly.)

PuTTY tool suite 2004-03-24 pterm(1)