ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/doc/rxvt.1.pod
(Generate patch)

Comparing rxvt-unicode/doc/rxvt.1.pod (file contents):
Revision 1.218 by root, Tue Jun 5 22:26:55 2012 UTC vs.
Revision 1.255 by root, Sat Jul 24 11:00:58 2021 UTC

… …
84far greater than those listed. For example: `@@RXVT_NAME@@ --loginShell --color1 84far greater than those listed. For example: `@@RXVT_NAME@@ --loginShell --color1
85Orange'. 85Orange'.
86 86
87The following options are available: 87The following options are available:
88 88
89=over 4 89=over
90 90
91=item B<-help>, B<--help> 91=item B<-help>, B<--help>
92 92
93Print out a message describing available options. 93Print out a message describing available options.
94 94
… …
98is still respected. but deprecated). In the absence of this option, the 98is still respected. but deprecated). In the absence of this option, the
99display specified by the B<DISPLAY> environment variable is used. 99display specified by the B<DISPLAY> environment variable is used.
100 100
101=item B<-depth> I<bitdepth> 101=item B<-depth> I<bitdepth>
102 102
103Compile I<xft>: Attempt to find a visual with the given bit depth; 103Compile I<frills>: Attempt to find a visual with the given bit depth;
104resource B<depth>. 104resource B<depth>.
105 105
106[Please note that many X servers (and libXft) are buggy with 106[Please note that many X servers (and libXft) are buggy with
107respect to C<-depth 32> and/or alpha channels, and will cause all sorts 107respect to C<-depth 32> and/or alpha channels, and will cause all sorts
108of graphical corruption. This is harmless, but we can't do anything about 108of graphical corruption. This is harmless, but we can't do anything about
109this, so watch out] 109this, so watch out]
110 110
111=item B<-visual> I<visualID>
112
113Compile I<frills>: Use the given visual (see e.g. C<xdpyinfo> for
114possible visual ids) instead of the default, and also allocate a private
115colormap. All visual types except for DirectColor are supported.
116
111=item B<-geometry> I<geom> 117=item B<-geometry> I<geom>
112 118
113Window geometry (B<-g> still respected); resource B<geometry>. 119Window geometry (B<-g> still respected); resource B<geometry>.
114 120
115=item B<-rv>|B<+rv> 121=item B<-rv>|B<+rv>
… …
121Turn on/off jump scrolling (allow multiple lines per refresh); resource B<jumpScroll>. 127Turn on/off jump scrolling (allow multiple lines per refresh); resource B<jumpScroll>.
122 128
123=item B<-ss>|B<+ss> 129=item B<-ss>|B<+ss>
124 130
125Turn on/off skip scrolling (allow multiple screens per refresh); resource B<skipScroll>. 131Turn on/off skip scrolling (allow multiple screens per refresh); resource B<skipScroll>.
126
127=item B<-tr>|B<+tr>
128
129Turn on/off pseudo-transparency by using the root pixmap as background; resource B<transparent>.
130
131B<-ip> is still accepted as an obsolete alias but will be removed in
132future versions.
133 132
134=item B<-fade> I<number> 133=item B<-fade> I<number>
135 134
136Fade the text by the given percentage when focus is lost. Small values 135Fade the text by the given percentage when focus is lost. Small values
137fade a little only, 100 completely replaces all colours by the fade 136fade a little only, 100 completely replaces all colours by the fade
… …
140=item B<-fadecolor> I<colour> 139=item B<-fadecolor> I<colour>
141 140
142Fade to this colour when fading is used (see B<-fade>). The default colour 141Fade to this colour when fading is used (see B<-fade>). The default colour
143is opaque black. resource B<fadeColor>. 142is opaque black. resource B<fadeColor>.
144 143
145=item B<-tint> I<colour>
146
147Tint the transparent background with the given colour;
148resource I<tintColor>.
149
150=item B<-sh> I<number>
151
152Darken (0 .. 99) or lighten (101 .. 200) the transparent background.
153A value of 100 means no shading; resource I<shading>.
154
155=item B<-blr> I<HxV>
156
157Apply Gaussian Blur with the specified radii to the transparent
158background. If a single number is specified, the vertical and
159horizontal radii are considered to be the same. Setting one of the
160radii to 1 and the other to a large number creates interesting effects
161on some backgrounds. The maximum radius value is 128. An horizontal or
162vertical radius of 0 disables blurring;
163resource I<blurRadius>.
164
165=item B<-icon> I<file> 144=item B<-icon> I<file>
166 145
167Compile I<pixbuf>: Use the specified image as application icon. This 146Compile I<pixbuf>: Use the specified image as application icon. This
168is used by many window managers, taskbars and pagers to represent the 147is used by many window managers, taskbars and pagers to represent the
169application window; resource I<iconFile>. 148application window; resource I<iconFile>.
… …
173Window background colour; resource B<background>. 152Window background colour; resource B<background>.
174 153
175=item B<-fg> I<colour> 154=item B<-fg> I<colour>
176 155
177Window foreground colour; resource B<foreground>. 156Window foreground colour; resource B<foreground>.
178
179=item B<-pixmap> I<file[;oplist]>
180
181Compile I<pixbuf>: Specify image file for the background and also
182optionally specify a list of operations to modify it. Note you may need to
183add quotes to avoid special shell interpretation of the C<;> in the
184command-line; for more details see resource B<backgroundPixmap>.
185 157
186=item B<-cr> I<colour> 158=item B<-cr> I<colour>
187 159
188The cursor colour; resource B<cursorColor>. 160The cursor colour; resource B<cursorColor>.
189 161
… …
248 220
249=item B<-ls>|B<+ls> 221=item B<-ls>|B<+ls>
250 222
251Start as a login-shell/sub-shell; resource B<loginShell>. 223Start as a login-shell/sub-shell; resource B<loginShell>.
252 224
225=item B<-mc> I<milliseconds>
226
227Specify the maximum time between multi-click selections.
228
253=item B<-ut>|B<+ut> 229=item B<-ut>|B<+ut>
254 230
255Compile I<utmp>: Inhibit/enable writing a utmp entry; resource 231Compile I<utmp>: Inhibit/enable writing a utmp entry; resource
256B<utmpInhibit>. 232B<utmpInhibit>.
257 233
… …
335 311
336=item B<-override-redirect> 312=item B<-override-redirect>
337 313
338Compile I<frills>: Sets override-redirect on the window; resource 314Compile I<frills>: Sets override-redirect on the window; resource
339B<override-redirect>. 315B<override-redirect>.
316
317=item B<-dockapp>
318
319Sets the initial state of the window to WithdrawnState, which makes
320window managers that support this extension treat it as a dockapp.
340 321
341=item B<-sbg> 322=item B<-sbg>
342 323
343Compile I<frills>: Disable the usage of the built-in block graphics/line 324Compile I<frills>: Disable the usage of the built-in block graphics/line
344drawing characters and just rely on what the specified fonts provide. Use 325drawing characters and just rely on what the specified fonts provide. Use
… …
399=item B<-pt> I<style> 380=item B<-pt> I<style>
400 381
401Compile I<XIM>: input style for input method; B<OverTheSpot>, 382Compile I<XIM>: input style for input method; B<OverTheSpot>,
402B<OffTheSpot>, B<Root>; resource B<preeditType>. 383B<OffTheSpot>, B<Root>; resource B<preeditType>.
403 384
385If the perl extension C<xim-onthespot> is used (which is the default),
386then additionally the C<OnTheSpot> preedit type is available.
387
404=item B<-im> I<text> 388=item B<-im> I<text>
405 389
406Compile I<XIM>: input method name. resource B<inputMethod>. 390Compile I<XIM>: input method name. resource B<inputMethod>.
407 391
408=item B<-imlocale> I<string> 392=item B<-imlocale> I<string>
… …
422Change the meaning of triple-click selection with the left mouse 406Change the meaning of triple-click selection with the left mouse
423button. Only effective when the original (non-perl) selection code is 407button. Only effective when the original (non-perl) selection code is
424in-use. Instead of selecting a full line it will extend the selection to 408in-use. Instead of selecting a full line it will extend the selection to
425the end of the logical line only. resource B<tripleclickwords>. 409the end of the logical line only. resource B<tripleclickwords>.
426 410
411=item B<-dpb>|B<+dpb>
412
413Compile frills: Disable (or enable) emitting bracketed paste mode
414sequences (default enabled). Bracketed paste mode allows programs
415to detect when something is pasted. Since more and more programs
416abuse this, these sequences can be disabled. The command sequences to
417enable and query paste mode will still work, but the actual bracket
418sequences will no longer be emitted. You can also toggle this from the
419ctrl-middle-mouse-button menu; resource B<disablePasteBrackets>.
420
427=item B<-insecure> 421=item B<-insecure>
428 422
429Enable "insecure" mode, which currently enables most of the escape 423Enable "insecure" mode, which currently enables most of the escape
430sequences that echo strings. See the resource B<insecure> for more 424sequences that echo strings. See the resource B<insecure> for more
431info. 425info.
… …
443 437
444=item B<-ssr>|B<+ssr> 438=item B<-ssr>|B<+ssr>
445 439
446Turn on/off secondary screen scroll (default enabled); resource 440Turn on/off secondary screen scroll (default enabled); resource
447B<secondaryScroll>. 441B<secondaryScroll>.
442
443=item B<-rm> I<mode>
444
445Compile I<frills>: Sets long line rewrapping behaviour on window resizes
446to one of B<auto> (the default), B<always> or B<never>. The latter two
447modes do the obvious, B<auto> rewraps (acts like B<always>) if scrollback
448is non-empty, and wings lines (acts like B<never>) otherwise; resource
449B<rewrapMode>.
448 450
449=item B<-hold>|B<+hold> 451=item B<-hold>|B<+hold>
450 452
451Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@ 453Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@
452will not immediately destroy its window when the program executed within 454will not immediately destroy its window when the program executed within
… …
567be used. Command-line arguments can be used to override resource 569be used. Command-line arguments can be used to override resource
568settings. The following resources are supported (you might want to 570settings. The following resources are supported (you might want to
569check the @@RXVT_NAME@@perl(3) manpage for additional settings by perl 571check the @@RXVT_NAME@@perl(3) manpage for additional settings by perl
570extensions not documented here): 572extensions not documented here):
571 573
572=over 4 574=over
573 575
574=item B<depth:> I<bitdepth> 576=item B<depth:> I<bitdepth>
575 577
576Compile I<xft>: Attempt to find a visual with the given bit depth; 578Compile I<xft>: Attempt to find a visual with the given bit depth;
577option B<-depth>. 579option B<-depth>.
… …
678 680
679B<False>: specify that everything is to be displayed, even 681B<False>: specify that everything is to be displayed, even
680if the refresh is too fast for the human eye to read anything (or the 682if the refresh is too fast for the human eye to read anything (or the
681monitor to display anything); option B<+ss>. 683monitor to display anything); option B<+ss>.
682 684
683=item B<transparent:> I<boolean>
684
685Turn on/off pseudo-transparency by using the root pixmap as background.
686
687B<inheritPixmap> is still accepted as an obsolete alias but will be removed in
688future versions.
689
690=item B<fading:> I<number> 685=item B<fading:> I<number>
691 686
692Fade the text by the given percentage when focus is lost; option B<-fade>. 687Fade the text by the given percentage when focus is lost; option B<-fade>.
693 688
694=item B<fadeColor:> I<colour> 689=item B<fadeColor:> I<colour>
695 690
696Fade to this colour, when fading is used (see B<fading:>). The default 691Fade to this colour, when fading is used (see B<fading:>). The default
697colour is black; option B<-fadecolor>. 692colour is black; option B<-fadecolor>.
698 693
699=item B<tintColor:> I<colour>
700
701Tint the transparent background with the given colour. If the RENDER
702extension is not available only black, red, green, yellow, blue,
703magenta, cyan and white tints can be performed server-side. Note that
704a black tint yields a completely black image while a white tint yields
705the image unchanged; option B<-tint>.
706
707=item B<shading:> I<number>
708
709Darken (0 .. 99) or lighten (101 .. 200) the transparent background.
710A value of 100 means no shading; option B<-sh>.
711
712=item B<blurRadius:> I<number>
713
714Apply gaussian blur with the specified radius to the transparent
715background; option B<-blr>.
716
717=item B<iconFile:> I<file> 694=item B<iconFile:> I<file>
718 695
719Set the application icon pixmap; option B<-icon>. 696Set the application icon pixmap; option B<-icon>.
720 697
721=item B<scrollColor:> I<colour> 698=item B<scrollColor:> I<colour>
… …
729 706
730=item B<borderColor:> I<colour> 707=item B<borderColor:> I<colour>
731 708
732The colour of the border around the text area and between the scrollbar 709The colour of the border around the text area and between the scrollbar
733and the text. 710and the text.
734
735=item B<backgroundPixmap:> I<file[;oplist]>
736
737Use the specified image file for the background and also
738optionally specify a colon separated list of operations to modify it.
739Supported operations are:
740
741=over 4
742
743=item B<WxH+X+Y>
744
745sets scale and position. B<"W" / "H"> specify the horizontal/vertical
746scale (percent), and B<"X" / "Y"> locate the image centre (percent). A
747scale of 0 disables scaling.
748
749=item B<op=tile>
750
751enables tiling
752
753=item B<op=keep-aspect>
754
755maintain the image aspect ratio when scaling
756
757=item B<op=root-align>
758
759use the position of the terminal window relative to the root window as
760the image offset, simulating a root window background
761
762=back
763
764The default scale and position setting is C<100x100+50+50>.
765Alternatively, a predefined set of templates can be used to achieve
766the most common setups:
767
768=over 4
769
770=item B<style=tiled>
771
772the image is tiled with no scaling. Equivalent to 0x0+0+0:op=tile
773
774=item B<style=aspect-stretched>
775
776the image is scaled to fill the whole window maintaining the aspect
777ratio and centered. Equivalent to 100x100+50+50:op=keep-aspect
778
779=item B<style=stretched>
780
781the image is scaled to fill the whole window. Equivalent to 100x100
782
783=item B<style=centered>
784
785the image is centered with no scaling. Equivalent to 0x0+50+50
786
787=item B<style=root-tiled>
788
789the image is tiled with no scaling and using 'root' positioning.
790Equivalent to 0x0:op=tile:op=root-align
791
792=back
793
794If multiple templates are specified the last one wins. Note that a
795template overrides all the scale, position and operations settings.
796
797If used in conjunction with B<-tr> option, the specified pixmap will be
798blended over the transparent background using alpha-blending.
799
800=item B<path:> I<path>
801
802Specify the colon-delimited search path for finding background image files.
803 711
804=item B<font:> I<fontlist> 712=item B<font:> I<fontlist>
805 713
806Select the fonts to be used. This is a comma separated list of font names 714Select the fonts to be used. This is a comma separated list of font names
807that are checked in order when trying to find glyphs for characters. The 715that are checked in order when trying to find glyphs for characters. The
… …
904 812
905B<True>: start as a login shell by prepending a `-' to B<argv[0]> of 813B<True>: start as a login shell by prepending a `-' to B<argv[0]> of
906the shell; option B<-ls>. B<False>: start as a normal sub-shell 814the shell; option B<-ls>. B<False>: start as a normal sub-shell
907[default]; option B<+ls>. 815[default]; option B<+ls>.
908 816
817=item B<multiClickTime:> I<number>
818
819Specify the maximum time in milliseconds between multi-click select
820events. The default is 500 milliseconds; option B<-mc>.
821
909=item B<utmpInhibit:> I<boolean> 822=item B<utmpInhibit:> I<boolean>
910 823
911B<True>: inhibit writing record into the system log file B<utmp>; 824B<True>: inhibit writing record into the system log file B<utmp>;
912option B<-ut>. B<False>: write record into the system log file B<utmp> 825option B<-ut>. B<False>: write record into the system log file B<utmp>
913[default]; option B<+ut>. 826[default]; option B<+ut>.
… …
976are not passed onto the shell; option B<-sk>. B<False>: do not scroll to 889are not passed onto the shell; option B<-sk>. B<False>: do not scroll to
977bottom when a non-special key is pressed; option B<+sk>. 890bottom when a non-special key is pressed; option B<+sk>.
978 891
979=item B<saveLines:> I<number> 892=item B<saveLines:> I<number>
980 893
981Save I<number> lines in the scrollback buffer [default 64]. This 894Save I<number> lines in the scrollback buffer [default 1000]; option B<-sl>.
982resource is limited on most machines to 65535; option B<-sl>.
983 895
984=item B<internalBorder:> I<number> 896=item B<internalBorder:> I<number>
985 897
986Internal border of I<number> pixels. This resource is limited to 100; 898Internal border of I<number> pixels. This resource is limited to 100;
987option B<-b>. 899option B<-b>.
… …
1050 962
1051=item B<pointerColor2:> I<colour> 963=item B<pointerColor2:> I<colour>
1052 964
1053Mouse pointer background colour. 965Mouse pointer background colour.
1054 966
967=item B<pointerShape:> I<string>
968
969Compile I<frills>: Specifies the name of the mouse pointer shape
970[default B<xterm>]. See the macros in the B<X11/cursorfont.h> include
971file for possible values (omit the C<XC_> prefix).
972
1055=item B<pointerBlankDelay:> I<number> 973=item B<pointerBlankDelay:> I<number>
1056 974
1057Specifies number of seconds before blanking the pointer [default 2]. Use a 975Specifies number of seconds before blanking the pointer [default 2]. Use a
1058large number (e.g. C<987654321>) to effectively disable the timeout. 976large number (e.g. C<987654321>) to effectively disable the timeout.
1059 977
… …
1085 1003
1086B<< BACKSLASH `"'&()*,;<=>?@[]^{|} >> 1004B<< BACKSLASH `"'&()*,;<=>?@[]^{|} >>
1087 1005
1088=item B<preeditType:> I<style> 1006=item B<preeditType:> I<style>
1089 1007
1090B<OverTheSpot>, B<OffTheSpot>, B<Root>; option B<-pt>. 1008B<OnTheSpot>, B<OverTheSpot>, B<OffTheSpot>, B<Root>; option B<-pt>.
1091 1009
1092=item B<inputMethod:> I<name> 1010=item B<inputMethod:> I<name>
1093 1011
1094I<name> of inputMethod to use; option B<-im>. 1012I<name> of inputMethod to use; option B<-im>.
1095 1013
… …
1113 1031
1114Change the meaning of triple-click selection with the left mouse 1032Change the meaning of triple-click selection with the left mouse
1115button. Instead of selecting a full line it will extend the selection to 1033button. Instead of selecting a full line it will extend the selection to
1116the end of the logical line only; option B<-tcw>. 1034the end of the logical line only; option B<-tcw>.
1117 1035
1036=item B<disablePasteBrackets:> I<boolean>
1037
1038Prevent emission of paste bracket sequences; option B<-dpb>.
1039
1118=item B<insecure:> I<boolean> 1040=item B<insecure:> I<boolean>
1119 1041
1120Enables "insecure" mode. Rxvt-unicode offers some escape sequences that 1042Enable "insecure" mode. Rxvt-unicode offers some escape sequences that
1121echo arbitrary strings like the icon name or the locale. This could be 1043echo arbitrary strings like the icon name or the locale. This could be
1122abused if somebody gets 8-bit-clean access to your display, whether 1044abused if somebody gets 8-bit-clean access to your display, whether
1123through a mail client displaying mail bodies unfiltered or through 1045through a mail client displaying mail bodies unfiltered or through
1124write(1) or any other means. Therefore, these sequences are disabled by 1046write(1) or any other means. Therefore, these sequences are disabled by
1125default. (Note that many other terminals, including xterm, have these 1047default. (Note that many other terminals, including xterm, have these
… …
1143 1065
1144=item B<secondaryScreen:> I<boolean> 1066=item B<secondaryScreen:> I<boolean>
1145 1067
1146Turn on/off secondary screen (default enabled). 1068Turn on/off secondary screen (default enabled).
1147 1069
1070=item B<rewrapMode:> I<mode>
1071
1072Sets long line rewrap behaviour on window resize to one of B<auto>
1073(default), B<always> or B<never>.
1074
1148=item B<secondaryScroll:> I<boolean> 1075=item B<secondaryScroll:> I<boolean>
1149 1076
1150Turn on/off secondary screen scroll (default enabled). If this 1077Turn on/off secondary screen scroll (default enabled). If this
1151option is enabled, scrolls on the secondary screen will change the 1078option is enabled, scrolls on the secondary screen will change the
1152scrollback buffer and, when secondaryScreen is off, switching 1079scrollback buffer and, when secondaryScreen is off, switching
… …
1164Sets the working directory for the shell (or the command specified via 1091Sets the working directory for the shell (or the command specified via
1165B<-e>). The I<path> must be an absolute path and it must exist for 1092B<-e>). The I<path> must be an absolute path and it must exist for
1166@@RXVT_NAME@@ to start. If it isn't specified then the current working 1093@@RXVT_NAME@@ to start. If it isn't specified then the current working
1167directory will be used; option B<-cd>. 1094directory will be used; option B<-cd>.
1168 1095
1169=item B<keysym.>I<sym>: I<string> 1096=item B<keysym.>I<sym>: I<action>
1170 1097
1171Compile I<frills>: Associate I<string> with keysym I<sym>. The 1098Compile I<frills>: Associate I<action> with keysym I<sym>. The intervening
1172intervening resource name B<keysym.> cannot be omitted. 1099resource name B<keysym.> cannot be omitted.
1173 1100
1174The format of I<sym> is "I<(modifiers-)key>", where I<modifiers> can be 1101Using this resource, you can map key combinations such as
1175any combination of B<ISOLevel3>, B<AppKeypad>, B<Control>, B<NumLock>, 1102C<Ctrl-Shift-BackSpace> to various actions, such as outputting a different
1176B<Shift>, B<Meta>, B<Lock>, B<Mod1>, B<Mod2>, B<Mod3>, B<Mod4>, B<Mod5>, 1103string than would normally result from that combination, making the
1177and the abbreviated B<I>, B<K>, B<C>, B<N>, B<S>, B<M>, B<A>, B<L>, B<1>, 1104terminal scroll up or down the way you want it, or any other thing an
1178B<2>, B<3>, B<4>, B<5>. 1105extension might provide.
1106
1107The key combination that triggers the action, I<sym>, has the following format:
1108
1109 (modifiers-)key
1110
1111Where I<modifiers> can be any combination of the following full or
1112abbreviated modifier names:
1113
1114=begin table
1115
1116 B<ISOLevel3> B<I>
1117 B<AppKeypad> B<K>
1118 B<Control> B<C>
1119 B<NumLock> B<N>
1120 B<Shift> B<S>
1121 B<Meta> B<M> I<or> B<A>
1122 B<Lock> B<L>
1123 B<Mod1> B<1>
1124 B<Mod2> B<2>
1125 B<Mod3> B<3>
1126 B<Mod4> B<4>
1127 B<Mod5> B<5>
1128
1129=end table
1179 1130
1180The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to 1131The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to
1181whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr 1132whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr
1182keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the 1133keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the
1183current application keymap mode state. 1134current application keymap mode state.
1184 1135
1185The spellings of I<key> can be obtained by using B<xev>(1) command or 1136Due the the large number of modifier combinations, a key mapping will
1186searching keysym macros from B</usr/X11R6/include/X11/keysymdef.h> and 1137match if I<at least> the specified identifiers are being set, and no other
1138key mappings with those and more bits are being defined. That means that
1139defining a mapping for C<a> will automatically provide definitions for
1140C<Meta-a>, C<Shift-a> and so on, unless some of those are defined mappings
1141themselves. See the C<builtin:> action, below, for a way to work around
1142this when this is a problem.
1143
1144The spelling of I<key> depends on your implementation of X. An easy way to
1145find a key name is to use the B<xev>(1) command. You can find a list by
1146looking for the C<XK_> macros in the B<X11/keysymdef.h> include file (omit
1187omitting the prefix B<XK_>. Alternatively you can specify I<key> by its hex 1147the C<XK_> prefix). Alternatively you can specify I<key> by its hex keysym
1188keysym value (B<0x0000 - 0xFFFF>). Note that the lookup of I<sym>s is not 1148value (B<0x0000 - 0xFFFF>).
1189performed in an exact manner; however, the closest match is assured.
1190 1149
1191I<string> may contain escape values (C<\n>: newline, C<\000>: octal 1150As with any resource value, the I<action> string may contain backslash
1151escape sequences (C<\n>: newline, C<\\>: backslash, C<\000>: octal
1192number), see RESOURCES in C<man 7 X> for further details. 1152number), see RESOURCES in C<man 7 X> for further details.
1193 1153
1194You can define a range of keysyms in one shot by 1154An action starts with an action prefix that selects a certain type
1195loading the C<keysym-list> perl extension and providing a I<string> 1155of action, followed by a colon. An action string without colons is
1196with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimiter `/' 1156interpreted as a literal string to pass to the tty (as if it was
1157prefixed with C<string:>).
1158
1159The following action prefixes are known - extensions can provide
1160additional prefixes:
1161
1162=over
1163
1164=item string:STRING
1165
1166If the I<action> starts with C<string:> (or otherwise contains no colons),
1167then the remaining C<STRING> will be passed to the program running in the
1168terminal. For example, you could replace whatever Shift-Tab outputs by the
1169string C<echo rm -rf /> followed by a newline:
1170
1171 URxvt.keysym.Shift-Tab: string:echo rm -rf /\n
1172
1173This could in theory be used to completely redefine your keymap.
1174
1175In addition, for actions of this type, you can define a range of
1176keysyms in one shot by loading the C<keysym-list> perl extension and
1177providing an I<action> with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where
1197should be a character not used by the strings. 1178the delimiter `/' should be a character not used by the strings.
1198 1179
1199Its usage can be demonstrated by an example: 1180Its usage can be demonstrated by an example:
1200 1181
1201 URxvt.keysym.M-C-0x61: list|\033<|abc|> 1182 URxvt.keysym.M-C-0x61: list|\033<|abc|>
1202 1183
1203The above line is equivalent to the following three lines: 1184The above line is equivalent to the following three lines:
1204 1185
1205 URxvt.keysym.Meta-Control-0x61: \033<a> 1186 URxvt.keysym.Meta-Control-0x61: string:\033<a>
1206 URxvt.keysym.Meta-Control-0x62: \033<b> 1187 URxvt.keysym.Meta-Control-0x62: string:\033<b>
1207 URxvt.keysym.Meta-Control-0x63: \033<c> 1188 URxvt.keysym.Meta-Control-0x63: string:\033<c>
1208 1189
1190=item command:STRING
1191
1209If I<string> takes the form of C<command:STRING>, the specified B<STRING> 1192If I<action> takes the form of C<command:STRING>, the specified B<STRING>
1210is interpreted and executed as @@RXVT_NAME@@'s control sequence. For 1193is interpreted and executed as @@RXVT_NAME@@'s control sequence (basically
1194the opposite of C<string:> - instead of sending it to the program running
1195in the terminal, it will be treated as if it were program output). This is
1196most useful to feed command sequences into @@RXVT_NAME@@.
1197
1211example the following means "change the current locale to C<zh_CN.GBK> 1198For example the following means "change the current locale to C<zh_CN.GBK>
1212when Control-Meta-c is being pressed": 1199when Control-Meta-c is being pressed":
1213 1200
1214 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 1201 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
1215 1202
1216If I<string> takes the form C<perl:STRING>, then the specified B<STRING> 1203The following example will map Control-Meta-1 and Control-Meta-2 to
1217is passed to the C<on_user_command> perl handler. See the @@RXVT_NAME@@perl(3) 1204the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
1218manpage. For example, the F<selection> extension (activated via 1205font-switching at runtime:
1219C<@@RXVT_NAME@@ -pe selection>) listens for C<selection:rot13> events:
1220 1206
1221 URxvt.keysym.M-C-c: perl:selection:rot13 1207 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
1208 URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
1222 1209
1223Due the the large number of modifier combinations, a defined key mapping 1210Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
1224will match if I<at least> the specified identifiers are being set, and 1211info):
1225no other key mappings with those and more bits are being defined. That
1226means that defining a key map for C<a> will automatically provide
1227definitions for C<Meta-a>, C<Shift-a> and so on, unless some of those are defined
1228mappings themselves.
1229 1212
1230Unfortunately, this will override built-in key mappings. For example 1213 URxvt.keysym.M-C-3: command:\033[8;25;80t
1214 URxvt.keysym.M-C-4: command:\033[8;48;110t
1215
1216=item builtin:
1217
1218The builtin action is the action that @@RXVT_NAME@@ would execute if no
1219key binding existed for the key combination. The obvious use is to undo
1220the effect of existing bindings. The not so obvious use is to reinstate
1221bindings when another binding overrides too many modifiers.
1222
1231if you overwrite the C<Insert> key you will disable @@RXVT_NAME@@'s 1223For example if you overwrite the C<Insert> key you will disable
1232C<Shift-Insert> mapping. To re-enable that, you can poke "holes" into the 1224@@RXVT_NAME@@'s C<Shift-Insert> mapping. To re-enable that, you can poke
1233user-defined keymap using the C<builtin:> replacement: 1225"holes" into the user-defined keymap using the C<builtin:> replacement:
1234 1226
1235 URxvt.keysym.Insert: <my insert key sequence> 1227 URxvt.keysym.Insert: <my insert key sequence>
1236 URxvt.keysym.S-Insert: builtin: 1228 URxvt.keysym.S-Insert: builtin:
1237 1229
1238The first line defines a mapping for C<Insert> and I<any> combination 1230The first line defines a mapping for C<Insert> and I<any> combination
1239of modifiers. The second line re-establishes the default mapping for 1231of modifiers. The second line re-establishes the default mapping for
1240C<Shift-Insert>. 1232C<Shift-Insert>.
1241 1233
1242The following example will map Control-Meta-1 and Control-Meta-2 to 1234=item builtin-string:
1243the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
1244font-switching at runtime:
1245 1235
1246 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007 1236This action is mainly useful to restore string mappings for keys that
1247 URxvt.keysym.M-C-2: command:\033]50;9x15bold\007 1237have predefined actions in @@RXVT_NAME@@. The exact semantics are a bit
1238difficult to explain - basically, this action will send the string to the
1239application that would be sent if @@RXVT_NAME@@ wouldn't have a built-in
1240action for it.
1248 1241
1249Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more 1242An example might make it clearer: @@RXVT_NAME@@ normally pastes the
1250info): 1243selection when you press C<Shift-Insert>. With the following bindings, it
1244would instead emit the (undocumented, but what applications running in the
1245terminal might expect) sequence C<ESC [ 2 $> instead:
1251 1246
1252 URxvt.keysym.M-C-3: command:\033[8;25;80t 1247 URxvt.keysym.S-Insert: builtin-string:
1253 URxvt.keysym.M-C-4: command:\033[8;48;110t 1248 URxvt.keysym.C-S-Insert: builtin:
1249
1250The first line disables the paste functionality for that key
1251combination, and the second reinstates the default behaviour for
1252C<Control-Shift-Insert>, which would otherwise be overridden.
1253
1254Similarly, to let applications gain access to the C<C-M-c> (copy to
1255clipboard) and C<C-M-v> (paste clipboard) key combination, you can do
1256this:
1257
1258 URxvt.keysym.C-M-c: builtin-string:
1259 URxvt.keysym.C-M-v: builtin-string:
1260
1261=item EXTENSION:STRING
1262
1263An action of this form invokes the action B<STRING>, if any, provided
1264by the @@RXVT_NAME@@perl(3) extension B<EXTENSION>. The extension will
1265be loaded automatically if necessary.
1266
1267Not all extensions define actions, but popular extensions that do
1268include the I<selection> and I<matcher> extensions (documented in their
1269own manpages, @@RXVT_NAME@@-selection(1) and @@RXVT_NAME@@-matcher(1),
1270respectively).
1271
1272From the silly examples department, this will rot13-"encrypt"
1273@@RXVT_NAME@@'s selection when Alt-Control-c is pressed on typical PC
1274keyboards:
1275
1276 URxvt.keysym.M-C-c: selection:rot13
1277
1278=item perl:STRING *DEPRECATED*
1279
1280This is a deprecated way of invoking commands provided by perl
1281extensions. It is still supported, but should not be used anymore.
1282
1283=back
1254 1284
1255=item B<perl-ext-common>: I<string> 1285=item B<perl-ext-common>: I<string>
1256 1286
1257=item B<perl-ext>: I<string> 1287=item B<perl-ext>: I<string>
1258 1288
1259Comma-separated list(s) of perl extension scripts (default: C<default>) to 1289Comma-separated list(s) of perl extension scripts (default: C<default>) to
1260use in this terminal instance; option B<-pe>. 1290use in this terminal instance; option B<-pe>.
1261 1291
1262Extension names can be prefixed with a C<-> sign to prohibit using 1292Extension names can be prefixed with a C<-> sign to remove them again, in
1263them. This can be useful to selectively disable some extensions loaded 1293case they had been specified earlier. This can be useful to selectively
1264by default, or specified via the C<perl-ext-common> resource. For 1294disable some extensions loaded by default, or specified via the
1265example, C<default,-selection> will use all the default extension except 1295C<perl-ext-common> resource. For example, C<default,-selection> will use
1266C<selection>. 1296all the default extensions except C<selection>.
1267 1297
1268Extension names can also be followed by an argument in angle brackets 1298To prohibit autoloading of extensions, you can prefix them with C</>,
1269(e.g. C<< searchable-scrollback<M-s> >>, which binds the hotkey for 1299which will make urxvt refuse to automatically load them (this can be
1270searchable scrollback to Alt/Meta-s). Mentioning the same extension 1300overriden, however, by specifying the extension name again without a
1271multiple times with different arguments will pass multiple arguments to 1301prefix, though). This does not prohibit extensions themselves loading
1272the extension. 1302other extensions. For example, C<default,/background> will keep the
1303C<background> extension from being loaded when a background OSC sequence
1304is received.
1305
1306The default set includes the C<selection>, C<option-popup>,
1307C<selection-popup>, C<readline>, C<searchable-scrollback> and
1308C<confirm-paste> extensions, as well as any extensions which are mentioned
1309in B<keysym> resources.
1310
1311Any extension such that a corresponding resource is given on the
1312command line is automatically appended to B<perl-ext>.
1273 1313
1274Each extension is looked up in the library directories, loaded if 1314Each extension is looked up in the library directories, loaded if
1275necessary, and bound to the current terminal instance. 1315necessary, and bound to the current terminal instance. When the library
1316search path contains multiple extension files of the same name, then the
1317first one found will be used.
1276 1318
1277If both of these resources are the empty string, then the perl 1319If both of these resources are the empty string, then the perl interpreter
1278interpreter will not be initialized. The idea behind two options is that 1320will not be initialized. The rationale for having two options is that
1279B<perl-ext-common> will be used for extensions that should be available to 1321B<perl-ext-common> will be used for extensions that should be available to
1280all instances, while B<perl-ext> is used for specific instances. 1322all instances, while B<perl-ext> is used for specific instances.
1281 1323
1282=item B<perl-eval>: I<string> 1324=item B<perl-eval>: I<string>
1283 1325
… …
1301=item B<< selection-autotransform.I<idx> >>: I<perl-transform> 1343=item B<< selection-autotransform.I<idx> >>: I<perl-transform>
1302 1344
1303Selection auto-transform patterns, see the @@RXVT_NAME@@perl(3) manpage 1345Selection auto-transform patterns, see the @@RXVT_NAME@@perl(3) manpage
1304for details. 1346for details.
1305 1347
1306=item B<searchable-scrollback:> I<keysym> 1348=item B<searchable-scrollback:> I<keysym> *DEPRECATED*
1307 1349
1308Sets the hotkey that starts the incremental scrollback buffer search 1350This resource is deprecated and will be removed. Use a B<keysym> resource
1309(default: C<M-s>). 1351instead, e.g.:
1310 1352
1353 URxvt.keysym.M-s: searchable-scrollback:start
1354
1311=item B<urlLauncher>: I<string> 1355=item B<url-launcher>: I<string>
1312 1356
1313Specifies the program to be started with a URL argument. Used by the 1357Specifies the program to be started with a URL argument. Used by the
1314C<selection-popup> and C<matcher> perl extensions. 1358C<selection-popup> and C<matcher> perl extensions.
1315 1359
1316=item B<transient-for>: I<windowid> 1360=item B<transient-for>: I<windowid>
… …
1360=head1 THE SELECTION: SELECTING AND PASTING TEXT 1404=head1 THE SELECTION: SELECTING AND PASTING TEXT
1361 1405
1362The behaviour of text selection and insertion/pasting mechanism is similar 1406The behaviour of text selection and insertion/pasting mechanism is similar
1363to I<xterm>(1). 1407to I<xterm>(1).
1364 1408
1365=over 4 1409=over
1366 1410
1367=item B<Selecting>: 1411=item B<Selecting>:
1368 1412
1369Left click at the beginning of the region, drag to the end of the region 1413Left click at the beginning of the region, drag to the end of the region
1370and release; Right click to extend the marked region; Left double-click 1414and release; Right click to extend the marked region; Left double-click
… …
1385B<Meta> modifier) to be inserted as if it had been typed on the keyboard. 1429B<Meta> modifier) to be inserted as if it had been typed on the keyboard.
1386 1430
1387Pressing B<Shift-Insert> causes the value of the PRIMARY selection to be 1431Pressing B<Shift-Insert> causes the value of the PRIMARY selection to be
1388inserted too. 1432inserted too.
1389 1433
1434rxvt-unicode also provides the bindings B<Ctrl-Meta-c> and
1435<Ctrl-Meta-v> to interact with the CLIPBOARD selection. The first
1436binding causes the value of the internal selection to be copied to the
1437CLIPBOARD selection, while the second binding causes the value of the
1438CLIPBOARD selection to be inserted.
1439
1390=back 1440=back
1391 1441
1392=head1 CHANGING FONTS 1442=head1 CHANGING FONTS
1393 1443
1394Changing fonts (or font sizes, respectively) via the keypad is not yet 1444Changing fonts (or font sizes, respectively) via the keypad is not yet
… …
1411and character codes using the keyboard. It consists of 4 parts. The 1461and character codes using the keyboard. It consists of 4 parts. The
1412first part is available if rxvt-unicode has been compiled with 1462first part is available if rxvt-unicode has been compiled with
1413C<--enable-frills>, the rest is available when rxvt-unicode was compiled 1463C<--enable-frills>, the rest is available when rxvt-unicode was compiled
1414with C<--enable-iso14755>. 1464with C<--enable-iso14755>.
1415 1465
1416=over 4 1466=over
1417 1467
1418=item * 5.1: Basic method 1468=item * 5.1: Basic method
1419 1469
1420This allows you to enter unicode characters using their hexcode. 1470This allows you to enter unicode characters using their hexcode.
1421 1471
… …
1482In addition to the default foreground and background colours, 1532In addition to the default foreground and background colours,
1483B<@@RXVT_NAME@@> can display up to 88/256 colours: 8 ANSI colours plus 1533B<@@RXVT_NAME@@> can display up to 88/256 colours: 8 ANSI colours plus
1484high-intensity (potentially bold/blink) versions of the same, and 72 (or 1534high-intensity (potentially bold/blink) versions of the same, and 72 (or
1485240 in 256 colour mode) colours arranged in an 4x4x4 (or 6x6x6) colour RGB 1535240 in 256 colour mode) colours arranged in an 4x4x4 (or 6x6x6) colour RGB
1486cube plus a 8 (24) colour greyscale ramp. 1536cube plus a 8 (24) colour greyscale ramp.
1537
1538B<@@RXVT_NAME@@> supports direct 24-bit fg/bg RGB colour escapes
1539C< ESC [ 38 ; 2 ; R ; G ; Bm > / C< ESC [ 48 ; 2; R ; G ; Bm >. However the
1540number of 24-bit colours that can be used is limited: an internal 7x7x5 (256
1541colour mode) or 6x6x4 (88 colour mode) colour cube is used to index into the
154224-bit colour space. When indexing collisions happen, the nearest old colour in
1543the cube will be adapted to the new 24-bit RGB colour. That means one cannot
1544use many similar 24-bit colours. It's typically not a problem in common
1545scenarios.
1487 1546
1488Here is a list of the ANSI colours with their names. 1547Here is a list of the ANSI colours with their names.
1489 1548
1490=begin table 1549=begin table
1491 1550
… …
1518The following text gives values for the standard 88 colour mode (and 1577The following text gives values for the standard 88 colour mode (and
1519values for the 256 colour mode in parentheses). 1578values for the 256 colour mode in parentheses).
1520 1579
1521The RGB cube uses indices 16..79 (16..231) using the following formulas: 1580The RGB cube uses indices 16..79 (16..231) using the following formulas:
1522 1581
1523 index_88 = (r * 4 + g) * 4 + b + 16 # r, g, b = 0..3 1582 index_88 = (r * 4 + g) * 4 + b + 16 # r, g, b = 0..3
1524 index_256 = (r * 16 + g) * 16 + b + 16 # r, g, b = 0..15 1583 index_256 = (r * 6 + g) * 6 + b + 16 # r, g, b = 0..5
1525 1584
1526The grayscale ramp uses indices 80..87 (232..239), from 10% to 90% in 10% 1585The grayscale ramp uses indices 80..87 (232..239), from 10% to 90% in 10%
1527steps (1/26 to 25/26 in 1/26 steps) - black and white are already part of 1586steps (1/26 to 25/26 in 1/26 steps) - black and white are already part of
1528the RGB cube. 1587the RGB cube.
1529 1588
… …
1592 1651
1593=head1 ENVIRONMENT 1652=head1 ENVIRONMENT
1594 1653
1595B<@@RXVT_NAME@@> sets and/or uses the following environment variables: 1654B<@@RXVT_NAME@@> sets and/or uses the following environment variables:
1596 1655
1597=over 4 1656=over
1598 1657
1599=item B<TERM> 1658=item B<TERM>
1600 1659
1601Normally set to C<rxvt-unicode>, unless overwritten at configure time, via 1660Normally set to C<rxvt-unicode>, unless overwritten at configure time, via
1602resources or on the command line. 1661resources or on the command line.
… …
1673 1732
1674=back 1733=back
1675 1734
1676=head1 FILES 1735=head1 FILES
1677 1736
1678=over 4 1737=over
1679 1738
1680=item B</usr/lib/X11/rgb.txt> 1739=item B</usr/lib/X11/rgb.txt>
1681 1740
1682Colour names. 1741Colour names.
1683 1742
1684=back 1743=back
1685 1744
1686=head1 SEE ALSO 1745=head1 SEE ALSO
1687 1746
1688@@RXVT_NAME@@(7), @@RXVT_NAME@@c(1), @@RXVT_NAME@@d(1), @@RXVT_NAME@@perl(3), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5) 1747@@RXVT_NAME@@(7), @@RXVT_NAME@@c(1), @@RXVT_NAME@@d(1), @@RXVT_NAME@@-extensions(1),
1748@@RXVT_NAME@@perl(3), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5)
1689 1749
1690=head1 CURRENT PROJECT COORDINATOR 1750=head1 CURRENT PROJECT COORDINATOR
1691 1751
1692=over 4 1752=over
1693 1753
1694=item Project Coordinator 1754=item Project Coordinator
1695 1755
1696Marc A. Lehmann L<< <rxvt-unicode@schmorp.de> >> 1756Marc A. Lehmann <rxvt-unicode@schmorp.de>.
1697 1757
1698L<http://software.schmorp.de/pkg/rxvt-unicode.html> 1758L<http://software.schmorp.de/pkg/rxvt-unicode.html>
1699 1759
1700=back 1760=back
1701 1761
1702=head1 AUTHORS 1762=head1 AUTHORS
1703 1763
1704=over 4 1764=over
1705 1765
1706=item John Bovey 1766=item John Bovey
1707 1767
1708University of Kent, 1992, wrote the original Xvt. 1768University of Kent, 1992, wrote the original Xvt.
1709 1769
1710=item Rob Nation L<< <nation@rocket.sanders.lockheed.com> >> 1770=item Rob Nation <nation@rocket.sanders.lockheed.com>
1711 1771
1712very heavily modified Xvt and came up with Rxvt 1772very heavily modified Xvt and came up with Rxvt
1713 1773
1714=item Angelo Haritsis L<< <ah@doc.ic.ac.uk> >> 1774=item Angelo Haritsis <ah@doc.ic.ac.uk>
1715 1775
1716wrote the Greek Keyboard Input (no longer in code) 1776wrote the Greek Keyboard Input (no longer in code)
1717 1777
1718=item mj olesen L<< <olesen@me.QueensU.CA> >> 1778=item mj olesen <olesen@me.QueensU.CA>
1719 1779
1720Wrote the menu system. 1780Wrote the menu system.
1721 1781
1722Project Coordinator (changes.txt 2.11 to 2.21) 1782Project Coordinator (changes.txt 2.11 to 2.21)
1723 1783
1724=item Oezguer Kesim L<< <kesim@math.fu-berlin.de> >> 1784=item Oezguer Kesim <kesim@math.fu-berlin.de>
1725 1785
1726Project Coordinator (changes.txt 2.21a to 2.4.5) 1786Project Coordinator (changes.txt 2.21a to 2.4.5)
1727 1787
1728=item Geoff Wing L<< <gcw@pobox.com> >> 1788=item Geoff Wing <gcw@pobox.com>
1729 1789
1730Rewrote screen display and text selection routines. 1790Rewrote screen display and text selection routines.
1731 1791
1732Project Coordinator (changes.txt 2.4.6 - rxvt-unicode) 1792Project Coordinator (changes.txt 2.4.6 - rxvt-unicode)
1733 1793
1734=item Marc Alexander Lehmann L<< <rxvt-unicode@schmorp.de> >> 1794=item Marc Alexander Lehmann <rxvt-unicode@schmorp.de>
1735 1795
1736Forked rxvt-unicode, unicode support, rewrote almost all the code, perl 1796Forked rxvt-unicode, unicode support, rewrote almost all the code, perl
1737extension, random hacks, numerous bugfixes and extensions. 1797extension, random hacks, numerous bugfixes and extensions.
1738 1798
1739Project Coordinator (Changes 1.0 -) 1799Project Coordinator (Changes 1.0 -)
1740 1800
1741=item Emanuele Giaquinta L<< <e.giaquinta@glauco.it> >> 1801=item Emanuele Giaquinta <emanuele.giaquinta@gmail.com>
1742 1802
1743pty/utmp code rewrite, image code improvements, many random hacks and bugfixes. 1803pty/utmp code rewrite, image code improvements, many random hacks and bugfixes.
1744 1804
1745=back 1805=back
1746 1806

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines