Rxvt Technical Reference

Geoff Wing (gcw@pobox.com)

18 April 1998



Reworked from XTerm documentation and other sources

Definitions


c
The literal character c.

C
A single (required) character.

Ps
A single (usually optional) numeric parameter, composed of one or more digits.

Pm
A multiple numeric parameter composed of any number of single numeric parameters, separated by ; character(s).

Pt
A text parameter composed of printable characters.
Top


Values


ENQ
Enquiry (Ctrl-E) = Send Device Attributes (DA)
request attributes from terminal == ESC[Psc

BEL
Bell (Ctrl-G)

BS
Backspace (Ctrl-H)

TAB
Horizontal Tab (HT) (Ctrl-I)

LF
Line Feed or New Line (NL) (Ctrl-J)

VT
Vertical Tab (Ctrl-K) same as LF

FF
Form Feed or New Page (NP) (Ctrl-L) same as LF

CR
Carriage Return (Ctrl-M)

SO
Shift Out (Ctrl-N), invokes the G1 character set.
Switch to Alternate Character Set

SI
Shift In (Ctrl-O), invokes the G0 character set (the default)
Switch to Standard Character Set

SPC
Space Character
Top


Escape Sequences


ESC # 8
DEC Screen Alignment Test (DECALN)

ESC 7
ESC 8
Save Cursor (SC)
Restore Cursor

ESC =
ESC >
Application Keypad (SMKX) == ESC[?66h
Normal Keypad (RMKX) == ESC[?66l

Note: If the numeric keypad is activated, eg, Num_Lock has been pressed, numbers or control functions are generated by the numeric keypad (see Key Codes)

ESC D
Index (IND)

ESC E
Next Line (NEL)

ESC H
Tab Set (HTS)

ESC M
Reverse Index (RI)

ESC N
Single Shift Select of G2 Character Set (SS2): affects next character only unimplemented

ESC O
Single Shift Select of G3 Character Set (SS3): affects next character only unimplemented

ESC Z
Obsolete form of ESC[c
returns: ESC[?1;2C rxvt compile-time option

ESC c
Full reset (RIS)

ESC n
Invoke the G2 Character Set (LS2)

ESC o
Invoke the G3 Character Set (LS3)

ESC ( C
ESC ) C
ESC * C
ESC + C
ESC $ C
Designate G0 Character Set (ISO 2022)
Designate G1 Character Set (ISO 2022)
Designate G2 Character Set (ISO 2022)
Designate G3 Character Set (ISO 2022)
Designate Kanji Character Set
where C is
C = 0 DEC Special Character and Line Drawing Set
C = A United Kingdom (UK)
C = B United States (USASCII)
C = < Multinational character set unimplemented
C = 5 Finnish character set unimplemented
C = C Finnish character set unimplemented
C = K German character set unimplemented
Top


CSI (Code Sequence Introducer) Sequences


ESC [ Ps @
Insert Ps (Blank) Character(s) [default: 1] (ICH)

ESC [ Ps A
Cursor Up Ps Times [default: 1] (CUU)

ESC [ Ps B
Cursor Down Ps Times [default: 1] (CUD)
ESC [ Ps C
Cursor Forward Ps Times [default: 1] (CUF)

ESC [ Ps D
Cursor Backward Ps Times [default: 1] (CUB)

ESC [ Ps E
Cursor Down Ps Times [default: 1] and to first column

ESC [ Ps F
Cursor Up Ps Times [default: 1] and to first column

ESC [ Ps G
Cursor to Column Ps (HPA)

ESC [ Ps;Ps H
Cursor Position [row;column] [default: 1;1] (CUP)

ESC [ Ps I
Move forward Ps tab stops [default: 1]

ESC [ Ps J
Erase in Display (ED)
Ps = 0 Clear Below (default)
Ps = 1 Clear Above
Ps = 2 Clear All
ESC [ Ps K
Erase in Line (EL)
Ps = 0 Clear to Right (default)
Ps = 1 Clear to Left
Ps = 2 Clear All
ESC [ Ps L
Insert Ps Line(s) [default: 1] (IL)

ESC [ Ps M
Delete Ps Line(s) [default: 1] (DL)

ESC [ Ps P
Delete Ps Character(s) [default: 1] (DCH)

ESC [ Ps;Ps;Ps;Ps;Ps T
Initiate hilite mouse tracking. unimplemented Parameters are [func;startx;starty;firstrow;lastrow].

ESC [ Ps W
Tabulator functions
Ps = 0 Tab Set (HTS)
Ps = 2 Tab Clear (TBC), Clear Current Column (default)
Ps = 5 Tab Clear (TBC), Clear All
ESC [ Ps X
Erase Ps Character(s) [default: 1] (ECH)

ESC [ Ps Z
Move backward Ps [default: 1] tab stops

ESC [ Ps '
== ESC [ Ps G

ESC [ Ps a
== ESC [ Ps C

ESC [ Ps c
Send Device Attributes (DA)
Ps = 0 (or omitted) : request attributes from terminal
returns: ESC[?1;2c (``I am a VT100 with Advanced Video Option'')

ESC [ Ps d
Cursor to Line Ps (VPA)

ESC [ Ps e
== ESC [ Ps A

ESC [ Ps;Ps f
Horizontal and Vertical Position [row;column] (HVP) [default: 1;1]

ESC [ Ps g
Tab Clear (TBC)
Ps = 0 Clear Current Column (default)
Ps = 3 Clear All (TBC)
ESC [ Ps i
Printing
Ps = 4 disable transparent print mode (MC4)
Ps = 5 enable transparent print mode (MC5) unimplemented
ESC [ Pm h
ESC [ Pm l
Set Mode (SM)
Reset Mode (RM)
Ps = 4
h Insert Mode (SMIR)
l Replace Mode (RMIR)
Ps = 20 unimplemented
h Automatic Newline (LNM)
h Normal Linefeed (LNM)
ESC [ Pm m
Character Attributes (SGR)
Ps = 0 Normal (default)
Ps = 1 / 22 On / Off Bold (bright fg)
Ps = 4 / 24 On / Off Underline
Ps = 5 / 25 On / Off Blink (bright bg)
Ps = 7 / 27 On / Off Inverse
Ps = 30 / 40 fg/bg Black
Ps = 31 / 41 fg/bg Red
Ps = 32 / 42 fg/bg Green
Ps = 33 / 43 fg/bg Yellow
Ps = 34 / 44 fg/bg Blue
Ps = 35 / 45 fg/bg Magenta
Ps = 36 / 46 fg/bg Cyan
Ps = 37 / 47 fg/bg White
Ps = 39 / 49 fg/bg Default
ESC [ Ps n
Device Status Report (DSR)
Ps = 5 Status Report ESC [ 0 n (``OK'')
Ps = 6 Report Cursor Position (CPR) [row;column] as ESC [ r ; c R
Ps = 7 Request Display Name
Ps = 8 Request Version Number (place in window title)
ESC [ Ps;Ps r
Set Scrolling Region [top;bottom]
[default: full size of window] (CSR)

ESC [ Ps x
Request Terminal Parameters (DECREQTPARM)
Top


DEC Private Modes


ESC [ ? Pm h
DEC Private Mode Set (DECSET)

ESC [ ? Pm l
DEC Private Mode Reset (DECRST)

ESC [ ? Pm r
Restore previously saved DEC Private Mode Values.

ESC [ ? Pm s
Save DEC Private Mode Values.

ESC [ ? Pm t
Toggle DEC Private Mode Values (rxvt extension).
where
Ps = 1 (DECCKM)
h Application Cursor Keys
l Normal Cursor Keys
Ps = 2 unimplemented
h Designate USASCII for character sets G0-G3.
Ps = 3
h 132 Column Mode (DECCOLM)
l 80 Column Mode (DECCOLM)
Ps = 4 unimplemented
h Smooth (Slow) Scroll (DECSCLM)
l Jump (Fast) Scroll (DECSCLM)
Ps = 5
h Reverse Video (DECSCNM)
l Normal Video (DECSCNM)
Ps = 6
h Origin Mode (DECOM)
l Normal Cursor Mode (DECOM)
Ps = 7
h Wraparound Mode (DECAWM)
l No Wraparound Mode (DECAWM)
Ps = 8 unimplemented
h Auto-repeat Keys (DECARM)
l No Auto-repeat Keys (DECARM)
Ps = 9 X10 XTerm mouse reporting
h Send Mouse X & Y on button press.
l No mouse reporting.
Ps = 10 (rxvt)
h menuBar visible
l menuBar invisible
Ps = 25
h Visible cursor {cnorm/cvvis}
l Invisible cursor {civis}
Ps = 30
h scrollBar visisble
l scrollBar invisisble
Ps = 35 (rxvt)
h Allow XTerm Shift+key sequences
l Disallow XTerm Shift+key sequences
Ps = 38 unimplemented
Enter Tektronix Mode (DECTEK)
Ps = 40
h Allow 80/132 Mode
l Disallow 80/132 Mode
Ps = 44 unimplemented
h Turn On Margin Bell
l Turn Off Margin Bell
Ps = 45 unimplemented
h Reverse-wraparound Mode
l No Reverse-wraparound Mode
Ps = 46 unimplemented

Ps = 47 unimplemented
h Use Alternate Screen Buffer
l Use Normal Screen Buffer
Ps = 66
h Application Keypad (DECPAM) == ESC =
l Normal Keypad (DECPNM) == ESC >
Ps = 67
h Backspace key sends BS (DECBKM)
l Backspace key sends DEL
Ps = 1000 (X11 XTerm mouse reporting)
h Send Mouse X & Y on button press and release.
l No mouse reporting.
Ps = 1001 (X11 XTerm mouse tracking) unimplemented
h Use Hilite Mouse Tracking.
l No mouse reporting.
Ps = 1010
h Don't scroll to bottom on TTY output
l Scroll to bottom on TTY output
Ps = 1011
h Scroll to bottom when a key is pressed
l Don't scroll to bottom when a key is pressed


Top


XTerm Escape Sequences


ESC ] Ps;Pt BEL
Set XTerm Parameters
Ps = 0 Change Icon Name and Window Title to Pt
Ps = 1 Change Icon Name to Pt
Ps = 2 Change Window Title to Pt
Ps = 10 menuBar command Pt rxvt compile-time option
Ps = 20 Change default background pixmap to Pt
Ps = 39 Change default foreground colour to Pt rxvt compile-time option
Ps = 46 Change Log File to Pt unimplemented
Ps = 49 Change default background colour to Pt rxvt compile-time option
Ps = 50 Set Font to Pt, with the following special values of Pt (rxvt)
#+n change up n font(s)
#-n change down n font(s)
if n is missing of 0, a value of 1 is used
empty change to font0
n change to font n
Top


menuBar


The exact syntax used is almost solidified.
In the menus, DON'T try to use menuBar commands that add or remove a menuBar.


Note that in all of the commands, the /path/ cannot be omitted: use ./ to specify a menu relative to the current menu.


Overview of menuBar operation


For the menuBar XTerm escape sequence ESC ] 10; Pt BEL, the syntax of Pt can be used for a variety of tasks:


At the top level is the current menuBar which is a member of a circular linked-list of other such menuBars.


The menuBar acts as a parent for the various drop-down menus, which in turn, may have labels, separator lines, menuItems and subMenus.


The menuItems are the useful bits: you can use them to mimic keyboard input or even to send text or escape sequences back to rxvt.


The menuBar syntax is intended to provide a simple yet robust method of constructing and manipulating menus and navigating through the menuBars.


The first step is to use the tag [menu:name] which creates the menuBar called name and allows access. You may now add or remove menus, subMenus, and menuItems. Finally, use the tag [done] to set the menuBar access as readonly to prevent accidental corruption of the menus. To re-access the current menuBar for alterations, use the tag [menu], make the alterations and then use [done]


Commands


[menu:name]
access the named menuBar for creation or alteration. If a new menuBar is created, it is called name (max of 15 chars) and the current menuBar is pushed onto the stack

[menu]
access the current menuBar for alteration

[title:string]
set the current menuBar's title to string, which may contain the following format specifiers:
%% : literal % character
%n : rxvt name (as per the -name command-line option)
%v : rxvt version

[done]
set menuBar access as readonly.
End-of-file tag for [read:file] operations.

[read:file]
read menu commands directly from file (extension ".menu" will be appended if required.) Start reading at a line with [menu] or [menu:name and continuing until [done] is encountered.


Blank and comment lines (starting with #) are ignored. Actually, since any invalid menu commands are also ignored, almost anything could be construed as a comment line, but this may be tightened up in the future ... so don't count on it!.

[read:file;name]
The same as [read:file], but start reading at a line with [menu:name] and continuing until [done:name] or [done] is encountered.

[dump]
dump all menuBars to the file /tmp/rxvt-PID in a format suitable for later rereading.

[rm:name]
[rm] [rm:]
[rm*] [rm:*]
remove the named menuBar
remove the current menuBar
remove all menuBars

[swap]
swap the top two menuBars

[prev]
[next]
access the previous or next menuBar

[show]
[hide]
control display of the menuBar ... just like ESC[?10 h/l

[pixmap:name]
[pixmap:name;scaling]
set the background pixmap globally ... just like ESC]20; Pt BEL


A Future implementation may make this local to the menubar

[:command:]
ignore the menu readonly status and issue a command to Add/Modify or Remove a menu or menuitem or change the Quick Arrows; a useful shortcut for setting the quick arrows from a menuBar.


Adding and accessing menus


The following commands may also be + prefixed.

/
./
../
../../
access menuBar top level
access current menu level
access parent menu (1 level up)
access parent menu (multiple levels up)
/path/menu
add/access menu
/path/menu/*
add/access menu and clear it if it exists
/path/{-}
add separator
/path/{item}
add item as a label
/path/{item} action
add/alter menuitem with an associated action
/path/{item}{right-text}
add/alter menuitem with right-text as the right-justified text and as the associated action
/path/{item}{rtext} action
add/alter menuitem with an associated action and with rtext as the right-justified text.
Special characters in action must be backslash-escaped:
\a \b \E \e \n \r \t \octal
or in control-character notation:
^@, ^A .. ^Z .. ^_, ^?


To send a string starting with a NUL (^@) character to the program, start action with a pair of NUL characters (^@^@), the first of which will be stripped off and the balance directed to the program. Otherwise if action begins with NUL followed by non-NUL characters, the leading NUL is stripped off and the balance is sent back to rxvt.


As a convenience for the many Emacs-type editors, action may start with M- (eg, M-$ is equivalent to \E$) and a CR will be appended if missed from M-x commands.


As a convenience for issuing XTerm ESC] sequences from a menubar (or quick arrow), a BEL (^G) will be appended if needed.


For example,
M-xapropos is equivalent to \Exapropos\r
and
\E]10;mona;100 is equivalent to \E]10;mona;100\a


The option {right-rtext} will be right-justified. In the absence of a specified action, this text will be used as the action as well.


For example,
/File/{Open}{^X^F} is equivalent to /File/{Open}{^X^F} ^X^F


The left label is necessary, since it's used for matching, but implicitly hiding the left label (by using same name for both left and right labels), or explicitly hiding the left label (by preceeding it with a dot), makes it possible to have right-justified text only.

For example,
/File/{Open}{Open} Open-File-Action
or hiding it
/File/{.anylabel}{Open} Open-File-Action


Removing menus


-/*
-/pathmenu
-/path{item}
-/path{-}
remove all menus from the menuBar, the same as [clear]
remove menu
remove item
remove separator
-/path/menu/*
remove all items, separators and submenus from menu


Quick Arrows


The menus also provide a hook for quick arrows to provide easier user access. If nothing has been explicitly set, the default is to emulate the curror keys. The syntax permits each arrow to be altered individually or all four at once without re-entering their common beginning/end text. For example, to explicitly associate cursor actions with the arrows, any of the following forms could be used:


<r>Right
<l>Left
<u>Up
<d>Down
Define actions for the respective arrow buttons
<b>Begin
<e>End
Define common beginning/end parts for quick arrows which used in conjunction with the above <r> <l> <u> <d> constructs


For example, define arrows individually,
<u>\E[A
<d>\E[B
<r>\E[C
<l>\E[D
or all at once
<u>\E[A<d>\E[B<r>\E[C<l>\E[D
or more compactly (factoring out common parts)
<b>\E[<u>A<d>B<r>C<l>D


Command Summary


A short summary of the most common commands:


[menu:name]
use an existing named menuBar or start a new one
[menu]
use the current menuBar
[title:string]
set menuBar title
[done]
set menu access to readonly and, if reading from a file, signal EOF
[done:name]
if reading from a file using [read:file;name] signal EOF
[rm:name]
[rm] [rm:]
[rm*] [rm:*]
remove named, current, or all menuBar(s)
[swap]
swap top two menuBars
[prev]
[next]
access the previous/next menuBar
[show]
[hide]
map/unmap menuBar
[pixmap;file]
[pixmap;file;scaling]
set a background pixmap
[read:file]
[read:file;name]
read in a menu from a file
[dump]
dump out all menuBars to /tmp/rxvt-PID
/
access menuBar top level
./
../
../../
access current or parent menu level
/path/menu
add/access menu
/path/{-}
add separator
/path/{item}{rtext} action
add/alter menu item
({rtext} and/or action, may be omitted)
-/*
remove all menus from the menuBar
-/path/menu
remove menu items, separators and submenus from menu
-/path/menu
remove menu
-/path/{item}
remove item
-/path/{-}
remove separator
<b>Begin<r>Right<l>Left<u>Up<d>Down<e>End
menu quick arrows
Top


background image


For the background image XTerm escape sequence ESC ] 20; Pt BEL then value of Pt can be the name of the background pixmap followed by a sequence of scaling/positioning commands separated by semi-colons. The scaling/positioning commands are as follows:


query scale/position
?

background image change scale and position
WxH+X+Y
WxH+X (== WxH+X+X)
WxH (same as WxH+50+50)
W+X+Y (same as WxW+X+Y)
W+X (same as WxW+X+X)
W (same as WxW+50+50)

change position (absolute)
=+X+Y
=+X (same as =+X+Y)

change position (relative)
+X+Y
+X (same as +X+Y)

rescale (relative)
Wx0 -> W *= (W/100)
0xH -> H *= (H/100)


Note: when width is 1, the pixmap is not tiled across and if x is also -0 it is centred. Similarly, for height and y.


For example:


\E]20;funky\a
load funky.xpm as a tiled image

\E]20;mona;100\a
load mona.xpm with a scaling of 100%

\E]20;;200;?\a
rescale the current pixmap to 200% and display the image geometry in the title
Top


Mouse Reporting


ESC [ M <b> <x> <y>
report mouse position
The lower 2 bits of <b> indicate the button:
Button = (<b> - SPACE) & 3
0 = Button1 pressed
1 = Button2 pressed
2 = Button3 pressed
3 = button released (X11 mouse report)


The upper bits of <b> indicate the modifiers when the button was pressed and are added together (X11 mouse report only):


State = (<b> - SPACE) & 60
4 = Shift
8 = Meta
16 = Control
32 = Double Click (Rxvt extension)
Col = <x> - SPACE
Row = <y> - SPACE
Top


Special Graphics Mode


Add more documentation here, if anyone actually cares.


ESC G Q
query if graphics are available
returns: ESC G 0 no graphics available
returns: ESC G 1 graphics available (colour only)

ESC G W <;x>;<y>;<w>;<h>:
create window

ESC G C <id>
clear window

ESC G G <it>:
query window
returns: ESC G <id> <x> <y> <w> <h> <fw> <fh> <nw> <nh>

ESC G L <id>
ESC G P <id>
ESC G F <id>
start point
start line
start fill

;<x>;<y>
extend point/line/fill

ESC G T <id>;<x>;<y>;<mode>;<len>:<text>
place text
Top


Key Codes


Note: Shift + F1-F10 generates F11-F20


For the keypad, use Shift to temporarily override Application-Keypad setting use Num_Lock to toggle Application-Keypad setting if Num_Lock is off, escape sequences toggle Application-Keypad setting. Also note that values of Home, End, Delete may have been compiled differently on your system.


Normal Shift Control Ctrl+Shift
Tab ^I ESC [ Z ^I ESC [ Z
BackSpace ^H ^? ^? ^?
Find ESC [ 1 ~ ESC [ 1 $ ESC [ 1 ^ ESC [ 1 @
Insert ESC [ 2 ~ paste ESC [ 2 ^ ESC [ 2 @
Execute ESC [ 3 ~ ESC [ 3 $ ESC [ 3 ^ ESC [ 3 @
Select ESC [ 4 ~ ESC [ 4 $ ESC [ 4 ^ ESC [ 4 @
Prior ESC [ 5 ~ scroll-up ESC [ 5 ^ ESC [ 5 @
Next ESC [ 6 ~ scroll-down ESC [ 6 ^ ESC [ 6 @
Home ESC [ 7 ~ ESC [ 7 $ ESC [ 7 ^ ESC [ 7 @
End ESC [ 8 ~ ESC [ 8 $ ESC [ 8 ^ ESC [ 8 @
Delete ESC [ 3 ~ ESC [ 3 $ ESC [ 3 ^ ESC [ 3 @
F1 ESC [ 11 ~ ESC [ 23 ~ ESC [ 11 ^ ESC [ 23 ^
F2 ESC [ 12 ~ ESC [ 24 ~ ESC [ 12 ^ ESC [ 24 ^
F3 ESC [ 13 ~ ESC [ 25 ~ ESC [ 13 ^ ESC [ 25 ^
F4 ESC [ 14 ~ ESC [ 26 ~ ESC [ 14 ^ ESC [ 26 ^
F5 ESC [ 15 ~ ESC [ 28 ~ ESC [ 15 ^ ESC [ 28 ^
F6 ESC [ 17 ~ ESC [ 29 ~ ESC [ 17 ^ ESC [ 29 ^
F7 ESC [ 18 ~ ESC [ 31 ~ ESC [ 18 ^ ESC [ 31 ^
F8 ESC [ 19 ~ ESC [ 32 ~ ESC [ 19 ^ ESC [ 32 ^
F9 ESC [ 20 ~ ESC [ 33 ~ ESC [ 20 ^ ESC [ 33 ^
F10 ESC [ 21 ~ ESC [ 34 ~ ESC [ 21 ^ ESC [ 34 ^
F11 ESC [ 23 ~ ESC [ 23 $ ESC [ 23 ^ ESC [ 23 @
F12 ESC [ 24 ~ ESC [ 24 $ ESC [ 24 ^ ESC [ 24 @
F13 ESC [ 25 ~ ESC [ 25 $ ESC [ 25 ^ ESC [ 25 @
F14 ESC [ 26 ~ ESC [ 26 $ ESC [ 26 ^ ESC [ 26 @
F15 (Help) ESC [ 28 ~ ESC [ 28 $ ESC [ 28 ^ ESC [ 28 @
F16 (Menu) ESC [ 29 ~ ESC [ 29 $ ESC [ 29 ^ ESC [ 29 @
F17 ESC [ 31 ~ ESC [ 31 $ ESC [ 31 ^ ESC [ 31 @
F18 ESC [ 32 ~ ESC [ 32 $ ESC [ 32 ^ ESC [ 32 @
F19 ESC [ 33 ~ ESC [ 33 $ ESC [ 33 ^ ESC [ 33 @
F20 ESC [ 34 ~ ESC [ 34 $ ESC [ 34 ^ ESC [ 34 @
Application
Up ESC [ A ESC [ a ESC O a ESC O A
Down ESC [ B ESC [ b ESC O b ESC O B
Right ESC [ C ESC [ c ESC O c ESC O C
Left ESC [ D ESC [ d ESC O d ESC O D
KP_Enter ^M ESC O M
KP_F1 ESC O P ESC O P
KP_F2 ESC O Q ESC O Q
KP_F3 ESC O R ESC O R
KP_F4 ESC O S ESC O S
XK_KP_Multiply * ESC O j
XK_KP_Add + ESC O k
XK_KP_Separator , ESC O l
XK_KP_Subtract - ESC O m
XK_KP_Decimal . ESC O n
XK_KP_Divide / ESC O o
XK_KP_0 0 ESC O p
XK_KP_1 1 ESC O q
XK_KP_2 2 ESC O r
XK_KP_3 3 ESC O s
XK_KP_4 4 ESC O t
XK_KP_5 5 ESC O u
XK_KP_6 6 ESC O v
XK_KP_7 7 ESC O w
XK_KP_8 8 ESC O x
XK_KP_9 9 ESC O y
Top