1=head1 NAME 2 3rxvt-unicode (ouR XVT, unicode) - (a VT102 emulator for the X window system) 4 5=head1 SYNOPSIS 6 7B<@@RXVT_NAME@@> [options] [-e command [ args ]] 8 9=head1 DESCRIPTION 10 11B<rxvt-unicode>, version B<@@RXVT_VERSION@@>, is a colour vt102 terminal 12emulator intended as an I<xterm>(1) replacement for users who do not 13require features such as Tektronix 4014 emulation and toolkit-style 14configurability. As a result, B<rxvt-unicode> uses much less swap space -- 15a significant advantage on a machine serving many X sessions. 16 17This document is also available on the World-Wide-Web at 18L<http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.1.pod>. 19 20=head1 FREQUENTLY ASKED QUESTIONS 21 22See @@RXVT_NAME@@(7) (try C<man 7 @@RXVT_NAME@@>) for a list of 23frequently asked questions and answer to them and some common 24problems. That document is also accessible on the World-Wide-Web at 25L<http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.7.pod>. 26 27=head1 RXVT-UNICODE VS. RXVT 28 29Unlike the original rxvt, B<rxvt-unicode> stores all text in Unicode 30internally. That means it can store and display most scripts in the 31world. Being a terminal emulator, however, some things are very difficult, 32especially cursive scripts such as arabic, vertically written scripts 33like mongolian or scripts requiring extremely complex combining rules, 34like tibetan or devanagari. Don't expect pretty output when using these 35scripts. Most other scripts, latin, cyrillic, kanji, thai etc. should work 36fine, though. A somewhat difficult case are right-to-left scripts, such 37as hebrew: B<rxvt-unicode> adopts the view that bidirectional algorithms 38belong in the application, not the terminal emulator (too many things -- 39such as cursor-movement while editing -- break otherwise), but that might 40change. 41 42If you are looking for a terminal that supports more exotic scripts, let 43me recommend C<mlterm>, which is a very user friendly, lean and clean 44terminal emulator. In fact, the reason rxvt-unicode was born was solely 45because the author couldn't get C<mlterm> to use one font for latin1 and 46another for japanese. 47 48Therefore another design rationale was the use of multiple fonts to 49display characters: The idea of a single unicode font which many other 50programs force onto its users never made sense to me: You should be able 51to choose any font for any script freely. 52 53Apart from that, rxvt-unicode is also much better internationalised than 54its predecessor, supports things such as XFT and ISO 14755 that are handy 55in i18n-environments, is faster, and has a lot bugs less than the original 56rxvt. This all in addition to dozens of other small improvements. 57 58It is still faithfully following the original rxvt idea of being lean 59and nice on resources: for example, you can still configure rxvt-unicode 60without most of its features to get a lean binary. It also comes with 61a client/daemon pair that lets you open any number of terminal windows 62from within a single process, which makes startup time very fast and 63drastically reduces memory usage. See @@RXVT_NAME@@d(1) (daemon) and 64@@RXVT_NAME@@c(1) (client). 65 66It also makes technical information about escape sequences (which have 67been extended) more accessible: see @@RXVT_NAME@@(7) for technical 68reference documentation (escape sequences etc.). 69 70=head1 OPTIONS 71 72The B<@@RXVT_NAME@@> options (mostly a subset of I<xterm>'s) are listed 73below. In keeping with the smaller-is-better philosophy, options may be 74eliminated or default values chosen at compile-time, so options and 75defaults listed may not accurately reflect the version installed on 76your system. `@@RXVT_NAME@@ -h' gives a list of major compile-time options on 77the I<Options> line. Option descriptions may be prefixed with which 78compile option each is dependent upon. e.g. `Compile I<XIM>:' requires 79I<XIM> on the I<Options> line. Note: `@@RXVT_NAME@@ -help' gives a list of all 80command-line options compiled into your version. 81 82Note that B<@@RXVT_NAME@@> permits the resource name to be used as a 83long-option (--/++ option) so the potential command-line options are 84far greater than those listed. For example: `@@RXVT_NAME@@ --loginShell --color1 85Orange'. 86 87The following options are available: 88 89=over 90 91=item B<-help>, B<--help> 92 93Print out a message describing available options. 94 95=item B<-display> I<displayname> 96 97Attempt to open a window on the named X display (the older form B<-d> 98is still respected. but deprecated). In the absence of this option, the 99display specified by the B<DISPLAY> environment variable is used. 100 101=item B<-depth> I<bitdepth> 102 103Compile I<frills>: Attempt to find a visual with the given bit depth; 104resource B<depth>. 105 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 108of graphical corruption. This is harmless, but we can't do anything about 109this, so watch out] 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 117=item B<-geometry> I<geom> 118 119Window geometry (B<-g> still respected); resource B<geometry>. 120 121=item B<-rv>|B<+rv> 122 123Turn on/off simulated reverse video; resource B<reverseVideo>. 124 125=item B<-j>|B<+j> 126 127Turn on/off jump scrolling (allow multiple lines per refresh); resource B<jumpScroll>. 128 129=item B<-ss>|B<+ss> 130 131Turn on/off skip scrolling (allow multiple screens per refresh); resource B<skipScroll>. 132 133=item B<-fade> I<number> 134 135Fade the text by the given percentage when focus is lost. Small values 136fade a little only, 100 completely replaces all colours by the fade 137colour; resource B<fading>. 138 139=item B<-fadecolor> I<colour> 140 141Fade to this colour when fading is used (see B<-fade>). The default colour 142is opaque black. resource B<fadeColor>. 143 144=item B<-icon> I<file> 145 146Compile I<pixbuf>: Use the specified image as application icon. This 147is used by many window managers, taskbars and pagers to represent the 148application window; resource I<iconFile>. 149 150=item B<-bg> I<colour> 151 152Window background colour; resource B<background>. 153 154=item B<-fg> I<colour> 155 156Window foreground colour; resource B<foreground>. 157 158=item B<-cr> I<colour> 159 160The cursor colour; resource B<cursorColor>. 161 162=item B<-pr> I<colour> 163 164The mouse pointer foreground colour; resource B<pointerColor>. 165 166=item B<-pr2> I<colour> 167 168The mouse pointer background colour; resource B<pointerColor2>. 169 170=item B<-bd> I<colour> 171 172The colour of the border around the text area and between the scrollbar and the text; 173resource B<borderColor>. 174 175=item B<-fn> I<fontlist> 176 177Select the fonts to be used. This is a comma separated list of font names 178that are checked in order when trying to find glyphs for characters. The 179first font defines the cell size for characters; other fonts might be 180smaller, but not (in general) larger. A (hopefully) reasonable default 181font list is always appended to it. See resource B<font> for more details. 182 183In short, to specify an X11 core font, just specify its name or prefix it 184with C<x:>. To specify an XFT-font, you need to prefix it with C<xft:>, 185e.g.: 186 187 @@RXVT_NAME@@ -fn "xft:Bitstream Vera Sans Mono:pixelsize=15" 188 @@RXVT_NAME@@ -fn "9x15bold,xft:Bitstream Vera Sans Mono" 189 190See also the question "How does rxvt-unicode choose fonts?" in the FAQ 191section of @@RXVT_NAME@@(7). 192 193=item B<-fb> I<fontlist> 194 195Compile I<font-styles>: The bold font list to use when B<bold> characters 196are to be printed. See resource B<boldFont> for details. 197 198=item B<-fi> I<fontlist> 199 200Compile I<font-styles>: The italic font list to use when I<italic> 201characters are to be printed. See resource B<italicFont> for details. 202 203=item B<-fbi> I<fontlist> 204 205Compile I<font-styles>: The bold italic font list to use when B<< I<bold 206italic> >> characters are to be printed. See resource B<boldItalicFont> 207for details. 208 209=item B<-is>|B<+is> 210 211Compile I<font-styles>: Bold/Blink font styles imply high intensity 212foreground/background (default). See resource B<intensityStyles> for 213details. 214 215=item B<-name> I<name> 216 217Specify the application name under which resources are to be obtained, 218rather than the default executable file name. Name should not contain 219`.' or `*' characters. Also sets the icon and title name. 220 221=item B<-ls>|B<+ls> 222 223Start as a login-shell/sub-shell; resource B<loginShell>. 224 225=item B<-mc> I<milliseconds> 226 227Specify the maximum time between multi-click selections. 228 229=item B<-ut>|B<+ut> 230 231Compile I<utmp>: Inhibit/enable writing a utmp entry; resource 232B<utmpInhibit>. 233 234=item B<-vb>|B<+vb> 235 236Turn on/off visual bell on receipt of a bell character; resource 237B<visualBell>. 238 239=item B<-sb>|B<+sb> 240 241Turn on/off scrollbar; resource B<scrollBar>. 242 243=item B<-sr>|B<+sr> 244 245Put scrollbar on right/left; resource B<scrollBar_right>. 246 247=item B<-st>|B<+st> 248 249Display rxvt (non XTerm/NeXT) scrollbar without/with a trough; 250resource B<scrollBar_floating>. 251 252=item B<-si>|B<+si> 253 254Turn on/off scroll-to-bottom on TTY output inhibit; resource 255B<scrollTtyOutput> has opposite effect. 256 257=item B<-sk>|B<+sk> 258 259Turn on/off scroll-to-bottom on keypress; resource 260B<scrollTtyKeypress>. 261 262=item B<-sw>|B<+sw> 263 264Turn on/off scrolling with the scrollback buffer as new lines appear. 265This only takes effect if B<-si> is also given; resource 266B<scrollWithBuffer>. 267 268=item B<-ptab>|B<+ptab> 269 270If enabled (default), "Horizontal Tab" characters are being stored as 271actual wide characters in the screen buffer, which makes it possible to 272select and paste them. Since a horizontal tab is a cursor movement and 273not an actual glyph, this can sometimes be visually annoying as the cursor 274on a tab character is displayed as a wide cursor; resource B<pastableTabs>. 275 276=item B<-bc>|B<+bc> 277 278Blink the cursor; resource B<cursorBlink>. 279 280=item B<-uc>|B<+uc> 281 282Make the cursor underlined; resource B<cursorUnderline>. 283 284=item B<-iconic> 285 286Start iconified, if the window manager supports that option. 287Alternative form is B<-ic>. 288 289=item B<-sl> I<number> 290 291Save I<number> lines in the scrollback buffer. See resource entry for 292limits; resource B<saveLines>. 293 294=item B<-b> I<number> 295 296Compile I<frills>: Internal border of I<number> pixels. See resource 297entry for limits; resource B<internalBorder>. 298 299=item B<-w> I<number> 300 301Compile I<frills>: External border of I<number> pixels. Also, B<-bw> 302and B<-borderwidth>. See resource entry for limits; resource 303B<externalBorder>. 304 305=item B<-bl> 306 307Compile I<frills>: Set MWM hints to request a borderless window, i.e. 308if honoured by the WM, the rxvt-unicode window will not have window 309decorations; resource B<borderLess>. If the window manager does not 310support MWM hints (e.g. kwin), enables override-redirect mode. 311 312=item B<-override-redirect> 313 314Compile I<frills>: Sets override-redirect on the window; resource 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. 321 322=item B<-sbg> 323 324Compile I<frills>: Disable the usage of the built-in block graphics/line 325drawing characters and just rely on what the specified fonts provide. Use 326this if you have a good font and want to use its block graphic glyphs; 327resource B<skipBuiltinGlyphs>. 328 329=item B<-lsp> I<number> 330 331Compile I<frills>: Lines (pixel height) to insert between each row of 332the display. Useful to work around font rendering problems; resource 333B<lineSpace>. 334 335=item B<-letsp> I<number> 336 337Compile I<frills>: Amount to adjust the computed character width by 338to control overall letter spacing. Negative values will tighten up the 339letter spacing, positive values will space letters out more. Useful to 340work around odd font metrics; resource B<letterSpace>. 341 342=item B<-tn> I<termname> 343 344This option specifies the name of the terminal type to be set in the 345B<TERM> environment variable. This terminal type must exist in the 346I<termcap(5)> database and should have I<li#> and I<co#> entries; 347resource B<termName>. 348 349=item B<-e> I<command [arguments]> 350 351Run the command with its command-line arguments in the B<@@RXVT_NAME@@> 352window; also sets the window title and icon name to be the basename of 353the program being executed if neither I<-title> (I<-T>) nor I<-n> are 354given on the command line. If this option is used, it must be the last 355on the command-line. If there is no B<-e> option then the default is to 356run the program specified by the B<SHELL> environment variable or, 357failing that, I<sh(1)>. 358 359Please note that you must specify a program with arguments. If you want to 360run shell commands, you have to specify the shell, like this: 361 362 @@RXVT_NAME@@ -e sh -c "shell commands" 363 364=item B<-title> I<text> 365 366Window title (B<-T> still respected); the default title is the basename 367of the program specified after the B<-e> option, if any, otherwise the 368application name; resource B<title>. 369 370=item B<-n> I<text> 371 372Icon name; the default name is the basename of the program specified 373after the B<-e> option, if any, otherwise the application name; 374resource B<iconName>. 375 376=item B<-C> 377 378Capture system console messages. 379 380=item B<-pt> I<style> 381 382Compile I<XIM>: input style for input method; B<OverTheSpot>, 383B<OffTheSpot>, B<Root>; resource B<preeditType>. 384 385If the perl extension C<xim-onthespot> is used (which is the default), 386then additionally the C<OnTheSpot> preedit type is available. 387 388=item B<-im> I<text> 389 390Compile I<XIM>: input method name. resource B<inputMethod>. 391 392=item B<-imlocale> I<string> 393 394The locale to use for opening the IM. You can use an C<LC_CTYPE> of e.g. 395C<de_DE.UTF-8> for normal text processing but C<ja_JP.EUC-JP> for the 396input extension to be able to input japanese characters while staying in 397another locale. resource B<imLocale>. 398 399=item B<-imfont> I<fontset> 400 401Set the font set to use for the X Input Method, see resource B<imFont> 402for more info. 403 404=item B<-tcw> 405 406Change the meaning of triple-click selection with the left mouse 407button. Only effective when the original (non-perl) selection code is 408in-use. Instead of selecting a full line it will extend the selection to 409the end of the logical line only. resource B<tripleclickwords>. 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 421=item B<-insecure> 422 423Enable "insecure" mode, which currently enables most of the escape 424sequences that echo strings. See the resource B<insecure> for more 425info. 426 427=item B<-mod> I<modifier> 428 429Override detection of Meta modifier with specified key: B<alt>, 430B<meta>, B<hyper>, B<super>, B<mod1>, B<mod2>, B<mod3>, B<mod4>, 431B<mod5>; resource I<modifier>. 432 433=item B<-ssc>|B<+ssc> 434 435Turn on/off secondary screen (default enabled); resource 436B<secondaryScreen>. 437 438=item B<-ssr>|B<+ssr> 439 440Turn on/off secondary screen scroll (default enabled); resource 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>. 450 451=item B<-hold>|B<+hold> 452 453Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@ 454will not immediately destroy its window when the program executed within 455it exits. Instead, it will wait till it is being killed or closed by the 456user; resource B<hold>. 457 458=item B<-cd> I<path> 459 460Sets the working directory for the shell (or the command specified via 461B<-e>). The I<path> must be an absolute path and it must exist for 462@@RXVT_NAME@@ to start; resource B<chdir>. 463 464=item B<-xrm> I<string> 465 466Works like the X Toolkit option of the same name, by adding the I<string> 467as if it were specified in a resource file. Resource values specified this 468way take precedence over all other resource specifications. 469 470Note that you need to use the I<same> syntax as in the .Xdefaults file, 471e.g. C<*.background: black>. Also note that all @@RXVT_NAME@@-specific 472options can be specified as long-options on the commandline, so use 473of B<-xrm> is mostly limited to cases where you want to specify other 474resources (e.g. for input methods) or for compatibility with other 475programs. 476 477=item B<-keysym.>I<sym> I<string> 478 479Remap a key symbol. See resource B<keysym>. 480 481=item B<-embed> I<windowid> 482 483Tells @@RXVT_NAME@@ to embed its windows into an already-existing window, 484which enables applications to easily embed a terminal. 485 486Right now, @@RXVT_NAME@@ will first unmap/map the specified window, so it 487shouldn't be a top-level window. @@RXVT_NAME@@ will also reconfigure it 488quite a bit, so don't expect it to keep some specific state. It's best to 489create an extra subwindow for @@RXVT_NAME@@ and leave it alone. 490 491The window will not be destroyed when @@RXVT_NAME@@ exits. 492 493It might be useful to know that @@RXVT_NAME@@ will not close file 494descriptors passed to it (except for stdin/out/err, of course), so you 495can use file descriptors to communicate with the programs within the 496terminal. This works regardless of whether the C<-embed> option was used or 497not. 498 499Here is a short Gtk2-perl snippet that illustrates how this option can be 500used (a longer example is in F<doc/embed>): 501 502 my $rxvt = new Gtk2::Socket; 503 $rxvt->signal_connect_after (realize => sub { 504 my $xid = $_[0]->window->get_xid; 505 system "@@RXVT_NAME@@ -embed $xid &"; 506 }); 507 508=item B<-pty-fd> I<file descriptor> 509 510Tells @@RXVT_NAME@@ NOT to execute any commands or create a new pty/tty 511pair but instead use the given file descriptor as the tty master. This is 512useful if you want to drive @@RXVT_NAME@@ as a generic terminal emulator 513without having to run a program within it. 514 515If this switch is given, @@RXVT_NAME@@ will not create any utmp/wtmp 516entries and will not tinker with pty/tty permissions - you have to do that 517yourself if you want that. 518 519As an extremely special case, specifying C<-1> will completely suppress 520pty/tty operations, which is probably only useful in conjunction with some 521perl extension that manages the terminal. 522 523Here is a example in perl that illustrates how this option can be used (a 524longer example is in F<doc/pty-fd>): 525 526 use IO::Pty; 527 use Fcntl; 528 529 my $pty = new IO::Pty; 530 fcntl $pty, F_SETFD, 0; # clear close-on-exec 531 system "@@RXVT_NAME@@ -pty-fd " . (fileno $pty) . "&"; 532 close $pty; 533 534 # now communicate with rxvt 535 my $slave = $pty->slave; 536 while (<$slave>) { print $slave "got <$_>\n" } 537 538Note that, despite what the name might imply, the file descriptor does not 539need to be a pty, it can be a bi-directional pipe as well (e.g. a unix 540domain or tcp socket). While tty operations cannot be done in this case, 541B<@@RXVT_NAME@@> can still be remote controlled with it: 542 543 use Socket; 544 use Fcntl; 545 546 socketpair my $URXVT, my $slave, Socket::AF_UNIX, Socket::SOCK_STREAM, Socket::PF_UNSPEC; 547 fcntl $slave, Fcntl::F_SETFD, 0; 548 system "exec @@RXVT_NAME@@ -pty-fd " . (fileno $slave) . " &"; 549 close $slave; 550 551 syswrite $URXVT, "Type a secret password: "; 552 my $secret = do { local $/ = "\r"; <$URXVT> }; 553 print "Not so secret anymore: $secret\n"; 554 555=item B<-pe> I<string> 556 557Comma-separated list of perl extension scripts to use (or not to use) in 558this terminal instance. See resource B<perl-ext> for details. 559 560=back 561 562=head1 RESOURCES 563 564Note: `@@RXVT_NAME@@ --help' gives a list of all resources (long 565options) compiled into your version. All resources are also available as 566long-options. 567 568You can set and change the resources using X11 tools like B<xrdb>. Many 569distribution do also load settings from the B<~/.Xresources> file when X 570starts. @@RXVT_NAME@@ will consult the following files/resources in order, 571with later settings overwriting earlier ones: 572 573 1. app-defaults file in $XAPPLRESDIR 574 2. $HOME/.Xdefaults 575 3. RESOURCE_MANAGER property on root-window of screen 0 576 4. SCREEN_RESOURCES property on root-window of the current screen 577 5. $XENVIRONMENT file OR $HOME/.Xdefaults-<nodename> 578 6. resources specified via -xrm on the commandline 579 580Note that when reading X resources, B<@@RXVT_NAME@@> recognizes two class 581names: B<Rxvt> and B<URxvt>. The class name B<Rxvt> allows resources 582common to both B<@@RXVT_NAME@@> and the original I<rxvt> to be easily 583configured, while the class name B<URxvt> allows resources unique to 584B<@@RXVT_NAME@@>, to be shared between different B<@@RXVT_NAME@@> 585configurations. If no resources are specified, suitable defaults will 586be used. Command-line arguments can be used to override resource 587settings. The following resources are supported (you might want to 588check the @@RXVT_NAME@@perl(3) manpage for additional settings by perl 589extensions not documented here): 590 591=over 592 593=item B<depth:> I<bitdepth> 594 595Compile I<xft>: Attempt to find a visual with the given bit depth; 596option B<-depth>. 597 598=item B<buffered:> I<boolean> 599 600Compile I<xft>: Turn on/off double-buffering for xft (default enabled). 601On some card/driver combination enabling it slightly decreases 602performance, on most it greatly helps it. The slowdown is small, so it 603should normally be enabled. 604 605=item B<geometry:> I<geom> 606 607Create the window with the specified X window geometry [default 80x24]; 608option B<-geometry>. 609 610=item B<background:> I<colour> 611 612Use the specified colour as the window's background colour [default 613White]; option B<-bg>. 614 615=item B<foreground:> I<colour> 616 617Use the specified colour as the window's foreground colour [default 618Black]; option B<-fg>. 619 620=item B<color>I<n>B<:> I<colour> 621 622Use the specified colour for the colour value I<n>, where 0-7 623corresponds to low-intensity (normal) colours and 8-15 corresponds to 624high-intensity (bold = bright foreground, blink = bright background) 625colours. The canonical names are as follows: 0=black, 1=red, 2=green, 6263=yellow, 4=blue, 5=magenta, 6=cyan, 7=white, but the actual colour 627names used are listed in the B<COLOURS AND GRAPHICS> section. 628 629Colours higher than 15 cannot be set using resources (yet), but can be 630changed using an escape command (see @@RXVT_NAME@@(7)). 631 632Colours 16-79 form a standard 4x4x4 colour cube (the same as xterm with 63388 colour support). Colours 80-87 are evenly spaces grey steps. 634 635=item B<colorBD:> I<colour> 636 637=item B<colorIT:> I<colour> 638 639Use the specified colour to display bold or italic characters when the 640foreground colour is the default. If font styles are not available 641(Compile I<styles>) and this option is unset, reverse video is used instead. 642 643=item B<colorUL:> I<colour> 644 645Use the specified colour to display underlined characters when the 646foreground colour is the default. 647 648=item B<underlineColor:> I<colour> 649 650If set, use the specified colour as the colour for the underline 651itself. If unset, use the foreground colour. 652 653=item B<highlightColor:> I<colour> 654 655If set, use the specified colour as the background for highlighted 656characters. If unset, use reverse video. 657 658=item B<highlightTextColor:> I<colour> 659 660If set and highlightColor is set, use the specified colour as the 661foreground for highlighted characters. 662 663=item B<cursorColor:> I<colour> 664 665Use the specified colour for the cursor. The default is to use the 666foreground colour; option B<-cr>. 667 668=item B<cursorColor2:> I<colour> 669 670Use the specified colour for the colour of the cursor text. For this to 671take effect, B<cursorColor> must also be specified. The default is to 672use the background colour. 673 674=item B<reverseVideo:> I<boolean> 675 676B<True>: simulate reverse video by foreground and background colours; 677option B<-rv>. B<False>: regular screen colours [default]; option 678B<+rv>. See note in B<COLOURS AND GRAPHICS> section. 679 680=item B<jumpScroll:> I<boolean> 681 682B<True>: specify that jump scrolling should be used. When receiving lots 683of lines, @@RXVT_NAME@@ will only scroll once a whole screen height of lines 684has been read, resulting in fewer updates while still displaying every 685received line; option B<-j>. 686 687B<False>: specify that smooth scrolling should be used. @@RXVT_NAME@@ will 688force a screen refresh on each new line it received; option B<+j>. 689 690=item B<skipScroll:> I<boolean> 691 692B<True>: (the default) specify that skip scrolling should be used. When 693receiving lots of lines, @@RXVT_NAME@@ will only scroll once in a while 694(around 60 times per second), resulting in far fewer updates. This can 695result in @@RXVT_NAME@@ not ever displaying some of the lines it receives; 696option B<-ss>. 697 698B<False>: specify that everything is to be displayed, even 699if the refresh is too fast for the human eye to read anything (or the 700monitor to display anything); option B<+ss>. 701 702=item B<fading:> I<number> 703 704Fade the text by the given percentage when focus is lost; option B<-fade>. 705 706=item B<fadeColor:> I<colour> 707 708Fade to this colour, when fading is used (see B<fading:>). The default 709colour is black; option B<-fadecolor>. 710 711=item B<iconFile:> I<file> 712 713Set the application icon pixmap; option B<-icon>. 714 715=item B<scrollColor:> I<colour> 716 717Use the specified colour for the scrollbar [default #B2B2B2]. 718 719=item B<troughColor:> I<colour> 720 721Use the specified colour for the scrollbar's trough area [default 722#969696]. Only relevant for rxvt (non XTerm/NeXT) scrollbar. 723 724=item B<borderColor:> I<colour> 725 726The colour of the border around the text area and between the scrollbar 727and the text. 728 729=item B<font:> I<fontlist> 730 731Select the fonts to be used. This is a comma separated list of font names 732that are checked in order when trying to find glyphs for characters. The 733first font defines the cell size for characters; other fonts might be 734smaller, but not (in general) larger. A (hopefully) reasonable default 735font list is always appended to it; option B<-fn>. 736 737Each font can either be a standard X11 core font (XLFD) name, with 738optional prefix C<x:> or a Xft font (Compile I<xft>), prefixed with C<xft:>. 739 740In addition, each font can be prefixed with additional hints and 741specifications enclosed in square brackets (C<[]>). The only available 742hint currently is C<codeset=codeset-name>, and this is only used for Xft 743fonts. 744 745For example, this font resource 746 747 URxvt.font: 9x15bold,\ 748 -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso10646-1,\ 749 -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1, \ 750 [codeset=JISX0208]xft:Kochi Gothic:antialias=false, \ 751 xft:Code2000:antialias=false 752 753specifies five fonts to be used. The first one is C<9x15bold> (actually 754the iso8859-1 version of the second font), which is the base font (because 755it is named first) and thus defines the character cell grid to be 9 pixels 756wide and 15 pixels high. 757 758The second font is just used to add additional unicode characters not in 759the base font, likewise the third, which is unfortunately non-bold, but 760the bold version of the font does contain fewer characters, so this is a 761useful supplement. 762 763The third font is an Xft font with aliasing turned off, and the characters 764are limited to the B<JIS 0208> codeset (i.e. japanese kanji). The font 765contains other characters, but we are not interested in them. 766 767The last font is a useful catch-all font that supplies most of the 768remaining unicode characters. 769 770=item B<boldFont:> I<fontlist> 771 772=item B<italicFont:> I<fontlist> 773 774=item B<boldItalicFont:> I<fontlist> 775 776The font list to use for displaying B<bold>, I<italic> or B<< I<bold 777italic> >> characters, respectively. 778 779If specified and non-empty, then the syntax is the same as for the 780B<font>-resource, and the given font list will be used as is, which makes 781it possible to substitute completely different font styles for bold and 782italic. 783 784If unset (the default), a suitable font list will be synthesized by 785"morphing" the normal text font list into the desired shape. If that is 786not possible, replacement fonts of the desired shape will be tried. 787 788If set, but empty, then this specific style is disabled and the normal 789text font will being used for the given style. 790 791=item B<intensityStyles:> I<boolean> 792 793When font styles are not enabled, or this option is enabled (B<True>, 794option B<-is>, the default), bold/blink font styles imply high 795intensity foreground/background colours. Disabling this option (B<False>, 796option B<+is>) disables this behaviour, the high intensity colours are not 797reachable. 798 799=item B<title:> I<string> 800 801Set window title string, the default title is the command-line 802specified after the B<-e> option, if any, otherwise the application 803name; option B<-title>. 804 805=item B<iconName:> I<string> 806 807Set the name used to label the window's icon or displayed in an icon 808manager window, it also sets the window's title unless it is explicitly 809set; option B<-n>. 810 811=item B<mapAlert:> I<boolean> 812 813B<True>: de-iconify (map) on receipt of a bell character. B<False>: no 814de-iconify (map) on receipt of a bell character [default]. 815 816=item B<urgentOnBell:> I<boolean> 817 818B<True>: set the urgency hint for the wm on receipt of a bell character. 819B<False>: do not set the urgency hint [default]. 820 821@@RXVT_NAME@@ resets the urgency hint on every focus change. 822 823=item B<visualBell:> I<boolean> 824 825B<True>: use visual bell on receipt of a bell character; option B<-vb>. 826B<False>: no visual bell [default]; option B<+vb>. 827 828=item B<loginShell:> I<boolean> 829 830B<True>: start as a login shell by prepending a `-' to B<argv[0]> of 831the shell; option B<-ls>. B<False>: start as a normal sub-shell 832[default]; option B<+ls>. 833 834=item B<multiClickTime:> I<number> 835 836Specify the maximum time in milliseconds between multi-click select 837events. The default is 500 milliseconds; option B<-mc>. 838 839=item B<utmpInhibit:> I<boolean> 840 841B<True>: inhibit writing record into the system log file B<utmp>; 842option B<-ut>. B<False>: write record into the system log file B<utmp> 843[default]; option B<+ut>. 844 845=item B<print-pipe:> I<string> 846 847Specify a command pipe for vt100 printer [default I<lpr(1)>]. Use 848B<Print> to initiate a screen dump to the printer and B<Ctrl-Print> or 849B<Shift-Print> to include the scrollback as well. 850 851The string will be interpreted as if typed into the shell as-is. 852 853Example: 854 855 URxvt.print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX) 856 857This creates a new file in your home directory with the screen contents 858every time you hit C<Print>. 859 860=item B<scrollstyle:> I<mode> 861 862Set scrollbar style to B<rxvt>, B<plain>, B<next> or B<xterm>. B<plain> is 863the author's favourite. 864 865=item B<thickness:> I<number> 866 867Set the scrollbar width in pixels. 868 869=item B<scrollBar:> I<boolean> 870 871B<True>: enable the scrollbar [default]; option B<-sb>. B<False>: 872disable the scrollbar; option B<+sb>. 873 874=item B<scrollBar_right:> I<boolean> 875 876B<True>: place the scrollbar on the right of the window; option B<-sr>. 877B<False>: place the scrollbar on the left of the window; option B<+sr>. 878 879=item B<scrollBar_floating:> I<boolean> 880 881B<True>: display an rxvt scrollbar without a trough; option B<-st>. 882B<False>: display an rxvt scrollbar with a trough; option B<+st>. 883 884=item B<scrollBar_align:> I<mode> 885 886Align the B<top>, B<bottom> or B<centre> [default] of the scrollbar 887thumb with the pointer on middle button press/drag. 888 889=item B<scrollTtyOutput:> I<boolean> 890 891B<True>: scroll to bottom when tty receives output; option B<-si>. 892B<False>: do not scroll to bottom when tty receives output; option 893B<+si>. 894 895=item B<scrollWithBuffer:> I<boolean> 896 897B<True>: scroll with scrollback buffer when tty receives new lines (i.e. 898try to show the same lines) and B<scrollTtyOutput> is False; option 899B<-sw>. B<False>: do not scroll with scrollback buffer when tty receives 900new lines; option B<+sw>. 901 902=item B<scrollTtyKeypress:> I<boolean> 903 904B<True>: scroll to bottom when a non-special key is pressed. Special keys 905are those which are intercepted by rxvt-unicode for special handling and 906are not passed onto the shell; option B<-sk>. B<False>: do not scroll to 907bottom when a non-special key is pressed; option B<+sk>. 908 909=item B<saveLines:> I<number> 910 911Save I<number> lines in the scrollback buffer [default 1000]; option B<-sl>. 912 913=item B<internalBorder:> I<number> 914 915Internal border of I<number> pixels. This resource is limited to 100; 916option B<-b>. 917 918=item B<externalBorder:> I<number> 919 920External border of I<number> pixels. This resource is limited to 100; 921option B<-w>, B<-bw>, B<-borderwidth>. 922 923=item B<borderLess:> I<boolean> 924 925Set MWM hints to request a borderless window, i.e. if honoured by the 926WM, the rxvt-unicode window will not have window decorations; option B<-bl>. 927 928=item B<skipBuiltinGlyphs:> I<boolean> 929 930Compile I<frills>: Disable the usage of the built-in block graphics/line 931drawing characters and just rely on what the specified fonts provide. Use 932this if you have a good font and want to use its block graphic glyphs; 933option B<-sbg>. 934 935=item B<termName:> I<termname> 936 937Specifies the terminal type name to be set in the B<TERM> environment 938variable; option B<-tn>. 939 940=item B<lineSpace:> I<number> 941 942Specifies number of lines (pixel height) to insert between each row of 943the display [default 0]; option B<-lsp>. 944 945=item B<meta8:> I<boolean> 946 947B<True>: handle Meta (Alt) + keypress to set the 8th bit. B<False>: 948handle Meta (Alt) + keypress as an escape prefix [default]. 949 950=item B<mouseWheelScrollPage:> I<boolean> 951 952B<True>: the mouse wheel scrolls a page full. B<False>: the mouse wheel 953scrolls five lines [default]. 954 955=item B<pastableTabs:> I<boolean> 956 957B<True>: store tabs as wide characters. B<False>: interpret tabs as cursor 958movement only; option C<-ptab>. 959 960=item B<cursorBlink:> I<boolean> 961 962B<True>: blink the cursor. B<False>: do not blink the cursor [default]; 963option B<-bc>. 964 965=item B<cursorUnderline:> I<boolean> 966 967B<True>: Make the cursor underlined. B<False>: Make the cursor a box [default]; 968option B<-uc>. 969 970=item B<pointerBlank:> I<boolean> 971 972B<True>: blank the pointer when a key is pressed or after a set number 973of seconds of inactivity. B<False>: the pointer is always visible 974[default]. 975 976=item B<pointerColor:> I<colour> 977 978Mouse pointer foreground colour. 979 980=item B<pointerColor2:> I<colour> 981 982Mouse pointer background colour. 983 984=item B<pointerShape:> I<string> 985 986Compile I<frills>: Specifies the name of the mouse pointer shape 987[default B<xterm>]. See the macros in the B<X11/cursorfont.h> include 988file for possible values (omit the C<XC_> prefix). 989 990=item B<pointerBlankDelay:> I<number> 991 992Specifies number of seconds before blanking the pointer [default 2]. Use a 993large number (e.g. C<987654321>) to effectively disable the timeout. 994 995=item B<backspacekey:> I<string> 996 997The string to send when the backspace key is pressed. If set to B<DEC> 998or unset it will send B<Delete> (code 127) or, with control, B<Backspace> 999(code 8) - which can be reversed with the appropriate DEC private mode 1000escape sequence. 1001 1002=item B<deletekey:> I<string> 1003 1004The string to send when the delete key (not the keypad delete key) is 1005pressed. If unset it will send the sequence traditionally associated 1006with the B<Execute> key. 1007 1008=item B<cutchars:> I<string> 1009 1010The characters used as delimiters for double-click word selection 1011(whitespace delimiting is added automatically if resource is given). 1012 1013When the perl selection extension is in use (the default if compiled 1014in, see the @@RXVT_NAME@@perl(3) manpage), a suitable regex using these 1015characters will be created (if the resource exists, otherwise, no regex 1016will be created). In this mode, characters outside ISO-8859-1 can be used. 1017 1018When the selection extension is not used, only ISO-8859-1 characters can 1019be used. If not specified, the built-in default is used: 1020 1021B<< BACKSLASH `"'&()*,;<=>?@[]^{|} >> 1022 1023=item B<preeditType:> I<style> 1024 1025B<OnTheSpot>, B<OverTheSpot>, B<OffTheSpot>, B<Root>; option B<-pt>. 1026 1027=item B<inputMethod:> I<name> 1028 1029I<name> of inputMethod to use; option B<-im>. 1030 1031=item B<imLocale:> I<name> 1032 1033The locale to use for opening the IM. You can use an C<LC_CTYPE> of e.g. 1034C<de_DE.UTF-8> for normal text processing but C<ja_JP.EUC-JP> for the 1035input extension to be able to input japanese characters while staying in 1036another locale; option B<-imlocale>. 1037 1038=item B<imFont:> I<fontset> 1039 1040Specify the font-set used for XIM styles C<OverTheSpot> or 1041C<OffTheSpot>. It must be a standard X font set (XLFD patterns separated 1042by commas), i.e. it's not in the same format as the other font lists used 1043in @@RXVT_NAME@@. The default will be set-up to chose *any* suitable found 1044found, preferably one or two pixels differing in size to the base font. 1045option B<-imfont>. 1046 1047=item B<tripleclickwords:> I<boolean> 1048 1049Change the meaning of triple-click selection with the left mouse 1050button. Instead of selecting a full line it will extend the selection to 1051the end of the logical line only; option B<-tcw>. 1052 1053=item B<disablePasteBrackets:> I<boolean> 1054 1055Prevent emission of paste bracket sequences; option B<-dpb>. 1056 1057=item B<insecure:> I<boolean> 1058 1059Enable "insecure" mode. Rxvt-unicode offers some escape sequences that 1060echo arbitrary strings like the icon name or the locale. This could be 1061abused if somebody gets 8-bit-clean access to your display, whether 1062through a mail client displaying mail bodies unfiltered or through 1063write(1) or any other means. Therefore, these sequences are disabled by 1064default. (Note that many other terminals, including xterm, have these 1065sequences enabled by default, which doesn't make it safer, though). 1066 1067You can enable them by setting this boolean resource or specifying 1068B<-insecure> as an option. At the moment, this enables display-answer, 1069locale, findfont, icon label and window title requests. 1070 1071=item B<modifier:> I<modifier> 1072 1073Set the key to be interpreted as the Meta key to: B<alt>, B<meta>, 1074B<hyper>, B<super>, B<mod1>, B<mod2>, B<mod3>, B<mod4>, B<mod5>; option 1075B<-mod>. 1076 1077=item B<answerbackString:> I<string> 1078 1079Specify the reply rxvt-unicode sends to the shell when an ENQ (control-E) 1080character is passed through. It may contain escape values as described 1081in the entry on B<keysym> following. 1082 1083=item B<secondaryScreen:> I<boolean> 1084 1085Turn on/off secondary screen (default enabled). 1086 1087=item B<rewrapMode:> I<mode> 1088 1089Sets long line rewrap behaviour on window resize to one of B<auto> 1090(default), B<always> or B<never>. 1091 1092=item B<secondaryScroll:> I<boolean> 1093 1094Turn on/off secondary screen scroll (default enabled). If this 1095option is enabled, scrolls on the secondary screen will change the 1096scrollback buffer and, when secondaryScreen is off, switching 1097to/from the secondary screen will instead scroll the screen up. 1098 1099=item B<hold>: I<boolean> 1100 1101Turn on/off hold window after exit support. If enabled, @@RXVT_NAME@@ 1102will not immediately destroy its window when the program executed within 1103it exits. Instead, it will wait till it is being killed or closed by the 1104user. 1105 1106=item B<chdir>: I<path> 1107 1108Sets the working directory for the shell (or the command specified via 1109B<-e>). The I<path> must be an absolute path and it must exist for 1110@@RXVT_NAME@@ to start. If it isn't specified then the current working 1111directory will be used; option B<-cd>. 1112 1113=item B<keysym.>I<sym>: I<action> 1114 1115Compile I<frills>: Associate I<action> with keysym I<sym>. The intervening 1116resource name B<keysym.> cannot be omitted. 1117 1118Using this resource, you can map key combinations such as 1119C<Ctrl-Shift-BackSpace> to various actions, such as outputting a different 1120string than would normally result from that combination, making the 1121terminal scroll up or down the way you want it, or any other thing an 1122extension might provide. 1123 1124The key combination that triggers the action, I<sym>, has the following format: 1125 1126 (modifiers-)key 1127 1128Where I<modifiers> can be any combination of the following full or 1129abbreviated modifier names: 1130 1131=begin table 1132 1133 B<ISOLevel3> B<I> 1134 B<AppKeypad> B<K> 1135 B<Control> B<C> 1136 B<NumLock> B<N> 1137 B<Shift> B<S> 1138 B<Meta> B<M> I<or> B<A> 1139 B<Lock> B<L> 1140 B<Mod1> B<1> 1141 B<Mod2> B<2> 1142 B<Mod3> B<3> 1143 B<Mod4> B<4> 1144 B<Mod5> B<5> 1145 1146=end table 1147 1148The B<NumLock>, B<Meta> and B<ISOLevel3> modifiers are usually aliased to 1149whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr 1150keys are being mapped. B<AppKeypad> is a synthetic modifier mapped to the 1151current application keymap mode state. 1152 1153Due the the large number of modifier combinations, a key mapping will 1154match if I<at least> the specified identifiers are being set, and no other 1155key mappings with those and more bits are being defined. That means that 1156defining a mapping for C<a> will automatically provide definitions for 1157C<Meta-a>, C<Shift-a> and so on, unless some of those are defined mappings 1158themselves. See the C<builtin:> action, below, for a way to work around 1159this when this is a problem. 1160 1161The spelling of I<key> depends on your implementation of X. An easy way to 1162find a key name is to use the B<xev>(1) command. You can find a list by 1163looking for the C<XK_> macros in the B<X11/keysymdef.h> include file (omit 1164the C<XK_> prefix). Alternatively you can specify I<key> by its hex keysym 1165value (B<0x0000 - 0xFFFF>). 1166 1167As with any resource value, the I<action> string may contain backslash 1168escape sequences (C<\n>: newline, C<\\>: backslash, C<\000>: octal 1169number), see RESOURCES in C<man 7 X> for further details. 1170 1171An action starts with an action prefix that selects a certain type 1172of action, followed by a colon. An action string without colons is 1173interpreted as a literal string to pass to the tty (as if it was 1174prefixed with C<string:>). 1175 1176The following action prefixes are known - extensions can provide 1177additional prefixes: 1178 1179=over 1180 1181=item string:STRING 1182 1183If the I<action> starts with C<string:> (or otherwise contains no colons), 1184then the remaining C<STRING> will be passed to the program running in the 1185terminal. For example, you could replace whatever Shift-Tab outputs by the 1186string C<echo rm -rf /> followed by a newline: 1187 1188 URxvt.keysym.Shift-Tab: string:echo rm -rf /\n 1189 1190This could in theory be used to completely redefine your keymap. 1191 1192In addition, for actions of this type, you can define a range of 1193keysyms in one shot by loading the C<keysym-list> perl extension and 1194providing an I<action> with pattern B<list/PREFIX/MIDDLE/SUFFIX>, where 1195the delimiter `/' should be a character not used by the strings. 1196 1197Its usage can be demonstrated by an example: 1198 1199 URxvt.keysym.M-C-0x61: list|\033<|abc|> 1200 1201The above line is equivalent to the following three lines: 1202 1203 URxvt.keysym.Meta-Control-0x61: string:\033<a> 1204 URxvt.keysym.Meta-Control-0x62: string:\033<b> 1205 URxvt.keysym.Meta-Control-0x63: string:\033<c> 1206 1207=item command:STRING 1208 1209If I<action> takes the form of C<command:STRING>, the specified B<STRING> 1210is interpreted and executed as @@RXVT_NAME@@'s control sequence (basically 1211the opposite of C<string:> - instead of sending it to the program running 1212in the terminal, it will be treated as if it were program output). This is 1213most useful to feed command sequences into @@RXVT_NAME@@. 1214 1215For example the following means "change the current locale to C<zh_CN.GBK> 1216when Control-Meta-c is being pressed": 1217 1218 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 1219 1220The following example will map Control-Meta-1 and Control-Meta-2 to 1221the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited 1222font-switching at runtime: 1223 1224 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007 1225 URxvt.keysym.M-C-2: command:\033]50;9x15bold\007 1226 1227Other things are possible, e.g. resizing (see @@RXVT_NAME@@(7) for more 1228info): 1229 1230 URxvt.keysym.M-C-3: command:\033[8;25;80t 1231 URxvt.keysym.M-C-4: command:\033[8;48;110t 1232 1233=item builtin: 1234 1235The builtin action is the action that @@RXVT_NAME@@ would execute if no 1236key binding existed for the key combination. The obvious use is to undo 1237the effect of existing bindings. The not so obvious use is to reinstate 1238bindings when another binding overrides too many modifiers. 1239 1240For example if you overwrite the C<Insert> key you will disable 1241@@RXVT_NAME@@'s C<Shift-Insert> mapping. To re-enable that, you can poke 1242"holes" into the user-defined keymap using the C<builtin:> replacement: 1243 1244 URxvt.keysym.Insert: <my insert key sequence> 1245 URxvt.keysym.S-Insert: builtin: 1246 1247The first line defines a mapping for C<Insert> and I<any> combination 1248of modifiers. The second line re-establishes the default mapping for 1249C<Shift-Insert>. 1250 1251=item builtin-string: 1252 1253This action is mainly useful to restore string mappings for keys that 1254have predefined actions in @@RXVT_NAME@@. The exact semantics are a bit 1255difficult to explain - basically, this action will send the string to the 1256application that would be sent if @@RXVT_NAME@@ wouldn't have a built-in 1257action for it. 1258 1259An example might make it clearer: @@RXVT_NAME@@ normally pastes the 1260selection when you press C<Shift-Insert>. With the following bindings, it 1261would instead emit the (undocumented, but what applications running in the 1262terminal might expect) sequence C<ESC [ 2 $> instead: 1263 1264 URxvt.keysym.S-Insert: builtin-string: 1265 URxvt.keysym.C-S-Insert: builtin: 1266 1267The first line disables the paste functionality for that key 1268combination, and the second reinstates the default behaviour for 1269C<Control-Shift-Insert>, which would otherwise be overridden. 1270 1271Similarly, to let applications gain access to the C<C-M-c> (copy to 1272clipboard) and C<C-M-v> (paste clipboard) key combination, you can do 1273this: 1274 1275 URxvt.keysym.C-M-c: builtin-string: 1276 URxvt.keysym.C-M-v: builtin-string: 1277 1278=item EXTENSION:STRING 1279 1280An action of this form invokes the action B<STRING>, if any, provided 1281by the @@RXVT_NAME@@perl(3) extension B<EXTENSION>. The extension will 1282be loaded automatically if necessary. 1283 1284Not all extensions define actions, but popular extensions that do 1285include the I<selection> and I<matcher> extensions (documented in their 1286own manpages, @@RXVT_NAME@@-selection(1) and @@RXVT_NAME@@-matcher(1), 1287respectively). 1288 1289From the silly examples department, this will rot13-"encrypt" 1290@@RXVT_NAME@@'s selection when Alt-Control-c is pressed on typical PC 1291keyboards: 1292 1293 URxvt.keysym.M-C-c: selection:rot13 1294 1295=item perl:STRING *DEPRECATED* 1296 1297This is a deprecated way of invoking commands provided by perl 1298extensions. It is still supported, but should not be used anymore. 1299 1300=back 1301 1302=item B<perl-ext-common>: I<string> 1303 1304=item B<perl-ext>: I<string> 1305 1306Comma-separated list(s) of perl extension scripts (default: C<default>) to 1307use in this terminal instance; option B<-pe>. 1308 1309Extension names can be prefixed with a C<-> sign to remove them again, in 1310case they had been specified earlier. This can be useful to selectively 1311disable some extensions loaded by default, or specified via the 1312C<perl-ext-common> resource. For example, C<default,-selection> will use 1313all the default extensions except C<selection>. 1314 1315To prohibit autoloading of extensions, you can prefix them with C</>, 1316which will make urxvt refuse to automatically load them (this can be 1317overriden, however, by specifying the extension name again without a 1318prefix, though). This does not prohibit extensions themselves loading 1319other extensions. For example, C<default,/background> will keep the 1320C<background> extension from being loaded when a background OSC sequence 1321is received. 1322 1323The default set includes the C<selection>, C<option-popup>, 1324C<selection-popup>, C<readline>, C<searchable-scrollback> and 1325C<confirm-paste> extensions, as well as any extensions which are mentioned 1326in B<keysym> resources. 1327 1328Any extension such that a corresponding resource is given on the 1329command line is automatically appended to B<perl-ext>. 1330 1331Each extension is looked up in the library directories, loaded if 1332necessary, and bound to the current terminal instance. When the library 1333search path contains multiple extension files of the same name, then the 1334first one found will be used. 1335 1336If both of these resources are the empty string, then the perl interpreter 1337will not be initialized. The rationale for having two options is that 1338B<perl-ext-common> will be used for extensions that should be available to 1339all instances, while B<perl-ext> is used for specific instances. 1340 1341=item B<perl-eval>: I<string> 1342 1343Perl code to be evaluated when all extensions have been registered. See 1344the @@RXVT_NAME@@perl(3) manpage. 1345 1346=item B<perl-lib>: I<path> 1347 1348Colon-separated list of additional directories that hold extension 1349scripts. When looking for perl extensions, @@RXVT_NAME@@ will first look 1350in these directories, then in C<$URXVT_PERL_LIB>, F<$HOME/.urxvt/ext> and 1351lastly in F<@@RXVT_LIBDIR@@/urxvt/perl/>. 1352 1353See the @@RXVT_NAME@@perl(3) manpage. 1354 1355=item B<< selection.pattern-I<idx> >>: I<perl-regex> 1356 1357Additional selection patterns, see the @@RXVT_NAME@@perl(3) manpage for 1358details. 1359 1360=item B<< selection-autotransform.I<idx> >>: I<perl-transform> 1361 1362Selection auto-transform patterns, see the @@RXVT_NAME@@perl(3) manpage 1363for details. 1364 1365=item B<searchable-scrollback:> I<keysym> *DEPRECATED* 1366 1367This resource is deprecated and will be removed. Use a B<keysym> resource 1368instead, e.g.: 1369 1370 URxvt.keysym.M-s: searchable-scrollback:start 1371 1372=item B<url-launcher>: I<string> 1373 1374Specifies the program to be started with a URL argument. Used by the 1375C<selection-popup> and C<matcher> perl extensions. 1376 1377=item B<transient-for>: I<windowid> 1378 1379Compile I<frills>: Sets the WM_TRANSIENT_FOR property to the given window id. 1380 1381=item B<override-redirect>: I<boolean> 1382 1383Compile I<frills>: Sets override-redirect for the terminal window, making 1384it almost invisible to window managers; option B<-override-redirect>. 1385 1386=item B<iso14755:> I<boolean> 1387 1388Turn on/off ISO 14755 (default enabled). 1389 1390=item B<iso14755_52:> I<boolean> 1391 1392Turn on/off ISO 14755 5.2 mode (default enabled). 1393 1394=back 1395 1396=head1 THE SCROLLBAR 1397 1398Lines of text that scroll off the top of the B<@@RXVT_NAME@@> window 1399(resource: B<saveLines>) and can be scrolled back using the scrollbar 1400or by keystrokes. The normal B<@@RXVT_NAME@@> scrollbar has arrows and 1401its behaviour is fairly intuitive. The B<xterm-scrollbar> is without 1402arrows and its behaviour mimics that of I<xterm> 1403 1404Scroll down with B<Button1> (B<xterm-scrollbar>) or B<Shift-Next>. 1405Scroll up with B<Button3> (B<xterm-scrollbar>) or B<Shift-Prior>. 1406Continuous scroll with B<Button2>. 1407 1408=head1 MOUSE REPORTING 1409 1410To temporarily override mouse reporting, for either the scrollbar or 1411the normal text selection/insertion, hold either the Shift or the Meta 1412(Alt) key while performing the desired mouse action. 1413 1414If mouse reporting mode is active, the normal scrollbar actions are 1415disabled -- on the assumption that we are using a fullscreen 1416application. Instead, pressing Button1 and Button3 sends B<ESC [ 6 ~> 1417(Next) and B<ESC [ 5 ~> (Prior), respectively. Similarly, clicking on the 1418up and down arrows sends B<ESC [ A> (Up) and B<ESC [ B> (Down), 1419respectively. 1420 1421=head1 THE SELECTION: SELECTING AND PASTING TEXT 1422 1423The behaviour of text selection and insertion/pasting mechanism is similar 1424to I<xterm>(1). 1425 1426=over 1427 1428=item B<Selecting>: 1429 1430Left click at the beginning of the region, drag to the end of the region 1431and release; Right click to extend the marked region; Left double-click 1432to select a word; Left triple-click to select the entire logical line 1433(which can span multiple screen lines), unless modified by resource 1434B<tripleclickwords>. 1435 1436Starting a selection while pressing the B<Meta> key (or B<Meta+Ctrl> keys) 1437(Compile: I<frills>) will create a rectangular selection instead of a 1438normal one. In this mode, every selected row becomes its own line in the 1439selection, and trailing whitespace is visually underlined and removed from 1440the selection. 1441 1442=item B<Pasting>: 1443 1444Pressing and releasing the Middle mouse button in an B<@@RXVT_NAME@@> 1445window causes the value of the PRIMARY selection (or CLIPBOARD with the 1446B<Meta> modifier) to be inserted as if it had been typed on the keyboard. 1447 1448Pressing B<Shift-Insert> causes the value of the PRIMARY selection to be 1449inserted too. 1450 1451rxvt-unicode also provides the bindings B<Ctrl-Meta-c> and 1452<Ctrl-Meta-v> to interact with the CLIPBOARD selection. The first 1453binding causes the value of the internal selection to be copied to the 1454CLIPBOARD selection, while the second binding causes the value of the 1455CLIPBOARD selection to be inserted. 1456 1457=back 1458 1459=head1 CHANGING FONTS 1460 1461Changing fonts (or font sizes, respectively) via the keypad is not yet 1462supported in rxvt-unicode. Bug me if you need this. 1463 1464You can, however, switch fonts at runtime using escape sequences, e.g.: 1465 1466 printf '\e]710;%s\007' "9x15bold,xft:Kochi Gothic" 1467 1468You can use keyboard shortcuts, too: 1469 1470 URxvt.keysym.M-C-1: command:\033]710;suxuseuro\007\033]711;suxuseuro\007 1471 URxvt.keysym.M-C-2: command:\033]710;9x15bold\007\033]711;9x15bold\007 1472 1473rxvt-unicode will automatically re-apply these fonts to the output so far. 1474 1475=head1 ISO 14755 SUPPORT 1476 1477ISO 14755 is a standard for entering and viewing unicode characters 1478and character codes using the keyboard. It consists of 4 parts. The 1479first part is available if rxvt-unicode has been compiled with 1480C<--enable-frills>, the rest is available when rxvt-unicode was compiled 1481with C<--enable-iso14755>. 1482 1483=over 1484 1485=item * 5.1: Basic method 1486 1487This allows you to enter unicode characters using their hexcode. 1488 1489Start by pressing and holding both C<Control> and C<Shift>, then enter 1490hex-digits (between one and six). Releasing C<Control> and C<Shift> will 1491commit the character as if it were typed directly. While holding down 1492C<Control> and C<Shift> you can also enter multiple characters by pressing 1493C<Space>, which will commit the current character and lets you start a new 1494one. 1495 1496As an example of use, imagine a business card with a japanese e-mail 1497address, which you cannot type. Fortunately, the card has the e-mail 1498address printed as hexcodes, e.g. C<671d 65e5>. You can enter this easily 1499by pressing C<Control> and C<Shift>, followed by C<6-7-1-D-SPACE-6-5-E-5>, 1500followed by releasing the modifier keys. 1501 1502=item * 5.2: Keyboard symbols entry method 1503 1504This mode lets you input characters representing the keycap symbols of 1505your keyboard, if representable in the current locale encoding. 1506 1507Start by pressing C<Control> and C<Shift> together, then releasing 1508them. The next special key (cursor keys, home etc.) you enter will not 1509invoke its usual function but instead will insert the corresponding 1510keycap symbol. The symbol will only be entered when the key has been 1511released, otherwise pressing e.g. C<Shift> would enter the symbol for 1512C<ISO Level 2 Switch>, although your intention might have been to enter a 1513reverse tab (Shift-Tab). 1514 1515=item * 5.3: Screen-selection entry method 1516 1517While this is implemented already (it's basically the selection 1518mechanism), it could be extended by displaying a unicode character map. 1519 1520=item * 5.4: Feedback method for identifying displayed characters for later input 1521 1522This method lets you display the unicode character code associated with 1523characters already displayed. 1524 1525You enter this mode by holding down C<Control> and C<Shift> together, then 1526pressing and holding the left mouse button and moving around. The unicode 1527hex code(s) (it might be a combining character) of the character under the 1528pointer is displayed until you release C<Control> and C<Shift>. 1529 1530In addition to the hex codes it will display the font used to draw this 1531character - due to implementation reasons, characters combined with 1532combining characters, line drawing characters and unknown characters will 1533always be drawn using the built-in support font. 1534 1535=back 1536 1537With respect to conformance, rxvt-unicode is supposed to be compliant to 1538both scenario A and B of ISO 14755, including part 5.2. 1539 1540=head1 LOGIN STAMP 1541 1542B<@@RXVT_NAME@@> tries to write an entry into the I<utmp>(5) file so that 1543it can be seen via the I<who(1)> command, and can accept messages. To 1544allow this feature, B<@@RXVT_NAME@@> may need to be installed setuid root 1545on some systems or setgid to root or to some other group on others. 1546 1547=head1 COLOURS AND GRAPHICS 1548 1549In addition to the default foreground and background colours, 1550B<@@RXVT_NAME@@> can display up to 88/256 colours: 8 ANSI colours plus 1551high-intensity (potentially bold/blink) versions of the same, and 72 (or 1552240 in 256 colour mode) colours arranged in an 4x4x4 (or 6x6x6) colour RGB 1553cube plus a 8 (24) colour greyscale ramp. 1554 1555B<@@RXVT_NAME@@> supports direct 24-bit fg/bg RGB colour escapes 1556C< ESC [ 38 ; 2 ; R ; G ; Bm > / C< ESC [ 48 ; 2; R ; G ; Bm >. However the 1557number of 24-bit colours that can be used is limited: an internal 7x7x5 (256 1558colour mode) or 6x6x4 (88 colour mode) colour cube is used to index into the 155924-bit colour space. When indexing collisions happen, the nearest old colour in 1560the cube will be adapted to the new 24-bit RGB colour. That means one cannot 1561use many similar 24-bit colours. It's typically not a problem in common 1562scenarios. 1563 1564Here is a list of the ANSI colours with their names. 1565 1566=begin table 1567 1568 B<color0> (black) = Black 1569 B<color1> (red) = Red3 1570 B<color2> (green) = Green3 1571 B<color3> (yellow) = Yellow3 1572 B<color4> (blue) = Blue3 1573 B<color5> (magenta) = Magenta3 1574 B<color6> (cyan) = Cyan3 1575 B<color7> (white) = AntiqueWhite 1576 B<color8> (bright black) = Grey25 1577 B<color9> (bright red) = Red 1578 B<color10> (bright green) = Green 1579 B<color11> (bright yellow) = Yellow 1580 B<color12> (bright blue) = Blue 1581 B<color13> (bright magenta) = Magenta 1582 B<color14> (bright cyan) = Cyan 1583 B<color15> (bright white) = White 1584 B<foreground> = Black 1585 B<background> = White 1586 1587=end table 1588 1589It is also possible to specify the colour values of B<foreground>, 1590B<background>, B<cursorColor>, B<cursorColor2>, B<colorBD>, B<colorUL> as 1591a number 0-15, as a convenient shorthand to reference the colour name of 1592color0-color15. 1593 1594The following text gives values for the standard 88 colour mode (and 1595values for the 256 colour mode in parentheses). 1596 1597The RGB cube uses indices 16..79 (16..231) using the following formulas: 1598 1599 index_88 = (r * 4 + g) * 4 + b + 16 # r, g, b = 0..3 1600 index_256 = (r * 6 + g) * 6 + b + 16 # r, g, b = 0..5 1601 1602The grayscale ramp uses indices 80..87 (232..239), from 10% to 90% in 10% 1603steps (1/26 to 25/26 in 1/26 steps) - black and white are already part of 1604the RGB cube. 1605 1606Together, all those colours implement the 88 (256) colour xterm 1607colours. Only the first 16 can be changed using resources currently, the 1608rest can only be changed via command sequences ("escape codes"). 1609 1610Applications are advised to use terminfo or command sequences to discover 1611number and RGB values of all colours (yes, you can query this...). 1612 1613Note that B<-rv> (B<"reverseVideo: True">) simulates reverse video by 1614always swapping the foreground/background colours. This is in contrast to 1615I<xterm>(1) where the colours are only swapped if they have not otherwise 1616been specified. For example, 1617 1618 @@RXVT_NAME@@ -fg Black -bg White -rv 1619 1620would yield White on Black, while on I<xterm>(1) it would yield Black on 1621White. 1622 1623=head2 ALPHA CHANNEL SUPPORT 1624 1625If Xft support has been compiled in and as long as Xft/Xrender/X don't get 1626their act together, rxvt-unicode will do its own alpha channel management: 1627 1628You can prefix any colour with an opaqueness percentage enclosed in 1629brackets, i.e. C<[percent]>, where C<percent> is a decimal percentage 1630(0-100) that specifies the opacity of the colour, where C<0> is completely 1631transparent and C<100> is completely opaque. For example, C<[50]red> is a 1632half-transparent red, while C<[95]#00ff00> is an almost opaque green. This 1633is the recommended format to specify transparency values, and works with 1634all ways to specify a colour. 1635 1636For complete control, rxvt-unicode also supports 1637C<rgba:rrrr/gggg/bbbb/aaaa> (exactly four hex digits/component) colour 1638specifications, where the additional C<aaaa> component specifies opacity 1639(alpha) values. The minimum value of C<0000> is completely transparent, 1640while C<ffff> is completely opaque). The two example colours from 1641earlier could also be specified as C<rgba:ff00/0000/0000/8000> and 1642C<rgba:0000/ff00/0000/f332>. 1643 1644You probably need to specify B<"-depth 32">, too, to force a visual with 1645alpha channels, and have the luck that your X-server uses ARGB pixel 1646layout, as X is far from just supporting ARGB visuals out of the box, and 1647rxvt-unicode just fudges around. 1648 1649For example, the following selects an almost completely transparent black 1650background, and an almost opaque pink foreground: 1651 1652 @@RXVT_NAME@@ -depth 32 -bg rgba:0000/0000/0000/4444 -fg "[80]pink" 1653 1654When not using a background image, then the interpretation of the 1655alpha channel is up to your compositing manager (most interpret it as 1656transparency of course). 1657 1658When using a background pixmap or pseudo-transparency, then the background 1659colour will always behave as if it were completely transparent (so the 1660background image shows instead), regardless of how it was specified, while 1661other colours will either be transparent as specified (the background 1662image will show through) on servers supporting the RENDER extension, or 1663fully opaque on servers not supporting the RENDER EXTENSION. 1664 1665Please note that due to bugs in Xft, specifying alpha values might result 1666in garbage being displayed when the X-server does not support the RENDER 1667extension. 1668 1669=head1 ENVIRONMENT 1670 1671B<@@RXVT_NAME@@> sets and/or uses the following environment variables: 1672 1673=over 1674 1675=item B<TERM> 1676 1677Normally set to C<rxvt-unicode>, unless overwritten at configure time, via 1678resources or on the command line. 1679 1680=item B<COLORTERM> 1681 1682Either C<rxvt>, C<rxvt-xpm>, depending on whether @@RXVT_NAME@@ was 1683compiled with background image support, and optionally with the added 1684extension C<-mono> to indicate that rxvt-unicode runs on a monochrome 1685screen. 1686 1687=item B<COLORFGBG> 1688 1689Set to a string of the form C<fg;bg> or C<fg;xpm;bg>, where C<fg> is 1690the colour code used as default foreground/text colour (or the string 1691C<default> to indicate that the default-colour escape sequence is to be 1692used), C<bg> is the colour code used as default background colour (or the 1693string C<default>), and C<xpm> is the string C<default> if @@RXVT_NAME@@ 1694was compiled with background image support. Libraries like C<ncurses> 1695and C<slang> can (and do) use this information to optimize screen output. 1696 1697=item B<WINDOWID> 1698 1699Set to the (decimal) X Window ID of the @@RXVT_NAME@@ window (the toplevel 1700window, which usually has subwindows for the scrollbar, the terminal 1701window and so on). 1702 1703=item B<TERMINFO> 1704 1705Set to the terminfo directory iff @@RXVT_NAME@@ was configured with 1706C<--with-terminfo=PATH>. 1707 1708=item B<DISPLAY> 1709 1710Used by @@RXVT_NAME@@ to connect to the display and set to the correct 1711display in its child processes if C<-display> isn't used to override. It 1712defaults to C<:0> if it doesn't exist. 1713 1714=item B<SHELL> 1715 1716The shell to be used for command execution, defaults to C</bin/sh>. 1717 1718=item B<RXVT_SOCKET> [I<sic>] 1719 1720The unix domain socket path used by @@RXVT_NAME@@c(1) and 1721@@RXVT_NAME@@d(1). 1722 1723Default F<<< $HOME/.urxvt/urxvtd-I<< <nodename> >> >>>. 1724 1725=item B<URXVT_PERL_LIB> 1726 1727Additional F<:>-separated library search path for perl extensions. Will be 1728searched after B<-perl-lib> but before F<~/.urxvt/ext> and the system library 1729directory. 1730 1731=item B<URXVT_PERL_VERBOSITY> 1732 1733See L<@@RXVT_NAME@@perl>(3). 1734 1735=item B<HOME> 1736 1737Used to locate the default directory for the unix domain socket for 1738daemon communications and to locate various resource files (such as 1739C<.Xdefaults>) 1740 1741=item B<XAPPLRESDIR> 1742 1743Directory where application-specific X resource files are located. 1744 1745=item B<XENVIRONMENT> 1746 1747If set and accessible, gives the name of a X resource file to be loaded by 1748@@RXVT_NAME@@. 1749 1750=back 1751 1752=head1 FILES 1753 1754=over 1755 1756=item B</usr/lib/X11/rgb.txt> 1757 1758Colour names. 1759 1760=back 1761 1762=head1 SEE ALSO 1763 1764@@RXVT_NAME@@(7), @@RXVT_NAME@@c(1), @@RXVT_NAME@@d(1), @@RXVT_NAME@@-extensions(1), 1765@@RXVT_NAME@@perl(3), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5) 1766 1767=head1 CURRENT PROJECT COORDINATOR 1768 1769=over 1770 1771=item Project Coordinator 1772 1773Marc A. Lehmann <rxvt-unicode@schmorp.de>. 1774 1775L<http://software.schmorp.de/pkg/rxvt-unicode.html> 1776 1777=back 1778 1779=head1 AUTHORS 1780 1781=over 1782 1783=item John Bovey 1784 1785University of Kent, 1992, wrote the original Xvt. 1786 1787=item Rob Nation <nation@rocket.sanders.lockheed.com> 1788 1789very heavily modified Xvt and came up with Rxvt 1790 1791=item Angelo Haritsis <ah@doc.ic.ac.uk> 1792 1793wrote the Greek Keyboard Input (no longer in code) 1794 1795=item mj olesen <olesen@me.QueensU.CA> 1796 1797Wrote the menu system. 1798 1799Project Coordinator (changes.txt 2.11 to 2.21) 1800 1801=item Oezguer Kesim <kesim@math.fu-berlin.de> 1802 1803Project Coordinator (changes.txt 2.21a to 2.4.5) 1804 1805=item Geoff Wing <gcw@pobox.com> 1806 1807Rewrote screen display and text selection routines. 1808 1809Project Coordinator (changes.txt 2.4.6 - rxvt-unicode) 1810 1811=item Marc Alexander Lehmann <rxvt-unicode@schmorp.de> 1812 1813Forked rxvt-unicode, unicode support, rewrote almost all the code, perl 1814extension, random hacks, numerous bugfixes and extensions. 1815 1816Project Coordinator (Changes 1.0 -) 1817 1818=item Emanuele Giaquinta <emanuele.giaquinta@gmail.com> 1819 1820pty/utmp code rewrite, image code improvements, many random hacks and bugfixes. 1821 1822=back 1823 1824