--- rxvt-unicode/doc/rxvt.1.html 2005/02/03 10:24:10 1.6 +++ rxvt-unicode/doc/rxvt.1.html 2006/01/13 12:40:46 1.45 @@ -29,7 +29,6 @@
rxvt [options] [-e command [ args ]]
+urxvt [options] [-e command [ args ]]
rxvt-unicode, version 4.9, is a colour vt102 terminal +
rxvt-unicode, version 7.0, is a colour vt102 terminal emulator intended as an xterm(1) replacement for users who do not require features such as Tektronix 4014 emulation and toolkit-style configurability. As a result, rxvt-unicode uses much less swap space -- @@ -58,8 +57,10 @@
See rxvt(7)
(try man 7 rxvt
) for a list of frequently
-asked questions and answer to them and some common problems.
See urxvt(7)
(try man 7 urxvt
) for a list of
+frequently asked questions and answer to them and some common
+problems. That document is also accessible on the World-Wide-Web at
+http://cvs.schmorp.de/browse/*checkout*/rxvt-unicode/doc/rxvt.7.html.
rxvtd(1)
(daemon) and
-rxvtc(1)
(client).
+drastically reduces memory usage. See urxvtd(1)
(daemon) and
+urxvtc(1)
(client).
It also makes technical information about escape sequences (which have
-been extended) easier accessible: see rxvt(7)
for technical
+been extended) easier accessible: see urxvt(7)
for technical
reference documentation (escape sequences etc.).
The rxvt options (mostly a subset of xterm's) are listed +
The urxvt options (mostly a subset of xterm's) are listed below. In keeping with the smaller-is-better philosophy, options may be eliminated or default values chosen at compile-time, so options and defaults listed may not accurately reflect the version installed on -your system. `rxvt -h' gives a list of major compile-time options on +your system. `urxvt -h' gives a list of major compile-time options on the Options line. Option descriptions may be prefixed with which compile option each is dependent upon. e.g. `Compile XIM:' requires -XIM on the Options line. Note: `rxvt -help' gives a list of all +XIM on the Options line. Note: `urxvt -help' gives a list of all command-line options compiled into your version.
-Note that rxvt permits the resource name to be used as a +
Note that urxvt permits the resource name to be used as a long-option (--/++ option) so the potential command-line options are -far greater than those listed. For example: `rxvt --loginShell --color1 +far greater than those listed. For example: `urxvt --loginShell --color1 Orange'.
The following options are available:
+ urxvt -tr -tint blue -sh 40
- rxvt -fn "xft:Bitstream Vera Sans Mono:pixelsize=15" - rxvt -fn "9x15bold,xft:Bitstream Vera Sans Mono"+ urxvt -fn "xft:Bitstream Vera Sans Mono:pixelsize=15" + urxvt -fn "9x15bold,xft:Bitstream Vera Sans Mono"
See also the question ``How does rxvt-unicode choose fonts?'' in the FAQ -section of rxvt(7).
+section of urxvt(7).Please note that you must specify a program with arguments. If you want to +run shell commands, you have to specify the shell, like this:
++ urxvt -e sh -c "shell commands"+
Right now, urxvt will first unmap/map the specified window, so it +shouldn't be a top-level window. urxvt will also reconfigure it +quite a bit, so don't expect it to keep some specific state. It's best to +create an extra subwindow for urxvt and leave it alone.
+The window will not be destroyed when urxvt exits.
+It might be useful to know that urxvt will not close file
+descriptors passed to it (except for stdin/out/err, of course), so you
+can use file descriptors to communicate with the programs within the
+terminal. This works regardless of wether the -embed
option was used or
+not.
Here is a short Gtk2-perl snippet that illustrates how this option can be +used (a longer example is in doc/embed):
++ my $rxvt = new Gtk2::Socket; + $rxvt->signal_connect_after (realize => sub { + my $xid = $_[0]->window->get_xid; + system "urxvt -embed $xid &"; + });+
If this switch is given, urxvt will not create any utmp/wtmp +entries and will not tinker with pty/tty permissions - you have to do that +yourself if you want that.
+As an extremely special case, specifying -1
will completely suppress
+pty/tty operations.
Here is a example in perl that illustrates how this option can be used (a +longer example is in doc/pty-fd):
++ use IO::Pty; + use Fcntl;+
+ my $pty = new IO::Pty; + fcntl $pty, F_SETFD, 0; # clear close-on-exec + system "urxvt -pty-fd " . (fileno $pty) . "&"; + close $pty;+
+ # now communicate with rxvt + my $slave = $pty->slave; + while (<$slave>) { print $slave "got <$_>\n" }+
Note: `rxvt --help' gives a list of all resources (long +
Note: `urxvt --help' gives a list of all resources (long options) compiled into your version.
-There are two different methods that rxvt can use to get the -Xresource data: using the X libraries (Xrm*-functions) or internal -Xresources reader (~/.Xdefaults). For the first method (ie. -rxvt -h lists XGetDefaults), you can set and change the -resources using X11 tools like xset. Many distribution do also load -settings from the ~/.Xresources file when X starts.
-If compiled with internal Xresources support (i.e. rxvt -h -lists .Xdefaults) then rxvt accepts application defaults -set in XAPPLOADDIR/URxvt (compile-time defined: usually -/usr/lib/X11/app-defaults/URxvt) and resources set in -~/.Xdefaults, or ~/.Xresources if ~/.Xdefaults does not exist. -Note that when reading X resources, rxvt recognizes two -class names: XTerm and URxvt. The class name Rxvt allows -resources common to both rxvt and the original rxvt to be -easily configured, while the class name URxvt allows resources -unique to rxvt, notably colours and key-handling, to be -shared between different rxvt configurations. If no -resources are specified, suitable defaults will be used. Command-line -arguments can be used to override resource settings. The following -resources are allowed:
+You can set and change the resources using X11 tools like xrdb. Many +distribution do also load settings from the ~/.Xresources file when X +starts. urxvt will consult the following files/resources in order, +with later settings overwriting earlier ones:
++ 1. system-wide app-defaults file, either locale-dependent OR global + 2. app-defaults file in $XAPPLRESDIR + 3. RESOURCE_MANAGER property on root-window OR $HOME/.Xdefaults + 4. SCREEN_RESOURCES for the current screen + 5. $XENVIRONMENT file OR $HOME/.Xdefaults-<nodename>+
Note that when reading X resources, urxvt recognizes two class
+names: Rxvt and URxvt. The class name Rxvt allows resources
+common to both urxvt and the original rxvt to be easily
+configured, while the class name URxvt allows resources unique to
+urxvt, to be shared between different urxvt
+configurations. If no resources are specified, suitable defaults will
+be used. Command-line arguments can be used to override resource
+settings. The following resources are supported (you might want to
+check the urxvtperl(3)
manpage for additional settings by perl
+extensions not documented here):
Colours higher than 15 cannot be set using resources (yet), but can be -changed using an escape command (see rxvt(7)).
+changed using an escape command (see urxvt(7)).Colours 16-79 form a standard 4x4x4 colour cube (the same as xterm with @@ -659,13 +789,21 @@
Each font can either be a standard X11 core font (XLFD) name, with @@ -803,6 +941,16 @@ text font will being used for the given style.
The string will be interpreted as if typed into the shell as-is.
+Example:
++ URxvt*print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX)+
This creates a new file in your home directory with the screen contents
+everytime you hit Print
.
987654321
) to effectively disable the timeout.
LC_CTYPE
of e.g.
de_DE.UTF-8
for normal text processing but ja_JP.EUC-JP
for the
input extension to be able to input japanese characters while staying in
-another locale. option -imlocale.
+another locale; option -imlocale.
OverTheSpot
or
OffTheSpot
. It must be a standard X font set (XLFD patterns separated
by commas), i.e. it's not in the same format as the other font lists used
-in rxvt. The default will be set-up to chose *any* suitable found
+in urxvt. The default will be set-up to chose *any* suitable found
found, preferably one or two pixels differing in size to the base font.
option -imfont.
@@ -1085,7 +1257,7 @@
write(1)
or any other means. Therefore, these sequences are disabled by
+default. (Note that many other terminals, including xterm, have these
+sequences enabled by default, which doesn't make it safer, though).
+
+You can enable them by setting this boolean resource or specifying +-insecure as an option. At the moment, this enables display-answer, +locale, findfont, icon label and window title requests as well as dynamic +menubar dispatch.
Please note that you need to double the \
in resource files, as
+Xlib itself does it's own de-escaping (you can use \033
instead of
+\e
(and so on), which will work with both Xt and urxvt's own
+processing).
You can define a range of keysyms in one shot by providing a string with pattern list/PREFIX/MIDDLE/SUFFIX, where the delimeter `/' should be a character not used by the strings.
@@ -1177,49 +1367,176 @@- URxvt.keysym.M-C-0x61: list|\e<M-C-|abc|>+ URxvt.keysym.M-C-0x61: list|\033<M-C-|abc|>
The above line is equivalent to the following three lines:
- URxvt.keysym.Meta-Control-0x61: \e<M-C-a> - URxvt.keysym.Meta-Control-0x62: \e<M-C-b> - URxvt.keysym.Meta-Control-0x63: \e<M-C-c>+ URxvt.keysym.Meta-Control-0x61: \033<M-C-a> + URxvt.keysym.Meta-Control-0x62: \033<M-C-b> + URxvt.keysym.Meta-Control-0x63: \033<M-C-c>
If string takes the form of proto:STRING
, the specified STRING
-is interpreted and executed as rxvt's control sequence. For
+
If string takes the form of command:STRING
, the specified STRING
+is interpreted and executed as urxvt's control sequence. For
example the following means ``change the current locale to zh_CN.GBK
when Control-Meta-c is being pressed'':
- URxvt.keysym.M-C-c: proto:\033]701;zh_CN.GBK\007+ URxvt.keysym.M-C-c: command:\033]701;zh_CN.GBK\007 +
If string takes the form perl:STRING
, then the specified STRING
+is passed to the on_keyboard_command
perl handler. See the urxvtperl(3)
+manpage. For example, the selection extension (activated via
+urxvt -pe selection
) listens for selection:rot13
events:
+ URxvt.keysym.M-C-c: perl:selection:rot13+
Due the the large number of modifier combinations, a defined key mapping
+will match if at at least the specified identifiers are being set, and
+no other key mappings with those and more bits are being defined. That
+means that defining a key map for a
will automatically provide
+definitions for Meta-a
, Shift-a
and so on, unless some of those are defined
+mappings themselves.
Unfortunately, this will override built-in key mappings. For example
+if you overwrite the Insert
key you will disable urxvt's
+Shift-Insert
mapping. To re-enable that, you can poke ``holes'' into the
+user-defined keymap using the builtin:
replacement:
+ URxvt.keysym.Insert: <my insert key sequence> + URxvt.keysym.S-Insert: builtin:+
The first line defines a mapping for Insert
and any combination
+of modifiers. The second line re-establishes the default mapping for
+Shift-Insert
.
The following example will map Control-Meta-1 and Control-Meta-2 to
-the fonts suxuseuro
and 9x15bold
, so you cna have some limited
+the fonts suxuseuro
and 9x15bold
, so you can have some limited
font-switching at runtime:
- URxvt.keysym.M-C-1: proto:\033]50;suxuseuro\007 - URxvt.keysym.M-C-2: proto:\033]50;9x15bold\007+ URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007 + URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
proto:\033]701;zh_CN.GBK\007
means: change the current locale to
-zh_CN.GBK
.
Other things are possible, e.g. resizing (see urxvt(7)
for more
+info):
+ URxvt.keysym.M-C-3: command:\033[8;25;80t + URxvt.keysym.M-C-4: command:\033[8;48;110t+
list(s)
of perl extension scripts (default: default
) to
+use in this terminal instance; option -pe.
+Extension names can be prefixed with a -
sign to prohibit using
+them. This can be useful to selectively disable some extensions loaded
+by default, or specified via the perl-ext-common
resource. For
+example, default,-selection
will use all the default extension except
+selection
.
Extension names can also be followed by an argument in angle brackets
+(e.g. searchable-scrollback<M-s>
, which binds the hotkey for
+searchable scorllback to Alt/Meta-s). Mentioning the same extension
+multiple times with different arguments will pass multiple arguments to
+the extension.
Each extension is looked up in the library directories, loaded if +necessary, and bound to the current terminal instance.
+If both of these resources are the empty string, then the perl +interpreter will not be initialized. The idea behind two options is that +perl-ext-common will be used for extensions that should be available to +all instances, while perl-ext is used for specific instances.
+urxvtperl(3)
manpage. Due to security reasons, this resource
+will be ignored when running setuid/setgid.
+perl
resource,
+urxvt will first look in these directories and then in
+/usr/local/lib/urxvt/perl/. Due to security reasons, this resource
+will be ignored when running setuid/setgid.
+See the urxvtperl(3)
manpage.
urxvtperl(3)
manpage for
+details.
+urxvtperl(3)
manpage
+for details.
+M-s
).
+selection-popup
and mark-urls
perl extensions.
+
Lines of text that scroll off the top of the rxvt window +
Lines of text that scroll off the top of the urxvt window (resource: saveLines) and can be scrolled back using the scrollbar -or by keystrokes. The normal rxvt scrollbar has arrows and +or by keystrokes. The normal urxvt scrollbar has arrows and its behaviour is fairly intuitive. The xterm-scrollbar is without arrows and its behaviour mimics that of xterm
Scroll down with Button1 (xterm-scrollbar) or Shift-Next. @@ -1234,9 +1551,9 @@ (Alt) key while performing the desired mouse action.
If mouse reporting mode is active, the normal scrollbar actions are disabled -- on the assumption that we are using a fullscreen -application. Instead, pressing Button1 and Button3 sends ESC[6~ -(Next) and ESC[5~ (Prior), respectively. Similarly, clicking on the -up and down arrows sends ESC[A (Up) and ESC[B (Down), +application. Instead, pressing Button1 and Button3 sends ESC [ 6 ~ +(Next) and ESC [ 5 ~ (Prior), respectively. Similarly, clicking on the +up and down arrows sends ESC [ A (Up) and ESC [ B (Down), respectively.
@@ -1256,15 +1573,17 @@
Starting a selection while pressing the Meta key (or Meta+Ctrl keys) -(Compile: frills) will create a rectangular selection instead of a normal -one.
+(Compile: frills) will create a rectangular selection instead of a +normal one. In this mode, every selected row becomes its own line in the +selection, and trailing whitespace is visually underlined and removed from +the selection.You can, however, switch fonts at runtime using escape sequences (and therefore using the menubar), e.g.:
- printf '\e]701;%s\007' "9x15bold,xft:Kochi Gothic"+ printf '\e]710;%s\007' "9x15bold,xft:Kochi Gothic"
rxvt-unicode will automatically re-apply these fonts to the output so far.
@@ -1340,16 +1659,16 @@
rxvt tries to write an entry into the utmp(5) file so that +
urxvt tries to write an entry into the utmp(5) file so that it can be seen via the who(1) command, and can accept messages. To -allow this feature, rxvt may need to be installed setuid root +allow this feature, urxvt may need to be installed setuid root on some systems or setgid to root or to some other group on others.
In addition to the default foreground and background colours, -rxvt can display up to 16 colours (8 ANSI colours plus +urxvt can display up to 16 colours (8 ANSI colours plus high-intensity bold/blink versions of the same). Here is a list of the colours with their rgb.txt names.