pterm(1)

🌸 NAME 🌸

pterm — yet another X terminal emulator. This is the pterm(1) page from the PuTTY tool suite, and bestie, it’s giving useful terminal-emulator realness. 💅

✨ SYNOPSIS ✨

pterm [ options ]

🎀 DESCRIPTION 🎀

pterm is a terminal emulator for X. It’s based on a port of the terminal emulation engine in the Windows SSH client PuTTY. Iconic lineage, honestly. 🦋

💖 OPTIONS 💖

The command-line options supported by pterm are:

• -e command [ arguments ] — tells pterm to run a command in the new terminal. Everything on the command line after this option gets passed straight to the execvp system call; so if you need the command to redirect its input or output, you’ll have to use sh:

pterm -e sh -c 'mycommand < inputfile'

• --display display-name — specifies 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 — specifies 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 lets you set up several different sets of defaults and choose between them. ✨
• -fn font-name — specifies the font to use for normal text displayed in the terminal. For example, -fn fixed, -fn "Monospace 12".
• -fb font-name — specifies 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 — specifies the font to use for double-width characters (typically Chinese, Japanese and Korean text) displayed in the terminal.
• -fwb font-name — specifies 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 — specifies 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 — specifies the number of lines of scrollback to save off the top of the terminal.
• -fg colour — specifies the foreground colour to use for normal text.
• -bg colour — specifies the background colour to use for normal text.
• -bfg colour — specifies the foreground colour to use for bold text, if the BoldAsColour resource is set to 1 (the default) or 2.
• -bbg colour — specifies 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 — specifies the foreground colour to use for text covered by the cursor.
• -cbg colour — specifies the background colour to use for text covered by the cursor. In other words, this is the main colour of the cursor.
• -title title — specifies 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. Slay. 🎮
• -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

straightforward 0-or-1 situation, bestie — default is 0. flip it to 1 and the server can no longer remotely control the title of your pterm window. that's the whole thing 💅

pterm.NoRemoteQTitle

0 or 1 again, but heads up: the default here is 1. set to 1, it stops the server from remotely requesting the title of the pterm window.

⚠️ POTENTIAL SECURITY HAZARD — the page is literally yelling in caps and honestly? deserved. if a malicious application can write data to your terminal (like, you merely cat a file owned by someone else on the server machine 🙈), it can change your window title — unless you've disabled that using the NoRemoteWinTitle resource — and then use this service to have the new window title sent back to the server as if it was typed at the keyboard. that lets an attacker fake keypresses and potentially make your server-side applications do things you did not want. so this feature is disabled by default, and the page recommends you do not turn it on unless you really know what you're doing. fr fr, leave it alone. 🫶

pterm.NoDBackspace

0 or 1, default 0. set it to 1 and it disables the normal action of the Delete (^?) character when it's sent from the server to the terminal — which would normally move the cursor left by one space and erase the character now under it. gone. poof. 🦋

pterm.ApplicationCursorKeys

0 or 1, default 0. set it to 1 and the default initial state of the cursor keys is application mode (meaning those keys send function-key-like sequences instead of numbers or arrow keys). set it to 0 and the default state is the normal one. simple as ✨

pterm.ApplicationKeypad

0 or 1, default 0. same energy, but for the numeric keypad: 1 means the default initial state is application mode (keys send function-key-like sequences instead of numbers or arrow keys), 0 means the normal one.

pterm.NetHackKeypad

0 or 1, default 0. set it to 1 and the numeric keypad operates in NetHack mode. it's equivalent to the -nethack command-line option 🎮

pterm.Answerback

this one controls the string the terminal sends in response to receiving the ^E character (the "tell me about yourself" one). by default that string is PuTTY. iconic, no notes 👑

pterm.HideMousePtr

0 or 1, default 0. set it to 1 and the mouse pointer disappears if it's over the pterm window and you press a key — then it reappears as soon as you move it. peekaboo 🐭

pterm.WindowBorder

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

pterm.CurType

0, 1 or 2 — default is 0. pick your cursor fighter:

• 0 — rectangular block
• 1 — underline
• 2 — vertical line

pterm.BlinkCur

0 or 1, default 0. set it to 1 and the text cursor blinks when the window is active 💜

pterm.Beep

0 or 2 — yes, 2, the page is being so serious about that — and the default is 0. set it to 2 and pterm responds to a bell character (^G) by flashing the window instead of beeping. no beeps, just vibes ✨

pterm.BellOverload

0 or 1, default 0. set it to 1 and pterm watches out for large numbers of bells arriving in a short time and temporarily disables the bell until they stop. the idea? if you cat a binary file, the frantic beeping mostly gets silenced by this feature instead of driving 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 turns itself off again.

bell overload mode is always deactivated by any keypress in the terminal — which means it can respond to large unexpected streams of data without interfering with ordinary command-line activities that generate beeps (filename completion, looking at you 👀).

pterm.BellOverloadN

counts the number of bell characters which will activate bell overload if they're received within a length of time T. default is 5.

pterm.BellOverloadT

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

pterm.BellOverloadS

the time period of silence required to turn bell overload mode back off. also measured in microseconds, so like 1000000 for one second. default is 5000000 (five seconds of silence) 🤫

pterm.ScrollbackLines

how many lines of scrollback get saved above the visible terminal screen. default is 200. equivalent to the -sl command-line option.

pterm.DECOriginMode

0 or 1, default 0. specifies the default state of DEC Origin Mode. and in the page's own words: if you don't know what that means, you probably don't need to mess with it. honestly? respect 😭

pterm.AutoWrapMode

0 or 1, default 1. specifies the default state of auto wrap mode. set to 1, very long lines wrap over onto the next line on the terminal; set to 0, long lines get squashed against the right-hand edge of the screen. brutal but valid.

pterm.LFImpliesCR

0 or 1, default 0. set it to 1 and the terminal returns the cursor to the left side of the screen whenever it receives a line feed character ✨

pterm.WinTitle

same as the -T command-line option — it controls the initial title of the window. default is pterm 👑

pterm.TermWidth

same as the width part of the -geometry command-line option — it controls the number of columns of text in the window. default is 80.

pterm.TermHeight

the page says this is the same as the width part of the -geometry command-line option and that it controls the number of columns of text in the window — yes, that's literally what it says, I'm just the messenger 🙈 — and the default is 24.

pterm.Font

same as the -fn command-line option — it controls the font used to display normal text. default is fixed.

pterm.BoldFont

same as the -fb command-line option — it controls the font used to display bold text when BoldAsColour is set to 0 or 2. default is unset (the font will be bolded by printing it twice at a one-pixel offset). cute little hack tbh 💅

pterm.WideFont

same as the -fw command-line option — it controls the font used to display double-width characters. default is unset (double-width characters cannot be displayed). 💀

pterm.WideBoldFont

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. default is unset (double-width characters are displayed in bold by printing them twice at a one-pixel offset).

pterm.ShadowBoldOffset

settable to an integer; the page opens with "the default is -1" and then a couple lines later hits you with "the default (1)". yeah. both. iykyk 😭 it specifies the offset at which text is overprinted when using shadow bold mode. the default (1) means the text gets printed in the normal place, and also one character to the right — which seems to work well for most X bitmap fonts, since they've got a blank line of pixels down the right-hand side. for some fonts you may need to set this to -1 so the text is overprinted one pixel to the left; and for really large fonts you might want to set it higher than 1 (in one direction or the other) 🌀

pterm.BoldAsColour

0, 1 or 2 — default 1. how bold text should be displayed, your choice:

• 1 — bold text is shown in a brighter colour
• 0 — bold text is shown in a heavier font
• 2 — both effects happen at once (a heavy font and a brighter colour)

slay 💖

pterm.Colour0, pterm.Colour1, ..., pterm.Colour21

these options control the various colours used to display text in the pterm window. each one gets specified as a triple of decimal numbers giving red, green and blue values — so black is 0,0,0, white is 255,255,255, red is 255,0,0 and so on 🌈

the mapping, bestie:

• 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 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 — bestie, this one is literally just 0 or 1, and the default is 0. Set it to 0 and dragging your mouse down over several lines selects all the way to the end of each line and from the beginning of the next one (the normal, "flowing text" vibe). Set it to 1 and that same drag selects a rectangular region instead 👑. Either way, if you hold down Alt while you drag, you get the other behaviour. Sneaky little flip-flop, we stan.
• pterm.MouseOverride — also 0 or 1, defaulting to 1. When it's 1, and the application you're in asks for mouse tracking (meaning your clicks get yeeted to the app instead of doing selection), holding down Shift reverts the mouse to normal selection — a little escape hatch, love that for us 🫶. When it's 0, mouse tracking totally disables selection, no take-backs. Periodt.
• pterm.Printer — unset by default, so nothing happens unless you set it. Once you do, server-controlled printing is on: the server can send control sequences asking for data to be sent to a printer, and that data gets piped straight into the command you put here. So like, you might set it to lpr, for example, or lpr -Pmyprinter 💅. It's literally a pipe to whatever you want.
• pterm.ScrollBar — 0 or 1, default 1. Set it to 0 and the scrollbar is hidden (although Shift-PageUp and Shift-PageDown still work, so you're not stranded). This is the same as the -sb command-line option. Twin flames fr fr.
• pterm.ScrollbarOnLeft — 0 or 1, default 0. Set it to 1 and the scrollbar shows up on the left of the terminal instead of the right. Left-handed girlies rise 🙈
• pterm.ScrollOnKey — 0 or 1, default 0. Set it to 1 and literally any keypress snaps the scrollback position right back down to the very bottom. Very "no thoughts, back to the present" energy.
• pterm.ScrollOnDisp — 0 or 1, default 1. Set it to 1 and any activity in the display resets the scrollback position to the very bottom. Basically if something new happens, you're catching up on it immediately 🔥
• pterm.LineCodePage — tells pterm which character set to use for the session. Same as the -cs command-line option. Iconic.
• pterm.NoRemoteCharset — this one disables the terminal's ability to change its own character set when it gets escape sequences telling it to. Why would you want that? Because you might need it to interoperate with programs that incorrectly change the character set to something they think is sensible. Rude of them ngl, but here's your shield 💀
• pterm.BCE — 0 or 1, default 1. Set it to 1 and the various control sequences that erase parts of the terminal display will erase in whatever the current background colour is. Set it to 0 and they'll erase in black, always, no matter what. Choose your fighter ✨
• pterm.BlinkText — 0 or 1, default 0. Set it to 1 and text that the server says should be blinking will actually blink on and off 😭. Leave it at 0 and pterm takes the less distracting route: making the text's background colour bold instead. Honestly the glow-up we deserve.
• pterm.StampUtmp — 0 or 1, default 1. Set to 1, pterm logs the login in the various system log files. This resource is equivalent to the -ut command-line option. Receipts, kept 📝
• pterm.LoginShell — 0 or 1, default 1. Set to 1 and pterm executes your shell as a login shell. This resource is equivalent to the -ls command-line option. Main character shell behaviour, honestly 👑

---

💀 BUGS 💀

So… most of the X resources have silly names. Not me saying it, the page says it. Historical reasons from PuTTY, mostly. We don't ask questions about the ancestors 🧚

---

And that's the whole page bestie!! 🎀 This little masterpiece came from the PuTTY tool suite, dated 2004‐03‐24. A vintage icon, truly. Go forth and configure your terminal with taste 💖✨