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.59 by root, Thu Feb 17 15:07:48 2005 UTC vs.
Revision 1.108 by root, Sun Jan 29 21:45:47 2006 UTC

93 93
94Attempt to open a window on the named X display (B<-d> still 94Attempt to open a window on the named X display (B<-d> still
95respected). In the absence of this option, the display specified by the 95respected). In the absence of this option, the display specified by the
96B<DISPLAY> environment variable is used. 96B<DISPLAY> environment variable is used.
97 97
98=item B<-depth> I<bitdepth>
99
100Compile I<frills>: Attempt to find a visual with the given bit depth;
101resource B<depth>.
102
98=item B<-geometry> I<geom> 103=item B<-geometry> I<geom>
99 104
100Window geometry (B<-g> still respected); resource B<geometry>. 105Window geometry (B<-g> still respected); resource B<geometry>.
101 106
102=item B<-rv>|B<+rv> 107=item B<-rv>|B<+rv>
105 110
106=item B<-j>|B<+j> 111=item B<-j>|B<+j>
107 112
108Turn on/off jump scrolling; resource B<jumpScroll>. 113Turn on/off jump scrolling; resource B<jumpScroll>.
109 114
110=item B<-ip>|B<+ip> 115=item B<-ip>|B<+ip> | B<-tr>|B<+tr>
111 116
112Turn on/off inheriting parent window's pixmap. Alternative form is 117Turn on/off inheriting parent window's pixmap. Alternative form is
113B<-tr>; resource B<inheritPixmap>. 118B<-tr>; resource B<inheritPixmap>.
114 119
115=item B<-fade> I<number> 120=item B<-fade> I<number>
116 121
117Fade the text by the given percentage when focus is lost. resource B<fading>. 122Fade the text by the given percentage when focus is lost. Small values
123fade a little only, 100 completely replaces all colours by the fade
124colour; resource B<fading>.
125
126=item B<-fadecolor> I<colour>
127
128Fade to this colour when fading is used (see B<-fade>). The default colour
129is black. resource B<fadeColor>.
118 130
119=item B<-tint> I<colour> 131=item B<-tint> I<colour>
120 132
121Tint the transparent background pixmap with the given colour when 133Tint the transparent background pixmap with the given colour when
122transparency is enabled with B<-tr> or B<-ip>. See also the B<-sh> 134transparency is enabled with B<-tr> or B<-ip>. This only works for
123option that can be used to brighten or darken the image in addition to 135non-tiled backgrounds, currently. See also the B<-sh> option that can be
124tinting it. 136used to brighten or darken the image in addition to tinting it; resource
137I<tintColor>. Example:
138
139 @@RXVT_NAME@@ -tr -tint blue -sh 40
125 140
126=item B<-sh> 141=item B<-sh>
127 142
128I<number> Darken (0 .. 100) or lighten (-1 .. -100) the transparent 143I<number> Darken (0 .. 100) or lighten (-1 .. -100) the transparent
129background image in addition to tinting it (i.e. B<-tint> must be 144background image in addition to tinting it (i.e. B<-tint> must be
162resource B<borderColor>. 177resource B<borderColor>.
163 178
164=item B<-fn> I<fontlist> 179=item B<-fn> I<fontlist>
165 180
166Select the fonts to be used. This is a comma separated list of font names 181Select the fonts to be used. This is a comma separated list of font names
167that are used in turn when trying to display Unicode characters. The 182that are checked in order when trying to find glyphs for characters. The
168first font defines the cell size for characters; other fonts might be 183first font defines the cell size for characters; other fonts might be
169smaller, but not (in general) larger. A (hopefully) reasonable default 184smaller, but not (in general) larger. A (hopefully) reasonable default
170font list is always appended to it. See resource B<font> for more details. 185font list is always appended to it. See resource B<font> for more details.
171 186
172In short, to specify an X11 core font, just specify it's name or prefix it 187In short, to specify an X11 core font, just specify it's name or prefix it
179See also the question "How does rxvt-unicode choose fonts?" in the FAQ 194See also the question "How does rxvt-unicode choose fonts?" in the FAQ
180section of @@RXVT_NAME@@(7). 195section of @@RXVT_NAME@@(7).
181 196
182=item B<-fb> I<fontlist> 197=item B<-fb> I<fontlist>
183 198
184Compile font-styles: The bold font list to use when bold characters are to 199Compile I<font-styles>: The bold font list to use when B<bold> characters
185be printed. See resource B<boldFont> for details. 200are to be printed. See resource B<boldFont> for details.
186 201
187=item B<-fi> I<fontlist> 202=item B<-fi> I<fontlist>
188 203
189Compile font-styles: The italic font list to use when bold characters are to 204Compile I<font-styles>: The italic font list to use when I<italic>
190be printed. See resource B<italicFont> for details. 205characters are to be printed. See resource B<italicFont> for details.
191 206
192=item B<-fbi> I<fontlist> 207=item B<-fbi> I<fontlist>
193 208
194Compile font-styles: The bold italic font list to use when bold characters are to 209Compile I<font-styles>: The bold italic font list to use when B<< I<bold
195be printed. See resource B<boldItalicFont> for details. 210italic> >> characters are to be printed. See resource B<boldItalicFont>
211for details.
212
213=item B<-is>|B<+is>
214
215Compile I<font-styles>: Bold/Italic font styles imply high intensity
216foreground/background (default). See resource B<intensityStyles> for
217details.
196 218
197=item B<-name> I<name> 219=item B<-name> I<name>
198 220
199Specify the application name under which resources are to be obtained, 221Specify the application name under which resources are to be obtained,
200rather than the default executable file name. Name should not contain 222rather than the default executable file name. Name should not contain
238 260
239Put scrollbar on right/left; resource B<scrollBar_right>. 261Put scrollbar on right/left; resource B<scrollBar_right>.
240 262
241=item B<-st>|B<+st> 263=item B<-st>|B<+st>
242 264
243Display normal (non XTerm/NeXT) scrollbar without/with a trough; 265Display rxvt (non XTerm/NeXT) scrollbar without/with a trough;
244resource B<scrollBar_floating>. 266resource B<scrollBar_floating>.
245 267
246=item B<-ptab>|B<+ptab> 268=item B<-ptab>|B<+ptab>
247 269
248If enabled (default), "Horizontal Tab" characters are being stored as 270If enabled (default), "Horizontal Tab" characters are being stored as
279=item B<-bl> 301=item B<-bl>
280 302
281Compile I<frills>: Set MWM hints to request a borderless window, i.e. 303Compile I<frills>: Set MWM hints to request a borderless window, i.e.
282if honoured by the WM, the rxvt-unicode window will not have window 304if honoured by the WM, the rxvt-unicode window will not have window
283decorations; resource B<borderLess>. 305decorations; resource B<borderLess>.
306
307=item B<-override-redirect>
308
309Compile I<frills>: Sets override-redirect on the window; resource
310B<override-redirect>.
311
312=item B<-sbg>
313
314Compile I<frills>: Disable the usage of the built-in block graphics/line
315drawing characters and just rely on what the specified fonts provide. Use
316this if you have a good font and want to use its block graphic glyphs;
317resource B<skipBuiltinGlyphs>.
284 318
285=item B<-lsp> I<number> 319=item B<-lsp> I<number>
286 320
287Compile I<frills>: Lines (pixel height) to insert between each row of 321Compile I<frills>: Lines (pixel height) to insert between each row of
288the display. Useful to work around font rendering problems; resource 322the display. Useful to work around font rendering problems; resource
303given on the command line. If this option is used, it must be the last 337given on the command line. If this option is used, it must be the last
304on the command-line. If there is no B<-e> option then the default is to 338on the command-line. If there is no B<-e> option then the default is to
305run the program specified by the B<SHELL> environment variable or, 339run the program specified by the B<SHELL> environment variable or,
306failing that, I<sh(1)>. 340failing that, I<sh(1)>.
307 341
342Please note that you must specify a program with arguments. If you want to
343run shell commands, you have to specify the shell, like this:
344
345 @@RXVT_NAME@@ -e sh -c "shell commands"
346
308=item B<-title> I<text> 347=item B<-title> I<text>
309 348
310Window title (B<-T> still respected); the default title is the basename 349Window title (B<-T> still respected); the default title is the basename
311of the program specified after the B<-e> option, if any, otherwise the 350of the program specified after the B<-e> option, if any, otherwise the
312application name; resource B<title>. 351application name; resource B<title>.
367 406
368=item B<-ssr>|B<+ssr> 407=item B<-ssr>|B<+ssr>
369 408
370Turn on/off secondary screen scroll (default enabled); resource 409Turn on/off secondary screen scroll (default enabled); resource
371B<secondaryScroll>. 410B<secondaryScroll>.
411
412=item B<-hold>|B<+hold>
413
414Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@
415will not immediately destroy its window when the program executed within
416it exits. Instead, it will wait till it is being killed or closed by the
417user; resource B<hold>.
372 418
373=item B<-keysym.>I<sym> I<string> 419=item B<-keysym.>I<sym> I<string>
374 420
375Remap a key symbol. See resource B<keysym>. 421Remap a key symbol. See resource B<keysym>.
376 422
393not. 439not.
394 440
395Here is a short Gtk2-perl snippet that illustrates how this option can be 441Here is a short Gtk2-perl snippet that illustrates how this option can be
396used (a longer example is in F<doc/embed>): 442used (a longer example is in F<doc/embed>):
397 443
398 my $rxvt = new Gtk2::DrawingArea; 444 my $rxvt = new Gtk2::Socket;
399 $...->add ($rxvt); # important to add it somewhere first 445 $rxvt->signal_connect_after (realize => sub {
400 $rxvt->realize; # now it can be realized
401 my $xid = $rxvt->window->get_xid; 446 my $xid = $_[0]->window->get_xid;
402
403 system "@@RXVT_NAME@@ -embed $xid &"; 447 system "@@RXVT_NAME@@ -embed $xid &";
448 });
404 449
405=item B<-pty-fd> I<fileno> 450=item B<-pty-fd> I<file descriptor>
406 451
407Tells @@RXVT_NAME@@ NOT to execute any commands or create a new pty/tty 452Tells @@RXVT_NAME@@ NOT to execute any commands or create a new pty/tty
408pair but instead use the given filehandle as the tty master. This is 453pair but instead use the given filehandle as the tty master. This is
409useful if you want to drive @@RXVT_NAME@@ as a generic terminal emulator 454useful if you want to drive @@RXVT_NAME@@ as a generic terminal emulator
410without having to run a program within it. 455without having to run a program within it.
411 456
412If this switch is given, @@RXVT_NAME@@ will not create any utmp/wtmp 457If this switch is given, @@RXVT_NAME@@ will not create any utmp/wtmp
413entries and will not tinker with pty/tty permissions - you have to do that 458entries and will not tinker with pty/tty permissions - you have to do that
414yourself if you want that. 459yourself if you want that.
415 460
461As an extremely special case, specifying C<-1> will completely suppress
462pty/tty operations.
463
416Here is a example in perl that illustrates how this option can be used (a 464Here is a example in perl that illustrates how this option can be used (a
417longer example is in F<doc/pty-fd>): 465longer example is in F<doc/pty-fd>):
418 466
419 use IO::Pty; 467 use IO::Pty;
420 use Fcntl; 468 use Fcntl;
421 469
422 my $pty = new IO::Pty; 470 my $pty = new IO::Pty;
423 fcntl $pty, F_SETFD, 0; # clear close-on-exec 471 fcntl $pty, F_SETFD, 0; # clear close-on-exec
424
425 system "@@RXVT_NAME@@ -pty-fd " . (fileno $pty) . "&"; 472 system "@@RXVT_NAME@@ -pty-fd " . (fileno $pty) . "&";
473 close $pty;
426 474
427 # now communicate with rxvt 475 # now communicate with rxvt
428 my $slave = $pty->slave; 476 my $slave = $pty->slave;
429 while (<$slave>) { print $slave "got <$_>\n" } 477 while (<$slave>) { print $slave "got <$_>\n" }
430 478
479=item B<-pe> I<string>
480
481Comma-separated list of perl extension scripts to use (or not to use) in
482this terminal instance. See resource B<perl-ext> for details.
483
431=back 484=back
432 485
433=head1 RESOURCES (available also as long-options) 486=head1 RESOURCES (available also as long-options)
434 487
435Note: `@@RXVT_NAME@@ --help' gives a list of all resources (long 488Note: `@@RXVT_NAME@@ --help' gives a list of all resources (long
436options) compiled into your version. 489options) compiled into your version.
437 490
438There are two different methods that @@RXVT_NAME@@ can use to get the 491You can set and change the resources using X11 tools like B<xrdb>. Many
439Xresource data: using the X libraries (Xrm*-functions) or internal 492distribution do also load settings from the B<~/.Xresources> file when X
440Xresources reader (B<~/.Xdefaults>). For the first method (ie. 493starts. @@RXVT_NAME@@ will consult the following files/resources in order,
441B<@@RXVT_NAME@@ -h> lists B<XGetDefaults>), you can set and change the 494with later settings overwriting earlier ones:
442resources using X11 tools like B<xrdb>. Many distribution do also load
443settings from the B<~/.Xresources> file when X starts. @@RXVT_NAME@@
444will consult the following files/resources in order, with later settings
445overwriting earlier ones:
446 495
447 1. system-wide app-defaults file, either locale-dependent OR global 496 1. system-wide app-defaults file, either locale-dependent OR global
448 2. app-defaults file in $XAPPLRESDIR 497 2. app-defaults file in $XAPPLRESDIR
449 3. RESOURCE_MANAGER property on root-window OR $HOME/.Xdefaults 498 3. RESOURCE_MANAGER property on root-window OR $HOME/.Xdefaults
450 4. SCREEN_RESOURCES for the current screen 499 4. SCREEN_RESOURCES for the current screen
451 5. $XENVIRONMENT file OR $HOME/.Xdefaults-<nodename> 500 5. $XENVIRONMENT file OR $HOME/.Xdefaults-<nodename>
452 501
453If compiled with internal Xresources support (i.e. B<@@RXVT_NAME@@ -h>
454lists B<.Xdefaults>) then B<@@RXVT_NAME@@> accepts application defaults
455set in XAPPLOADDIR/URxvt (compile-time defined: usually
456B</usr/lib/X11/app-defaults/URxvt>) and resources set in
457B<~/.Xdefaults>, or B<~/.Xresources> if B<~/.Xdefaults> does not exist.
458Note that when reading X resources, B<@@RXVT_NAME@@> recognizes two 502Note that when reading X resources, B<@@RXVT_NAME@@> recognizes two class
459class names: B<XTerm> and B<URxvt>. The class name B<Rxvt> allows 503names: B<Rxvt> and B<URxvt>. The class name B<Rxvt> allows resources
460resources common to both B<@@RXVT_NAME@@> and the original I<rxvt> to be 504common to both B<@@RXVT_NAME@@> and the original I<rxvt> to be easily
461easily configured, while the class name B<URxvt> allows resources 505configured, while the class name B<URxvt> allows resources unique to
462unique to B<@@RXVT_NAME@@>, notably colours and key-handling, to be 506B<@@RXVT_NAME@@>, to be shared between different B<@@RXVT_NAME@@>
463shared between different B<@@RXVT_NAME@@> configurations. If no 507configurations. If no resources are specified, suitable defaults will
464resources are specified, suitable defaults will be used. Command-line 508be used. Command-line arguments can be used to override resource
465arguments can be used to override resource settings. The following 509settings. The following resources are supported (you might want to
466resources are allowed: 510check the @@RXVT_NAME@@perl(3) manpage for additional settings by perl
511extensions not documented here):
467 512
468=over 4 513=over 4
514
515=item B<depth:> I<bitdepth>
516
517Compile I<frills>: Attempt to find a visual with the given bit depth;
518option B<-depth>.
469 519
470=item B<geometry:> I<geom> 520=item B<geometry:> I<geom>
471 521
472Create the window with the specified X window geometry [default 80x24]; 522Create the window with the specified X window geometry [default 80x24];
473option B<-geometry>. 523option B<-geometry>.
549artificial transparency. B<False>: do not inherit the parent windows' 599artificial transparency. B<False>: do not inherit the parent windows'
550pixmap. 600pixmap.
551 601
552=item B<fading:> I<number> 602=item B<fading:> I<number>
553 603
554Fade the text by the given percentage when focus is lost. 604Fade the text by the given percentage when focus is lost; option B<-fade>.
605
606=item B<fadeColor:> I<colour>
607
608Fade to this colour, when fading is used (see B<fading:>). The default
609colour is black; option B<-fadecolor>.
555 610
556=item B<tintColor:> I<colour> 611=item B<tintColor:> I<colour>
557 612
558Tint the transparent background pixmap with the given colour. 613Tint the transparent background pixmap with the given colour; option
614B<-tint>.
559 615
560=item B<shading:> I<number> 616=item B<shading:> I<number>
561 617
562Darken (0 .. 100) or lighten (-1 .. -100) the transparent background 618Darken (0 .. 100) or lighten (-1 .. -100) the transparent background
563image in addition to tinting it. 619image in addition to tinting it.
567Use the specified colour for the scrollbar [default #B2B2B2]. 623Use the specified colour for the scrollbar [default #B2B2B2].
568 624
569=item B<troughColor:> I<colour> 625=item B<troughColor:> I<colour>
570 626
571Use the specified colour for the scrollbar's trough area [default 627Use the specified colour for the scrollbar's trough area [default
572#969696]. Only relevant for normal (non XTerm/NeXT) scrollbar. 628#969696]. Only relevant for rxvt (non XTerm/NeXT) scrollbar.
573 629
574=item B<borderColor:> I<colour> 630=item B<borderColor:> I<colour>
575 631
576The colour of the border around the text area and between the scrollbar 632The colour of the border around the text area and between the scrollbar
577and the text. 633and the text.
586of 1 displays the image without any scaling. A scale of 2 to 9 642of 1 displays the image without any scaling. A scale of 2 to 9
587specifies an integer number of images in that direction. No image will 643specifies an integer number of images in that direction. No image will
588be magnified beyond 10 times its original size. The maximum permitted 644be magnified beyond 10 times its original size. The maximum permitted
589scale is 1000. [default 0x0+50+50] 645scale is 1000. [default 0x0+50+50]
590 646
591=item B<menu:> I<file[;tag]>
592
593Read in the specified menu file (note the `.menu' extension is
594optional) and also optionally specify a starting tag to find. See the
595reference documentation for details on the syntax for the menuBar.
596
597=item B<path:> I<path> 647=item B<path:> I<path>
598 648
599Specify the colon-delimited search path for finding files (XPM and 649Specify the colon-delimited search path for finding XPM files.
600menus), in addition to the paths specified by the B<RXVTPATH> and
601B<PATH> environment variables.
602 650
603=item B<font:> I<fontlist> 651=item B<font:> I<fontlist>
604 652
605Select the fonts to be used. This is a comma separated list of font 653Select the fonts to be used. This is a comma separated list of font names
606names that are used in turn when trying to display Unicode characters. 654that are checked in order when trying to find glyphs for characters. The
607The first font defines the cell size for characters; other fonts might 655first font defines the cell size for characters; other fonts might be
608be smaller, but not larger. A reasonable default font list is always 656smaller, but not (in general) larger. A (hopefully) reasonable default
609appended to it. option B<-fn>. 657font list is always appended to it; option B<-fn>.
610 658
611Each font can either be a standard X11 core font (XLFD) name, with 659Each font can either be a standard X11 core font (XLFD) name, with
612optional prefix C<x:> or a Xft font (Compile I<xft>), prefixed with C<xft:>. 660optional prefix C<x:> or a Xft font (Compile I<xft>), prefixed with C<xft:>.
613 661
614In addition, each font can be prefixed with additional hints and 662In addition, each font can be prefixed with additional hints and
616hint currently is C<codeset=codeset-name>, and this is only used for Xft 664hint currently is C<codeset=codeset-name>, and this is only used for Xft
617fonts. 665fonts.
618 666
619For example, this font resource 667For example, this font resource
620 668
621 URxvt*font: 9x15bold,\ 669 URxvt.font: 9x15bold,\
622 -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso10646-1,\ 670 -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso10646-1,\
623 -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1, \ 671 -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1, \
624 [codeset=JISX0208]xft:Kochi Gothic:antialias=false, \ 672 [codeset=JISX0208]xft:Kochi Gothic:antialias=false, \
625 xft:Code2000:antialias=false 673 xft:Code2000:antialias=false
626 674
660not possible, replacement fonts of the desired shape will be tried. 708not possible, replacement fonts of the desired shape will be tried.
661 709
662If set, but empty, then this specific style is disabled and the normal 710If set, but empty, then this specific style is disabled and the normal
663text font will being used for the given style. 711text font will being used for the given style.
664 712
713=item B<intensityStyles:> I<boolean>
714
715When font styles are not enabled, or this option is enabled (B<True>,
716option B<-is>, the default), bold and italic font styles imply high
717intensity foreground/backround colours. Disabling this option (B<False>,
718option B<+is>) disables this behaviour, the high intensity colours are not
719reachable.
720
665=item B<selectstyle:> I<mode> 721=item B<selectstyle:> I<mode>
666 722
667Set mouse selection style to B<old> which is 2.20, B<oldword> which is 723Set mouse selection style to B<old> which is 2.20, B<oldword> which is
668xterm style with 2.20 old word selection, or anything else which gives 724xterm style with 2.20 old word selection, or anything else which gives
669xterm style selection. 725xterm style selection.
670 726
671=item B<scrollstyle:> I<mode> 727=item B<scrollstyle:> I<mode>
672 728
673Set scrollbar style to B<rxvt>, B<plain>, B<next> or B<xterm>. B<plain> is 729Set scrollbar style to B<rxvt>, B<plain>, B<next> or B<xterm>. B<plain> is
674the author's favourite.. 730the author's favourite.
675 731
676=item B<title:> I<string> 732=item B<title:> I<string>
677 733
678Set window title string, the default title is the command-line 734Set window title string, the default title is the command-line
679specified after the B<-e> option, if any, otherwise the application 735specified after the B<-e> option, if any, otherwise the application
710=item B<print-pipe:> I<string> 766=item B<print-pipe:> I<string>
711 767
712Specify a command pipe for vt100 printer [default I<lpr(1)>]. Use 768Specify a command pipe for vt100 printer [default I<lpr(1)>]. Use
713B<Print> to initiate a screen dump to the printer and B<Ctrl-Print> or 769B<Print> to initiate a screen dump to the printer and B<Ctrl-Print> or
714B<Shift-Print> to include the scrollback as well. 770B<Shift-Print> to include the scrollback as well.
771
772The string will be interpreted as if typed into the shell as-is.
773
774Example:
775
776 URxvt.print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX)
777
778This creates a new file in your home directory with the screen contents
779everytime you hit C<Print>.
715 780
716=item B<scrollBar:> I<boolean> 781=item B<scrollBar:> I<boolean>
717 782
718B<True>: enable the scrollbar [default]; option B<-sb>. B<False>: 783B<True>: enable the scrollbar [default]; option B<-sb>. B<False>:
719disable the scrollbar; option B<+sb>. 784disable the scrollbar; option B<+sb>.
770=item B<borderLess:> I<boolean> 835=item B<borderLess:> I<boolean>
771 836
772Set MWM hints to request a borderless window, i.e. if honoured by the 837Set MWM hints to request a borderless window, i.e. if honoured by the
773WM, the rxvt-unicode window will not have window decorations; option B<-bl>. 838WM, the rxvt-unicode window will not have window decorations; option B<-bl>.
774 839
840=item B<skipBuiltinGlyphs:> I<boolean>
841
842Compile I<frills>: Disable the usage of the built-in block graphics/line
843drawing characters and just rely on what the specified fonts provide. Use
844this if you have a good font and want to use its block graphic glyphs;
845option B<-sbg>.
846
775=item B<termName:> I<termname> 847=item B<termName:> I<termname>
776 848
777Specifies the terminal type name to be set in the B<TERM> environment 849Specifies the terminal type name to be set in the B<TERM> environment
778variable; option B<-tn>. 850variable; option B<-tn>.
779 851
816 888
817Mouse pointer background colour. 889Mouse pointer background colour.
818 890
819=item B<pointerBlankDelay:> I<number> 891=item B<pointerBlankDelay:> I<number>
820 892
821Specifies number of seconds before blanking the pointer [default 2]. 893Specifies number of seconds before blanking the pointer [default 2]. Use a
894large number (e.g. C<987654321>) to effectively disable the timeout.
822 895
823=item B<backspacekey:> I<string> 896=item B<backspacekey:> I<string>
824 897
825The string to send when the backspace key is pressed. If set to B<DEC> 898The string to send when the backspace key is pressed. If set to B<DEC>
826or unset it will send B<Delete> (code 127) or, if shifted, B<Backspace> 899or unset it will send B<Delete> (code 127) or, if shifted, B<Backspace>
833pressed. If unset it will send the sequence traditionally associated 906pressed. If unset it will send the sequence traditionally associated
834with the B<Execute> key. 907with the B<Execute> key.
835 908
836=item B<cutchars:> I<string> 909=item B<cutchars:> I<string>
837 910
838The characters used as delimiters for double-click word selection. The 911The characters used as delimiters for double-click word selection
839built-in default: 912(whitespace delimiting is added automatically if resource is given).
913
914When the selection extension is in use (the default if compiled in, see
915the @@RXVT_NAME@@perl(3) manpage), a suitable regex using these characters
916will be created (if the resource exists, otherwise, no regex will be
917created). In this mode, characters outside ISO-8859-1 can be used.
918
919When the selection extension is not used, only ISO-8859-1 characters can
920be used. If not specified, the built-in default is used:
840 921
841B<< BACKSLASH `"'&()*,;<=>?@[]{|} >> 922B<< BACKSLASH `"'&()*,;<=>?@[]{|} >>
842 923
843=item B<preeditType:> I<style> 924=item B<preeditType:> I<style>
844 925
851=item B<imLocale:> I<name> 932=item B<imLocale:> I<name>
852 933
853The locale to use for opening the IM. You can use an C<LC_CTYPE> of e.g. 934The locale to use for opening the IM. You can use an C<LC_CTYPE> of e.g.
854C<de_DE.UTF-8> for normal text processing but C<ja_JP.EUC-JP> for the 935C<de_DE.UTF-8> for normal text processing but C<ja_JP.EUC-JP> for the
855input extension to be able to input japanese characters while staying in 936input extension to be able to input japanese characters while staying in
856another locale. option B<-imlocale>. 937another locale; option B<-imlocale>.
857 938
858=item B<imFont:> I<fontset> 939=item B<imFont:> I<fontset>
859 940
860Specify the font-set used for XIM styles C<OverTheSpot> or 941Specify the font-set used for XIM styles C<OverTheSpot> or
861C<OffTheSpot>. It must be a standard X font set (XLFD patterns separated 942C<OffTheSpot>. It must be a standard X font set (XLFD patterns separated
866 947
867=item B<tripleclickwords:> I<boolean> 948=item B<tripleclickwords:> I<boolean>
868 949
869Change the meaning of triple-click selection with the left mouse 950Change the meaning of triple-click selection with the left mouse
870button. Instead of selecting a full line it will extend the selection to 951button. Instead of selecting a full line it will extend the selection to
871the end of the logical line only. option B<-tcw>. 952the end of the logical line only; option B<-tcw>.
872 953
873=item B<insecure:> I<boolean> 954=item B<insecure:> I<boolean>
874 955
875Enables "insecure" mode. Rxvt-unicode offers some escape sequences that 956Enables "insecure" mode. Rxvt-unicode offers some escape sequences that
876echo arbitrary strings like the icon name or the locale. This could be 957echo arbitrary strings like the icon name or the locale. This could be
877abused if somebody gets 8-bit-clean access to your display, whether 958abused if somebody gets 8-bit-clean access to your display, whether
878throuh a mail client displaying mail bodies unfiltered or though 959through a mail client displaying mail bodies unfiltered or through
879write(1). Therefore, these sequences are disabled by default. (Note 960write(1) or any other means. Therefore, these sequences are disabled by
880that other terminals, including xterm, have these sequences 961default. (Note that many other terminals, including xterm, have these
881enabled by default). You can enable them by setting this boolean 962sequences enabled by default, which doesn't make it safer, though).
882resource or specifying B<-insecure> as an option. At the moment, this 963
883enabled display-answer, locale, findfont, icon label and window title 964You can enable them by setting this boolean resource or specifying
884requests as well as dynamic menubar dispatch. 965B<-insecure> as an option. At the moment, this enables display-answer,
966locale, findfont, icon label and window title requests.
885 967
886=item B<modifier:> I<modifier> 968=item B<modifier:> I<modifier>
887 969
888Set the key to be interpreted as the Meta key to: B<alt>, B<meta>, 970Set the key to be interpreted as the Meta key to: B<alt>, B<meta>,
889B<hyper>, B<super>, B<mod1>, B<mod2>, B<mod3>, B<mod4>, B<mod5>; option 971B<hyper>, B<super>, B<mod1>, B<mod2>, B<mod3>, B<mod4>, B<mod5>; option
893 975
894Specify the reply rxvt-unicode sends to the shell when an ENQ (control-E) 976Specify the reply rxvt-unicode sends to the shell when an ENQ (control-E)
895character is passed through. It may contain escape values as described 977character is passed through. It may contain escape values as described
896in the entry on B<keysym> following. 978in the entry on B<keysym> following.
897 979
898=item B<secondaryScreen:> I<bool> 980=item B<secondaryScreen:> I<boolean>
899 981
900Turn on/off secondary screen (default enabled). 982Turn on/off secondary screen (default enabled).
901 983
902=item B<secondaryScroll:> I<bool> 984=item B<secondaryScroll:> I<boolean>
903 985
904Turn on/off secondary screen scroll (default enabled). If the this 986Turn on/off secondary screen scroll (default enabled). If the this
905option is enabled, scrolls on the secondary screen will change the 987option is enabled, scrolls on the secondary screen will change the
906scrollback buffer and switching to/from the secondary screen will 988scrollback buffer and switching to/from the secondary screen will
907instead scroll the screen up. 989instead scroll the screen up.
990
991=item B<hold>: I<boolean>
992
993Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@
994will not immediately destroy its window when the program executed within
995it exits. Instead, it will wait till it is being killed or closed by the
996user.
908 997
909=item B<keysym.>I<sym>: I<string> 998=item B<keysym.>I<sym>: I<string>
910 999
911Compile I<frills>: Associate I<string> with keysym I<sym>. The 1000Compile I<frills>: Associate I<string> with keysym I<sym>. The
912intervening resource name B<keysym.> cannot be omitted. 1001intervening resource name B<keysym.> cannot be omitted.
932C<\e>, C<\E>: escape, C<\n>: newline, C<\r>: carriage return, C<\t>: tab, 1021C<\e>, C<\E>: escape, C<\n>: newline, C<\r>: carriage return, C<\t>: tab,
933C<\000>: octal number) or verbatim control characters (C<^?>: delete, 1022C<\000>: octal number) or verbatim control characters (C<^?>: delete,
934C<^@>: null, C<^A> ...) and may be enclosed with double quotes so that it 1023C<^@>: null, C<^A> ...) and may be enclosed with double quotes so that it
935can start or end with whitespace. 1024can start or end with whitespace.
936 1025
937Please note that you need to double the C<\> when using 1026Please note that you need to double the C<\> in resource files, as
938C<--enable-xgetdefault>, as X itself does it's own de-escaping (you can 1027Xlib itself does it's own de-escaping (you can use C<\033> instead of
939use C<\033> instead of C<\e> (and so on), which will work with both Xt and 1028C<\e> (and so on), which will work with both Xt and @@RXVT_NAME@@'s own
940@@RXVT_NAME@@'s own processing). 1029processing).
941 1030
942You can define a range of keysyms in one shot by providing a I<string> 1031You can define a range of keysyms in one shot by providing a I<string>
943with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimeter `/' 1032with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where the delimeter `/'
944should be a character not used by the strings. 1033should be a character not used by the strings.
945 1034
958example the following means "change the current locale to C<zh_CN.GBK> 1047example the following means "change the current locale to C<zh_CN.GBK>
959when Control-Meta-c is being pressed": 1048when Control-Meta-c is being pressed":
960 1049
961 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 1050 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
962 1051
1052If I<string> takes the form C<perl:STRING>, then the specified B<STRING>
1053is passed to the C<on_keyboard_command> perl handler. See the @@RXVT_NAME@@perl(3)
1054manpage. For example, the F<selection> extension (activated via
1055C<@@RXVT_NAME@@ -pe selection>) listens for C<selection:rot13> events:
1056
1057 URxvt.keysym.M-C-c: perl:selection:rot13
1058
1059Due the the large number of modifier combinations, a defined key mapping
1060will match if at I<at least> the specified identifiers are being set, and
1061no other key mappings with those and more bits are being defined. That
1062means that defining a key map for C<a> will automatically provide
1063definitions for C<Meta-a>, C<Shift-a> and so on, unless some of those are defined
1064mappings themselves.
1065
1066Unfortunately, this will override built-in key mappings. For example
1067if you overwrite the C<Insert> key you will disable @@RXVT_NAME@@'s
1068C<Shift-Insert> mapping. To re-enable that, you can poke "holes" into the
1069user-defined keymap using the C<builtin:> replacement:
1070
1071 URxvt.keysym.Insert: <my insert key sequence>
1072 URxvt.keysym.S-Insert: builtin:
1073
1074The first line defines a mapping for C<Insert> and I<any> combination
1075of modifiers. The second line re-establishes the default mapping for
1076C<Shift-Insert>.
1077
963The following example will map Control-Meta-1 and Control-Meta-2 to 1078The following example will map Control-Meta-1 and Control-Meta-2 to
964the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited 1079the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
965font-switching at runtime: 1080font-switching at runtime:
966 1081
967 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007 1082 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
970Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more 1085Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more
971info): 1086info):
972 1087
973 URxvt.keysym.M-C-3: command:\033[8;25;80t 1088 URxvt.keysym.M-C-3: command:\033[8;25;80t
974 URxvt.keysym.M-C-4: command:\033[8;48;110t 1089 URxvt.keysym.M-C-4: command:\033[8;48;110t
1090
1091=item B<perl-ext-common>: I<string>
1092
1093=item B<perl-ext>: I<string>
1094
1095Comma-separated list(s) of perl extension scripts (default: C<default>) to
1096use in this terminal instance; option B<-pe>.
1097
1098Extension names can be prefixed with a C<-> sign to prohibit using
1099them. This can be useful to selectively disable some extensions loaded
1100by default, or specified via the C<perl-ext-common> resource. For
1101example, C<default,-selection> will use all the default extension except
1102C<selection>.
1103
1104Extension names can also be followed by an argument in angle brackets
1105(e.g. C<< searchable-scrollback<M-s> >>, which binds the hotkey for
1106searchable scorllback to Alt/Meta-s). Mentioning the same extension
1107multiple times with different arguments will pass multiple arguments to
1108the extension.
1109
1110Each extension is looked up in the library directories, loaded if
1111necessary, and bound to the current terminal instance.
1112
1113If both of these resources are the empty string, then the perl
1114interpreter will not be initialized. The idea behind two options is that
1115B<perl-ext-common> will be used for extensions that should be available to
1116all instances, while B<perl-ext> is used for specific instances.
1117
1118=item B<perl-eval>: I<string>
1119
1120Perl code to be evaluated when all extensions have been registered. See
1121the @@RXVT_NAME@@perl(3) manpage. Due to security reasons, this resource
1122will be ignored when running setuid/setgid.
1123
1124=item B<perl-lib>: I<path>
1125
1126Colon-separated list of additional directories that hold extension
1127scripts. When looking for extensions specified by the C<perl> resource,
1128@@RXVT_NAME@@ will first look in these directories and then in
1129F<@@RXVT_LIBDIR@@/urxvt/perl/>. Due to security reasons, this resource
1130will be ignored when running setuid/setgid.
1131
1132See the @@RXVT_NAME@@perl(3) manpage.
1133
1134=item B<< selection.pattern-I<idx> >>: I<perl-regex>
1135
1136Additional selection patterns, see the @@RXVT_NAME@@perl(3) manpage for
1137details.
1138
1139=item B<< selection-autotransform.I<idx> >>: I<perl-transform>
1140
1141Selection auto-transform patterns, see the @@RXVT_NAME@@perl(3) manpage
1142for details.
1143
1144=item B<searchable-scrollback:> I<keysym>
1145
1146Sets the hotkey that starts the incremental scrollback buffer search
1147(default: C<M-s>).
1148
1149=item B<urlLauncher>: I<string>
1150
1151Specifies the program to be started with a URL argument. Used by the
1152C<selection-popup> and C<mark-urls> perl extensions.
1153
1154=item B<transient-for>: I<windowid>
1155
1156Compile I<frills>: Sets the WM_TRANSIENT_FOR property to the given window id.
1157
1158=item B<override-redirect>: I<boolean>
1159
1160Compile I<frills>: Sets override-redirect for the terminal window, making
1161it almost invisible to window managers; option B<-override-redirect>.
975 1162
976=back 1163=back
977 1164
978=head1 THE SCROLLBAR 1165=head1 THE SCROLLBAR
979 1166
1014to select a word; Left triple-click to select the entire logical line 1201to select a word; Left triple-click to select the entire logical line
1015(which can span multiple screen lines), unless modified by resource 1202(which can span multiple screen lines), unless modified by resource
1016B<tripleclickwords>. 1203B<tripleclickwords>.
1017 1204
1018Starting a selection while pressing the B<Meta> key (or B<Meta+Ctrl> keys) 1205Starting a selection while pressing the B<Meta> key (or B<Meta+Ctrl> keys)
1019(Compile: I<frills>) will create a rectangular selection instead of a normal 1206(Compile: I<frills>) will create a rectangular selection instead of a
1020one. 1207normal one. In this mode, every selected row becomes its own line in the
1208selection, and trailing whitespace is visually underlined and removed from
1209the selection.
1021 1210
1022=item B<Insertion>: 1211=item B<Insertion>:
1023 1212
1024Pressing and releasing the Middle mouse button (or B<Shift-Insert>) in 1213Pressing and releasing the Middle mouse button in an B<@@RXVT_NAME@@>
1025an B<@@RXVT_NAME@@> window causes the current text selection to be 1214window causes the value of the PRIMARY selection (or CLIPBOARD with the
1026inserted as if it had been typed on the keyboard. 1215Meta modifier) to be inserted as if it had been typed on the keyboard.
1216
1217Pressing B<Shift-Insert> causes the value of the PRIMARY selection to be
1218inserted too.
1027 1219
1028=back 1220=back
1029 1221
1030=head1 CHANGING FONTS 1222=head1 CHANGING FONTS
1031 1223
1032Changing fonts (or font sizes, respectively) via the keypad is not yet 1224Changing fonts (or font sizes, respectively) via the keypad is not yet
1033supported in rxvt-unicode. Bug me if you need this. 1225supported in rxvt-unicode. Bug me if you need this.
1034 1226
1035You can, however, switch fonts at runtime using escape sequences (and 1227You can, however, switch fonts at runtime using escape sequences, e.g.:
1036therefore using the menubar), e.g.:
1037 1228
1038 printf '\e]701;%s\007' "9x15bold,xft:Kochi Gothic" 1229 printf '\e]710;%s\007' "9x15bold,xft:Kochi Gothic"
1230
1231You can use keyboard shortcuts, too:
1232
1233 URxvt.keysym.M-C-1: command:\033]710;suxuseuro\007\033]711;suxuseuro\007
1234 URxvt.keysym.M-C-2: command:\033]710;9x15bold\007\033]711;9x15bold\007
1039 1235
1040rxvt-unicode will automatically re-apply these fonts to the output so far. 1236rxvt-unicode will automatically re-apply these fonts to the output so far.
1041 1237
1042=head1 ISO 14755 SUPPORT 1238=head1 ISO 14755 SUPPORT
1043 1239
1114=head1 COLORS AND GRAPHICS 1310=head1 COLORS AND GRAPHICS
1115 1311
1116In addition to the default foreground and background colours, 1312In addition to the default foreground and background colours,
1117B<@@RXVT_NAME@@> can display up to 16 colours (8 ANSI colours plus 1313B<@@RXVT_NAME@@> can display up to 16 colours (8 ANSI colours plus
1118high-intensity bold/blink versions of the same). Here is a list of the 1314high-intensity bold/blink versions of the same). Here is a list of the
1119colours with their B<rgb.txt> names. 1315colours with their names.
1120 1316
1121=begin table 1317=begin table
1122 1318
1123 B<color0> (black) = Black 1319 B<color0> (black) = Black
1124 B<color1> (red) = Red3 1320 B<color1> (red) = Red3
1144It is also possible to specify the colour values of B<foreground>, 1340It is also possible to specify the colour values of B<foreground>,
1145B<background>, B<cursorColor>, B<cursorColor2>, B<colorBD>, B<colorUL> as 1341B<background>, B<cursorColor>, B<cursorColor2>, B<colorBD>, B<colorUL> as
1146a number 0-15, as a convenient shorthand to reference the colour name of 1342a number 0-15, as a convenient shorthand to reference the colour name of
1147color0-color15. 1343color0-color15.
1148 1344
1345If Xft support has been compiled in and as long as Xft/Xrender/X don't get
1346their act together, rxvt-unicode will support C<rgba:rrrr/gggg/bbbb/aaaa>
1347(recommended, but B<MUST> have 4 digits/component), C<#ARGB>, C<#AARRGGBB>
1348and C<#AAAARRRRGGGGBBBB> colour specifications, in addition to the ones
1349provided by X, where the additional A component specifies alpha (opacity)
1350values (0 is completely transparent and the maximum is opaque). You
1351probably need to specify B<"-depth 32">, too, and have the luck that your
1352X-server uses ARGB pixel layout, as X is far from just supporting ARGB
1353visuals out of the box, and rxvt-unicode just fudges around.
1354
1149Note that B<-rv> (B<"reverseVideo: True">) simulates reverse video by 1355Note that B<-rv> (B<"reverseVideo: True">) simulates reverse video by
1150always swapping the foreground/background colours. This is in contrast to 1356always swapping the foreground/background colours. This is in contrast to
1151I<xterm>(1) where the colours are only swapped if they have not otherwise 1357I<xterm>(1) where the colours are only swapped if they have not otherwise
1152been specified. For example, 1358been specified. For example,
1153 1359
1205 1411
1206=item B<SHELL> 1412=item B<SHELL>
1207 1413
1208The shell to be used for command execution, defaults to C</bin/sh>. 1414The shell to be used for command execution, defaults to C</bin/sh>.
1209 1415
1210=item B<RXVTPATH>
1211
1212The path where @@RXVT_NAME@@ looks for support files such as menu and xpm
1213files.
1214
1215=item B<PATH>
1216
1217Used in the same way as C<RXVTPATH>.
1218
1219=item B<RXVT_SOCKET> 1416=item B<RXVT_SOCKET>
1220 1417
1221The unix domain socket path used by @@RXVT_NAME@@c(1) and 1418The unix domain socket path used by @@RXVT_NAME@@c(1) and
1222@@RXVT_NAME@@d(1). 1419@@RXVT_NAME@@d(1).
1223 1420
1224Default C<< $HOME/.rxvt-unicode-<nodename >>. 1421Default F<<< $HOME/.rxvt-unicode-I<< <nodename >> >>>.
1225 1422
1226=item B<HOME> 1423=item B<HOME>
1227 1424
1228Used to locate the default directory for the unix domain socket for 1425Used to locate the default directory for the unix domain socket for
1229daemon communications and to locate various resource files (such as 1426daemon communications and to locate various resource files (such as
1250 1447
1251=back 1448=back
1252 1449
1253=head1 SEE ALSO 1450=head1 SEE ALSO
1254 1451
1255@@RXVT_NAME@@(7), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5) 1452@@RXVT_NAME@@(7), @@RXVT_NAME@@c(1), @@RXVT_NAME@@d(1), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5)
1256
1257=head1 BUGS
1258
1259Check the BUGS file for an up-to-date list.
1260
1261Cursor change support is not yet implemented.
1262
1263Click-and-drag doesn't work with X11 mouse report overriding.
1264 1453
1265=head1 CURRENT PROJECT COORDINATOR 1454=head1 CURRENT PROJECT COORDINATOR
1266 1455
1267=over 4 1456=over 4
1268 1457
1300 1489
1301Project Coordinator (changes.txt 2.21a to 2.4.5) 1490Project Coordinator (changes.txt 2.21a to 2.4.5)
1302 1491
1303=item Geoff Wing L<< <gcw@pobox.com> >> 1492=item Geoff Wing L<< <gcw@pobox.com> >>
1304 1493
1305Rewrote screen display and text selection routines. Project Coordinator 1494Rewrote screen display and text selection routines.
1495
1306(changes.txt 2.4.6 - rxvt-unicode) 1496Project Coordinator (changes.txt 2.4.6 - rxvt-unicode)
1307 1497
1308=item Marc Alexander Lehmann L<< <rxvt-unicode@schmorp.de> >> 1498=item Marc Alexander Lehmann L<< <rxvt-unicode@schmorp.de> >>
1309 1499
1310Forked rxvt-unicode, rewrote most of the display code and internal 1500Forked rxvt-unicode, unicode support, rewrote almost all the code, perl
1311character handling to store text in unicode, improve xterm 1501extension, random hacks, numerous bugfixes and extensions.
1312compatibility and apply numerous other bugfixes and extensions.
1313 1502
1314Project Coordinator (Changes 1.0 -) 1503Project Coordinator (Changes 1.0 -)
1315 1504
1505=item Emanuele Giaquinta L<< <e.giaquinta@glauco.it> >>
1506
1507Pty/tty/utmp/wtmp rewrite, lots of random hacking and bugfixing.
1508
1316=back 1509=back
1317 1510

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines