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.48 by root, Thu Feb 3 10:24:10 2005 UTC vs.
Revision 1.68 by root, Thu Aug 11 02:05:07 2005 UTC

14configurability. As a result, B<rxvt-unicode> uses much less swap space -- 14configurability. As a result, B<rxvt-unicode> uses much less swap space --
15a significant advantage on a machine serving many X sessions. 15a significant advantage on a machine serving many X sessions.
16 16
17=head1 FREQUENTLY ASKED QUESTIONS 17=head1 FREQUENTLY ASKED QUESTIONS
18 18
19See @@RXVT_NAME@@(7) (try C<man 7 @@RXVT_NAME@@>) for a list of frequently 19See @@RXVT_NAME@@(7) (try C<man 7 @@RXVT_NAME@@>) for a list of
20asked questions and answer to them and some common problems. 20frequently asked questions and answer to them and some common
21problems. That document is also accessible on the World-Wide-Web at
22L<http://cvs.schmorp.de/browse/*checkout*/rxvt-unicode/doc/rxvt.7.html>.
21 23
22=head1 RXVT-UNICODE VS. RXVT 24=head1 RXVT-UNICODE VS. RXVT
23 25
24Unlike the original rxvt, B<rxvt-unicode> stores all text in Unicode 26Unlike the original rxvt, B<rxvt-unicode> stores all text in Unicode
25internally. That means it can store and display most scripts in the 27internally. That means it can store and display most scripts in the
110Turn on/off inheriting parent window's pixmap. Alternative form is 112Turn on/off inheriting parent window's pixmap. Alternative form is
111B<-tr>; resource B<inheritPixmap>. 113B<-tr>; resource B<inheritPixmap>.
112 114
113=item B<-fade> I<number> 115=item B<-fade> I<number>
114 116
115Fade the text by the given percentage when focus is lost. resource B<fading>. 117Fade the text by the given percentage when focus is lost. Small values
118fade a little only, 100 completely replaces all colours by the fade
119colour; resource B<fading>.
120
121=item B<-fadecolor> I<colour>
122
123Fade to this colour when fading is used (see B<-fade>). The default colour
124is black. resource B<fadeColor>.
116 125
117=item B<-tint> I<colour> 126=item B<-tint> I<colour>
118 127
119Tint the transparent background pixmap with the given colour when 128Tint the transparent background pixmap with the given colour when
120transparency is enabled with B<-tr> or B<-ip>. See also the B<-sh> 129transparency is enabled with B<-tr> or B<-ip>. See also the B<-sh>
121option that can be used to brighten or darken the image in addition to 130option that can be used to brighten or darken the image in addition to
122tinting it. 131tinting it; resource I<tintColor>.
123 132
124=item B<-sh> 133=item B<-sh>
125 134
126I<number> Darken (0 .. 100) or lighten (-1 .. -100) the transparent 135I<number> Darken (0 .. 100) or lighten (-1 .. -100) the transparent
127background image in addition to tinting it (i.e. B<-tint> must be 136background image in addition to tinting it (i.e. B<-tint> must be
236 245
237Put scrollbar on right/left; resource B<scrollBar_right>. 246Put scrollbar on right/left; resource B<scrollBar_right>.
238 247
239=item B<-st>|B<+st> 248=item B<-st>|B<+st>
240 249
241Display normal (non XTerm/NeXT) scrollbar without/with a trough; 250Display rxvt (non XTerm/NeXT) scrollbar without/with a trough;
242resource B<scrollBar_floating>. 251resource B<scrollBar_floating>.
243 252
244=item B<-ptab>|B<+ptab> 253=item B<-ptab>|B<+ptab>
245 254
246If enabled (default), "Horizontal Tab" characters are being stored as 255If enabled (default), "Horizontal Tab" characters are being stored as
366=item B<-ssr>|B<+ssr> 375=item B<-ssr>|B<+ssr>
367 376
368Turn on/off secondary screen scroll (default enabled); resource 377Turn on/off secondary screen scroll (default enabled); resource
369B<secondaryScroll>. 378B<secondaryScroll>.
370 379
371=item B<-xrm> I<resourcestring> 380=item B<-keysym.>I<sym> I<string>
372 381
373No effect on rxvt-unicode. Simply passes through an argument to be made 382Remap a key symbol. See resource B<keysym>.
374available in the instance's argument list. Appears in I<WM_COMMAND> in 383
375some window managers. 384=item B<-embed> I<windowid>
385
386Tells @@RXVT_NAME@@ to embed it's windows into an already-existing window,
387which enables applications to easily embed a terminal.
388
389Right now, @@RXVT_NAME@@ will first unmap/map the specified window, so it
390shouldn't be a top-level window. @@RXVT_NAME@@ will also reconfigure it
391quite a bit, so don't expect it to keep some specific state. It's best to
392create an extra subwindow for @@RXVT_NAME@@ and leave it alone.
393
394The window will not be destroyed when @@RXVT_NAME@@ exits.
395
396It might be useful to know that @@RXVT_NAME@@ will not close file
397descriptors passed to it (except for stdin/out/err, of course), so you
398can use file descriptors to communicate with the programs within the
399terminal. This works regardless of wether the C<-embed> option was used or
400not.
401
402Here is a short Gtk2-perl snippet that illustrates how this option can be
403used (a longer example is in F<doc/embed>):
404
405 my $rxvt = new Gtk2::Socket;
406 $rxvt->signal_connect_after (realize => sub {
407 my $xid = $_[0]->window->get_xid;
408 system "@@RXVT_NAME@@ -embed $xid &";
409 });
410
411=item B<-pty-fd> I<fileno>
412
413Tells @@RXVT_NAME@@ NOT to execute any commands or create a new pty/tty
414pair but instead use the given filehandle as the tty master. This is
415useful if you want to drive @@RXVT_NAME@@ as a generic terminal emulator
416without having to run a program within it.
417
418If this switch is given, @@RXVT_NAME@@ will not create any utmp/wtmp
419entries and will not tinker with pty/tty permissions - you have to do that
420yourself if you want that.
421
422Here is a example in perl that illustrates how this option can be used (a
423longer example is in F<doc/pty-fd>):
424
425 use IO::Pty;
426 use Fcntl;
427
428 my $pty = new IO::Pty;
429 fcntl $pty, F_SETFD, 0; # clear close-on-exec
430 system "@@RXVT_NAME@@ -pty-fd " . (fileno $pty) . "&";
431 close $pty;
432
433 # now communicate with rxvt
434 my $slave = $pty->slave;
435 while (<$slave>) { print $slave "got <$_>\n" }
376 436
377=back 437=back
378 438
379=head1 RESOURCES (available also as long-options) 439=head1 RESOURCES (available also as long-options)
380 440
383 443
384There are two different methods that @@RXVT_NAME@@ can use to get the 444There are two different methods that @@RXVT_NAME@@ can use to get the
385Xresource data: using the X libraries (Xrm*-functions) or internal 445Xresource data: using the X libraries (Xrm*-functions) or internal
386Xresources reader (B<~/.Xdefaults>). For the first method (ie. 446Xresources reader (B<~/.Xdefaults>). For the first method (ie.
387B<@@RXVT_NAME@@ -h> lists B<XGetDefaults>), you can set and change the 447B<@@RXVT_NAME@@ -h> lists B<XGetDefaults>), you can set and change the
388resources using X11 tools like B<xset>. Many distribution do also load 448resources using X11 tools like B<xrdb>. Many distribution do also load
389settings from the B<~/.Xresources> file when X starts. 449settings from the B<~/.Xresources> file when X starts. @@RXVT_NAME@@
450will consult the following files/resources in order, with later settings
451overwriting earlier ones:
452
453 1. system-wide app-defaults file, either locale-dependent OR global
454 2. app-defaults file in $XAPPLRESDIR
455 3. RESOURCE_MANAGER property on root-window OR $HOME/.Xdefaults
456 4. SCREEN_RESOURCES for the current screen
457 5. $XENVIRONMENT file OR $HOME/.Xdefaults-<nodename>
390 458
391If compiled with internal Xresources support (i.e. B<@@RXVT_NAME@@ -h> 459If compiled with internal Xresources support (i.e. B<@@RXVT_NAME@@ -h>
392lists B<.Xdefaults>) then B<@@RXVT_NAME@@> accepts application defaults 460lists B<.Xdefaults>) then B<@@RXVT_NAME@@> accepts application defaults
393set in XAPPLOADDIR/URxvt (compile-time defined: usually 461set in XAPPLOADDIR/URxvt (compile-time defined: usually
394B</usr/lib/X11/app-defaults/URxvt>) and resources set in 462B</usr/lib/X11/app-defaults/URxvt>) and resources set in
487artificial transparency. B<False>: do not inherit the parent windows' 555artificial transparency. B<False>: do not inherit the parent windows'
488pixmap. 556pixmap.
489 557
490=item B<fading:> I<number> 558=item B<fading:> I<number>
491 559
492Fade the text by the given percentage when focus is lost. 560Fade the text by the given percentage when focus is lost; option B<-fade>.
561
562=item B<fadeColor:> I<colour>
563
564Fade to this colour, when fading is used (see B<fading:>). The default
565colour is black; option B<-fadecolor>.
493 566
494=item B<tintColor:> I<colour> 567=item B<tintColor:> I<colour>
495 568
496Tint the transparent background pixmap with the given colour. 569Tint the transparent background pixmap with the given colour; option
570B<-tint>.
497 571
498=item B<shading:> I<number> 572=item B<shading:> I<number>
499 573
500Darken (0 .. 100) or lighten (-1 .. -100) the transparent background 574Darken (0 .. 100) or lighten (-1 .. -100) the transparent background
501image in addition to tinting it. 575image in addition to tinting it.
505Use the specified colour for the scrollbar [default #B2B2B2]. 579Use the specified colour for the scrollbar [default #B2B2B2].
506 580
507=item B<troughColor:> I<colour> 581=item B<troughColor:> I<colour>
508 582
509Use the specified colour for the scrollbar's trough area [default 583Use the specified colour for the scrollbar's trough area [default
510#969696]. Only relevant for normal (non XTerm/NeXT) scrollbar. 584#969696]. Only relevant for rxvt (non XTerm/NeXT) scrollbar.
511 585
512=item B<borderColor:> I<colour> 586=item B<borderColor:> I<colour>
513 587
514The colour of the border around the text area and between the scrollbar 588The colour of the border around the text area and between the scrollbar
515and the text. 589and the text.
607xterm style selection. 681xterm style selection.
608 682
609=item B<scrollstyle:> I<mode> 683=item B<scrollstyle:> I<mode>
610 684
611Set scrollbar style to B<rxvt>, B<plain>, B<next> or B<xterm>. B<plain> is 685Set scrollbar style to B<rxvt>, B<plain>, B<next> or B<xterm>. B<plain> is
612the author's favourite.. 686the author's favourite.
613 687
614=item B<title:> I<string> 688=item B<title:> I<string>
615 689
616Set window title string, the default title is the command-line 690Set window title string, the default title is the command-line
617specified after the B<-e> option, if any, otherwise the application 691specified after the B<-e> option, if any, otherwise the application
649 723
650Specify a command pipe for vt100 printer [default I<lpr(1)>]. Use 724Specify a command pipe for vt100 printer [default I<lpr(1)>]. Use
651B<Print> to initiate a screen dump to the printer and B<Ctrl-Print> or 725B<Print> to initiate a screen dump to the printer and B<Ctrl-Print> or
652B<Shift-Print> to include the scrollback as well. 726B<Shift-Print> to include the scrollback as well.
653 727
728The string will be interpreted as if typed into the shell as-is.
729
730Example:
731
732 URxvt*print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX)
733
734This creates a new file in your home directory with the screen contents
735everytime you hit C<Print>.
736
654=item B<scrollBar:> I<boolean> 737=item B<scrollBar:> I<boolean>
655 738
656B<True>: enable the scrollbar [default]; option B<-sb>. B<False>: 739B<True>: enable the scrollbar [default]; option B<-sb>. B<False>:
657disable the scrollbar; option B<+sb>. 740disable the scrollbar; option B<+sb>.
658 741
678B<+si>. 761B<+si>.
679 762
680=item B<scrollWithBuffer:> I<boolean> 763=item B<scrollWithBuffer:> I<boolean>
681 764
682B<True>: scroll with scrollback buffer when tty receives new lines (and 765B<True>: scroll with scrollback buffer when tty receives new lines (and
683B<scrollTtyOutput> is False); option B<+sw>. B<False>: do not scroll 766B<scrollTtyOutput> is False); option B<-sw>. B<False>: do not scroll
684with scrollback buffer when tty recieves new lines; option B<-sw>. 767with scrollback buffer when tty recieves new lines; option B<+sw>.
685 768
686=item B<scrollTtyKeypress:> I<boolean> 769=item B<scrollTtyKeypress:> I<boolean>
687 770
688B<True>: scroll to bottom when a non-special key is pressed. Special keys 771B<True>: scroll to bottom when a non-special key is pressed. Special keys
689are those which are intercepted by rxvt-unicode for special handling and 772are those which are intercepted by rxvt-unicode for special handling and
754 837
755Mouse pointer background colour. 838Mouse pointer background colour.
756 839
757=item B<pointerBlankDelay:> I<number> 840=item B<pointerBlankDelay:> I<number>
758 841
759Specifies number of seconds before blanking the pointer [default 2]. 842Specifies number of seconds before blanking the pointer [default 2]. Use a
843large number (e.g. C<987654321>) to effectively disable the timeout.
760 844
761=item B<backspacekey:> I<string> 845=item B<backspacekey:> I<string>
762 846
763The string to send when the backspace key is pressed. If set to B<DEC> 847The string to send when the backspace key is pressed. If set to B<DEC>
764or unset it will send B<Delete> (code 127) or, if shifted, B<Backspace> 848or unset it will send B<Delete> (code 127) or, if shifted, B<Backspace>
896example the following means "change the current locale to C<zh_CN.GBK> 980example the following means "change the current locale to C<zh_CN.GBK>
897when Control-Meta-c is being pressed": 981when Control-Meta-c is being pressed":
898 982
899 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 983 URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007
900 984
985Due the the large number of modifier combinations, a defined key mapping
986will match if at I<at least> the specified identifiers are being set, and
987no other key mappings with those and more bits are being defined. That
988means that defining a key map for C<a> will automatically provide
989definitions for C<Meta-a>, C<Shift-a> and so on, unless some of those are defined
990mappings themselves.
991
992Unfortunately, this will override built-in key mappings. For example
993if you overwrite the C<Insert> key you will disable @@RXVT_NAME@@'s
994C<Shift-Insert> mapping. To re-enable that, you can poke "holes" into the
995user-defined keymap using the C<builtin:> replacement:
996
997 URxvt.keysym.Insert: <my insert key sequence>
998 URxvt.keysym.S-Insert: builtin:
999
1000The first line defines a mapping for C<Insert> and I<any> combination
1001of modifiers. The second line re-establishes the default mapping for
1002C<Shift-Insert>.
1003
901The following example will map Control-Meta-1 and Control-Meta-2 to 1004The following example will map Control-Meta-1 and Control-Meta-2 to
902the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited 1005the fonts C<suxuseuro> and C<9x15bold>, so you can have some limited
903font-switching at runtime: 1006font-switching at runtime:
904 1007
905 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007 1008 URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
931the normal text selection/insertion, hold either the Shift or the Meta 1034the normal text selection/insertion, hold either the Shift or the Meta
932(Alt) key while performing the desired mouse action. 1035(Alt) key while performing the desired mouse action.
933 1036
934If mouse reporting mode is active, the normal scrollbar actions are 1037If mouse reporting mode is active, the normal scrollbar actions are
935disabled -- on the assumption that we are using a fullscreen 1038disabled -- on the assumption that we are using a fullscreen
936application. Instead, pressing Button1 and Button3 sends B<ESC[6~> 1039application. Instead, pressing Button1 and Button3 sends B<ESC [ 6 ~>
937(Next) and B<ESC[5~> (Prior), respectively. Similarly, clicking on the 1040(Next) and B<ESC [ 5 ~> (Prior), respectively. Similarly, clicking on the
938up and down arrows sends B<ESC[A> (Up) and B<ESC[B> (Down), 1041up and down arrows sends B<ESC [ A> (Up) and B<ESC [ B> (Down),
939respectively. 1042respectively.
940 1043
941=head1 TEXT SELECTION AND INSERTION 1044=head1 TEXT SELECTION AND INSERTION
942 1045
943The behaviour of text selection and insertion mechanism is similar to 1046The behaviour of text selection and insertion mechanism is similar to
1098 1201
1099=back 1202=back
1100 1203
1101=head1 ENVIRONMENT 1204=head1 ENVIRONMENT
1102 1205
1103B<@@RXVT_NAME@@> sets the environment variables B<TERM>, B<COLORTERM> 1206B<@@RXVT_NAME@@> sets and/or uses the following environment variables:
1104and B<COLORFGBG>. The environment variable B<WINDOWID> is set to the X 1207
1105window id number of the B<@@RXVT_NAME@@> window and it also uses and 1208=over 4
1106sets the environment variable B<DISPLAY> to specify which display 1209
1107terminal to use. B<@@RXVT_NAME@@> uses the environment variables 1210=item B<TERM>
1108B<RXVTPATH> and B<PATH> to find XPM files. 1211
1212Normally set to C<rxvt-unicode>, unless overwritten at configure time, via
1213resources or on the commandline.
1214
1215=item B<COLORTERM>
1216
1217Either C<rxvt>, C<rxvt-xpm>, depending on wether @@RXVT_NAME@@ was
1218compiled with XPM support, and optionally with the added extension
1219C<-mono> to indicate that rxvt-unicode runs on a monochrome screen.
1220
1221=item B<COLORFGBG>
1222
1223Set to a string of the form C<fg;bg> or C<fg;xpm;bg>, where C<fg> is
1224the colour code used as default foreground/text colour (or the string
1225C<default> to indicate that the default-colour escape sequence is to be
1226used), C<bg> is the colour code used as default background colour (or the
1227string C<default>), and C<xpm> is the string C<default> if @@RXVT_NAME@@
1228was compiled with XPM support. Libraries like C<ncurses> and C<slang> can
1229(and do) use this information to optimize screen output.
1230
1231=item B<WINDOWID>
1232
1233Set to the (decimal) X Window ID of the @@RXVT_NAME@@ window (the toplevel
1234window, which usually has subwindows for the scrollbar, the terminal
1235window and so on).
1236
1237=item B<TERMINFO>
1238
1239Set to the terminfo directory iff @@RXVT_NAME@@ was configured with
1240C<--with-terminfo=PATH>.
1241
1242=item B<DISPLAY>
1243
1244Used by @@RXVT_NAME@@ to connect to the display and set to the correct
1245display in it's child processes.
1246
1247=item B<SHELL>
1248
1249The shell to be used for command execution, defaults to C</bin/sh>.
1250
1251=item B<RXVTPATH>
1252
1253The path where @@RXVT_NAME@@ looks for support files such as menu and xpm
1254files.
1255
1256=item B<PATH>
1257
1258Used in the same way as C<RXVTPATH>.
1259
1260=item B<RXVT_SOCKET>
1261
1262The unix domain socket path used by @@RXVT_NAME@@c(1) and
1263@@RXVT_NAME@@d(1).
1264
1265Default F<<< $HOME/.rxvt-unicode-I<< <nodename >> >>>.
1266
1267=item B<HOME>
1268
1269Used to locate the default directory for the unix domain socket for
1270daemon communications and to locate various resource files (such as
1271C<.Xdefaults>)
1272
1273=item B<XAPPLRESDIR>
1274
1275Directory where various X resource files are being located.
1276
1277=item B<XENVIRONMENT>
1278
1279If set and accessible, gives the name of a X resource file to be loaded by
1280@@RXVT_NAME@@.
1281
1282=back
1109 1283
1110=head1 FILES 1284=head1 FILES
1111 1285
1112=over 4 1286=over 4
1113 1287
1117 1291
1118=back 1292=back
1119 1293
1120=head1 SEE ALSO 1294=head1 SEE ALSO
1121 1295
1122@@RXVT_NAME@@(7), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5) 1296@@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)
1123 1297
1124=head1 BUGS 1298=head1 BUGS
1125 1299
1126Check the BUGS file for an up-to-date list. 1300Check the BUGS file for an up-to-date list.
1127 1301
1133 1307
1134=over 4 1308=over 4
1135 1309
1136=item Project Coordinator 1310=item Project Coordinator
1137 1311
1138@@RXVT_MAINT@@ L<@@RXVT_MAINTEMAIL@@> 1312Marc A. Lehmann L<< <rxvt-unicode@schmorp.de> >>
1139 1313
1140=item Web page maintainter 1314L<http://software.schmorp.de/#rxvt-unicode>
1141
1142@@RXVT_WEBMAINT@@ L<@@RXVT_WEBMAINTEMAIL@@>
1143
1144L<@@RXVT_WEBPAGE@@>
1145 1315
1146=back 1316=back
1147 1317
1148=head1 AUTHORS 1318=head1 AUTHORS
1149 1319
1174=item Geoff Wing L<< <gcw@pobox.com> >> 1344=item Geoff Wing L<< <gcw@pobox.com> >>
1175 1345
1176Rewrote screen display and text selection routines. Project Coordinator 1346Rewrote screen display and text selection routines. Project Coordinator
1177(changes.txt 2.4.6 - rxvt-unicode) 1347(changes.txt 2.4.6 - rxvt-unicode)
1178 1348
1179=item Marc Alexander Lehmann L<< <rxvt@schmorp.de> >> 1349=item Marc Alexander Lehmann L<< <rxvt-unicode@schmorp.de> >>
1180 1350
1181Forked rxvt-unicode, rewrote most of the display code and internal 1351Forked rxvt-unicode, rewrote most of the display code and internal
1182character handling to store text in unicode, improve xterm 1352character handling to store text in unicode, improve xterm
1183compatibility and apply numerous other bugfixes and extensions. 1353compatibility and apply numerous other bugfixes and extensions.
1184 1354

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines