From: ayin Date: Wed, 12 Dec 2007 23:58:02 +0000 (+0000) Subject: *** empty log message *** X-Git-Url: http://git.openbox.org/?a=commitdiff_plain;h=24097684024b9fd19bc17498165743b1475ad6fd;p=dana%2Furxvt.git *** empty log message *** --- diff --git a/doc/Makefile.in b/doc/Makefile.in index e3cfcb6e..e67c13bc 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -73,8 +73,6 @@ rxvtperl.3.pod: ../src/urxvt.pm tags allbin: alldoc: rxvt.1.man.in rxvt.7.man.in rxvtc.1.man.in rxvtd.1.man.in rxvtperl.3.man.in \ - rxvt.1.txt rxvt.7.txt rxvtc.1.txt rxvtd.1.txt rxvtperl.3.txt \ - rxvt.1.html rxvt.7.html rxvtc.1.html rxvtd.1.html rxvtperl.3.html \ ../README.configure ../README.FAQ infocmp -C rxvt-unicode >$(srcdir)/etc/rxvt-unicode.termcap @@ -87,8 +85,6 @@ distclean: clean realclean: distclean rm -f rxvt.1.man.in rxvt.7.man.in rxvtc.1.man.in rxvtd.1.man.in rxvtperl.3.man.in - rm -f rxvt.1.txt rxvt.7.txt rxvtc.1.txt rxvtd.1.txt rxvtperl.3.txt - rm -f rxvt.1.html rxvt.7.html rxvtc.1.html rxvtd.1.html rxvtperl.3.html rm -f ../README.configure ../README.FAQ rm -f $(srcdir)/etc/rxvt-unicode.termcap diff --git a/doc/rxvt.1.html b/doc/rxvt.1.html deleted file mode 100644 index 5f65dd5c..00000000 --- a/doc/rxvt.1.html +++ /dev/null @@ -1,1579 +0,0 @@ - - - - - rxvt-unicode (ouR XVT, unicode) - - - - - - - -
- -

Index

- -
- - -

NAME

Top

-
-

rxvt-unicode (ouR XVT, unicode) - (a VT102 emulator for the X window system)

- -
-

SYNOPSIS

Top

-
-

rxvt [options] [-e command [ args ]]

- -
-

DESCRIPTION

Top

-
-

rxvt-unicode, version 8.6, 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 -- -a significant advantage on a machine serving many X sessions.

- -
-

FREQUENTLY ASKED QUESTIONS

Top

-
-

See rxvt(7) (try man 7 rxvt) 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/rxvt-unicode/doc/rxvt.7.html.

- -
-

RXVT-UNICODE VS. RXVT

Top

-
-

Unlike the original rxvt, rxvt-unicode stores all text in Unicode -internally. That means it can store and display most scripts in the -world. Being a terminal emulator, however, some things are very difficult, -especially cursive scripts such as arabic, vertically written scripts -like mongolian or scripts requiring extremely complex combining rules, -like tibetan or devanagari. Don't expect pretty output when using these -scripts. Most other scripts, latin, cyrillic, kanji, thai etc. should work -fine, though. A somewhat difficult case are right-to-left scripts, such -as hebrew: rxvt-unicode adopts the view that bidirectional algorithms -belong into the application, not the terminal emulator (too many things -- -such as cursor-movement while editing -- break otherwise), but that might -change.

-

If you are looking for a terminal that supports more exotic scripts, let -me recommend mlterm, which is a very user friendly, lean and clean -terminal emulator. In fact, the reason rxvt-unicode was born was solely -because the author couldn't get mlterm to use one font for latin1 and -another for japanese.

-

Therefore another design rationale was the use of multiple fonts to -display characters: The idea of a single unicode font which many other -programs force onto its users never made sense to me: You should be able -to choose any font for any script freely.

-

Apart from that, rxvt-unicode is also much better internationalised than -its predecessor, supports things such as XFT and ISO 14755 that are handy -in i18n-environments, is faster, and has a lot bugs less than the original -rxvt. This all in addition to dozens of other small improvements.

-

It is still faithfully following the original rxvt idea of being lean -and nice on resources: for example, you can still configure rxvt-unicode -without most of its features to get a lean binary. It also comes with -a client/daemon pair that lets you open any number of terminal windows -from within a single process, which makes startup time very fast and -drastically reduces memory usage. See rxvtd(1) (daemon) and -rxvtc(1) (client).

-

It also makes technical information about escape sequences (which have -been extended) more accessible: see rxvt(7) for technical -reference documentation (escape sequences etc.).

- -
-

OPTIONS

Top

-
-

The rxvt 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 -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 -command-line options compiled into your version.

-

Note that rxvt 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 -Orange'.

-

The following options are available:

-
-
-help, --help
-
-

Print out a message describing available options.

-
-
-display displayname
-
-

Attempt to open a window on the named X display (-d still -respected). In the absence of this option, the display specified by the -DISPLAY environment variable is used.

-
-
-depth bitdepth
-
-

Compile xft: Attempt to find a visual with the given bit depth; -resource depth.

-
-
-geometry geom
-
-

Window geometry (-g still respected); resource geometry.

-
-
-rv|+rv
-
-

Turn on/off simulated reverse video; resource reverseVideo.

-
-
-j|+j
-
-

Turn on/off jump scrolling (allow multiple lines per refresh); resource jumpScroll.

-
-
-ss|+ss
-
-

Turn on/off skip scrolling (allow multiple screens per refresh); resource skipScroll.

-
-
-tr|+tr
-
-

Turn on/off illusion of a transparent window background. Obsolete form of it is --ip and it should not be used anymore; resource transparent.

-

Please note that old resource name of inheritPixmap is obsolete and should be -changed to transparent. Backwards compatibility support for inheritPixmap will -be phased out in future versions of rxvt!

-

Please address all transparency related issues to Sasha Vasko at -sasha@aftercode.net. Read the FAQ (man 7 rxvt)!

-
-
-fade number
-
-

Fade the text by the given percentage when focus is lost. Small values -fade a little only, 100 completely replaces all colours by the fade -colour; resource fading.

-
-
-fadecolor colour
-
-

Fade to this colour when fading is used (see -fade). The default colour -is opaque black. resource fadeColor.

-
-
-tint colour
-
-

Tint the transparent background pixmap with the given colour when -transparency is enabled with -tr. This only works for -non-tiled backgrounds, currently. See also the -sh option that can be -used to brighten or darken the image in addition to tinting it. -Please note that certain tint colours can be applied on the server-side, -thus yielding performance gain of two orders of magnitude. These colours are: -blue, red, green, cyan, magenta, yellow, and those close to them. Also -pure black and pure white colors essentially mean no tinting; resource -tintColor. Example:

-
   rxvt -tr -tint blue -sh 40
-
-
-
-
-sh number
-
-

Darken (0 .. 100) or lighten (100 .. 200) the transparent -background image in addition to (or instead of) tinting it; -resource shading.

-
-
-blt string
-
-

Specify background blending type. If background pixmap is specified -at the same time as transparency - such pixmap will be blended over -transparency image, using method specified. Supported values are : -add, alphablend, allanon - color values averaging, colorize, -darken, diff, dissipate, hue, lighten, overlay, -saturate, screen, sub, tint, value. The default is -alpha-blending. Compile afterimage; resource blendType.

-
-
-blr HxV
-
-

Apply Gaussian Blur with the specified radii to the transparent -background image. If single number is specified - both vertical and -horizontal radii are considered to be the same. Setting one of the -radii to 1 and another to a large number creates interesting effects -on some backgrounds. Maximum radius value is 128. Compile afterimage; -resource blurRadius.

-
-
-bg colour
-
-

Window background colour; resource background.

-
-
-fg colour
-
-

Window foreground colour; resource foreground.

-
-
-pixmap file[;geom[:op1][:op2][...]]
-
-

Compile afterimage: Specify image file for the background and also -optionally specify its scaling with a geometry string. Note you may need to -add quotes to avoid special shell interpretation of the ; in the -command-line; for more details see resource backgroundPixmap.

-
-
-cr colour
-
-

The cursor colour; resource cursorColor.

-
-
-pr colour
-
-

The mouse pointer foreground colour; resource pointerColor.

-
-
-pr2 colour
-
-

The mouse pointer background colour; resource pointerColor2.

-
-
-bd colour
-
-

The colour of the border around the text area and between the scrollbar and the text; -resource borderColor.

-
-
-fn fontlist
-
-

Select the fonts to be used. This is a comma separated list of font names -that are checked in order when trying to find glyphs for characters. The -first font defines the cell size for characters; other fonts might be -smaller, but not (in general) larger. A (hopefully) reasonable default -font list is always appended to it. See resource font for more details.

-

In short, to specify an X11 core font, just specify its name or prefix it -with x:. To specify an XFT-font, you need to prefix it with xft:, -e.g.:

-
   rxvt -fn "xft:Bitstream Vera Sans Mono:pixelsize=15"
-   rxvt -fn "9x15bold,xft:Bitstream Vera Sans Mono"
-
-
-

See also the question "How does rxvt-unicode choose fonts?" in the FAQ -section of rxvt(7).

-
-
-fb fontlist
-
-

Compile font-styles: The bold font list to use when bold characters -are to be printed. See resource boldFont for details.

-
-
-fi fontlist
-
-

Compile font-styles: The italic font list to use when italic -characters are to be printed. See resource italicFont for details.

-
-
-fbi fontlist
-
-

Compile font-styles: The bold italic font list to use when bold -italic characters are to be printed. See resource boldItalicFont -for details.

-
-
-is|+is
-
-

Compile font-styles: Bold/Italic font styles imply high intensity -foreground/background (default). See resource intensityStyles for -details.

-
-
-name name
-
-

Specify the application name under which resources are to be obtained, -rather than the default executable file name. Name should not contain -`.' or `*' characters. Also sets the icon and title name.

-
-
-ls|+ls
-
-

Start as a login-shell/sub-shell; resource loginShell.

-
-
-ut|+ut
-
-

Compile utmp: Inhibit/enable writing a utmp entry; resource -utmpInhibit.

-
-
-vb|+vb
-
-

Turn on/off visual bell on receipt of a bell character; resource -visualBell.

-
-
-sb|+sb
-
-

Turn on/off scrollbar; resource scrollBar.

-
-
-si|+si
-
-

Turn on/off scroll-to-bottom on TTY output inhibit; resource -scrollTtyOutput has opposite effect.

-
-
-sk|+sk
-
-

Turn on/off scroll-to-bottom on keypress; resource -scrollTtyKeypress.

-
-
-sw|+sw
-
-

Turn on/off scrolling with the scrollback buffer as new lines appear. -This only takes effect if -si is also given; resource -scrollWithBuffer.

-
-
-sr|+sr
-
-

Put scrollbar on right/left; resource scrollBar_right.

-
-
-st|+st
-
-

Display rxvt (non XTerm/NeXT) scrollbar without/with a trough; -resource scrollBar_floating.

-
-
-ptab|+ptab
-
-

If enabled (default), "Horizontal Tab" characters are being stored as -actual wide characters in the screen buffer, which makes it possible to -select and paste them. Since a horizontal tab is a cursor movement and -not an actual glyph, this can sometimes be visually annoying as the cursor -on a tab character is displayed as a wide cursor; resource pastableTabs.

-
-
-bc|+bc
-
-

Blink the cursor; resource cursorBlink.

-
-
-iconic
-
-

Start iconified, if the window manager supports that option. -Alternative form is -ic.

-
-
-sl number
-
-

Save number lines in the scrollback buffer. See resource entry for -limits; resource saveLines.

-
-
-b number
-
-

Compile frills: Internal border of number pixels. See resource -entry for limits; resource internalBorder.

-
-
-w number
-
-

Compile frills: External border of number pixels. Also, -bw -and -borderwidth. See resource entry for limits; resource -externalBorder.

-
-
-bl
-
-

Compile frills: Set MWM hints to request a borderless window, i.e. -if honoured by the WM, the rxvt-unicode window will not have window -decorations; resource borderLess.

-
-
-override-redirect
-
-

Compile frills: Sets override-redirect on the window; resource -override-redirect.

-
-
-sbg
-
-

Compile frills: Disable the usage of the built-in block graphics/line -drawing characters and just rely on what the specified fonts provide. Use -this if you have a good font and want to use its block graphic glyphs; -resource skipBuiltinGlyphs.

-
-
-lsp number
-
-

Compile frills: Lines (pixel height) to insert between each row of -the display. Useful to work around font rendering problems; resource -lineSpace.

-
-
-tn termname
-
-

This option specifies the name of the terminal type to be set in the -TERM environment variable. This terminal type must exist in the -termcap(5) database and should have li# and co# entries; -resource termName.

-
-
-e command [arguments]
-
-

Run the command with its command-line arguments in the rxvt -window; also sets the window title and icon name to be the basename of -the program being executed if neither -title (-T) nor -n are -given on the command line. If this option is used, it must be the last -on the command-line. If there is no -e option then the default is to -run the program specified by the SHELL environment variable or, -failing that, sh(1).

-

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:

-
  rxvt -e sh -c "shell commands"
-
-
-
-
-title text
-
-

Window title (-T still respected); the default title is the basename -of the program specified after the -e option, if any, otherwise the -application name; resource title.

-
-
-n text
-
-

Icon name; the default name is the basename of the program specified -after the -e option, if any, otherwise the application name; -resource iconName.

-
-
-C
-
-

Capture system console messages.

-
-
-pt style
-
-

Compile XIM: input style for input method; OverTheSpot, -OffTheSpot, Root; resource preeditType.

-
-
-im text
-
-

Compile XIM: input method name. resource inputMethod.

-
-
-imlocale string
-
-

The locale to use for opening the IM. You can use an 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. resource imLocale.

-
-
-imfont fontset
-
-

Set the font set to use for the X Input Method, see resource imFont -for more info.

-
-
-tcw
-
-

Change the meaning of triple-click selection with the left mouse -button. Only effective when the original (non-perl) selection code is -in-use. Instead of selecting a full line it will extend the selection the -end of the logical line only. resource tripleclickwords.

-
-
-insecure
-
-

Enable "insecure" mode, which currently enables most of the escape -sequences that echo strings. See the resource insecure for more -info.

-
-
-mod modifier
-
-

Override detection of Meta modifier with specified key: alt, -meta, hyper, super, mod1, mod2, mod3, mod4, -mod5; resource modifier.

-
-
-ssc|+ssc
-
-

Turn on/off secondary screen (default enabled); resource -secondaryScreen.

-
-
-ssr|+ssr
-
-

Turn on/off secondary screen scroll (default enabled); resource -secondaryScroll.

-
-
-hold|+hold
-
-

Turn on/off hold window after exit support. If enabled, rxvt -will not immediately destroy its window when the program executed within -it exits. Instead, it will wait till it is being killed or closed by the -user; resource hold.

-
-
-xrm string
-
-

Works like the X Toolkit option of the same name, by adding the string -as if it were specified in a resource file. Resource values specified this -way take precedence over all other resource specifications.

-

Note that you need to use the same syntax as in the .Xdefaults file, -e.g. *.background: black. Also note that all rxvt-specific -options can be specified as long-options on the commandline, so use -of -xrm is mostly limited to cases where you want to specify other -resources (e.g. for input methods) or for compatibility with other -programs.

-
-
-keysym.sym string
-
-

Remap a key symbol. See resource keysym.

-
-
-embed windowid
-
-

Tells rxvt to embed its windows into an already-existing window, -which enables applications to easily embed a terminal.

-

Right now, rxvt will first unmap/map the specified window, so it -shouldn't be a top-level window. rxvt 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 rxvt and leave it alone.

-

The window will not be destroyed when rxvt exits.

-

It might be useful to know that rxvt 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 whether 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 "rxvt -embed $xid &";
-   });
-
-
-
-
-pty-fd file descriptor
-
-

Tells rxvt NOT to execute any commands or create a new pty/tty -pair but instead use the given file descriptor as the tty master. This is -useful if you want to drive rxvt as a generic terminal emulator -without having to run a program within it.

-

If this switch is given, rxvt 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 "rxvt -pty-fd " . (fileno $pty) . "&";
-   close $pty;
-
-   # now communicate with rxvt
-   my $slave = $pty->slave;
-   while (<$slave>) { print $slave "got <$_>\n" }
-
-
-
-
-pe string
-
-

Comma-separated list of perl extension scripts to use (or not to use) in -this terminal instance. See resource perl-ext for details.

-
-
- -
-

RESOURCES (available also as long-options)

Top

-
-

Note: `rxvt --help' gives a list of all resources (long -options) compiled into your version.

-

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. rxvt 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>
-  6. resources specified via -xrm on the commandline
-
-
-

Note that when reading X resources, rxvt recognizes two class -names: Rxvt 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, 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 supported (you might want to -check the rxvtperl(3) manpage for additional settings by perl -extensions not documented here):

-
-
depth: bitdepth
-
-

Compile xft: Attempt to find a visual with the given bit depth; -option -depth.

-
-
geometry: geom
-
-

Create the window with the specified X window geometry [default 80x24]; -option -geometry.

-
-
background: colour
-
-

Use the specified colour as the window's background colour [default -White]; option -bg.

-
-
foreground: colour
-
-

Use the specified colour as the window's foreground colour [default -Black]; option -fg.

-
-
colorn: colour
-
-

Use the specified colour for the colour value n, where 0-7 -corresponds to low-intensity (normal) colours and 8-15 corresponds to -high-intensity (bold = bright foreground, blink = bright background) -colours. The canonical names are as follows: 0=black, 1=red, 2=green, -3=yellow, 4=blue, 5=magenta, 6=cyan, 7=white, but the actual colour -names used are listed in the COLORS AND GRAPHICS section.

-

Colours higher than 15 cannot be set using resources (yet), but can be -changed using an escape command (see rxvt(7)).

-

Colours 16-79 form a standard 4x4x4 colour cube (the same as xterm with -88 colour support). Colours 80-87 are evenly spaces grey steps.

-
-
colorBD: colour
-
colorIT: colour
-
-

Use the specified colour to display bold or italic characters when the -foreground colour is the default. If font styles are not available -(Compile styles) and this option is unset, reverse video is used instead.

-
-
colorUL: colour
-
-

Use the specified colour to display underlined characters when the -foreground colour is the default.

-
-
colorRV: colour
-
-

Use the specified colour as the background for reverse video characters -when OPTION_HC is disabled (--disable-frills).

-
-
underlineColor: colour
-
-

If set, use the specified colour as the colour for the underline -itself. If unset, use the foreground colour.

-
-
cursorColor: colour
-
-

Use the specified colour for the cursor. The default is to use the -foreground colour; option -cr.

-
-
cursorColor2: colour
-
-

Use the specified colour for the colour of the cursor text. For this to -take effect, cursorColor must also be specified. The default is to -use the background colour.

-
-
reverseVideo: boolean
-
-

True: simulate reverse video by foreground and background colours; -option -rv. False: regular screen colours [default]; option -+rv. See note in COLORS AND GRAPHICS section.

-
-
jumpScroll: boolean
-
-

True: specify that jump scrolling should be used. When receiving lots -of lines, rxvt will only scroll once a whole screen height of lines -has been read, resulting in fewer updates while still displaying every -received line; option -j.

-

False: specify that smooth scrolling should be used. rxvt will -force a screen refresh on each new line it received; option +j.

-
-
skipScroll: boolean
-
-

True: (the default) specify that skip scrolling should be used. When -receiving lots of lines, rxvt will only scroll once in a while -(around 60 times per second), resulting in far fewer updates. This can -result in rxvt not ever displaying some of the lines it receives; -option -ss.

-

False: specify that everything is to be displayed, even -if the refresh is too fast for the human eye to read anything (or the -monitor to display anything); option +ss.

-
-
inheritPixmap: boolean
-
-

True: make the background inherit the parent windows' pixmap, giving -artificial transparency. False: do not inherit the parent windows' -pixmap.

-

Please note that transparency of any kind if completely unsupported by -the author. Don't bug him with installation questions!

-
-
fading: number
-
-

Fade the text by the given percentage when focus is lost; option -fade.

-
-
fadeColor: colour
-
-

Fade to this colour, when fading is used (see fading:). The default -colour is black; option -fadecolor.

-
-
tintColor: colour
-
-

Tint the transparent background pixmap with the given colour; option --tint.

-
-
shading: number
-
-

Darken (0 .. 100) or lighten (-1 .. -100) the transparent background image -in addition to tinting it; option -sh.

-
-
blendType: string
-
-

Specify background blending type; option -blt.

-
-
blurRadius: number
-
-

Apply Gaussian Blurr with the specified radius to the transparent -background image; option -blr.

-
-
scrollColor: colour
-
-

Use the specified colour for the scrollbar [default #B2B2B2].

-
-
troughColor: colour
-
-

Use the specified colour for the scrollbar's trough area [default -#969696]. Only relevant for rxvt (non XTerm/NeXT) scrollbar.

-
-
borderColor: colour
-
-

The colour of the border around the text area and between the scrollbar -and the text.

-
-
backgroundPixmap: file[;geom[:op1][:op2][...]]
-
-

Use the specified image file for the background and also -optionally specify its scaling with a geometry string WxH+X+Y, -(default 0x0+50+50) in which "W" / "H" specify the -horizontal/vertical scale (percent), and "X" / "Y" locate the image -centre (percent). A scale of 0 displays the image with tiling. A scale -of 1 displays the image without any scaling. A scale of 2 to 9 specifies -an integer number of images in that direction. No image will be magnified -beyond 10 times its original size. The maximum permitted scale is 1000. -Additional operations can be specified after colon :op1:op2.... -Supported operations are:

-
  tile        force background image to be tiled and not scaled. Equivalent to 0x0,
-  propscale   will scale image keeping proportions, 
-  auto        will scale image to match window size. Equivalent to 100x100;
-  hscale      will scale image horizontally to the window size; 
-  vscale      will scale image vertically to the window size;
-  scale       will scale image to match window size;
-  root        will tile image as if it was a root window background, auto-adjusting
-              whenever terminal window moves. 
-
-
-

If used in conjunction with -tr option, the specified pixmap will be -blended over transparency image using either alpha-blending, or any -other blending type, specified with -blt "type" option.

-
-
path: path
-
-

Specify the colon-delimited search path for finding background image files.

-
-
font: fontlist
-
-

Select the fonts to be used. This is a comma separated list of font names -that are checked in order when trying to find glyphs for characters. The -first font defines the cell size for characters; other fonts might be -smaller, but not (in general) larger. A (hopefully) reasonable default -font list is always appended to it; option -fn.

-

Each font can either be a standard X11 core font (XLFD) name, with -optional prefix x: or a Xft font (Compile xft), prefixed with xft:.

-

In addition, each font can be prefixed with additional hints and -specifications enclosed in square brackets ([]). The only available -hint currently is codeset=codeset-name, and this is only used for Xft -fonts.

-

For example, this font resource

-
   URxvt.font: 9x15bold,\
-               -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso10646-1,\
-               -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1, \
-               [codeset=JISX0208]xft:Kochi Gothic:antialias=false, \
-               xft:Code2000:antialias=false
-
-
-

specifies five fonts to be used. The first one is 9x15bold (actually -the iso8859-1 version of the second font), which is the base font (because -it is named first) and thus defines the character cell grid to be 9 pixels -wide and 15 pixels high.

-

The second font is just used to add additional unicode characters not in -the base font, likewise the third, which is unfortunately non-bold, but -the bold version of the font does contain less characters, so this is a -useful supplement.

-

The third font is an Xft font with aliasing turned off, and the characters -are limited to the JIS 0208 codeset (i.e. japanese kanji). The font -contains other characters, but we are not interested in them.

-

The last font is a useful catch-all font that supplies most of the -remaining unicode characters.

-
-
boldFont: fontlist
-
italicFont: fontlist
-
boldItalicFont: fontlist
-
-

The font list to use for displaying bold, italic or bold -italic characters, respectively.

-

If specified and non-empty, then the syntax is the same as for the -font-resource, and the given font list will be used as is, which makes -it possible to substitute completely different font styles for bold and -italic.

-

If unset (the default), a suitable font list will be synthesized by -"morphing" the normal text font list into the desired shape. If that is -not possible, replacement fonts of the desired shape will be tried.

-

If set, but empty, then this specific style is disabled and the normal -text font will being used for the given style.

-
-
intensityStyles: boolean
-
-

When font styles are not enabled, or this option is enabled (True, -option -is, the default), bold and italic font styles imply high -intensity foreground/background colours. Disabling this option (False, -option +is) disables this behaviour, the high intensity colours are not -reachable.

-
-
selectstyle: mode
-
-

Set mouse selection style to old which is 2.20, oldword which -is xterm style with 2.20 old word selection, or anything else which -gives xterm style selection. Only effective when the original (non-perl) -selection code is in use.

-
-
scrollstyle: mode
-
-

Set scrollbar style to rxvt, plain, next or xterm. plain is -the author's favourite.

-
-
title: string
-
-

Set window title string, the default title is the command-line -specified after the -e option, if any, otherwise the application -name; option -title.

-
-
iconName: string
-
-

Set the name used to label the window's icon or displayed in an icon -manager window, it also sets the window's title unless it is explicitly -set; option -n.

-
-
mapAlert: boolean
-
-

True: de-iconify (map) on receipt of a bell character. False: no -de-iconify (map) on receipt of a bell character [default].

-
-
urgentOnBell: boolean
-
-

True: set the urgency hint for the wm on receipt of a bell character. -False: do not set the urgency hint [default].

-
-
visualBell: boolean
-
-

True: use visual bell on receipt of a bell character; option -vb. -False: no visual bell [default]; option +vb.

-
-
loginShell: boolean
-
-

True: start as a login shell by prepending a `-' to argv[0] of -the shell; option -ls. False: start as a normal sub-shell -[default]; option +ls.

-
-
utmpInhibit: boolean
-
-

True: inhibit writing record into the system log file utmp; -option -ut. False: write record into the system log file utmp -[default]; option +ut.

-
-
print-pipe: string
-
-

Specify a command pipe for vt100 printer [default lpr(1)]. Use -Print to initiate a screen dump to the printer and Ctrl-Print or -Shift-Print to include the scrollback as well.

-

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 -every time you hit Print.

-
-
scrollBar: boolean
-
-

True: enable the scrollbar [default]; option -sb. False: -disable the scrollbar; option +sb.

-
-
scrollBar_right: boolean
-
-

True: place the scrollbar on the right of the window; option -sr. -False: place the scrollbar on the left of the window; option +sr.

-
-
scrollBar_floating: boolean
-
-

True: display an rxvt scrollbar without a trough; option -st. -False: display an rxvt scrollbar with a trough; option +st.

-
-
scrollBar_align: mode
-
-

Align the top, bottom or centre [default] of the scrollbar -thumb with the pointer on middle button press/drag.

-
-
scrollTtyOutput: boolean
-
-

True: scroll to bottom when tty receives output; option -si. -False: do not scroll to bottom when tty receives output; option -+si.

-
-
scrollWithBuffer: boolean
-
-

True: scroll with scrollback buffer when tty receives new lines (and -scrollTtyOutput is False); option -sw. False: do not scroll -with scrollback buffer when tty receives new lines; option +sw.

-
-
scrollTtyKeypress: boolean
-
-

True: scroll to bottom when a non-special key is pressed. Special keys -are those which are intercepted by rxvt-unicode for special handling and -are not passed onto the shell; option -sk. False: do not scroll to -bottom when a non-special key is pressed; option +sk.

-
-
saveLines: number
-
-

Save number lines in the scrollback buffer [default 64]. This -resource is limited on most machines to 65535; option -sl.

-
-
internalBorder: number
-
-

Internal border of number pixels. This resource is limited to 100; -option -b.

-
-
externalBorder: number
-
-

External border of number pixels. This resource is limited to 100; -option -w, -bw, -borderwidth.

-
-
borderLess: boolean
-
-

Set MWM hints to request a borderless window, i.e. if honoured by the -WM, the rxvt-unicode window will not have window decorations; option -bl.

-
-
skipBuiltinGlyphs: boolean
-
-

Compile frills: Disable the usage of the built-in block graphics/line -drawing characters and just rely on what the specified fonts provide. Use -this if you have a good font and want to use its block graphic glyphs; -option -sbg.

-
-
termName: termname
-
-

Specifies the terminal type name to be set in the TERM environment -variable; option -tn.

-
-
lineSpace: number
-
-

Specifies number of lines (pixel height) to insert between each row of -the display [default 0]; option -lsp.

-
-
meta8: boolean
-
-

True: handle Meta (Alt) + keypress to set the 8th bit. False: -handle Meta (Alt) + keypress as an escape prefix [default].

-
-
mouseWheelScrollPage: boolean
-
-

True: the mouse wheel scrolls a page full. False: the mouse wheel -scrolls five lines [default].

-
-
pastableTabs: boolean
-
-

True: store tabs as wide characters. False: interpret tabs as cursor -movement only; option -ptab.

-
-
cursorBlink: boolean
-
-

True: blink the cursor. False: do not blink the cursor [default]; -option -bc.

-
-
pointerBlank: boolean
-
-

True: blank the pointer when a key is pressed or after a set number -of seconds of inactivity. False: the pointer is always visible -[default].

-
-
pointerColor: colour
-
-

Mouse pointer foreground colour.

-
-
pointerColor2: colour
-
-

Mouse pointer background colour.

-
-
pointerBlankDelay: number
-
-

Specifies number of seconds before blanking the pointer [default 2]. Use a -large number (e.g. 987654321) to effectively disable the timeout.

-
-
backspacekey: string
-
-

The string to send when the backspace key is pressed. If set to DEC -or unset it will send Delete (code 127) or, if shifted, Backspace -(code 8) - which can be reversed with the appropriate DEC private mode -escape sequence.

-
-
deletekey: string
-
-

The string to send when the delete key (not the keypad delete key) is -pressed. If unset it will send the sequence traditionally associated -with the Execute key.

-
-
cutchars: string
-
-

The characters used as delimiters for double-click word selection -(whitespace delimiting is added automatically if resource is given).

-

When the perl selection extension is in use (the default if compiled -in, see the rxvtperl(3) manpage), a suitable regex using these -characters will be created (if the resource exists, otherwise, no regex -will be created). In this mode, characters outside ISO-8859-1 can be used.

-

When the selection extension is not used, only ISO-8859-1 characters can -be used. If not specified, the built-in default is used:

-

BACKSLASH `"'&()*,;<=>?@[]^{|}

-
-
preeditType: style
-
-

OverTheSpot, OffTheSpot, Root; option -pt.

-
-
inputMethod: name
-
-

name of inputMethod to use; option -im.

-
-
imLocale: name
-
-

The locale to use for opening the IM. You can use an 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.

-
-
imFont: fontset
-
-

Specify the font-set used for XIM styles 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 -found, preferably one or two pixels differing in size to the base font. -option -imfont.

-
-
tripleclickwords: boolean
-
-

Change the meaning of triple-click selection with the left mouse -button. Instead of selecting a full line it will extend the selection to -the end of the logical line only; option -tcw.

-
-
insecure: boolean
-
-

Enables "insecure" mode. Rxvt-unicode offers some escape sequences that -echo arbitrary strings like the icon name or the locale. This could be -abused if somebody gets 8-bit-clean access to your display, whether -through a mail client displaying mail bodies unfiltered or through -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.

-
-
modifier: modifier
-
-

Set the key to be interpreted as the Meta key to: alt, meta, -hyper, super, mod1, mod2, mod3, mod4, mod5; option --mod.

-
-
answerbackString: string
-
-

Specify the reply rxvt-unicode sends to the shell when an ENQ (control-E) -character is passed through. It may contain escape values as described -in the entry on keysym following.

-
-
secondaryScreen: boolean
-
-

Turn on/off secondary screen (default enabled).

-
-
secondaryScroll: boolean
-
-

Turn on/off secondary screen scroll (default enabled). If this -option is enabled, scrolls on the secondary screen will change the -scrollback buffer and switching to/from the secondary screen will -instead scroll the screen up.

-
-
hold: boolean
-
-

Turn on/off hold window after exit support. If enabled, rxvt -will not immediately destroy its window when the program executed within -it exits. Instead, it will wait till it is being killed or closed by the -user.

-
-
keysym.sym: string
-
-

Compile frills: Associate string with keysym sym. The -intervening resource name keysym. cannot be omitted.

-

The format of sym is "(modifiers-)key", where modifiers can be -any combination of ISOLevel3, AppKeypad, Control, NumLock, -Shift, Meta, Lock, Mod1, Mod2, Mod3, Mod4, Mod5, -and the abbreviated I, K, C, N, S, M, A, L, 1, -2, 3, 4, 5.

-

The NumLock, Meta and ISOLevel3 modifiers are usually aliased to -whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 Shift/AltGr -keys are being mapped. AppKeypad is a synthetic modifier mapped to the -current application keymap mode state.

-

The spellings of key can be obtained by using xev(1) command or -searching keysym macros from /usr/X11R6/include/X11/keysymdef.h and -omitting the prefix XK_. Alternatively you can specify key by its hex -keysym value (0x0000 - 0xFFFF). Note that the lookup of syms is not -performed in an exact manner; however, the closest match is assured.

-

string may contain escape values (\n: newline, \000: octal -number), see RESOURCES in man 7 X for futher details.

-

You can define a range of keysyms in one shot by providing a string -with pattern list/PREFIX/MIDDLE/SUFFIX, where the delimiter `/' -should be a character not used by the strings.

-

Its usage can be demonstrated by an example:

-
  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:    \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 command:STRING, the specified STRING -is interpreted and executed as rxvt'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: 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 rxvtperl(3) -manpage. For example, the selection extension (activated via -rxvt -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 rxvt'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 can have some limited -font-switching at runtime:

-
  URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007
-  URxvt.keysym.M-C-2: command:\033]50;9x15bold\007
-
-
-

Other things are possible, e.g. resizing (see rxvt(7) for more -info):

-
  URxvt.keysym.M-C-3: command:\033[8;25;80t
-  URxvt.keysym.M-C-4: command:\033[8;48;110t
-
-
-
-
perl-ext-common: string
-
perl-ext: string
-
-

Comma-separated 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 scrollback 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.

-
-
perl-eval: string
-
-

Perl code to be evaluated when all extensions have been registered. See -the rxvtperl(3) manpage. Due to security reasons, this resource -will be ignored when running setuid/setgid.

-
-
perl-lib: path
-
-

Colon-separated list of additional directories that hold extension -scripts. When looking for extensions specified by the perl resource, -rxvt will first look in these directories and then in -/opt/rxvt/lib/urxvt/perl/. Due to security reasons, this resource -will be ignored when running setuid/setgid.

-

See the rxvtperl(3) manpage.

-
-
selection.pattern-idx: perl-regex
-
-

Additional selection patterns, see the rxvtperl(3) manpage for -details.

-
-
selection-autotransform.idx: perl-transform
-
-

Selection auto-transform patterns, see the rxvtperl(3) manpage -for details.

-
-
searchable-scrollback: keysym
-
-

Sets the hotkey that starts the incremental scrollback buffer search -(default: M-s).

-
-
urlLauncher: string
-
-

Specifies the program to be started with a URL argument. Used by the -selection-popup and matcher perl extensions.

-
-
transient-for: windowid
-
-

Compile frills: Sets the WM_TRANSIENT_FOR property to the given window id.

-
-
override-redirect: boolean
-
-

Compile frills: Sets override-redirect for the terminal window, making -it almost invisible to window managers; option -override-redirect.

-
-
iso14755_52: boolean
-
-

Turn on/off ISO 14755 5.2 mode (default enabled).

-
-
- -
-

THE SCROLLBAR

Top

-
-

Lines of text that scroll off the top of the rxvt window -(resource: saveLines) and can be scrolled back using the scrollbar -or by keystrokes. The normal rxvt 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. -Scroll up with Button3 (xterm-scrollbar) or Shift-Prior. -Continuous scroll with Button2.

- -
-

MOUSE REPORTING

Top

-
-

To temporarily override mouse reporting, for either the scrollbar or -the normal text selection/insertion, hold either the Shift or the Meta -(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), -respectively.

- -
-

THE SELECTION: SELECTING AND PASTING TEXT

Top

-
-

The behaviour of text selection and insertion/pasting mechanism is similar -to xterm(1).

-
-
Selecting:
-
-

Left click at the beginning of the region, drag to the end of the region -and release; Right click to extend the marked region; Left double-click -to select a word; Left triple-click to select the entire logical line -(which can span multiple screen lines), unless modified by resource -tripleclickwords.

-

Starting a selection while pressing the Meta key (or Meta+Ctrl keys) -(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.

-
-
Pasting:
-
-

Pressing and releasing the Middle mouse button in an rxvt -window causes the value of the PRIMARY selection (or CLIPBOARD with the -Meta modifier) to be inserted as if it had been typed on the keyboard.

-

Pressing Shift-Insert causes the value of the PRIMARY selection to be -inserted too.

-
-
- -
-

CHANGING FONTS

Top

-
-

Changing fonts (or font sizes, respectively) via the keypad is not yet -supported in rxvt-unicode. Bug me if you need this.

-

You can, however, switch fonts at runtime using escape sequences, e.g.:

-
   printf '\e]710;%s\007' "9x15bold,xft:Kochi Gothic"
-
-
-

You can use keyboard shortcuts, too:

-
   URxvt.keysym.M-C-1: command:\033]710;suxuseuro\007\033]711;suxuseuro\007
-   URxvt.keysym.M-C-2: command:\033]710;9x15bold\007\033]711;9x15bold\007
-
-
-

rxvt-unicode will automatically re-apply these fonts to the output so far.

- -
-

ISO 14755 SUPPORT

Top

-
-

ISO 14755 is a standard for entering and viewing unicode characters -and character codes using the keyboard. It consists of 4 parts. The -first part is available if rxvt-unicode has been compiled with ---enable-frills, the rest is available when rxvt-unicode was compiled -with --enable-iso14755.

-
-
* 5.1: Basic method
-
-

This allows you to enter unicode characters using their hexcode.

-

Start by pressing and holding both Control and Shift, then enter -hex-digits (between one and six). Releasing Control and Shift will -commit the character as if it were typed directly. While holding down -Control and Shift you can also enter multiple characters by pressing -Space, which will commit the current character and lets you start a new -one.

-

As an example of use, imagine a business card with a japanese e-mail -address, which you cannot type. Fortunately, the card has the e-mail -address printed as hexcodes, e.g. 671d 65e5. You can enter this easily -by pressing Control and Shift, followed by 6-7-1-D-SPACE-6-5-E-5, -followed by releasing the modifier keys.

-
-
* 5.2: Keyboard symbols entry method
-
-

This mode lets you input characters representing the keycap symbols of -your keyboard, if representable in the current locale encoding.

-

Start by pressing Control and Shift together, then releasing -them. The next special key (cursor keys, home etc.) you enter will not -invoke its usual function but instead will insert the corresponding -keycap symbol. The symbol will only be entered when the key has been -released, otherwise pressing e.g. Shift would enter the symbol for -ISO Level 2 Switch, although your intention might have been to enter a -reverse tab (Shift-Tab).

-
-
* 5.3: Screen-selection entry method
-
-

While this is implemented already (it's basically the selection -mechanism), it could be extended by displaying a unicode character map.

-
-
* 5.4: Feedback method for identifying displayed characters for later input
-
-

This method lets you display the unicode character code associated with -characters already displayed.

-

You enter this mode by holding down Control and Shift together, then -pressing and holding the left mouse button and moving around. The unicode -hex code(s) (it might be a combining character) of the character under the -pointer is displayed until you release Control and Shift.

-

In addition to the hex codes it will display the font used to draw this -character - due to implementation reasons, characters combined with -combining characters, line drawing characters and unknown characters will -always be drawn using the built-in support font.

-
-
-

With respect to conformance, rxvt-unicode is supposed to be compliant to -both scenario A and B of ISO 14755, including part 5.2.

- -
-

LOGIN STAMP

Top

-
-

rxvt 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 -on some systems or setgid to root or to some other group on others.

- -
-

COLORS AND GRAPHICS

Top

-
-

In addition to the default foreground and background colours, -rxvt 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 names.

-
color0(black)= Black
color1(red)= Red3
color2(green)= Green3
color3(yellow)= Yellow3
color4(blue)= Blue3
color5(magenta)= Magenta3
color6(cyan)= Cyan3
color7(white)= AntiqueWhite
color8(bright black)= Grey25
color9(bright red)= Red
color10(bright green)= Green
color11(bright yellow)= Yellow
color12(bright blue)= Blue
color13(bright magenta)= Magenta
color14(bright cyan)= Cyan
color15(bright white)= White
foreground= Black
background= White

It is also possible to specify the colour values of foreground, -background, cursorColor, cursorColor2, colorBD, colorUL as -a number 0-15, as a convenient shorthand to reference the colour name of -color0-color15.

-

In addition to the colours defined above, rxvt offers an -additional 72 colours. The first 64 of those (with indices 16 to 79) -consist of a 4*4*4 RGB colour cube (i.e. index = r * 16 + g * 4 + b + -16), followed by 8 additional shades of gray (with indices 80 to 87).

-

Together, all those colours implement the 88 colour xterm colours. Only -the first 16 can be changed using resources currently, the rest can only -be changed via command sequences ("escape codes").

-

Note that -rv ("reverseVideo: True") simulates reverse video by -always swapping the foreground/background colours. This is in contrast to -xterm(1) where the colours are only swapped if they have not otherwise -been specified. For example,

-
-
rxvt -fg Black -bg White -rv
-
-

would yield White on Black, while on xterm(1) it would yield Black -on White.

-
-
- -
-

ALPHA CHANNEL SUPPORT

-
-

If Xft support has been compiled in and as long as Xft/Xrender/X don't get -their act together, rxvt-unicode will support rgba:rrrr/gggg/bbbb/aaaa -(recommended, but MUST have 4 digits/component) colour specifications, -in addition to the ones provided by X, where the additional A component -specifies opacity (alpha) values. The minimum value of 0 is completely -transparent). You can also prefix any color with [percent], where -percent is a decimal percentage (0-100) that specifies the opacity of -the color, where 0 is completely transparent and 100 is completelxy -opaque.

-

You probably need to specify "-depth 32", too, and have the luck that -your X-server uses ARGB pixel layout, as X is far from just supporting -ARGB visuals out of the box, and rxvt-unicode just fudges around.

-

For example, the following selects an almost completely transparent red -background, and an almost opaque pink foreground:

-
   rxvt -depth 32 -bg rgba:0000/0000/0000/aaaa -fg "[80]pink"
-
-
-

Please note that transparency of any kind if completely unsupported by -the author. Don't bug him with installation questions!

- -
-

ENVIRONMENT

Top

-
-

rxvt sets and/or uses the following environment variables:

-
-
TERM
-
-

Normally set to rxvt-unicode, unless overwritten at configure time, via -resources or on the command line.

-
-
COLORTERM
-
-

Either rxvt, rxvt-xpm, depending on whether rxvt was -compiled with background image support, and optionally with the added -extension -mono to indicate that rxvt-unicode runs on a monochrome -screen.

-
-
COLORFGBG
-
-

Set to a string of the form fg;bg or fg;xpm;bg, where fg is -the colour code used as default foreground/text colour (or the string -default to indicate that the default-colour escape sequence is to be -used), bg is the colour code used as default background colour (or the -string default), and xpm is the string default if rxvt -was compiled with background image support. Libraries like ncurses -and slang can (and do) use this information to optimize screen output.

-
-
WINDOWID
-
-

Set to the (decimal) X Window ID of the rxvt window (the toplevel -window, which usually has subwindows for the scrollbar, the terminal -window and so on).

-
-
TERMINFO
-
-

Set to the terminfo directory iff rxvt was configured with ---with-terminfo=PATH.

-
-
DISPLAY
-
-

Used by rxvt to connect to the display and set to the correct -display in its child processes.

-
-
SHELL
-
-

The shell to be used for command execution, defaults to /bin/sh.

-
-
RXVT_SOCKET
-
-

The unix domain socket path used by rxvtc(1) and -rxvtd(1).

-

Default $HOME/.rxvt-unicode-<nodename.

-
-
HOME
-
-

Used to locate the default directory for the unix domain socket for -daemon communications and to locate various resource files (such as -.Xdefaults)

-
-
XAPPLRESDIR
-
-

Directory where various X resource files are being located.

-
-
XENVIRONMENT
-
-

If set and accessible, gives the name of a X resource file to be loaded by -rxvt.

-
-
- -
-

FILES

Top

-
-
-
/usr/lib/X11/rgb.txt
-
-

Color names.

-
-
- -
-

SEE ALSO

Top

-
-

rxvt(7), rxvtc(1), rxvtd(1), xterm(1), sh(1), resize(1), X(1), pty(4), tty(4), utmp(5)

- -
-

CURRENT PROJECT COORDINATOR

Top

-
-
-
Project Coordinator
-
-

Marc A. Lehmann <rxvt-unicode@schmorp.de>

-

http://software.schmorp.de/pkg/rxvt-unicode.html

-
-
- -
-

AUTHORS

Top

-
-
-
John Bovey
-
-

University of Kent, 1992, wrote the original Xvt.

-
-
Rob Nation <nation@rocket.sanders.lockheed.com>
-
-

very heavily modified Xvt and came up with Rxvt

-
-
Angelo Haritsis <ah@doc.ic.ac.uk>
-
-

wrote the Greek Keyboard Input (no longer in code)

-
-
mj olesen <olesen@me.QueensU.CA>
-
-

Wrote the menu system.

-

Project Coordinator (changes.txt 2.11 to 2.21)

-
-
Oezguer Kesim <kesim@math.fu-berlin.de>
-
-

Project Coordinator (changes.txt 2.21a to 2.4.5)

-
-
Geoff Wing <gcw@pobox.com>
-
-

Rewrote screen display and text selection routines.

-

Project Coordinator (changes.txt 2.4.6 - rxvt-unicode)

-
-
Marc Alexander Lehmann <rxvt-unicode@schmorp.de>
-
-

Forked rxvt-unicode, unicode support, rewrote almost all the code, perl -extension, random hacks, numerous bugfixes and extensions.

-

Project Coordinator (Changes 1.0 -)

-
-
Emanuele Giaquinta <e.giaquinta@glauco.it>
-
-

Pty/tty/utmp/wtmp rewrite, lots of random hacking and bugfixing.

-
-
- -
-
- diff --git a/doc/rxvt.1.txt b/doc/rxvt.1.txt deleted file mode 100644 index 0f375833..00000000 --- a/doc/rxvt.1.txt +++ /dev/null @@ -1,1405 +0,0 @@ -NAME - rxvt-unicode (ouR XVT, unicode) - (a VT102 emulator for the X window - system) - -SYNOPSIS - rxvt [options] [-e command [ args ]] - -DESCRIPTION - rxvt-unicode, version 8.6, 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 -- a significant - advantage on a machine serving many X sessions. - -FREQUENTLY ASKED QUESTIONS - See rxvt(7) (try "man 7 rxvt") 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 - . - -RXVT-UNICODE VS. RXVT - Unlike the original rxvt, rxvt-unicode stores all text in Unicode - internally. That means it can store and display most scripts in the - world. Being a terminal emulator, however, some things are very - difficult, especially cursive scripts such as arabic, vertically written - scripts like mongolian or scripts requiring extremely complex combining - rules, like tibetan or devanagari. Don't expect pretty output when using - these scripts. Most other scripts, latin, cyrillic, kanji, thai etc. - should work fine, though. A somewhat difficult case are right-to-left - scripts, such as hebrew: rxvt-unicode adopts the view that bidirectional - algorithms belong into the application, not the terminal emulator (too - many things -- such as cursor-movement while editing -- break - otherwise), but that might change. - - If you are looking for a terminal that supports more exotic scripts, let - me recommend "mlterm", which is a very user friendly, lean and clean - terminal emulator. In fact, the reason rxvt-unicode was born was solely - because the author couldn't get "mlterm" to use one font for latin1 and - another for japanese. - - Therefore another design rationale was the use of multiple fonts to - display characters: The idea of a single unicode font which many other - programs force onto its users never made sense to me: You should be able - to choose any font for any script freely. - - Apart from that, rxvt-unicode is also much better internationalised than - its predecessor, supports things such as XFT and ISO 14755 that are - handy in i18n-environments, is faster, and has a lot bugs less than the - original rxvt. This all in addition to dozens of other small - improvements. - - It is still faithfully following the original rxvt idea of being lean - and nice on resources: for example, you can still configure rxvt-unicode - without most of its features to get a lean binary. It also comes with a - client/daemon pair that lets you open any number of terminal windows - from within a single process, which makes startup time very fast and - drastically reduces memory usage. See rxvtd(1) (daemon) and rxvtc(1) - (client). - - It also makes technical information about escape sequences (which have - been extended) more accessible: see rxvt(7) for technical reference - documentation (escape sequences etc.). - -OPTIONS - The rxvt 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 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 command-line options - compiled into your version. - - Note that rxvt 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 Orange'. - - The following options are available: - - -help, --help - Print out a message describing available options. - - -display *displayname* - Attempt to open a window on the named X display (-d still - respected). In the absence of this option, the display specified by - the DISPLAY environment variable is used. - - -depth *bitdepth* - Compile *xft*: Attempt to find a visual with the given bit depth; - resource depth. - - -geometry *geom* - Window geometry (-g still respected); resource geometry. - - -rv|+rv - Turn on/off simulated reverse video; resource reverseVideo. - - -j|+j - Turn on/off jump scrolling (allow multiple lines per refresh); - resource jumpScroll. - - -ss|+ss - Turn on/off skip scrolling (allow multiple screens per refresh); - resource skipScroll. - - -tr|+tr - Turn on/off illusion of a transparent window background. Obsolete - form of it is -ip and it should not be used anymore; resource - transparent. - - *Please note that old resource name of inheritPixmap is obsolete and - should be changed to transparent. Backwards compatibility support - for inheritPixmap will be phased out in future versions of rxvt!* - - *Please address all transparency related issues to Sasha Vasko at - sasha@aftercode.net. Read the FAQ (man 7 rxvt)!* - - -fade *number* - Fade the text by the given percentage when focus is lost. Small - values fade a little only, 100 completely replaces all colours by - the fade colour; resource fading. - - -fadecolor *colour* - Fade to this colour when fading is used (see -fade). The default - colour is opaque black. resource fadeColor. - - -tint *colour* - Tint the transparent background pixmap with the given colour when - transparency is enabled with -tr. This only works for non-tiled - backgrounds, currently. See also the -sh option that can be used to - brighten or darken the image in addition to tinting it. Please note - that certain tint colours can be applied on the server-side, thus - yielding performance gain of two orders of magnitude. These colours - are: blue, red, green, cyan, magenta, yellow, and those close to - them. Also pure black and pure white colors essentially mean no - tinting; resource *tintColor*. Example: - - rxvt -tr -tint blue -sh 40 - - -sh *number* - Darken (0 .. 100) or lighten (100 .. 200) the transparent background - image in addition to (or instead of) tinting it; resource *shading*. - - -blt *string* - Specify background blending type. If background pixmap is specified - at the same time as transparency - such pixmap will be blended over - transparency image, using method specified. Supported values are : - add, alphablend, allanon - color values averaging, colorize, darken, - diff, dissipate, hue, lighten, overlay, saturate, screen, sub, tint, - value. The default is alpha-blending. Compile *afterimage*; resource - *blendType*. - - -blr *HxV* - Apply Gaussian Blur with the specified radii to the transparent - background image. If single number is specified - both vertical and - horizontal radii are considered to be the same. Setting one of the - radii to 1 and another to a large number creates interesting effects - on some backgrounds. Maximum radius value is 128. Compile - *afterimage*; resource *blurRadius*. - - -bg *colour* - Window background colour; resource background. - - -fg *colour* - Window foreground colour; resource foreground. - - -pixmap *file[;geom[:op1][:op2][...]]* - Compile *afterimage*: Specify image file for the background and also - optionally specify its scaling with a geometry string. Note you may - need to add quotes to avoid special shell interpretation of the ";" - in the command-line; for more details see resource backgroundPixmap. - - -cr *colour* - The cursor colour; resource cursorColor. - - -pr *colour* - The mouse pointer foreground colour; resource pointerColor. - - -pr2 *colour* - The mouse pointer background colour; resource pointerColor2. - - -bd *colour* - The colour of the border around the text area and between the - scrollbar and the text; resource borderColor. - - -fn *fontlist* - Select the fonts to be used. This is a comma separated list of font - names that are checked in order when trying to find glyphs for - characters. The first font defines the cell size for characters; - other fonts might be smaller, but not (in general) larger. A - (hopefully) reasonable default font list is always appended to it. - See resource font for more details. - - In short, to specify an X11 core font, just specify its name or - prefix it with "x:". To specify an XFT-font, you need to prefix it - with "xft:", e.g.: - - rxvt -fn "xft:Bitstream Vera Sans Mono:pixelsize=15" - rxvt -fn "9x15bold,xft:Bitstream Vera Sans Mono" - - See also the question "How does rxvt-unicode choose fonts?" in the - FAQ section of rxvt(7). - - -fb *fontlist* - Compile *font-styles*: The bold font list to use when bold - characters are to be printed. See resource boldFont for details. - - -fi *fontlist* - Compile *font-styles*: The italic font list to use when *italic* - characters are to be printed. See resource italicFont for details. - - -fbi *fontlist* - Compile *font-styles*: The bold italic font list to use when *bold - italic* characters are to be printed. See resource boldItalicFont - for details. - - -is|+is - Compile *font-styles*: Bold/Italic font styles imply high intensity - foreground/background (default). See resource intensityStyles for - details. - - -name *name* - Specify the application name under which resources are to be - obtained, rather than the default executable file name. Name should - not contain `.' or `*' characters. Also sets the icon and title - name. - - -ls|+ls - Start as a login-shell/sub-shell; resource loginShell. - - -ut|+ut - Compile *utmp*: Inhibit/enable writing a utmp entry; resource - utmpInhibit. - - -vb|+vb - Turn on/off visual bell on receipt of a bell character; resource - visualBell. - - -sb|+sb - Turn on/off scrollbar; resource scrollBar. - - -si|+si - Turn on/off scroll-to-bottom on TTY output inhibit; resource - scrollTtyOutput has opposite effect. - - -sk|+sk - Turn on/off scroll-to-bottom on keypress; resource - scrollTtyKeypress. - - -sw|+sw - Turn on/off scrolling with the scrollback buffer as new lines - appear. This only takes effect if -si is also given; resource - scrollWithBuffer. - - -sr|+sr - Put scrollbar on right/left; resource scrollBar_right. - - -st|+st - Display rxvt (non XTerm/NeXT) scrollbar without/with a trough; - resource scrollBar_floating. - - -ptab|+ptab - If enabled (default), "Horizontal Tab" characters are being stored - as actual wide characters in the screen buffer, which makes it - possible to select and paste them. Since a horizontal tab is a - cursor movement and not an actual glyph, this can sometimes be - visually annoying as the cursor on a tab character is displayed as a - wide cursor; resource pastableTabs. - - -bc|+bc - Blink the cursor; resource cursorBlink. - - -iconic - Start iconified, if the window manager supports that option. - Alternative form is -ic. - - -sl *number* - Save *number* lines in the scrollback buffer. See resource entry for - limits; resource saveLines. - - -b *number* - Compile *frills*: Internal border of *number* pixels. See resource - entry for limits; resource internalBorder. - - -w *number* - Compile *frills*: External border of *number* pixels. Also, -bw and - -borderwidth. See resource entry for limits; resource - externalBorder. - - -bl Compile *frills*: Set MWM hints to request a borderless window, i.e. - if honoured by the WM, the rxvt-unicode window will not have window - decorations; resource borderLess. - - -override-redirect - Compile *frills*: Sets override-redirect on the window; resource - override-redirect. - - -sbg - Compile *frills*: Disable the usage of the built-in block - graphics/line drawing characters and just rely on what the specified - fonts provide. Use this if you have a good font and want to use its - block graphic glyphs; resource skipBuiltinGlyphs. - - -lsp *number* - Compile *frills*: Lines (pixel height) to insert between each row of - the display. Useful to work around font rendering problems; resource - lineSpace. - - -tn *termname* - This option specifies the name of the terminal type to be set in the - TERM environment variable. This terminal type must exist in the - *termcap(5)* database and should have *li#* and *co#* entries; - resource termName. - - -e *command [arguments]* - Run the command with its command-line arguments in the rxvt window; - also sets the window title and icon name to be the basename of the - program being executed if neither *-title* (*-T*) nor *-n* are given - on the command line. If this option is used, it must be the last on - the command-line. If there is no -e option then the default is to - run the program specified by the SHELL environment variable or, - failing that, *sh(1)*. - - 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: - - rxvt -e sh -c "shell commands" - - -title *text* - Window title (-T still respected); the default title is the basename - of the program specified after the -e option, if any, otherwise the - application name; resource title. - - -n *text* - Icon name; the default name is the basename of the program specified - after the -e option, if any, otherwise the application name; - resource iconName. - - -C Capture system console messages. - - -pt *style* - Compile *XIM*: input style for input method; OverTheSpot, - OffTheSpot, Root; resource preeditType. - - -im *text* - Compile *XIM*: input method name. resource inputMethod. - - -imlocale *string* - The locale to use for opening the IM. You can use an "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. resource imLocale. - - -imfont *fontset* - Set the font set to use for the X Input Method, see resource imFont - for more info. - - -tcw - Change the meaning of triple-click selection with the left mouse - button. Only effective when the original (non-perl) selection code - is in-use. Instead of selecting a full line it will extend the - selection the end of the logical line only. resource - tripleclickwords. - - -insecure - Enable "insecure" mode, which currently enables most of the escape - sequences that echo strings. See the resource insecure for more - info. - - -mod *modifier* - Override detection of Meta modifier with specified key: alt, meta, - hyper, super, mod1, mod2, mod3, mod4, mod5; resource *modifier*. - - -ssc|+ssc - Turn on/off secondary screen (default enabled); resource - secondaryScreen. - - -ssr|+ssr - Turn on/off secondary screen scroll (default enabled); resource - secondaryScroll. - - -hold|+hold - Turn on/off hold window after exit support. If enabled, rxvt will - not immediately destroy its window when the program executed within - it exits. Instead, it will wait till it is being killed or closed by - the user; resource hold. - - -xrm *string* - Works like the X Toolkit option of the same name, by adding the - *string* as if it were specified in a resource file. Resource values - specified this way take precedence over all other resource - specifications. - - Note that you need to use the *same* syntax as in the .Xdefaults - file, e.g. "*.background: black". Also note that all rxvt-specific - options can be specified as long-options on the commandline, so use - of -xrm is mostly limited to cases where you want to specify other - resources (e.g. for input methods) or for compatibility with other - programs. - - -keysym.*sym* *string* - Remap a key symbol. See resource keysym. - - -embed *windowid* - Tells rxvt to embed its windows into an already-existing window, - which enables applications to easily embed a terminal. - - Right now, rxvt will first unmap/map the specified window, so it - shouldn't be a top-level window. rxvt 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 rxvt and leave it alone. - - The window will not be destroyed when rxvt exits. - - It might be useful to know that rxvt 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 whether 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 "rxvt -embed $xid &"; - }); - - -pty-fd *file descriptor* - Tells rxvt NOT to execute any commands or create a new pty/tty pair - but instead use the given file descriptor as the tty master. This is - useful if you want to drive rxvt as a generic terminal emulator - without having to run a program within it. - - If this switch is given, rxvt 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 "rxvt -pty-fd " . (fileno $pty) . "&"; - close $pty; - - # now communicate with rxvt - my $slave = $pty->slave; - while (<$slave>) { print $slave "got <$_>\n" } - - -pe *string* - Comma-separated list of perl extension scripts to use (or not to - use) in this terminal instance. See resource perl-ext for details. - -RESOURCES (available also as long-options) - Note: `rxvt --help' gives a list of all resources (long options) - compiled into your version. - - 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. rxvt 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- - 6. resources specified via -xrm on the commandline - - Note that when reading X resources, rxvt recognizes two class names: - Rxvt 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, 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 supported (you might want to check - the rxvtperl(3) manpage for additional settings by perl extensions not - documented here): - - depth: *bitdepth* - Compile *xft*: Attempt to find a visual with the given bit depth; - option -depth. - - geometry: *geom* - Create the window with the specified X window geometry [default - 80x24]; option -geometry. - - background: *colour* - Use the specified colour as the window's background colour [default - White]; option -bg. - - foreground: *colour* - Use the specified colour as the window's foreground colour [default - Black]; option -fg. - - color*n*: *colour* - Use the specified colour for the colour value *n*, where 0-7 - corresponds to low-intensity (normal) colours and 8-15 corresponds - to high-intensity (bold = bright foreground, blink = bright - background) colours. The canonical names are as follows: 0=black, - 1=red, 2=green, 3=yellow, 4=blue, 5=magenta, 6=cyan, 7=white, but - the actual colour names used are listed in the COLORS AND GRAPHICS - section. - - Colours higher than 15 cannot be set using resources (yet), but can - be changed using an escape command (see rxvt(7)). - - Colours 16-79 form a standard 4x4x4 colour cube (the same as xterm - with 88 colour support). Colours 80-87 are evenly spaces grey steps. - - colorBD: *colour* - colorIT: *colour* - Use the specified colour to display bold or italic characters when - the foreground colour is the default. If font styles are not - available (Compile *styles*) and this option is unset, reverse video - is used instead. - - colorUL: *colour* - Use the specified colour to display underlined characters when the - foreground colour is the default. - - colorRV: *colour* - Use the specified colour as the background for reverse video - characters when OPTION_HC is disabled (--disable-frills). - - underlineColor: *colour* - If set, use the specified colour as the colour for the underline - itself. If unset, use the foreground colour. - - cursorColor: *colour* - Use the specified colour for the cursor. The default is to use the - foreground colour; option -cr. - - cursorColor2: *colour* - Use the specified colour for the colour of the cursor text. For this - to take effect, cursorColor must also be specified. The default is - to use the background colour. - - reverseVideo: *boolean* - True: simulate reverse video by foreground and background colours; - option -rv. False: regular screen colours [default]; option +rv. See - note in COLORS AND GRAPHICS section. - - jumpScroll: *boolean* - True: specify that jump scrolling should be used. When receiving - lots of lines, rxvt will only scroll once a whole screen height of - lines has been read, resulting in fewer updates while still - displaying every received line; option -j. - - False: specify that smooth scrolling should be used. rxvt will force - a screen refresh on each new line it received; option +j. - - skipScroll: *boolean* - True: (the default) specify that skip scrolling should be used. When - receiving lots of lines, rxvt will only scroll once in a while - (around 60 times per second), resulting in far fewer updates. This - can result in rxvt not ever displaying some of the lines it - receives; option -ss. - - False: specify that everything is to be displayed, even if the - refresh is too fast for the human eye to read anything (or the - monitor to display anything); option +ss. - - inheritPixmap: *boolean* - True: make the background inherit the parent windows' pixmap, giving - artificial transparency. False: do not inherit the parent windows' - pixmap. - - *Please note that transparency of any kind if completely unsupported - by the author. Don't bug him with installation questions!* - - fading: *number* - Fade the text by the given percentage when focus is lost; option - -fade. - - fadeColor: *colour* - Fade to this colour, when fading is used (see fading:). The default - colour is black; option -fadecolor. - - tintColor: *colour* - Tint the transparent background pixmap with the given colour; option - -tint. - - shading: *number* - Darken (0 .. 100) or lighten (-1 .. -100) the transparent background - image in addition to tinting it; option -sh. - - blendType: *string* - Specify background blending type; option -blt. - - blurRadius: *number* - Apply Gaussian Blurr with the specified radius to the transparent - background image; option -blr. - - scrollColor: *colour* - Use the specified colour for the scrollbar [default #B2B2B2]. - - troughColor: *colour* - Use the specified colour for the scrollbar's trough area [default - #969696]. Only relevant for rxvt (non XTerm/NeXT) scrollbar. - - borderColor: *colour* - The colour of the border around the text area and between the - scrollbar and the text. - - backgroundPixmap: *file[;geom[:op1][:op2][...]]* - Use the specified image file for the background and also optionally - specify its scaling with a geometry string WxH+X+Y, (default - "0x0+50+50") in which "W" / "H" specify the horizontal/vertical - scale (percent), and "X" / "Y" locate the image centre (percent). A - scale of 0 displays the image with tiling. A scale of 1 displays the - image without any scaling. A scale of 2 to 9 specifies an integer - number of images in that direction. No image will be magnified - beyond 10 times its original size. The maximum permitted scale is - 1000. Additional operations can be specified after colon - :op1:op2.... Supported operations are: - - tile force background image to be tiled and not scaled. Equivalent to 0x0, - propscale will scale image keeping proportions, - auto will scale image to match window size. Equivalent to 100x100; - hscale will scale image horizontally to the window size; - vscale will scale image vertically to the window size; - scale will scale image to match window size; - root will tile image as if it was a root window background, auto-adjusting - whenever terminal window moves. - - If used in conjunction with -tr option, the specified pixmap will be - blended over transparency image using either alpha-blending, or any - other blending type, specified with -blt "type" option. - - path: *path* - Specify the colon-delimited search path for finding background image - files. - - font: *fontlist* - Select the fonts to be used. This is a comma separated list of font - names that are checked in order when trying to find glyphs for - characters. The first font defines the cell size for characters; - other fonts might be smaller, but not (in general) larger. A - (hopefully) reasonable default font list is always appended to it; - option -fn. - - Each font can either be a standard X11 core font (XLFD) name, with - optional prefix "x:" or a Xft font (Compile *xft*), prefixed with - "xft:". - - In addition, each font can be prefixed with additional hints and - specifications enclosed in square brackets ("[]"). The only - available hint currently is "codeset=codeset-name", and this is only - used for Xft fonts. - - For example, this font resource - - URxvt.font: 9x15bold,\ - -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso10646-1,\ - -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1, \ - [codeset=JISX0208]xft:Kochi Gothic:antialias=false, \ - xft:Code2000:antialias=false - - specifies five fonts to be used. The first one is "9x15bold" - (actually the iso8859-1 version of the second font), which is the - base font (because it is named first) and thus defines the character - cell grid to be 9 pixels wide and 15 pixels high. - - The second font is just used to add additional unicode characters - not in the base font, likewise the third, which is unfortunately - non-bold, but the bold version of the font does contain less - characters, so this is a useful supplement. - - The third font is an Xft font with aliasing turned off, and the - characters are limited to the JIS 0208 codeset (i.e. japanese - kanji). The font contains other characters, but we are not - interested in them. - - The last font is a useful catch-all font that supplies most of the - remaining unicode characters. - - boldFont: *fontlist* - italicFont: *fontlist* - boldItalicFont: *fontlist* - The font list to use for displaying bold, *italic* or *bold italic* - characters, respectively. - - If specified and non-empty, then the syntax is the same as for the - font-resource, and the given font list will be used as is, which - makes it possible to substitute completely different font styles for - bold and italic. - - If unset (the default), a suitable font list will be synthesized by - "morphing" the normal text font list into the desired shape. If that - is not possible, replacement fonts of the desired shape will be - tried. - - If set, but empty, then this specific style is disabled and the - normal text font will being used for the given style. - - intensityStyles: *boolean* - When font styles are not enabled, or this option is enabled (True, - option -is, the default), bold and italic font styles imply high - intensity foreground/background colours. Disabling this option - (False, option +is) disables this behaviour, the high intensity - colours are not reachable. - - selectstyle: *mode* - Set mouse selection style to old which is 2.20, oldword which is - xterm style with 2.20 old word selection, or anything else which - gives xterm style selection. Only effective when the original - (non-perl) selection code is in use. - - scrollstyle: *mode* - Set scrollbar style to rxvt, plain, next or xterm. plain is the - author's favourite. - - title: *string* - Set window title string, the default title is the command-line - specified after the -e option, if any, otherwise the application - name; option -title. - - iconName: *string* - Set the name used to label the window's icon or displayed in an icon - manager window, it also sets the window's title unless it is - explicitly set; option -n. - - mapAlert: *boolean* - True: de-iconify (map) on receipt of a bell character. False: no - de-iconify (map) on receipt of a bell character [default]. - - urgentOnBell: *boolean* - True: set the urgency hint for the wm on receipt of a bell - character. False: do not set the urgency hint [default]. - - visualBell: *boolean* - True: use visual bell on receipt of a bell character; option -vb. - False: no visual bell [default]; option +vb. - - loginShell: *boolean* - True: start as a login shell by prepending a `-' to argv[0] of the - shell; option -ls. False: start as a normal sub-shell [default]; - option +ls. - - utmpInhibit: *boolean* - True: inhibit writing record into the system log file utmp; option - -ut. False: write record into the system log file utmp [default]; - option +ut. - - print-pipe: *string* - Specify a command pipe for vt100 printer [default *lpr(1)*]. Use - Print to initiate a screen dump to the printer and Ctrl-Print or - Shift-Print to include the scrollback as well. - - 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 every time you hit "Print". - - scrollBar: *boolean* - True: enable the scrollbar [default]; option -sb. False: disable the - scrollbar; option +sb. - - scrollBar_right: *boolean* - True: place the scrollbar on the right of the window; option -sr. - False: place the scrollbar on the left of the window; option +sr. - - scrollBar_floating: *boolean* - True: display an rxvt scrollbar without a trough; option -st. False: - display an rxvt scrollbar with a trough; option +st. - - scrollBar_align: *mode* - Align the top, bottom or centre [default] of the scrollbar thumb - with the pointer on middle button press/drag. - - scrollTtyOutput: *boolean* - True: scroll to bottom when tty receives output; option -si. False: - do not scroll to bottom when tty receives output; option +si. - - scrollWithBuffer: *boolean* - True: scroll with scrollback buffer when tty receives new lines (and - scrollTtyOutput is False); option -sw. False: do not scroll with - scrollback buffer when tty receives new lines; option +sw. - - scrollTtyKeypress: *boolean* - True: scroll to bottom when a non-special key is pressed. Special - keys are those which are intercepted by rxvt-unicode for special - handling and are not passed onto the shell; option -sk. False: do - not scroll to bottom when a non-special key is pressed; option +sk. - - saveLines: *number* - Save *number* lines in the scrollback buffer [default 64]. This - resource is limited on most machines to 65535; option -sl. - - internalBorder: *number* - Internal border of *number* pixels. This resource is limited to 100; - option -b. - - externalBorder: *number* - External border of *number* pixels. This resource is limited to 100; - option -w, -bw, -borderwidth. - - borderLess: *boolean* - Set MWM hints to request a borderless window, i.e. if honoured by - the WM, the rxvt-unicode window will not have window decorations; - option -bl. - - skipBuiltinGlyphs: *boolean* - Compile *frills*: Disable the usage of the built-in block - graphics/line drawing characters and just rely on what the specified - fonts provide. Use this if you have a good font and want to use its - block graphic glyphs; option -sbg. - - termName: *termname* - Specifies the terminal type name to be set in the TERM environment - variable; option -tn. - - lineSpace: *number* - Specifies number of lines (pixel height) to insert between each row - of the display [default 0]; option -lsp. - - meta8: *boolean* - True: handle Meta (Alt) + keypress to set the 8th bit. False: handle - Meta (Alt) + keypress as an escape prefix [default]. - - mouseWheelScrollPage: *boolean* - True: the mouse wheel scrolls a page full. False: the mouse wheel - scrolls five lines [default]. - - pastableTabs: *boolean* - True: store tabs as wide characters. False: interpret tabs as cursor - movement only; option "-ptab". - - cursorBlink: *boolean* - True: blink the cursor. False: do not blink the cursor [default]; - option -bc. - - pointerBlank: *boolean* - True: blank the pointer when a key is pressed or after a set number - of seconds of inactivity. False: the pointer is always visible - [default]. - - pointerColor: *colour* - Mouse pointer foreground colour. - - pointerColor2: *colour* - Mouse pointer background colour. - - pointerBlankDelay: *number* - Specifies number of seconds before blanking the pointer [default 2]. - Use a large number (e.g. 987654321) to effectively disable the - timeout. - - backspacekey: *string* - The string to send when the backspace key is pressed. If set to DEC - or unset it will send Delete (code 127) or, if shifted, Backspace - (code 8) - which can be reversed with the appropriate DEC private - mode escape sequence. - - deletekey: *string* - The string to send when the delete key (not the keypad delete key) - is pressed. If unset it will send the sequence traditionally - associated with the Execute key. - - cutchars: *string* - The characters used as delimiters for double-click word selection - (whitespace delimiting is added automatically if resource is given). - - When the perl selection extension is in use (the default if compiled - in, see the rxvtperl(3) manpage), a suitable regex using these - characters will be created (if the resource exists, otherwise, no - regex will be created). In this mode, characters outside ISO-8859-1 - can be used. - - When the selection extension is not used, only ISO-8859-1 characters - can be used. If not specified, the built-in default is used: - - BACKSLASH `"'&()*,;<=>?@[]^{|} - - preeditType: *style* - OverTheSpot, OffTheSpot, Root; option -pt. - - inputMethod: *name* - *name* of inputMethod to use; option -im. - - imLocale: *name* - The locale to use for opening the IM. You can use an "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. - - imFont: *fontset* - Specify the font-set used for XIM styles "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 found, preferably one or two pixels differing in size - to the base font. option -imfont. - - tripleclickwords: *boolean* - Change the meaning of triple-click selection with the left mouse - button. Instead of selecting a full line it will extend the - selection to the end of the logical line only; option -tcw. - - insecure: *boolean* - Enables "insecure" mode. Rxvt-unicode offers some escape sequences - that echo arbitrary strings like the icon name or the locale. This - could be abused if somebody gets 8-bit-clean access to your display, - whether through a mail client displaying mail bodies unfiltered or - through 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. - - modifier: *modifier* - Set the key to be interpreted as the Meta key to: alt, meta, hyper, - super, mod1, mod2, mod3, mod4, mod5; option -mod. - - answerbackString: *string* - Specify the reply rxvt-unicode sends to the shell when an ENQ - (control-E) character is passed through. It may contain escape - values as described in the entry on keysym following. - - secondaryScreen: *boolean* - Turn on/off secondary screen (default enabled). - - secondaryScroll: *boolean* - Turn on/off secondary screen scroll (default enabled). If this - option is enabled, scrolls on the secondary screen will change the - scrollback buffer and switching to/from the secondary screen will - instead scroll the screen up. - - hold: *boolean* - Turn on/off hold window after exit support. If enabled, rxvt will - not immediately destroy its window when the program executed within - it exits. Instead, it will wait till it is being killed or closed by - the user. - - keysym.*sym*: *string* - Compile *frills*: Associate *string* with keysym *sym*. The - intervening resource name keysym. cannot be omitted. - - The format of *sym* is "*(modifiers-)key*", where *modifiers* can be - any combination of ISOLevel3, AppKeypad, Control, NumLock, Shift, - Meta, Lock, Mod1, Mod2, Mod3, Mod4, Mod5, and the abbreviated I, K, - C, N, S, M, A, L, 1, 2, 3, 4, 5. - - The NumLock, Meta and ISOLevel3 modifiers are usually aliased to - whatever modifier the NumLock key, Meta/Alt keys or ISO Level3 - Shift/AltGr keys are being mapped. AppKeypad is a synthetic modifier - mapped to the current application keymap mode state. - - The spellings of *key* can be obtained by using xev(1) command or - searching keysym macros from /usr/X11R6/include/X11/keysymdef.h and - omitting the prefix XK_. Alternatively you can specify *key* by its - hex keysym value (0x0000 - 0xFFFF). Note that the lookup of *sym*s - is not performed in an exact manner; however, the closest match is - assured. - - *string* may contain escape values ("\n": newline, "\000": octal - number), see RESOURCES in "man 7 X" for futher details. - - You can define a range of keysyms in one shot by providing a - *string* with pattern list/PREFIX/MIDDLE/SUFFIX, where the delimiter - `/' should be a character not used by the strings. - - Its usage can be demonstrated by an example: - - URxvt.keysym.M-C-0x61: list|\033 - - The above line is equivalent to the following three lines: - - URxvt.keysym.Meta-Control-0x61: \033 - URxvt.keysym.Meta-Control-0x62: \033 - URxvt.keysym.Meta-Control-0x63: \033 - - If *string* takes the form of "command:STRING", the specified STRING - is interpreted and executed as rxvt'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: 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 - rxvtperl(3) manpage. For example, the selection extension (activated - via "rxvt -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 rxvt's - "Shift-Insert" mapping. To re-enable that, you can poke "holes" into - the user-defined keymap using the "builtin:" replacement: - - URxvt.keysym.Insert: - 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 can have some limited - font-switching at runtime: - - URxvt.keysym.M-C-1: command:\033]50;suxuseuro\007 - URxvt.keysym.M-C-2: command:\033]50;9x15bold\007 - - Other things are possible, e.g. resizing (see rxvt(7) for more - info): - - URxvt.keysym.M-C-3: command:\033[8;25;80t - URxvt.keysym.M-C-4: command:\033[8;48;110t - - perl-ext-common: *string* - perl-ext: *string* - Comma-separated 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", which binds the hotkey - for searchable scrollback 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. - - perl-eval: *string* - Perl code to be evaluated when all extensions have been registered. - See the rxvtperl(3) manpage. Due to security reasons, this resource - will be ignored when running setuid/setgid. - - perl-lib: *path* - Colon-separated list of additional directories that hold extension - scripts. When looking for extensions specified by the "perl" - resource, rxvt will first look in these directories and then in - /opt/rxvt/lib/urxvt/perl/. Due to security reasons, this resource - will be ignored when running setuid/setgid. - - See the rxvtperl(3) manpage. - - selection.pattern-*idx*: *perl-regex* - Additional selection patterns, see the rxvtperl(3) manpage for - details. - - selection-autotransform.*idx*: *perl-transform* - Selection auto-transform patterns, see the rxvtperl(3) manpage for - details. - - searchable-scrollback: *keysym* - Sets the hotkey that starts the incremental scrollback buffer search - (default: "M-s"). - - urlLauncher: *string* - Specifies the program to be started with a URL argument. Used by the - "selection-popup" and "matcher" perl extensions. - - transient-for: *windowid* - Compile *frills*: Sets the WM_TRANSIENT_FOR property to the given - window id. - - override-redirect: *boolean* - Compile *frills*: Sets override-redirect for the terminal window, - making it almost invisible to window managers; option - -override-redirect. - - iso14755_52: *boolean* - Turn on/off ISO 14755 5.2 mode (default enabled). - -THE SCROLLBAR - Lines of text that scroll off the top of the rxvt window (resource: - saveLines) and can be scrolled back using the scrollbar or by - keystrokes. The normal rxvt 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. Scroll up with - Button3 (xterm-scrollbar) or Shift-Prior. Continuous scroll with - Button2. - -MOUSE REPORTING - To temporarily override mouse reporting, for either the scrollbar or the - normal text selection/insertion, hold either the Shift or the Meta (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), respectively. - -THE SELECTION: SELECTING AND PASTING TEXT - The behaviour of text selection and insertion/pasting mechanism is - similar to *xterm*(1). - - Selecting: - Left click at the beginning of the region, drag to the end of the - region and release; Right click to extend the marked region; Left - double-click to select a word; Left triple-click to select the - entire logical line (which can span multiple screen lines), unless - modified by resource tripleclickwords. - - Starting a selection while pressing the Meta key (or Meta+Ctrl keys) - (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. - - Pasting: - Pressing and releasing the Middle mouse button in an rxvt window - causes the value of the PRIMARY selection (or CLIPBOARD with the - Meta modifier) to be inserted as if it had been typed on the - keyboard. - - Pressing Shift-Insert causes the value of the PRIMARY selection to - be inserted too. - -CHANGING FONTS - Changing fonts (or font sizes, respectively) via the keypad is not yet - supported in rxvt-unicode. Bug me if you need this. - - You can, however, switch fonts at runtime using escape sequences, e.g.: - - printf '\e]710;%s\007' "9x15bold,xft:Kochi Gothic" - - You can use keyboard shortcuts, too: - - URxvt.keysym.M-C-1: command:\033]710;suxuseuro\007\033]711;suxuseuro\007 - URxvt.keysym.M-C-2: command:\033]710;9x15bold\007\033]711;9x15bold\007 - - rxvt-unicode will automatically re-apply these fonts to the output so - far. - -ISO 14755 SUPPORT - ISO 14755 is a standard for entering and viewing unicode characters and - character codes using the keyboard. It consists of 4 parts. The first - part is available if rxvt-unicode has been compiled with - "--enable-frills", the rest is available when rxvt-unicode was compiled - with "--enable-iso14755". - - * 5.1: Basic method - This allows you to enter unicode characters using their hexcode. - - Start by pressing and holding both "Control" and "Shift", then enter - hex-digits (between one and six). Releasing "Control" and "Shift" - will commit the character as if it were typed directly. While - holding down "Control" and "Shift" you can also enter multiple - characters by pressing "Space", which will commit the current - character and lets you start a new one. - - As an example of use, imagine a business card with a japanese e-mail - address, which you cannot type. Fortunately, the card has the e-mail - address printed as hexcodes, e.g. "671d 65e5". You can enter this - easily by pressing "Control" and "Shift", followed by - "6-7-1-D-SPACE-6-5-E-5", followed by releasing the modifier keys. - - * 5.2: Keyboard symbols entry method - This mode lets you input characters representing the keycap symbols - of your keyboard, if representable in the current locale encoding. - - Start by pressing "Control" and "Shift" together, then releasing - them. The next special key (cursor keys, home etc.) you enter will - not invoke its usual function but instead will insert the - corresponding keycap symbol. The symbol will only be entered when - the key has been released, otherwise pressing e.g. "Shift" would - enter the symbol for "ISO Level 2 Switch", although your intention - might have been to enter a reverse tab (Shift-Tab). - - * 5.3: Screen-selection entry method - While this is implemented already (it's basically the selection - mechanism), it could be extended by displaying a unicode character - map. - - * 5.4: Feedback method for identifying displayed characters for later - input - This method lets you display the unicode character code associated - with characters already displayed. - - You enter this mode by holding down "Control" and "Shift" together, - then pressing and holding the left mouse button and moving around. - The unicode hex code(s) (it might be a combining character) of the - character under the pointer is displayed until you release "Control" - and "Shift". - - In addition to the hex codes it will display the font used to draw - this character - due to implementation reasons, characters combined - with combining characters, line drawing characters and unknown - characters will always be drawn using the built-in support font. - - With respect to conformance, rxvt-unicode is supposed to be compliant to - both scenario A and B of ISO 14755, including part 5.2. - -LOGIN STAMP - rxvt 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 on some systems or - setgid to root or to some other group on others. - -COLORS AND GRAPHICS - In addition to the default foreground and background colours, rxvt 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 names. - - color0 (black) = Black - color1 (red) = Red3 - color2 (green) = Green3 - color3 (yellow) = Yellow3 - color4 (blue) = Blue3 - color5 (magenta) = Magenta3 - color6 (cyan) = Cyan3 - color7 (white) = AntiqueWhite - color8 (bright black) = Grey25 - color9 (bright red) = Red - color10 (bright green) = Green - color11 (bright yellow) = Yellow - color12 (bright blue) = Blue - color13 (bright magenta) = Magenta - color14 (bright cyan) = Cyan - color15 (bright white) = White - foreground = Black - background = White - - It is also possible to specify the colour values of foreground, - background, cursorColor, cursorColor2, colorBD, colorUL as a number - 0-15, as a convenient shorthand to reference the colour name of - color0-color15. - - In addition to the colours defined above, rxvt offers an additional 72 - colours. The first 64 of those (with indices 16 to 79) consist of a - 4*4*4 RGB colour cube (i.e. *index = r * 16 + g * 4 + b + 16*), followed - by 8 additional shades of gray (with indices 80 to 87). - - Together, all those colours implement the 88 colour xterm colours. Only - the first 16 can be changed using resources currently, the rest can only - be changed via command sequences ("escape codes"). - - Note that -rv ("reverseVideo: True") simulates reverse video by always - swapping the foreground/background colours. This is in contrast to - *xterm*(1) where the colours are only swapped if they have not otherwise - been specified. For example, - - rxvt -fg Black -bg White -rv - would yield White on Black, while on *xterm*(1) it would yield Black - on White. - - ALPHA CHANNEL SUPPORT - If Xft support has been compiled in and as long as Xft/Xrender/X don't - get their act together, rxvt-unicode will support - "rgba:rrrr/gggg/bbbb/aaaa" (recommended, but MUST have 4 - digits/component) colour specifications, in addition to the ones - provided by X, where the additional A component specifies opacity - (alpha) values. The minimum value of 0 is completely transparent). You - can also prefix any color with "[percent]", where "percent" is a decimal - percentage (0-100) that specifies the opacity of the color, where 0 is - completely transparent and 100 is completelxy opaque. - - You probably need to specify "-depth 32", too, and have the luck that - your X-server uses ARGB pixel layout, as X is far from just supporting - ARGB visuals out of the box, and rxvt-unicode just fudges around. - - For example, the following selects an almost completely transparent red - background, and an almost opaque pink foreground: - - rxvt -depth 32 -bg rgba:0000/0000/0000/aaaa -fg "[80]pink" - - *Please note that transparency of any kind if completely unsupported by - the author. Don't bug him with installation questions!* - -ENVIRONMENT - rxvt sets and/or uses the following environment variables: - - TERM - Normally set to "rxvt-unicode", unless overwritten at configure - time, via resources or on the command line. - - COLORTERM - Either "rxvt", "rxvt-xpm", depending on whether rxvt was compiled - with background image support, and optionally with the added - extension "-mono" to indicate that rxvt-unicode runs on a monochrome - screen. - - COLORFGBG - Set to a string of the form "fg;bg" or "fg;xpm;bg", where "fg" is - the colour code used as default foreground/text colour (or the - string "default" to indicate that the default-colour escape sequence - is to be used), "bg" is the colour code used as default background - colour (or the string "default"), and "xpm" is the string "default" - if rxvt was compiled with background image support. Libraries like - "ncurses" and "slang" can (and do) use this information to optimize - screen output. - - WINDOWID - Set to the (decimal) X Window ID of the rxvt window (the toplevel - window, which usually has subwindows for the scrollbar, the terminal - window and so on). - - TERMINFO - Set to the terminfo directory iff rxvt was configured with - "--with-terminfo=PATH". - - DISPLAY - Used by rxvt to connect to the display and set to the correct - display in its child processes. - - SHELL - The shell to be used for command execution, defaults to "/bin/sh". - - RXVT_SOCKET - The unix domain socket path used by rxvtc(1) and rxvtd(1). - - Default $HOME/.rxvt-unicode-* - - - -AUTHORS - John Bovey - University of Kent, 1992, wrote the original Xvt. - - Rob Nation - very heavily modified Xvt and came up with Rxvt - - Angelo Haritsis - wrote the Greek Keyboard Input (no longer in code) - - mj olesen - Wrote the menu system. - - Project Coordinator (changes.txt 2.11 to 2.21) - - Oezguer Kesim - Project Coordinator (changes.txt 2.21a to 2.4.5) - - Geoff Wing - Rewrote screen display and text selection routines. - - Project Coordinator (changes.txt 2.4.6 - rxvt-unicode) - - Marc Alexander Lehmann - Forked rxvt-unicode, unicode support, rewrote almost all the code, - perl extension, random hacks, numerous bugfixes and extensions. - - Project Coordinator (Changes 1.0 -) - - Emanuele Giaquinta - Pty/tty/utmp/wtmp rewrite, lots of random hacking and bugfixing. - diff --git a/doc/rxvt.7.html b/doc/rxvt.7.html deleted file mode 100644 index e9108023..00000000 --- a/doc/rxvt.7.html +++ /dev/null @@ -1,2176 +0,0 @@ - - - - - RXVT REFERENCE - - - - - - - -
- -

Index

- -
- - -

NAME

Top

-
-

RXVT REFERENCE - FAQ, command sequences and other background information

- -
-

SYNOPSIS

Top

-
-
   # set a new font set
-   printf '\33]50;%s\007' 9x15,xft:Kochi" Mincho"
-
-   # change the locale and tell rxvt-unicode about it
-   export LC_CTYPE=ja_JP.EUC-JP; printf "\33]701;$LC_CTYPE\007"
-
-   # set window title
-   printf '\33]2;%s\007' "new window title"
-
-
- -
-

DESCRIPTION

Top

-
-

This document contains the FAQ, the RXVT TECHNICAL REFERENCE documenting -all escape sequences, and other background information.

-

The newest version of this document is also available on the World Wide Web at -http://cvs.schmorp.de/browse/rxvt-unicode/doc/rxvt.7.html.

- -
-

RXVT-UNICODE/URXVT FREQUENTLY ASKED QUESTIONS

Top

-
- - - - - -
-

Meta, Features & Commandline Issues

-
- -
-

My question isn't answered here, can I ask a human?

-
-

Before sending me mail, you could go to IRC: irc.freenode.net, -channel #rxvt-unicode has some rxvt-unicode enthusiasts that might be -interested in learning about new and exciting problems (but not FAQs :).

- -
-

Does it support tabs, can I have a tabbed rxvt-unicode?

-
-

Beginning with version 7.3, there is a perl extension that implements a -simple tabbed terminal. It is installed by default, so any of these should -give you tabs:

-
   urxvt -pe tabbed
-
-   URxvt.perl-ext-common: default,tabbed
-
-
-

It will also work fine with tabbing functionality of many window managers -or similar tabbing programs, and its embedding-features allow it to be -embedded into other programs, as witnessed by doc/rxvt-tabbed or -the upcoming Gtk2::URxvt perl module, which features a tabbed urxvt -(murxvt) terminal as an example embedding application.

- -
-

How do I know which rxvt-unicode version I'm using?

-
-

The version number is displayed with the usage (-h). Also the escape -sequence ESC [ 8 n sets the window title to the version number. When -using the urxvtc client, the version displayed is that of the -daemon.

- -
-

Rxvt-unicode uses gobs of memory, how can I reduce that?

-
-

Rxvt-unicode tries to obey the rule of not charging you for something you -don't use. One thing you should try is to configure out all settings that -you don't need, for example, Xft support is a resource hog by design, -when used. Compiling it out ensures that no Xft font will be loaded -accidentally when rxvt-unicode tries to find a font for your characters.

-

Also, many people (me included) like large windows and even larger -scrollback buffers: Without --enable-unicode3, rxvt-unicode will use -6 bytes per screen cell. For a 160x?? window this amounts to almost a -kilobyte per line. A scrollback buffer of 10000 lines will then (if full) -use 10 Megabytes of memory. With --enable-unicode3 it gets worse, as -rxvt-unicode then uses 8 bytes per screen cell.

- -
-

How can I start urxvtd in a race-free way?

-
-

Try urxvtd -f -o, which tells urxvtd to open the -display, create the listening socket and then fork.

- -
-

How can I start urxvtd automatically when I run urxvtc?

-
-

If you want to start urxvtd automatically whenever you run -urxvtc and the daemon isn't running yet, use this script:

-
   #!/bin/sh
-   urxvtc "$@"
-   if [ $? -eq 2 ]; then
-      urxvtd -q -o -f
-      urxvtc "$@"
-   fi
-
-
-

This tries to create a new terminal, and if fails with exit status 2, -meaning it couldn't connect to the daemon, it will start the daemon and -re-run the command. Subsequent invocations of the script will re-use the -existing daemon.

- -
-

How do I distinguish whether I'm running rxvt-unicode or a regular xterm? I need this to decide about setting colors etc.

-
-

The original rxvt and rxvt-unicode always export the variable "COLORTERM", -so you can check and see if that is set. Note that several programs, JED, -slrn, Midnight Commander automatically check this variable to decide -whether or not to use color.

- -
-

How do I set the correct, full IP address for the DISPLAY variable?

-
-

If you've compiled rxvt-unicode with DISPLAY_IS_IP and have enabled -insecure mode then it is possible to use the following shell script -snippets to correctly set the display. If your version of rxvt-unicode -wasn't also compiled with ESCZ_ANSWER (as assumed in these snippets) then -the COLORTERM variable can be used to distinguish rxvt-unicode from a -regular xterm.

-

Courtesy of Chuck Blake <cblake@BBN.COM> with the following shell script -snippets:

-
   # Bourne/Korn/POSIX family of shells:
-   [ ${TERM:-foo} = foo ] && TERM=xterm # assume an xterm if we don't know
-   if [ ${TERM:-foo} = xterm ]; then
-      stty -icanon -echo min 0 time 15 # see if enhanced rxvt or not
-      echo -n '^[Z'
-      read term_id
-      stty icanon echo
-      if [ ""${term_id} = '^[[?1;2C' -a ${DISPLAY:-foo} = foo ]; then
-         echo -n '^[[7n'        # query the rxvt we are in for the DISPLAY string
-         read DISPLAY           # set it in our local shell
-      fi
-   fi
-
-
- -
-

How do I compile the manual pages on my own?

-
-

You need to have a recent version of perl installed as /usr/bin/perl, -one that comes with pod2man, pod2text and pod2xhtml (from -Pod::Xhtml). Then go to the doc subdirectory and enter make alldoc.

- -
-

Isn't rxvt-unicode supposed to be small? Don't all those features bloat?

-
-

I often get asked about this, and I think, no, they didn't cause extra -bloat. If you compare a minimal rxvt and a minimal urxvt, you can see -that the urxvt binary is larger (due to some encoding tables always being -compiled in), but it actually uses less memory (RSS) after startup. Even -with --disable-everything, this comparison is a bit unfair, as many -features unique to urxvt (locale, encoding conversion, iso14755 etc.) are -already in use in this mode.

-
    text    data     bss     drs     rss filename
-   98398    1664      24   15695    1824 rxvt --disable-everything
-  188985    9048   66616   18222    1788 urxvt --disable-everything
-
-
-

When you --enable-everything (which is unfair, as this involves xft -and full locale/XIM support which are quite bloaty inside libX11 and my -libc), the two diverge, but not unreasonably so.

-
    text    data     bss     drs     rss filename
-  163431    2152      24   20123    2060 rxvt --enable-everything
- 1035683   49680   66648   29096    3680 urxvt --enable-everything
-
-
-

The very large size of the text section is explained by the east-asian -encoding tables, which, if unused, take up disk space but nothing else -and can be compiled out unless you rely on X11 core fonts that use those -encodings. The BSS size comes from the 64k emergency buffer that my c++ -compiler allocates (but of course doesn't use unless you are out of -memory). Also, using an xft font instead of a core font immediately adds a -few megabytes of RSS. Xft indeed is responsible for a lot of RSS even when -not used.

-

Of course, due to every character using two or four bytes instead of one, -a large scrollback buffer will ultimately make rxvt-unicode use more -memory.

-

Compared to e.g. Eterm (5112k), aterm (3132k) and xterm (4680k), this -still fares rather well. And compared to some monsters like gnome-terminal -(21152k + extra 4204k in separate processes) or konsole (22200k + extra -43180k in daemons that stay around after exit, plus half a minute of -startup time, including the hundreds of warnings it spits out), it fares -extremely well *g*.

- -
-

Why C++, isn't that unportable/bloated/uncool?

-
-

Is this a question? :) It comes up very often. The simple answer is: I had -to write it, and C++ allowed me to write and maintain it in a fraction -of the time and effort (which is a scarce resource for me). Put even -shorter: It simply wouldn't exist without C++.

-

My personal stance on this is that C++ is less portable than C, but in -the case of rxvt-unicode this hardly matters, as its portability limits -are defined by things like X11, pseudo terminals, locale support and unix -domain sockets, which are all less portable than C++ itself.

-

Regarding the bloat, see the above question: It's easy to write programs -in C that use gobs of memory, an certainly possible to write programs in -C++ that don't. C++ also often comes with large libraries, but this is -not necessarily the case with GCC. Here is what rxvt links against on my -system with a minimal config:

-
   libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x00002aaaaabc3000)
-   libc.so.6 => /lib/libc.so.6 (0x00002aaaaadde000)
-   libdl.so.2 => /lib/libdl.so.2 (0x00002aaaab01d000)
-   /lib64/ld-linux-x86-64.so.2 (0x00002aaaaaaab000)
-
-
-

And here is rxvt-unicode:

-
   libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x00002aaaaabc3000)
-   libgcc_s.so.1 => /lib/libgcc_s.so.1 (0x00002aaaaada2000)
-   libc.so.6 => /lib/libc.so.6 (0x00002aaaaaeb0000)
-   libdl.so.2 => /lib/libdl.so.2 (0x00002aaaab0ee000)
-   /lib64/ld-linux-x86-64.so.2 (0x00002aaaaaaab000)
-
-
-

No large bloated libraries (of course, none were linked in statically), -except maybe libX11 :)

- - - - - -
-

Rendering, Font & Look and Feel Issues

-
- -
-

I can't get transparency working, what am I doing wrong?

-
-

First of all, please address all transparency related issues to Sasha Vasko at -sasha@aftercode.net and do not bug the author about it. Also, if you can't -get it working consider it a rite of passage: ... and you failed.

-

Here are four ways to get transparency. Do read the manpage and option -descriptions for the programs mentioned and rxvt-unicode. Really, do it!

-

1. Use transparent mode:

-
   Esetroot wallpaper.jpg
-   urxvt -tr -tint red -sh 40
-
-
-

That works. If you think it doesn't, you lack transparency and tinting -support, or you are unable to read.

-

2. Use a simple pixmap and emulate pseudo-transparency. This enables you -to use effects other than tinting and shading: Just shade/tint/whatever -your picture with gimp or any other tool:

-
   convert wallpaper.jpg -blur 20x20 -modulate 30 background.jpg
-   urxvt -pixmap "background.jpg;:root"
-
-
-

That works. If you think it doesn't, you lack AfterImage support, or you -are unable to read.

-

3. Use an ARGB visual:

-
   urxvt -depth 32 -fg grey90 -bg rgba:0000/0000/4444/cccc
-
-
-

This requires XFT support, and the support of your X-server. If that -doesn't work for you, blame Xorg and Keith Packard. ARGB visuals aren't -there yet, no matter what they claim. Rxvt-Unicode contains the necessary -bugfixes and workarounds for Xft and Xlib to make it work, but that -doesn't mean that your WM has the required kludges in place.

-

4. Use xcompmgr and let it do the job:

-
  xprop -frame -f _NET_WM_WINDOW_OPACITY 32c \
-        -set _NET_WM_WINDOW_OPACITY 0xc0000000
-
-
-

Then click on a window you want to make transparent. Replace 0xc0000000 -by other values to change the degree of opacity. If it doesn't work and -your server crashes, you got to keep the pieces.

- -
-

Why does rxvt-unicode sometimes leave pixel droppings?

-
-

Most fonts were not designed for terminal use, which means that character -size varies a lot. A font that is otherwise fine for terminal use might -contain some characters that are simply too wide. Rxvt-unicode will avoid -these characters. For characters that are just "a bit" too wide a special -"careful" rendering mode is used that redraws adjacent characters.

-

All of this requires that fonts do not lie about character sizes, -however: Xft fonts often draw glyphs larger than their acclaimed bounding -box, and rxvt-unicode has no way of detecting this (the correct way is to -ask for the character bounding box, which unfortunately is wrong in these -cases).

-

It's not clear (to me at least), whether this is a bug in Xft, freetype, -or the respective font. If you encounter this problem you might try using -the -lsp option to give the font more height. If that doesn't work, you -might be forced to use a different font.

-

All of this is not a problem when using X11 core fonts, as their bounding -box data is correct.

- -
-

How can I keep rxvt-unicode from using reverse video so much?

-
-

First of all, make sure you are running with the right terminal settings -(TERM=rxvt-unicode), which will get rid of most of these effects. Then -make sure you have specified colours for italic and bold, as otherwise -rxvt-unicode might use reverse video to simulate the effect:

-
   URxvt.colorBD:  white
-   URxvt.colorIT:  green
-
-
- -
-

Some programs assume totally weird colours (red instead of blue), how can I fix that?

-
-

For some unexplainable reason, some rare programs assume a very weird -colour palette when confronted with a terminal with more than the standard -8 colours (rxvt-unicode supports 88). The right fix is, of course, to fix -these programs not to assume non-ISO colours without very good reasons.

-

In the meantime, you can either edit your rxvt-unicode terminfo -definition to only claim 8 colour support or use TERM=rxvt, which will -fix colours but keep you from using other rxvt-unicode features.

- -
-

Can I switch the fonts at runtime?

-
-

Yes, using an escape sequence. Try something like this, which has the same -effect as using the -fn switch, and takes effect immediately:

-
   printf '\33]50;%s\007' "9x15bold,xft:Kochi Gothic"
-
-
-

This is useful if you e.g. work primarily with japanese (and prefer a -japanese font), but you have to switch to chinese temporarily, where -japanese fonts would only be in your way.

-

You can think of this as a kind of manual ISO-2022 switching.

- -
-

Why do italic characters look as if clipped?

-
-

Many fonts have difficulties with italic characters and hinting. For -example, the otherwise very nicely hinted font xft:Bitstream Vera Sans -Mono completely fails in its italic face. A workaround might be to -enable freetype autohinting, i.e. like this:

-
   URxvt.italicFont:        xft:Bitstream Vera Sans Mono:italic:autohint=true
-   URxvt.boldItalicFont:    xft:Bitstream Vera Sans Mono:bold:italic:autohint=true
-
-
- -
-

Can I speed up Xft rendering somehow?

-
-

Yes, the most obvious way to speed it up is to avoid Xft entirely, as -it is simply slow. If you still want Xft fonts you might try to disable -antialiasing (by appending :antialias=false), which saves lots of -memory and also speeds up rendering considerably.

- -
-

Rxvt-unicode doesn't seem to anti-alias its fonts, what is wrong?

-
-

Rxvt-unicode will use whatever you specify as a font. If it needs to -fall back to its default font search list it will prefer X11 core -fonts, because they are small and fast, and then use Xft fonts. It has -antialiasing disabled for most of them, because the author thinks they -look best that way.

-

If you want antialiasing, you have to specify the fonts manually.

- -
- - -

I don't like the screen colors. How do I change them?

-
-

You can change the screen colors at run-time using ~/.Xdefaults -resources (or as long-options).

-

Here are values that are supposed to resemble a VGA screen, -including the murky brown that passes for low-intensity yellow:

-
   URxvt.color0:   #000000
-   URxvt.color1:   #A80000
-   URxvt.color2:   #00A800
-   URxvt.color3:   #A8A800
-   URxvt.color4:   #0000A8
-   URxvt.color5:   #A800A8
-   URxvt.color6:   #00A8A8
-   URxvt.color7:   #A8A8A8
-
-   URxvt.color8:   #000054
-   URxvt.color9:   #FF0054
-   URxvt.color10:  #00FF54
-   URxvt.color11:  #FFFF54
-   URxvt.color12:  #0000FF
-   URxvt.color13:  #FF00FF
-   URxvt.color14:  #00FFFF
-   URxvt.color15:  #FFFFFF
-
-
-

And here is a more complete set of non-standard colors.

-
   URxvt.cursorColor:  #dc74d1
-   URxvt.pointerColor: #dc74d1
-   URxvt.background:   #0e0e0e
-   URxvt.foreground:   #4ad5e1
-   URxvt.color0:       #000000
-   URxvt.color8:       #8b8f93
-   URxvt.color1:       #dc74d1
-   URxvt.color9:       #dc74d1
-   URxvt.color2:       #0eb8c7
-   URxvt.color10:      #0eb8c7
-   URxvt.color3:       #dfe37e
-   URxvt.color11:      #dfe37e
-   URxvt.color5:       #9e88f0
-   URxvt.color13:      #9e88f0
-   URxvt.color6:       #73f7ff
-   URxvt.color14:      #73f7ff
-   URxvt.color7:       #e1dddd
-   URxvt.color15:      #e1dddd
-
-
-

They have been described (not by me) as "pretty girly".

- -
-

Why do some characters look so much different than others?

-
-

See next entry.

- -
-

How does rxvt-unicode choose fonts?

-
-

Most fonts do not contain the full range of Unicode, which is -fine. Chances are that the font you (or the admin/package maintainer of -your system/os) have specified does not cover all the characters you want -to display.

-

rxvt-unicode makes a best-effort try at finding a replacement -font. Often the result is fine, but sometimes the chosen font looks -bad/ugly/wrong. Some fonts have totally strange characters that don't -resemble the correct glyph at all, and rxvt-unicode lacks the artificial -intelligence to detect that a specific glyph is wrong: it has to believe -the font that the characters it claims to contain indeed look correct.

-

In that case, select a font of your taste and add it to the font list, -e.g.:

-
   urxvt -fn basefont,font2,font3...
-
-
-

When rxvt-unicode sees a character, it will first look at the base -font. If the base font does not contain the character, it will go to the -next font, and so on. Specifying your own fonts will also speed up this -search and use less resources within rxvt-unicode and the X-server.

-

The only limitation is that none of the fonts may be larger than the base -font, as the base font defines the terminal character cell size, which -must be the same due to the way terminals work.

- -
-

Why do some chinese characters look so different than others?

-
-

This is because there is a difference between script and language -- -rxvt-unicode does not know which language the text that is output is, -as it only knows the unicode character codes. If rxvt-unicode first -sees a japanese/chinese character, it might choose a japanese font for -display. Subsequent japanese characters will use that font. Now, many -chinese characters aren't represented in japanese fonts, so when the first -non-japanese character comes up, rxvt-unicode will look for a chinese font --- unfortunately at this point, it will still use the japanese font for -chinese characters that are also in the japanese font.

-

The workaround is easy: just tag a chinese font at the end of your font -list (see the previous question). The key is to view the font list as -a preference list: If you expect more japanese, list a japanese font -first. If you expect more chinese, put a chinese font first.

-

In the future it might be possible to switch language preferences at -runtime (the internal data structure has no problem with using different -fonts for the same character at the same time, but no interface for this -has been designed yet).

-

Until then, you might get away with switching fonts at runtime (see Can I switch the fonts at runtime? later in this document).

- -
-

How can I make mplayer display video correctly?

-
-

We are working on it, in the meantime, as a workaround, use something like:

-
   urxvt -b 600 -geometry 20x1 -e sh -c 'mplayer -wid $WINDOWID file...'
-
-
-
-
-
- -
-

Keyboard, Mouse & User Interaction

-
- -
-

The new selection selects pieces that are too big, how can I select single words?

-
-

If you want to select e.g. alphanumeric words, you can use the following -setting:

-
   URxvt.selection.pattern-0: ([[:word:]]+)
-
-
-

If you click more than twice, the selection will be extended -more and more.

-

To get a selection that is very similar to the old code, try this pattern:

-
   URxvt.selection.pattern-0: ([^"&'()*,;<=>?@[\\\\]^`{|})]+)
-
-
-

Please also note that the LeftClick Shift-LeftClik combination also -selects words like the old code.

- -
-

I don't like the new selection/popups/hotkeys/perl, how do I change/disable it?

-
-

You can disable the perl extension completely by setting the -perl-ext-common resource to the empty string, which also keeps -rxvt-unicode from initialising perl, saving memory.

-

If you only want to disable specific features, you first have to -identify which perl extension is responsible. For this, read the section -PREPACKAGED EXTENSIONS in the urxvtperl(3) manpage. For -example, to disable the selection-popup and option-popup, specify -this perl-ext-common resource:

-
   URxvt.perl-ext-common: default,-selection-popup,-option-popup
-
-
-

This will keep the default extensions, but disable the two popup -extensions. Some extensions can also be configured, for example, -scrollback search mode is triggered by M-s. You can move it to any -other combination either by setting the searchable-scrollback resource:

-
   URxvt.searchable-scrollback: CM-s
-
-
- -
-

The cursor moves when selecting text in the current input line, how do I switch this off?

-
-

See next entry.

- -
-

During rlogin/ssh/telnet/etc. sessions, clicking near the cursor outputs strange escape sequences, how do I fix this?

-
-

These are caused by the readline perl extension. Under normal -circumstances, it will move your cursor around when you click into the -line that contains it. It tries hard not to do this at the wrong moment, -but when running a program that doesn't parse cursor movements or in some -cases during rlogin sessions, it fails to detect this properly.

-

You can permanently switch this feature off by disabling the readline -extension:

-
   URxvt.perl-ext-common: default,-readline
-
-
- -
-

My numerical keypad acts weird and generates differing output?

-
-

Some Debian GNUL/Linux users seem to have this problem, although no -specific details were reported so far. It is possible that this is caused -by the wrong TERM setting, although the details of whether and how -this can happen are unknown, as TERM=rxvt should offer a compatible -keymap. See the answer to the previous question, and please report if that -helped.

- -
-

My Compose (Multi_key) key is no longer working.

-
-

The most common causes for this are that either your locale is not set -correctly, or you specified a preeditStyle that is not supported by -your input method. For example, if you specified OverTheSpot and -your input method (e.g. the default input method handling Compose keys) -does not support this (for instance because it is not visual), then -rxvt-unicode will continue without an input method.

-

In this case either do not specify a preeditStyle or specify more than -one pre-edit style, such as OverTheSpot,Root,None.

- -
-

I cannot type Ctrl-Shift-2 to get an ASCII NUL character due to ISO 14755

-
-

Either try Ctrl-2 alone (it often is mapped to ASCII NUL even on -international keyboards) or simply use ISO 14755 support to your -advantage, typing <Ctrl-Shift-0> to get a ASCII NUL. This works for other -codes, too, such as Ctrl-Shift-1-d to type the default telnet escape -character and so on.

- -
-

Mouse cut/paste suddenly no longer works.

-
-

Make sure that mouse reporting is actually turned off since killing -some editors prematurely may leave the mouse in mouse report mode. I've -heard that tcsh may use mouse reporting unless it otherwise specified. A -quick check is to see if cut/paste works when the Alt or Shift keys are -depressed.

- -
-

What's with the strange Backspace/Delete key behaviour?

-
-

Assuming that the physical Backspace key corresponds to the -Backspace keysym (not likely for Linux ... see the following -question) there are two standard values that can be used for -Backspace: ^H and ^?.

-

Historically, either value is correct, but rxvt-unicode adopts the debian -policy of using ^? when unsure, because it's the one and only correct -choice :).

-

Rxvt-unicode tries to inherit the current stty settings and uses the value -of `erase' to guess the value for backspace. If rxvt-unicode wasn't -started from a terminal (say, from a menu or by remote shell), then the -system value of `erase', which corresponds to CERASE in <termios.h>, will -be used (which may not be the same as your stty setting).

-

For starting a new rxvt-unicode:

-
   # use Backspace = ^H
-   $ stty erase ^H
-   $ urxvt
-
-   # use Backspace = ^?
-   $ stty erase ^?
-   $ urxvt
-
-
-

Toggle with ESC [ 36 h / ESC [ 36 l.

-

For an existing rxvt-unicode:

-
   # use Backspace = ^H
-   $ stty erase ^H
-   $ echo -n "^[[36h"
-
-   # use Backspace = ^?
-   $ stty erase ^?
-   $ echo -n "^[[36l"
-
-
-

This helps satisfy some of the Backspace discrepancies that occur, but -if you use Backspace = ^H, make sure that the termcap/terminfo value -properly reflects that.

-

The Delete key is a another casualty of the ill-defined Backspace problem. -To avoid confusion between the Backspace and Delete keys, the Delete -key has been assigned an escape sequence to match the vt100 for Execute -(ESC [ 3 ~) and is in the supplied termcap/terminfo.

-

Some other Backspace problems:

-

some editors use termcap/terminfo, -some editors (vim I'm told) expect Backspace = ^H, -GNU Emacs (and Emacs-like editors) use ^H for help.

-

Perhaps someday this will all be resolved in a consistent manner.

- -
-

I don't like the key-bindings. How do I change them?

-
-

There are some compile-time selections available via configure. Unless -you have run "configure" with the --disable-resources option you can -use the `keysym' resource to alter the keystrings associated with keysyms.

-

Here's an example for a URxvt session started using urxvt -name URxvt

-
   URxvt.keysym.Home:          \033[1~
-   URxvt.keysym.End:           \033[4~
-   URxvt.keysym.C-apostrophe:  \033<C-'>
-   URxvt.keysym.C-slash:       \033<C-/>
-   URxvt.keysym.C-semicolon:   \033<C-;>
-   URxvt.keysym.C-grave:       \033<C-`>
-   URxvt.keysym.C-comma:       \033<C-,>
-   URxvt.keysym.C-period:      \033<C-.>
-   URxvt.keysym.C-0x60:        \033<C-`>
-   URxvt.keysym.C-Tab:         \033<C-Tab>
-   URxvt.keysym.C-Return:      \033<C-Return>
-   URxvt.keysym.S-Return:      \033<S-Return>
-   URxvt.keysym.S-space:       \033<S-Space>
-   URxvt.keysym.M-Up:          \033<M-Up>
-   URxvt.keysym.M-Down:        \033<M-Down>
-   URxvt.keysym.M-Left:        \033<M-Left>
-   URxvt.keysym.M-Right:       \033<M-Right>
-   URxvt.keysym.M-C-0:         list \033<M-C- 0123456789 >
-   URxvt.keysym.M-C-a:         list \033<M-C- abcdefghijklmnopqrstuvwxyz >
-   URxvt.keysym.F12:           command:\033]701;zh_CN.GBK\007
-
-
-

See some more examples in the documentation for the keysym resource.

- -
-

I'm using keyboard model XXX that has extra Prior/Next/Insert keys. How do I make use of them? For example, the Sun Keyboard type 4 has the following map

-
-
   KP_Insert == Insert
-   F22 == Print
-   F27 == Home
-   F29 == Prior
-   F33 == End
-   F35 == Next
-
-
-

Rather than have rxvt-unicode try to accommodate all the various possible -keyboard mappings, it is better to use `xmodmap' to remap the keys as -required for your particular machine.

- - - - - -
-

Terminal Configuration

-
- -
-

Can I see a typical configuration?

-
-

The default configuration tries to be xterm-like, which I don't like that -much, but it's least surprise to regular users.

-

As a rxvt or rxvt-unicode user, you are practically supposed to invest -time into customising your terminal. To get you started, here is the -author's .Xdefaults entries, with comments on what they do. It's certainly -not typical, but what's typical...

-
   URxvt.cutchars: "()*,<>[]{}|'
-   URxvt.print-pipe: cat >/tmp/xxx
-
-
-

These are just for testing stuff.

-
   URxvt.imLocale: ja_JP.UTF-8
-   URxvt.preeditType: OnTheSpot,None
-
-
-

This tells rxvt-unicode to use a special locale when communicating with -the X Input Method, and also tells it to only use the OnTheSpot pre-edit -type, which requires the xim-onthespot perl extension but rewards me -with correct-looking fonts.

-
   URxvt.perl-lib: /root/lib/urxvt
-   URxvt.perl-ext-common: default,selection-autotransform,selection-pastebin,xim-onthespot,remote-clipboard
-   URxvt.selection.pattern-0: ( at .*? line \\d+)
-   URxvt.selection.pattern-1: ^(/[^:]+):\ 
-   URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
-   URxvt.selection-autotransform.1: s/^ at (.*?) line (\\d+)$/:e \\Q$1\\E\\x0d:$2\\x0d/
-
-
-

This is my perl configuration. The first two set the perl library -directory and also tells urxvt to use a large number of extensions. I -develop for myself mostly, so I actually use most of the extensions I -write.

-

The selection stuff mainly makes the selection perl-error-message aware -and tells it to convert perl error messages into vi-commands to load the -relevant file and go tot he error line number.

-
   URxvt.scrollstyle:      plain
-   URxvt.secondaryScroll:  true
-
-
-

As the documentation says: plain is the preferred scrollbar for the -author. The secondaryScroll configures urxvt to scroll in full-screen -apps, like screen, so lines scrolled out of screen end up in urxvt's -scrollback buffer.

-
   URxvt.background:       #000000
-   URxvt.foreground:       gray90
-   URxvt.color7:           gray90
-   URxvt.colorBD:          #ffffff
-   URxvt.cursorColor:      #e0e080
-   URxvt.throughColor:     #8080f0
-   URxvt.highlightColor:   #f0f0f0
-
-
-

Some colours. Not sure which ones are being used or even non-defaults, but -these are in my .Xdefaults. Most notably, they set foreground/background -to light gray/black, and also make sure that the colour 7 matches the -default foreground colour.

-
   URxvt.underlineColor:   yellow
-
-
-

Another colour, makes underline lines look different. Sometimes hurts, but -is mostly a nice effect.

-
   URxvt.geometry:         154x36
-   URxvt.loginShell:       false
-   URxvt.meta:             ignore
-   URxvt.utmpInhibit:      true
-
-
-

Uh, well, should be mostly self-explanatory. By specifying some defaults -manually, I can quickly switch them for testing.

-
   URxvt.saveLines:        8192
-
-
-

A large scrollback buffer is essential. Really.

-
   URxvt.mapAlert:         true
-
-
-

The only case I use it is for my IRC window, which I like to keep -iconified till people msg me (which beeps).

-
   URxvt.visualBell:       true
-
-
-

The audible bell is often annoying, especially when in a crowd.

-
   URxvt.insecure:         true
-
-
-

Please don't hack my mutt! Ooops...

-
   URxvt.pastableTabs:     false
-
-
-

I once thought this is a great idea.

-
   urxvt.font:             9x15bold,\
-                           -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso10646-1,\
-                           -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1, \
-                           [codeset=JISX0208]xft:Kochi Gothic, \
-                           xft:Bitstream Vera Sans Mono:autohint=true, \
-                           xft:Code2000:antialias=false
-   urxvt.boldFont:         -xos4-terminus-bold-r-normal--14-140-72-72-c-80-iso8859-15
-   urxvt.italicFont:       xft:Bitstream Vera Sans Mono:italic:autohint=true
-   urxvt.boldItalicFont:   xft:Bitstream Vera Sans Mono:bold:italic:autohint=true
-
-
-

I wrote rxvt-unicode to be able to specify fonts exactly. So don't be -overwhelmed. A special note: the 9x15bold mentioned above is actually -the version from XFree-3.3, as XFree-4 replaced it by a totally different -font (different glyphs for ; and many other harmless characters), -while the second font is actually the 9x15bold from XFree4/XOrg. The -bold version has less chars than the medium version, so I use it for rare -characters, too. When editing sources with vim, I use italic for comments -and other stuff, which looks quite good with Bitstream Vera anti-aliased.

-

Terminus is a quite bad font (many very wrong glyphs), but for most of my -purposes, it works, and gives a different look, as my normal (Non-bold) -font is already bold, and I want to see a difference between bold and -normal fonts.

-

Please note that I used the urxvt instance name and not the URxvt -class name. Thats because I use different configs for different purposes, -for example, my IRC window is started with -name IRC, and uses these -defaults:

-
   IRC*title:              IRC
-   IRC*geometry:           87x12+535+542
-   IRC*saveLines:          0
-   IRC*mapAlert:           true
-   IRC*font:               suxuseuro
-   IRC*boldFont:           suxuseuro
-   IRC*colorBD:            white
-   IRC*keysym.M-C-1:       command:\033]710;suxuseuro\007\033]711;suxuseuro\007
-   IRC*keysym.M-C-2:       command:\033]710;9x15bold\007\033]711;9x15bold\007
-
-
-

Alt-Shift-1 and Alt-Shift-2 switch between two different font -sizes. suxuseuro allows me to keep an eye (and actually read) -stuff while keeping a very small window. If somebody pastes something -complicated (e.g. japanese), I temporarily switch to a larger font.

-

The above is all in my .Xdefaults (I don't use .Xresources nor -xrdb). I also have some resources in a separate .Xdefaults-hostname -file for different hosts, for example, on ym main desktop, I use:

-
   URxvt.keysym.C-M-q: command:\033[3;5;5t
-   URxvt.keysym.C-M-y: command:\033[3;5;606t
-   URxvt.keysym.C-M-e: command:\033[3;1605;5t
-   URxvt.keysym.C-M-c: command:\033[3;1605;606t
-   URxvt.keysym.C-M-p: perl:test
-
-
-

The first for keysym definitions allow me to quickly bring some windows -in the layout I like most. Ion users might start laughing but will stop -immediately when I tell them that I use my own Fvwm2 module for much the -same effect as Ion provides, and I only very rarely use the above key -combinations :->

- -
-

Why doesn't rxvt-unicode read my resources?

-
-

Well, why, indeed? It does, in a way very similar to other X -applications. Most importantly, this means that if you or your OS loads -resources into the X display (the right way to do it), rxvt-unicode will -ignore any resource files in your home directory. It will only read -$HOME/.Xdefaults when no resources are attached to the display.

-

If you have or use an $HOME/.Xresources file, chances are that -resources are loaded into your X-server. In this case, you have to -re-login after every change (or run xrdb -merge $HOME/.Xresources).

-

Also consider the form resources have to use:

-
  URxvt.resource: value
-
-
-

If you want to use another form (there are lots of different ways of -specifying resources), make sure you understand whether and why it -works. If unsure, use the form above.

- -
-

When I log-in to another system it tells me about missing terminfo data?

-
-

The terminal description used by rxvt-unicode is not as widely available -as that for xterm, or even rxvt (for which the same problem often arises).

-

The correct solution for this problem is to install the terminfo, this can -be done like this (with ncurses' infocmp and works as user and admin):

-
   REMOTE=remotesystem.domain
-   infocmp rxvt-unicode | ssh $REMOTE "mkdir -p .terminfo && cat >/tmp/ti && tic /tmp/ti"
-
-
-

... or by installing rxvt-unicode normally on the remote system,

-

One some systems you might need to set $TERMINFO to the full path of -$HOME/.terminfo for this to work.

-

If you cannot or do not want to do this, then you can simply set -TERM=rxvt or even TERM=xterm, and live with the small number of -problems arising, which includes wrong keymapping, less and different -colours and some refresh errors in fullscreen applications. It's a nice -quick-and-dirty workaround for rare cases, though.

-

If you always want to do this (and are fine with the consequences) you -can either recompile rxvt-unicode with the desired TERM value or use a -resource to set it:

-
   URxvt.termName: rxvt
-
-
-

If you don't plan to use rxvt (quite common...) you could also replace -the rxvt terminfo file with the rxvt-unicode one and use TERM=rxvt.

- -
-

tic outputs some error when compiling the terminfo entry.

-
-

Most likely it's the empty definition for enacs=. Just replace it by -enacs=\E[0@ and try again.

- -
-

bash's readline does not work correctly under urxvt.

-
-

See next entry.

- -
-

I need a termcap file entry.

-
-

One reason you might want this is that some distributions or operating -systems still compile some programs using the long-obsoleted termcap -library (Fedora Core's bash is one example) and rely on a termcap entry -for rxvt-unicode.

-

You could use rxvt's termcap entry with reasonable results in many cases. -You can also create a termcap entry by using terminfo's infocmp program -like this:

-
   infocmp -C rxvt-unicode
-
-
-

Or you could use this termcap entry, generated by the command above:

-
   rxvt-unicode|rxvt-unicode terminal (X Window System):\
-           :am:bw:eo:km:mi:ms:xn:xo:\
-           :co#80:it#8:li#24:lm#0:\
-           :AL=\E[%dL:DC=\E[%dP:DL=\E[%dM:DO=\E[%dB:IC=\E[%d@:\
-           :K1=\EOw:K2=\EOu:K3=\EOy:K4=\EOq:K5=\EOs:LE=\E[%dD:\
-           :RI=\E[%dC:SF=\E[%dS:SR=\E[%dT:UP=\E[%dA:ae=\E(B:al=\E[L:\
-           :as=\E(0:bl=^G:cd=\E[J:ce=\E[K:cl=\E[H\E[2J:\
-           :cm=\E[%i%d;%dH:cr=^M:cs=\E[%i%d;%dr:ct=\E[3g:dc=\E[P:\
-           :dl=\E[M:do=^J:ec=\E[%dX:ei=\E[4l:ho=\E[H:\
-           :i1=\E[?47l\E=\E[?1l:ic=\E[@:im=\E[4h:\
-           :is=\E[r\E[m\E[2J\E[H\E[?7h\E[?1;3;4;6l\E[4l:\
-           :k1=\E[11~:k2=\E[12~:k3=\E[13~:k4=\E[14~:k5=\E[15~:\
-           :k6=\E[17~:k7=\E[18~:k8=\E[19~:k9=\E[20~:kD=\E[3~:\
-           :kI=\E[2~:kN=\E[6~:kP=\E[5~:kb=\177:kd=\EOB:ke=\E[?1l\E>:\
-           :kh=\E[7~:kl=\EOD:kr=\EOC:ks=\E[?1h\E=:ku=\EOA:le=^H:\
-           :mb=\E[5m:md=\E[1m:me=\E[m\017:mr=\E[7m:nd=\E[C:rc=\E8:\
-           :sc=\E7:se=\E[27m:sf=^J:so=\E[7m:sr=\EM:st=\EH:ta=^I:\
-           :te=\E[r\E[?1049l:ti=\E[?1049h:ue=\E[24m:up=\E[A:\
-           :us=\E[4m:vb=\E[?5h\E[?5l:ve=\E[?25h:vi=\E[?25l:\
-           :vs=\E[?25h:
-
-
- -
-

Why does ls no longer have coloured output?

-
-

The ls in the GNU coreutils unfortunately doesn't use terminfo to -decide whether a terminal has colour, but uses its own configuration -file. Needless to say, rxvt-unicode is not in its default file (among -with most other terminals supporting colour). Either add:

-
   TERM rxvt-unicode
-
-
-

to /etc/DIR_COLORS or simply add:

-
   alias ls='ls --color=auto'
-
-
-

to your .profile or .bashrc.

- -
-

Why doesn't vim/emacs etc. use the 88 colour mode?

-
-

See next entry.

- -
-

Why doesn't vim/emacs etc. make use of italic?

-
-

See next entry.

- -
- - -

Encoding / Locale / Input Method Issues

-
- -
-

Rxvt-unicode does not seem to understand the selected encoding?

-
-

See next entry.

- -
-

Unicode does not seem to work?

-
-

If you encounter strange problems like typing an accented character but -getting two unrelated other characters or similar, or if program output is -subtly garbled, then you should check your locale settings.

-

Rxvt-unicode must be started with the same LC_CTYPE setting as the -programs running in it. Often rxvt-unicode is started in the C locale, -while the login script running within the rxvt-unicode window changes the -locale to something else, e.g. en_GB.UTF-8. Needless to say, this is -not going to work, and is the most common cause for problems.

-

The best thing is to fix your startup environment, as you will likely run -into other problems. If nothing works you can try this in your .profile.

-
  printf '\33]701;%s\007' "$LC_CTYPE"   # $LANG or $LC_ALL are worth a try, too
-
-
-

If this doesn't work, then maybe you use a LC_CTYPE specification not -supported on your systems. Some systems have a locale command which -displays this (also, perl -e0 can be used to check locale settings, as -it will complain loudly if it cannot set the locale). If it displays something -like:

-
  locale: Cannot set LC_CTYPE to default locale: ...
-
-
-

Then the locale you specified is not supported on your system.

-

If nothing works and you are sure that everything is set correctly then -you will need to remember a little known fact: Some programs just don't -support locales :(

- -
-

How does rxvt-unicode determine the encoding to use?

-
-

See next entry.

- -
-

Is there an option to switch encodings?

-
-

Unlike some other terminals, rxvt-unicode has no encoding switch, and no -specific "utf-8" mode, such as xterm. In fact, it doesn't even know about -UTF-8 or any other encodings with respect to terminal I/O.

-

The reasons is that there exists a perfectly fine mechanism for selecting -the encoding, doing I/O and (most important) communicating this to all -applications so everybody agrees on character properties such as width -and code number. This mechanism is the locale. Applications not using -that info will have problems (for example, xterm gets the width of -characters wrong as it uses its own, locale-independent table under all -locales).

-

Rxvt-unicode uses the LC_CTYPE locale category to select encoding. All -programs doing the same (that is, most) will automatically agree in the -interpretation of characters.

-

Unfortunately, there is no system-independent way to select locales, nor -is there a standard on how locale specifiers will look like.

-

On most systems, the content of the LC_CTYPE environment variable -contains an arbitrary string which corresponds to an already-installed -locale. Common names for locales are en_US.UTF-8, de_DE.ISO-8859-15, -ja_JP.EUC-JP, i.e. language_country.encoding, but other forms -(i.e. de or german) are also common.

-

Rxvt-unicode ignores all other locale categories, and except for -the encoding, ignores country or language-specific settings, -i.e. de_DE.UTF-8 and ja_JP.UTF-8 are the normally same to -rxvt-unicode.

-

If you want to use a specific encoding you have to make sure you start -rxvt-unicode with the correct LC_CTYPE category.

- -
-

Can I switch locales at runtime?

-
-

Yes, using an escape sequence. Try something like this, which sets -rxvt-unicode's idea of LC_CTYPE.

-
  printf '\33]701;%s\007' ja_JP.SJIS
-
-
-

See also the previous answer.

-

Sometimes this capability is rather handy when you want to work in -one locale (e.g. de_DE.UTF-8) but some programs don't support it -(e.g. UTF-8). For example, I use this script to start xjdic, which -first switches to a locale supported by xjdic and back later:

-
   printf '\33]701;%s\007' ja_JP.SJIS
-   xjdic -js
-   printf '\33]701;%s\007' de_DE.UTF-8
-
-
-

You can also use xterm's luit program, which usually works fine, except -for some locales where character width differs between program- and -rxvt-unicode-locales.

- -
-

I have problems getting my input method working.

-
-

Try a search engine, as this is slightly different for every input method server.

-

Here is a checklist:

-
-
- Make sure your locale and the imLocale are supported on your OS.
-
-

Try locale -a or check the documentation for your OS.

-
-
- Make sure your locale or imLocale matches a locale supported by your XIM.
-
-

For example, kinput2 does not support UTF-8 locales, you should use -ja_JP.EUC-JP or equivalent.

-
-
- Make sure your XIM server is actually running.
-
- Make sure the XMODIFIERS environment variable is set correctly when starting rxvt-unicode.
-
-

When you want to use e.g. kinput2, it must be set to -@im=kinput2. For scim, use @im=SCIM. You can see what input -method servers are running with this command:

-
   xprop -root XIM_SERVERS
-
-
-
-
-
- -
-

My input method wants <some encoding> but I want UTF-8, what can I do?

-
-

You can specify separate locales for the input method and the rest of the -terminal, using the resource imlocale:

-
   URxvt.imlocale: ja_JP.EUC-JP
-
-
-

Now you can start your terminal with LC_CTYPE=ja_JP.UTF-8 and still -use your input method. Please note, however, that, depending on your Xlib -version, you may not be able to input characters outside EUC-JP in a -normal way then, as your input method limits you.

- -
-

Rxvt-unicode crashes when the X Input Method changes or exits.

-
-

Unfortunately, this is unavoidable, as the XIM protocol is racy by -design. Applications can avoid some crashes at the expense of memory -leaks, and Input Methods can avoid some crashes by careful ordering at -exit time. kinput2 (and derived input methods) generally succeeds, -while SCIM (or similar input methods) fails. In the end, however, -crashes cannot be completely avoided even if both sides cooperate.

-

So the only workaround is not to kill your Input Method Servers.

- - - - - -
-

Operating Systems / Package Maintaining

-
- -
-

I am using Debian GNU/Linux and have a problem...

-
-

The Debian GNU/Linux package of rxvt-unicode in sarge contains large -patches that considerably change the behaviour of rxvt-unicode (but -unfortunately this notice has been removed). Before reporting a bug to -the original rxvt-unicode author please download and install the genuine -version (http://software.schmorp.de#rxvt-unicode) and try to reproduce -the problem. If you cannot, chances are that the problems are specific to -Debian GNU/Linux, in which case it should be reported via the Debian Bug -Tracking System (use reportbug to report the bug).

-

For other problems that also affect the Debian package, you can and -probably should use the Debian BTS, too, because, after all, it's also a -bug in the Debian version and it serves as a reminder for other users that -might encounter the same issue.

- -
-

I am maintaining rxvt-unicode for distribution/OS XXX, any recommendation?

-
-

You should build one binary with the default options. configure -now enables most useful options, and the trend goes to making them -runtime-switchable, too, so there is usually no drawback to enabling them, -except higher disk and possibly memory usage. The perl interpreter should -be enabled, as important functionality (menus, selection, likely more in -the future) depends on it.

-

You should not overwrite the perl-ext-common snd perl-ext resources -system-wide (except maybe with defaults). This will result in useful -behaviour. If your distribution aims at low memory, add an empty -perl-ext-common resource to the app-defaults file. This will keep the -perl interpreter disabled until the user enables it.

-

If you can/want build more binaries, I recommend building a minimal -one with --disable-everything (very useful) and a maximal one with ---enable-everything (less useful, it will be very big due to a lot of -encodings built-in that increase download times and are rarely used).

- -
-

I need to make it setuid/setgid to support utmp/ptys on my OS, is this safe?

-
-

It should be, starting with release 7.1. You are encouraged to properly -install urxvt with privileges necessary for your OS now.

-

When rxvt-unicode detects that it runs setuid or setgid, it will fork -into a helper process for privileged operations (pty handling on some -systems, utmp/wtmp/lastlog handling on others) and drop privileges -immediately. This is much safer than most other terminals that keep -privileges while running (but is more relevant to urxvt, as it contains -things as perl interpreters, which might be "helpful" to attackers).

-

This forking is done as the very first within main(), which is very early -and reduces possible bugs to initialisation code run before main(), or -things like the dynamic loader of your system, which should result in very -little risk.

- -
-

I am on FreeBSD and rxvt-unicode does not seem to work at all.

-
-

Rxvt-unicode requires the symbol __STDC_ISO_10646__ to be defined -in your compile environment, or an implementation that implements it, -whether it defines the symbol or not. __STDC_ISO_10646__ requires that -wchar_t is represented as unicode.

-

As you might have guessed, FreeBSD does neither define this symbol nor -does it support it. Instead, it uses its own internal representation of -wchar_t. This is, of course, completely fine with respect to standards.

-

However, that means rxvt-unicode only works in POSIX, ISO-8859-1 and -UTF-8 locales under FreeBSD (which all use Unicode as wchar_t.

-

__STDC_ISO_10646__ is the only sane way to support multi-language -apps in an OS, as using a locale-dependent (and non-standardized) -representation of wchar_t makes it impossible to convert between -wchar_t (as used by X11 and your applications) and any other encoding -without implementing OS-specific-wrappers for each and every locale. There -simply are no APIs to convert wchar_t into anything except the current -locale encoding.

-

Some applications (such as the formidable mlterm) work around this -by carrying their own replacement functions for character set handling -with them, and either implementing OS-dependent hacks or doing multiple -conversions (which is slow and unreliable in case the OS implements -encodings slightly different than the terminal emulator).

-

The rxvt-unicode author insists that the right way to fix this is in the -system libraries once and for all, instead of forcing every app to carry -complete replacements for them :)

- -
-

How can I use rxvt-unicode under cygwin?

-
-

rxvt-unicode should compile and run out of the box on cygwin, using -the X11 libraries that come with cygwin. libW11 emulation is no -longer supported (and makes no sense, either, as it only supported a -single font). I recommend starting the X-server in -multiwindow or --rootless mode instead, which will result in similar look&feel as the -old libW11 emulation.

-

At the time of this writing, cygwin didn't seem to support any multi-byte -encodings (you might try LC_CTYPE=C-UTF-8), so you are likely limited -to 8-bit encodings.

- -
-

Character widths are not correct.

-
-

urxvt uses the system wcwidth function to know the information about -the width of characters, so on systems with incorrect locale data you -will likely get bad results. Two notorious examples are Solaris 9, -where single-width characters like U+2514 are reported as double-width, -and Darwin 8, where combining chars are reported having width 1.

-

The solution is to upgrade your system or switch to a better one. A -possibly working workaround is to use a wcwidth implementation like

-

http://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c

- -
-

RXVT-UNICODE TECHNICAL REFERENCE

Top

-
-

The rest of this document describes various technical aspects of -rxvt-unicode. First the description of supported command sequences, -followed by pixmap support and last by a description of all features -selectable at configure time.

- -
-

Definitions

-
-
-
c
-
-

The literal character c.

-
-
C
-
-

A single (required) character.

-
-
Ps
-
-

A single (usually optional) numeric parameter, composed of one or more -digits.

-
-
Pm
-
-

A multiple numeric parameter composed of any number of single numeric -parameters, separated by ; character(s).

-
-
Pt
-
-

A text parameter composed of printable characters.

-
-
- -
-

Values

-
-
-
ENQ
-
-

Enquiry (Ctrl-E) = Send Device Attributes (DA) -request attributes from terminal. See ESC [ Ps c.

-
-
BEL
-
-

Bell (Ctrl-G)

-
-
BS
-
-

Backspace (Ctrl-H)

-
-
TAB
-
-

Horizontal Tab (HT) (Ctrl-I)

-
-
LF
-
-

Line Feed or New Line (NL) (Ctrl-J)

-
-
VT
-
-

Vertical Tab (Ctrl-K) same as LF

-
-
FF
-
-

Form Feed or New Page (NP) (Ctrl-L) same as LF

-
-
CR
-
-

Carriage Return (Ctrl-M)

-
-
SO
-
-

Shift Out (Ctrl-N), invokes the G1 character set. -Switch to Alternate Character Set

-
-
SI
-
-

Shift In (Ctrl-O), invokes the G0 character set (the default). -Switch to Standard Character Set

-
-
SPC
-
-

Space Character

-
-
- -
-

Escape Sequences

-
-
-
ESC # 8
-
-

DEC Screen Alignment Test (DECALN)

-
-
ESC 7
-
-

Save Cursor (SC)

-
-
ESC 8
-
-

Restore Cursor

-
-
ESC =
-
-

Application Keypad (SMKX). See also next sequence.

-
-
ESC
-
-

Normal Keypad (RMKX)

-

Note: If the numeric keypad is activated, eg, Num_Lock has been -pressed, numbers or control functions are generated by the numeric keypad -(see Key Codes).

-
-
ESC D
-
-

Index (IND)

-
-
ESC E
-
-

Next Line (NEL)

-
-
ESC H
-
-

Tab Set (HTS)

-
-
ESC M
-
-

Reverse Index (RI)

-
-
ESC N
-
-

Single Shift Select of G2 Character Set (SS2): affects next character -only unimplemented

-
-
ESC O
-
-

Single Shift Select of G3 Character Set (SS3): affects next character -only unimplemented

-
-
ESC Z
-
-

Obsolete form of returns: ESC [ ? 1 ; 2 C rxvt-unicode compile-time option

-
-
ESC c
-
-

Full reset (RIS)

-
-
ESC n
-
-

Invoke the G2 Character Set (LS2)

-
-
ESC o
-
-

Invoke the G3 Character Set (LS3)

-
-
ESC ( C
-
-

Designate G0 Character Set (ISO 2022), see below for values of C.

-
-
ESC ) C
-
-

Designate G1 Character Set (ISO 2022), see below for values of C.

-
-
ESC * C
-
-

Designate G2 Character Set (ISO 2022), see below for values of C.

-
-
ESC + C
-
-

Designate G3 Character Set (ISO 2022), see below for values of C.

-
-
ESC $ C
-
-

Designate Kanji Character Set

-

Where C is one of:

-
C = 0 DEC Special Character and Line Drawing Set
C = A United Kingdom (UK)
C = B United States (USASCII)
C = <Multinational character set unimplemented
C = 5 Finnish character set unimplemented
C = C Finnish character set unimplemented
C = K German character set unimplemented
-
-

CSI

- -
-

CSI (Command Sequence Introducer) Sequences

-
-
-
ESC [ Ps @
-
-

Insert Ps (Blank) Character(s) [default: 1] (ICH)ESCOBPsA

-
-
ESC [ Ps A
-
-

Cursor Up Ps Times [default: 1] (CUU)

-
-
ESC [ Ps B
-
-

Cursor Down Ps Times [default: 1] (CUD)ESCOBPsC

-
-
ESC [ Ps C
-
-

Cursor Forward Ps Times [default: 1] (CUF)

-
-
ESC [ Ps D
-
-

Cursor Backward Ps Times [default: 1] (CUB)

-
-
ESC [ Ps E
-
-

Cursor Down Ps Times [default: 1] and to first column

-
-
ESC [ Ps F
-
-

Cursor Up Ps Times [default: 1] and to first columnESCOBPsG

-
-
ESC [ Ps G
-
-

Cursor to Column Ps (HPA)

-
-
ESC [ Ps;Ps H
-
-

Cursor Position [row;column] [default: 1;1] (CUP)

-
-
ESC [ Ps I
-
-

Move forward Ps tab stops [default: 1]

-
-
ESC [ Ps J
-
-

Erase in Display (ED)

-
Ps = 0Clear Below (default)
Ps = 1Clear Above
Ps = 2Clear All
-
ESC [ Ps K
-
-

Erase in Line (EL)

-
Ps = 0Clear to Right (default)
Ps = 1Clear to Left
Ps = 2Clear All
-
ESC [ Ps L
-
-

Insert Ps Line(s) [default: 1] (IL)

-
-
ESC [ Ps M
-
-

Delete Ps Line(s) [default: 1] (DL)

-
-
ESC [ Ps P
-
-

Delete Ps Character(s) [default: 1] (DCH)

-
-
ESC [ Ps;Ps;Ps;Ps;Ps T
-
-

Initiate . unimplemented Parameters are -[func;startx;starty;firstrow;lastrow].

-
-
ESC [ Ps W
-
-

Tabulator functions

-
Ps = 0Tab Set (HTS)
Ps = 2Tab Clear (TBC), Clear Current Column (default)
Ps = 5Tab Clear (TBC), Clear All
-
ESC [ Ps X
-
-

Erase Ps Character(s) [default: 1] (ECH)

-
-
ESC [ Ps Z
-
-

Move backward Ps [default: 1] tab stops

-
-
ESC [ Ps '
-
-

See ESC [ Ps G

-
-
ESC [ Ps a
-
-

See ESC [ Ps C

-
-
ESC [ Ps c
-
-

Send Device Attributes (DA) -Ps = 0 (or omitted): request attributes from terminal -returns: ESC [ ? 1 ; 2 c (``I am a VT100 with Advanced Video -Option'')

-
-
ESC [ Ps d
-
-

Cursor to Line Ps (VPA)

-
-
ESC [ Ps e
-
-

See ESC [ Ps A

-
-
ESC [ Ps;Ps f
-
-

Horizontal and Vertical Position [row;column] (HVP) [default: 1;1]

-
-
ESC [ Ps g
-
-

Tab Clear (TBC)

-
Ps = 0Clear Current Column (default)
Ps = 3Clear All (TBC)
-
ESC [ Pm h
-
-

Set Mode (SM). See ESC [ Pm l sequence for description of Pm.

-
-
ESC [ Ps i
-
-

Printing. See also the print-pipe resource.

-
Ps = 0print screen (MC0)
Ps = 4disable transparent print mode (MC4)
Ps = 5enable transparent print mode (MC5)
-
ESC [ Pm l
-
-

Reset Mode (RM)

-

-

-
Ps = 4
-
hInsert Mode (SMIR)
lReplace Mode (RMIR)
Ps = 20 (partially implemented)
-
hAutomatic Newline (LNM)
lNormal Linefeed (LNM)
-

-
-
ESC [ Pm m
-
-

Character Attributes (SGR)

-
Ps = 0Normal (default)
Ps = 1 / 21On / Off Bold (bright fg)
Ps = 3 / 23On / Off Italic
Ps = 4 / 24On / Off Underline
Ps = 5 / 25On / Off Slow Blink (bright bg)
Ps = 6 / 26On / Off Rapid Blink (bright bg)
Ps = 7 / 27On / Off Inverse
Ps = 8 / 27On / Off Invisible (NYI)
Ps = 30 / 40fg/bg Black
Ps = 31 / 41fg/bg Red
Ps = 32 / 42fg/bg Green
Ps = 33 / 43fg/bg Yellow
Ps = 34 / 44fg/bg Blue
Ps = 35 / 45fg/bg Magenta
Ps = 36 / 46fg/bg Cyan
Ps = 38;5 / 48;5set fg/bg to color #m (ISO 8613-6)
Ps = 37 / 47fg/bg White
Ps = 39 / 49fg/bg Default
Ps = 90 / 100fg/bg Bright Black
Ps = 91 / 101fg/bg Bright Red
Ps = 92 / 102fg/bg Bright Green
Ps = 93 / 103fg/bg Bright Yellow
Ps = 94 / 104fg/bg Bright Blue
Ps = 95 / 105fg/bg Bright Magenta
Ps = 96 / 106fg/bg Bright Cyan
Ps = 97 / 107fg/bg Bright White
Ps = 99 / 109fg/bg Bright Default
-
ESC [ Ps n
-
-

Device Status Report (DSR)

-
Ps = 5Status Report ESC [ 0 n (``OK'')
Ps = 6Report Cursor Position (CPR) [row;column] as ESC [ r ; c R
Ps = 7Request Display Name
Ps = 8Request Version Number (place in window title)
-
ESC [ Ps;Ps r
-
-

Set Scrolling Region [top;bottom] -[default: full size of window] (CSR)

-
-
ESC [ s
-
-

Save Cursor (SC)

-
-
ESC [ Ps;Pt t
-
-

Window Operations

-
Ps = 1Deiconify (map) window
Ps = 2Iconify window
Ps = 3ESC [ 3 ; X ; Y t Move window to (X|Y)
Ps = 4ESC [ 4 ; H ; W t Resize to WxH pixels
Ps = 5Raise window
Ps = 6Lower window
Ps = 7Refresh screen once
Ps = 8ESC [ 8 ; R ; C t Resize to R rows and C columns
Ps = 11Report window state (responds with Ps = 1 or Ps = 2)
Ps = 13Report window position (responds with Ps = 3)
Ps = 14Report window pixel size (responds with Ps = 4)
Ps = 18Report window text size (responds with Ps = 7)
Ps = 19Currently the same as Ps = 18, but responds with Ps = 9
Ps = 20Reports icon label (ESC ] L NAME \234)
Ps = 21Reports window title (ESC ] l NAME \234)
Ps = 24..Set window height to Ps rows
-
ESC [ u
-
-

Restore Cursor

-
-
ESC [ Ps x
-
-

Request Terminal Parameters (DECREQTPARM)

-
-
-

PrivateModes

- -
-

DEC Private Modes

-
-
-
ESC [ ? Pm h
-
-

DEC Private Mode Set (DECSET)

-
-
ESC [ ? Pm l
-
-

DEC Private Mode Reset (DECRST)

-
-
ESC [ ? Pm r
-
-

Restore previously saved DEC Private Mode Values.

-
-
ESC [ ? Pm s
-
-

Save DEC Private Mode Values.

-
-
ESC [ ? Pm t
-
-

Toggle DEC Private Mode Values (rxvt extension). where

-

-

-
Pm = 1 (DECCKM)
-
hApplication Cursor Keys
lNormal Cursor Keys
Pm = 2 (ANSI/VT52 mode)
-
hEnter VT52 mode
lEnter VT52 mode
Pm = 3
-
h132 Column Mode (DECCOLM)
l80 Column Mode (DECCOLM)
Pm = 4
-
hSmooth (Slow) Scroll (DECSCLM)
lJump (Fast) Scroll (DECSCLM)
Pm = 5
-
hReverse Video (DECSCNM)
lNormal Video (DECSCNM)
Pm = 6
-
hOrigin Mode (DECOM)
lNormal Cursor Mode (DECOM)
Pm = 7
-
hWraparound Mode (DECAWM)
lNo Wraparound Mode (DECAWM)
Pm = 8 unimplemented
-
hAuto-repeat Keys (DECARM)
lNo Auto-repeat Keys (DECARM)
Pm = 9 X10 XTerm
-
hSend Mouse X & Y on button press.
lNo mouse reporting.
Pm = 25
-
hVisible cursor {cnorm/cvvis}
lInvisible cursor {civis}
Pm = 30
-
hscrollBar visisble
lscrollBar invisisble
Pm = 35 (rxvt)
-
hAllow XTerm Shift+key sequences
lDisallow XTerm Shift+key sequences
Pm = 38 unimplemented
-
-

Enter Tektronix Mode (DECTEK)

-
-
Pm = 40
-
hAllow 80/132 Mode
lDisallow 80/132 Mode
Pm = 44 unimplemented
-
hTurn On Margin Bell
lTurn Off Margin Bell
Pm = 45 unimplemented
-
hReverse-wraparound Mode
lNo Reverse-wraparound Mode
Pm = 46 unimplemented
-
Pm = 47
-
hUse Alternate Screen Buffer
lUse Normal Screen Buffer
-

Priv66

-
-
Pm = 66
-
hApplication Keypad (DECPAM) == ESC =
lNormal Keypad (DECPNM) == ESC >
Pm = 67
-
hBackspace key sends BS (DECBKM)
lBackspace key sends DEL
Pm = 1000 (X11 XTerm)
-
hSend Mouse X & Y on button press and release.
lNo mouse reporting.
Pm = 1001 (X11 XTerm) unimplemented
-
hUse Hilite Mouse Tracking.
lNo mouse reporting.
Pm = 1002 (X11 XTerm)
-
hSend Mouse X & Y on button press and release, and motion with a button pressed.
lNo mouse reporting.
Pm = 1003 (X11 XTerm)
-
hSend Mouse X & Y on button press and release, and motion.
lNo mouse reporting.
Pm = 1010 (rxvt)
-
hDon't scroll to bottom on TTY output
lScroll to bottom on TTY output
Pm = 1011 (rxvt)
-
hScroll to bottom when a key is pressed
lDon't scroll to bottom when a key is pressed
Pm = 1021 (rxvt)
-
hBold/italic implies high intensity (see option -is)
lFont styles have no effect on intensity (Compile styles)
Pm = 1047
-
hUse Alternate Screen Buffer
lUse Normal Screen Buffer - clear Alternate Screen Buffer if returning from it
Pm = 1048
-
hSave cursor position
lRestore cursor position
Pm = 1049
-
hUse Alternate Screen Buffer - clear Alternate Screen Buffer if switching to it
lUse Normal Screen Buffer
-

-
-
-

XTerm

- -
-

XTerm Operating System Commands

-
-
-
ESC ] Ps;Pt ST
-
-

Set XTerm Parameters. 8-bit ST: 0x9c, 7-bit ST sequence: ESC \ (0x1b, -0x5c), backwards compatible terminator BEL (0x07) is also accepted. any -octet can be escaped by prefixing it with SYN (0x16, ^V).

-
Ps = 0Change Icon Name and Window Title to Pt
Ps = 1Change Icon Name to Pt
Ps = 2Change Window Title to Pt
Ps = 3If Pt starts with a ?, query the (STRING) property of the window and return it. If Pt contains a =, set the named property to the given value, else delete the specified property.
Ps = 4Pt is a semi-colon separated sequence of one or more semi-colon separated number/name pairs, where number is an index to a colour and name is the name of a colour. Each pair causes the numbered colour to be changed to name. Numbers 0-7 corresponds to low-intensity (normal) colours and 8-15 corresponds to high-intensity colours. 0=black, 1=red, 2=green, 3=yellow, 4=blue, 5=magenta, 6=cyan, 7=white
Ps = 10Change colour of text foreground to Pt (NB: may change in future)
Ps = 11Change colour of text background to Pt (NB: may change in future)
Ps = 12Change colour of text cursor foreground to Pt
Ps = 13Change colour of mouse foreground to Pt
Ps = 17Change colour of highlight characters to Pt
Ps = 18Change colour of bold characters to Pt [deprecated, see 706]
Ps = 19Change colour of underlined characters to Pt [deprecated, see 707]
Ps = 20Change background pixmap parameters (see section BACKGROUND IMAGE) (Compile AfterImage).
Ps = 39Change default foreground colour to Pt.
Ps = 46Change Log File to Pt unimplemented
Ps = 49Change default background colour to Pt.
Ps = 50Set fontset to Pt, with the following special values of Pt (rxvt) #+n change up n #-n change down n if n is missing of 0, a value of 1 is used empty change to font0 n change to font n
Ps = 55Log all scrollback buffer and all of screen to Pt
Ps = 701Change current locale to Pt, or, if Pt is ?, return the current locale (Compile frills).
Ps = 702Request version if Pt is ?, returning rxvt-unicode, the resource name, the major and minor version numbers, e.g. ESC ] 702 ; rxvt-unicode ; urxvt ; 7 ; 4 ST.
Ps = 704Change colour of italic characters to Pt
Ps = 705Change background pixmap tint colour to Pt (Compile transparency).
Ps = 706Change colour of bold characters to Pt
Ps = 707Change colour of underlined characters to Pt
Ps = 710Set normal fontset to Pt. Same as Ps = 50.
Ps = 711Set bold fontset to Pt. Similar to Ps = 50 (Compile styles).
Ps = 712Set italic fontset to Pt. Similar to Ps = 50 (Compile styles).
Ps = 713Set bold-italic fontset to Pt. Similar to Ps = 50 (Compile styles).
Ps = 720Move viewing window up by Pt lines, or clear scrollback buffer if Pt = 0 (Compile frills).
Ps = 721Move viewing window down by Pt lines, or clear scrollback buffer if Pt = 0 (Compile frills).
Ps = 777Call the perl extension with the given string, which should be of the form extension:parameters (Compile perl).
-
- -
-

BACKGROUND IMAGE

Top

-
-

For the BACGROUND IMAGE XTerm escape sequence ESC ] 20 ; Pt ST then value -of Pt can be the name of the background image file followed by a -sequence of scaling/positioning commands separated by semi-colons. The -scaling/positioning commands are as follows:

-
-
query scale/position
-
-

?

-
-
change scale and position
-
-

WxH+X+Y

-

WxH+X (== WxH+X+X)

-

WxH (same as WxH+50+50)

-

W+X+Y (same as WxW+X+Y)

-

W+X (same as WxW+X+X)

-

W (same as WxW+50+50)

-
-
change position (absolute)
-
-

=+X+Y

-

=+X (same as =+X+Y)

-
-
change position (relative)
-
-

+X+Y

-

+X (same as +X+Y)

-
-
rescale (relative)
-
-

Wx0 -> W *= (W/100)

-

0xH -> H *= (H/100)

-
-
-

For example:

-
-
\E]20;funky.jpg\a
-
-

load funky.jpg as a tiled image

-
-
\E]20;mona.jpg;100\a
-
-

load mona.jpg with a scaling of 100%

-
-
\E]20;;200;?\a
-
-

rescale the current pixmap to 200% and display the image geometry in -the title

-
-
- -
-

Mouse Reporting

Top

-
-
-
ESC [ M <b> <x> <y>
-
-

report mouse position

-
-
-

The lower 2 bits of <b> indicate the button:

-
-
Button = (<b> - SPACE) & 3
-
0Button1 pressed
1Button2 pressed
2Button3 pressed
3button released (X11 mouse report)
-

The upper bits of <b> indicate the modifiers when the -button was pressed and are added together (X11 mouse report only):

-
-
State = (<b> - SPACE) & 60
-
4Shift
8Meta
16Control
32Double Click (rxvt extension)
-

Col = <x> - SPACE

-

Row = <y> - SPACE

-
-
- -
-

Key Codes

Top

-
-

Note: Shift + F1-F10 generates F11-F20

-

For the keypad, use Shift to temporarily override Application-Keypad -setting use Num_Lock to toggle Application-Keypad setting if -Num_Lock is off, toggle Application-Keypad setting. Also note that -values of Home, End, Delete may have been compiled differently on -your system.

-
NormalShiftControlCtrl+Shift
Tab^IESC [ Z^IESC [ Z
BackSpace^H^?^?^?
FindESC [ 1 ~ESC [ 1 $ESC [ 1 ^ESC [ 1 @
InsertESC [ 2 ~pasteESC [ 2 ^ESC [ 2 @
ExecuteESC [ 3 ~ESC [ 3 $ESC [ 3 ^ESC [ 3 @
SelectESC [ 4 ~ESC [ 4 $ESC [ 4 ^ESC [ 4 @
PriorESC [ 5 ~scroll-upESC [ 5 ^ESC [ 5 @
NextESC [ 6 ~scroll-downESC [ 6 ^ESC [ 6 @
HomeESC [ 7 ~ESC [ 7 $ESC [ 7 ^ESC [ 7 @
EndESC [ 8 ~ESC [ 8 $ESC [ 8 ^ESC [ 8 @
DeleteESC [ 3 ~ESC [ 3 $ESC [ 3 ^ESC [ 3 @
F1ESC [ 11 ~ESC [ 23 ~ESC [ 11 ^ESC [ 23 ^
F2ESC [ 12 ~ESC [ 24 ~ESC [ 12 ^ESC [ 24 ^
F3ESC [ 13 ~ESC [ 25 ~ESC [ 13 ^ESC [ 25 ^
F4ESC [ 14 ~ESC [ 26 ~ESC [ 14 ^ESC [ 26 ^
F5ESC [ 15 ~ESC [ 28 ~ESC [ 15 ^ESC [ 28 ^
F6ESC [ 17 ~ESC [ 29 ~ESC [ 17 ^ESC [ 29 ^
F7ESC [ 18 ~ESC [ 31 ~ESC [ 18 ^ESC [ 31 ^
F8ESC [ 19 ~ESC [ 32 ~ESC [ 19 ^ESC [ 32 ^
F9ESC [ 20 ~ESC [ 33 ~ESC [ 20 ^ESC [ 33 ^
F10ESC [ 21 ~ESC [ 34 ~ESC [ 21 ^ESC [ 34 ^
F11ESC [ 23 ~ESC [ 23 $ESC [ 23 ^ESC [ 23 @
F12ESC [ 24 ~ESC [ 24 $ESC [ 24 ^ESC [ 24 @
F13ESC [ 25 ~ESC [ 25 $ESC [ 25 ^ESC [ 25 @
F14ESC [ 26 ~ESC [ 26 $ESC [ 26 ^ESC [ 26 @
F15 (Help)ESC [ 28 ~ESC [ 28 $ESC [ 28 ^ESC [ 28 @
F16 (Menu)ESC [ 29 ~ESC [ 29 $ESC [ 29 ^ESC [ 29 @
F17ESC [ 31 ~ESC [ 31 $ESC [ 31 ^ESC [ 31 @
F18ESC [ 32 ~ESC [ 32 $ESC [ 32 ^ESC [ 32 @
F19ESC [ 33 ~ESC [ 33 $ESC [ 33 ^ESC [ 33 @
F20ESC [ 34 ~ESC [ 34 $ESC [ 34 ^ESC [ 34 @
Application
UpESC [ AESC [ aESC O aESC O A
DownESC [ BESC [ bESC O bESC O B
RightESC [ CESC [ cESC O cESC O C
LeftESC [ DESC [ dESC O dESC O D
KP_Enter^MESC O M
KP_F1ESC O PESC O P
KP_F2ESC O QESC O Q
KP_F3ESC O RESC O R
KP_F4ESC O SESC O S
XK_KP_Multiply*ESC O j
XK_KP_Add+ESC O k
XK_KP_Separator,ESC O l
XK_KP_Subtract-ESC O m
XK_KP_Decimal.ESC O n
XK_KP_Divide/ESC O o
XK_KP_00ESC O p
XK_KP_11ESC O q
XK_KP_22ESC O r
XK_KP_33ESC O s
XK_KP_44ESC O t
XK_KP_55ESC O u
XK_KP_66ESC O v
XK_KP_77ESC O w
XK_KP_88ESC O x
XK_KP_99ESC O y
-
-

CONFIGURE OPTIONS

Top

-
-

General hint: if you get compile errors, then likely your configuration -hasn't been tested well. Either try with --enable-everything or use -the default configuration (i.e. no --enable-xxx or --disable-xxx -switches). Of course, you should always report when a combination doesn't -work, so it can be fixed. Marc Lehmann <rxvt@schmorp.de>.

-

All

-
-
--enable-everything
-
-

Add (or remove) support for all non-multichoice options listed in "./configure ---help".

-

You can specify this and then disable options you do not like by -following this with the appropriate --disable-... arguments, -or you can start with a minimal configuration by specifying ---disable-everything and than adding just the --enable-... arguments -you want.

-
-
--enable-xft (default: enabled)
-
-

Add support for Xft (anti-aliases, among others) fonts. Xft fonts are -slower and require lots of memory, but as long as you don't use them, you -don't pay for them.

-
-
--enable-font-styles (default: on)
-
-

Add support for bold, italic and bold italic font -styles. The fonts can be set manually or automatically.

-
-
--with-codesets=NAME,... (default: all)
-
-

Compile in support for additional codeset (encoding) groups (eu, vn -are always compiled in, which includes most 8-bit character sets). These -codeset tables are used for driving X11 core fonts, they are not required -for Xft fonts, although having them compiled in lets rxvt-unicode choose -replacement fonts more intelligently. Compiling them in will make your -binary bigger (all of together cost about 700kB), but it doesn't increase -memory usage unless you use a font requiring one of these encodings.

-
allall available codeset groups
zhcommon chinese encodings
zh_extrarely used but very big chinese encodings
jpcommon japanese encodings
jp_extrarely used but big japanese encodings
krkorean encodings
-
--enable-xim (default: on)
-
-

Add support for XIM (X Input Method) protocol. This allows using -alternative input methods (e.g. kinput2) and will also correctly -set up the input for people using dead keys or compose keys.

-
-
--enable-unicode3 (default: off)
-
-

Recommended to stay off unless you really need non-BMP characters.

-

Enable direct support for displaying unicode codepoints above -65535 (the basic multilingual page). This increases storage -requirements per character from 2 to 4 bytes. X11 fonts do not yet -support these extra characters, but Xft does.

-

Please note that rxvt-unicode can store unicode code points >65535 -even without this flag, but the number of such characters is -limited to a few thousand (shared with combining characters, -see next switch), and right now rxvt-unicode cannot display them -(input/output and cut&paste still work, though).

-
-
--enable-combining (default: on)
-
-

Enable automatic composition of combining characters into -composite characters. This is required for proper viewing of text -where accents are encoded as seperate unicode characters. This is -done by using precomposited characters when available or creating -new pseudo-characters when no precomposed form exists.

-

Without --enable-unicode3, the number of additional precomposed -characters is somewhat limited (the 6400 private use characters will be -(ab-)used). With --enable-unicode3, no practical limit exists.

-

This option will also enable storage (but not display) of characters -beyond plane 0 (>65535) when --enable-unicode3 was not specified.

-

The combining table also contains entries for arabic presentation forms, -but these are not currently used. Bug me if you want these to be used (and -tell me how these are to be used...).

-
-
--enable-fallback(=CLASS) (default: Rxvt)
-
-

When reading resource settings, also read settings for class CLASS. To -disable resource fallback use --disable-fallback.

-
-
--with-res-name=NAME (default: urxvt)
-
-

Use the given name as default application name when -reading resources. Specify --with-res-name=rxvt to replace rxvt.

-
-
--with-res-class=CLASS /default: URxvt)
-
-

Use the given class as default application class -when reading resources. Specify --with-res-class=Rxvt to replace -rxvt.

-
-
--enable-utmp (default: on)
-
-

Write user and tty to utmp file (used by programs like w) at -start of rxvt execution and delete information when rxvt exits.

-
-
--enable-wtmp (default: on)
-
-

Write user and tty to wtmp file (used by programs like last) at -start of rxvt execution and write logout when rxvt exits. This -option requires --enable-utmp to also be specified.

-
-
--enable-lastlog (default: on)
-
-

Write user and tty to lastlog file (used by programs like -lastlogin) at start of rxvt execution. This option requires ---enable-utmp to also be specified.

-
-
--enable-afterimage (default: on)
-
-

Add support for libAfterImage to be used for transparency and background -images. It adds support for many file formats including JPG, PNG, -SVG, TIFF, GIF, XPM, BMP, ICO, XCF, TGA and AfterStep image XML -(http://www.afterstep.org/visualdoc.php?show=asimagexml).

-

This option also adds such eye candy as blending an image over the root -background, as well as dynamic scaling and bluring of background images.

-

Note that with this option enabled, rxvt's memory footprint might -increase by a few megabytes even if no extra features are used (mostly due -to third-party libraries used by libAI). Memory footprint may somewhat be -lowered if libAfterImage is configured without support for SVG.

-
-
--enable-transparency (default: on)
-
-

Add support for backgrounds, creating illusion of transparency in the term.

-
-
--enable-fading (default: on)
-
-

Add support for fading the text when focus is lost.

-
-
--enable-rxvt-scroll (default: on)
-
-

Add support for the original rxvt scrollbar.

-
-
--enable-next-scroll (default: on)
-
-

Add support for a NeXT-like scrollbar.

-
-
--enable-xterm-scroll (default: on)
-
-

Add support for an Xterm-like scrollbar.

-
-
--enable-plain-scroll (default: on)
-
-

Add support for a very unobtrusive, plain-looking scrollbar that -is the favourite of the rxvt-unicode author, having used it for -many years.

-
-
--enable-ttygid (default: off)
-
-

Change tty device setting to group "tty" - only use this if -your system uses this type of security.

-
-
--disable-backspace-key
-
-

Removes any handling of the backspace key by us - let the X server do it.

-
-
--disable-delete-key
-
-

Removes any handling of the delete key by us - let the X server -do it.

-
-
--disable-resources
-
-

Removes any support for resource checking.

-
-
--disable-swapscreen
-
-

Remove support for secondary/swap screen.

-
-
--enable-frills (default: on)
-
-

Add support for many small features that are not essential but nice to -have. Normally you want this, but for very small binaries you may want to -disable this.

-

A non-exhaustive list of features enabled by --enable-frills (possibly -in combination with other switches) is:

-
  MWM-hints
-  EWMH-hints (pid, utf8 names) and protocols (ping)
-  urgency hint
-  seperate underline colour (-underlineColor)
-  settable border widths and borderless switch (-w, -b, -bl)
-  visual depth selection (-depth)
-  settable extra linespacing /-lsp)
-  iso-14755 5.1 (basic) support
-  tripleclickwords (-tcw)
-  settable insecure mode (-insecure)
-  keysym remapping support
-  cursor blinking and underline cursor (-cb, -uc)
-  XEmbed support (-embed)
-  user-pty (-pty-fd)
-  hold on exit (-hold)
-  compile in built-in block graphics
-  skip builtin block graphics (-sbg)
-  separate highlightcolor support (-hc)
-
-
-

It also enables some non-essential features otherwise disabled, such as:

-
  some round-trip time optimisations
-  nearest color allocation on pseudocolor screens
-  UTF8_STRING support for selection
-  sgr modes 90..97 and 100..107
-  backindex and forwardindex escape sequences
-  view change/zero scrollback escape sequences
-  locale switching escape sequence
-  window op and some xterm/OSC escape sequences
-  rectangular selections
-  trailing space removal for selections
-  verbose X error handling
-
-
-
-
--enable-iso14755 (default: on)
-
-

Enable extended ISO 14755 support (see rxvt(1), or -doc/rxvt.1.txt). Basic support (section 5.1) is enabled by ---enable-frills, while support for 5.2, 5.3 and 5.4 is enabled with -this switch.

-
-
--enable-keepscrolling (default: on)
-
-

Add support for continual scrolling of the display when you hold -the mouse button down on a scrollbar arrow.

-
-
--enable-selectionscrolling (default: on)
-
-

Add support for scrolling when the selection moves to the top or -bottom of the screen.

-
-
--enable-mousewheel (default: on)
-
-

Add support for scrolling via mouse wheel or buttons 4 & 5.

-
-
--enable-slipwheeling (default: on)
-
-

Add support for continual scrolling (using the mouse wheel as an -accelerator) while the control key is held down. This option -requires --enable-mousewheel to also be specified.

-
-
--enable-smart-resize (default: off)
-
-

Add smart growth/shrink behaviour when resizing. -This should keep the window corner which is closest to a corner of -the screen in a fixed position.

-
-
--enable-pointer-blank (default: on)
-
-

Add support to have the pointer disappear when typing or inactive.

-
-
--enable-perl (default: on)
-
-

Enable an embedded perl interpreter. See the rxvtperl(3) -manpage (doc/rxvtperl.txt) for more info on this feature, or the -files in src/perl-ext/ for the extensions that are installed by -default. The perl interpreter that is used can be specified via the -PERL environment variable when running configure. Even when compiled -in, perl will not be initialised when all extensions have been disabled --pe "" --perl-ext-common "", so it should be safe to enable from a -resource standpoint.

-
-
--with-afterimage-config=DIR
-
-

Look for the libAfterImage config script in DIR.

-
-
--with-name=NAME (default: urxvt)
-
-

Set the basename for the installed binaries, resulting -in urxvt, urxvtd etc.). Specify --with-name=rxvt to replace with -rxvt.

-
-
--with-term=NAME (default: rxvt-unicode)
-
-

Change the environmental variable for the terminal to NAME.

-
-
--with-terminfo=PATH
-
-

Change the environmental variable for the path to the terminfo tree to -PATH.

-
-
--with-x
-
-

Use the X Window System (pretty much default, eh?).

-
-
- -
-

AUTHORS

Top

-
-

Marc Lehmann <rxvt@schmorp.de> converted this document to pod and -reworked it from the original Rxvt documentation, which was done by Geoff -Wing <gcw@pobox.com>, who in turn used the XTerm documentation and other -sources.

- -
-
- diff --git a/doc/rxvt.7.txt b/doc/rxvt.7.txt deleted file mode 100644 index 920ca4fc..00000000 --- a/doc/rxvt.7.txt +++ /dev/null @@ -1,2059 +0,0 @@ -NAME - RXVT REFERENCE - FAQ, command sequences and other background information - -SYNOPSIS - # set a new font set - printf '\33]50;%s\007' 9x15,xft:Kochi" Mincho" - - # change the locale and tell rxvt-unicode about it - export LC_CTYPE=ja_JP.EUC-JP; printf "\33]701;$LC_CTYPE\007" - - # set window title - printf '\33]2;%s\007' "new window title" - -DESCRIPTION - This document contains the FAQ, the RXVT TECHNICAL REFERENCE documenting - all escape sequences, and other background information. - - The newest version of this document is also available on the World Wide - Web at . - -RXVT-UNICODE/URXVT FREQUENTLY ASKED QUESTIONS - Meta, Features & Commandline Issues - My question isn't answered here, can I ask a human? - Before sending me mail, you could go to IRC: "irc.freenode.net", channel - "#rxvt-unicode" has some rxvt-unicode enthusiasts that might be - interested in learning about new and exciting problems (but not FAQs :). - - Does it support tabs, can I have a tabbed rxvt-unicode? - Beginning with version 7.3, there is a perl extension that implements a - simple tabbed terminal. It is installed by default, so any of these - should give you tabs: - - urxvt -pe tabbed - - URxvt.perl-ext-common: default,tabbed - - It will also work fine with tabbing functionality of many window - managers or similar tabbing programs, and its embedding-features allow - it to be embedded into other programs, as witnessed by doc/rxvt-tabbed - or the upcoming "Gtk2::URxvt" perl module, which features a tabbed urxvt - (murxvt) terminal as an example embedding application. - - How do I know which rxvt-unicode version I'm using? - The version number is displayed with the usage (-h). Also the escape - sequence "ESC [ 8 n" sets the window title to the version number. When - using the urxvtc client, the version displayed is that of the daemon. - - Rxvt-unicode uses gobs of memory, how can I reduce that? - Rxvt-unicode tries to obey the rule of not charging you for something - you don't use. One thing you should try is to configure out all settings - that you don't need, for example, Xft support is a resource hog by - design, when used. Compiling it out ensures that no Xft font will be - loaded accidentally when rxvt-unicode tries to find a font for your - characters. - - Also, many people (me included) like large windows and even larger - scrollback buffers: Without "--enable-unicode3", rxvt-unicode will use 6 - bytes per screen cell. For a 160x?? window this amounts to almost a - kilobyte per line. A scrollback buffer of 10000 lines will then (if - full) use 10 Megabytes of memory. With "--enable-unicode3" it gets - worse, as rxvt-unicode then uses 8 bytes per screen cell. - - How can I start urxvtd in a race-free way? - Try "urxvtd -f -o", which tells urxvtd to open the display, create the - listening socket and then fork. - - How can I start urxvtd automatically when I run urxvtc? - If you want to start urxvtd automatically whenever you run urxvtc and - the daemon isn't running yet, use this script: - - #!/bin/sh - urxvtc "$@" - if [ $? -eq 2 ]; then - urxvtd -q -o -f - urxvtc "$@" - fi - - This tries to create a new terminal, and if fails with exit status 2, - meaning it couldn't connect to the daemon, it will start the daemon and - re-run the command. Subsequent invocations of the script will re-use the - existing daemon. - - How do I distinguish whether I'm running rxvt-unicode or a regular xterm? I need this to decide about setting colors etc. - The original rxvt and rxvt-unicode always export the variable - "COLORTERM", so you can check and see if that is set. Note that several - programs, JED, slrn, Midnight Commander automatically check this - variable to decide whether or not to use color. - - How do I set the correct, full IP address for the DISPLAY variable? - If you've compiled rxvt-unicode with DISPLAY_IS_IP and have enabled - insecure mode then it is possible to use the following shell script - snippets to correctly set the display. If your version of rxvt-unicode - wasn't also compiled with ESCZ_ANSWER (as assumed in these snippets) - then the COLORTERM variable can be used to distinguish rxvt-unicode from - a regular xterm. - - Courtesy of Chuck Blake with the following shell script - snippets: - - # Bourne/Korn/POSIX family of shells: - [ ${TERM:-foo} = foo ] && TERM=xterm # assume an xterm if we don't know - if [ ${TERM:-foo} = xterm ]; then - stty -icanon -echo min 0 time 15 # see if enhanced rxvt or not - echo -n '^[Z' - read term_id - stty icanon echo - if [ ""${term_id} = '^[[?1;2C' -a ${DISPLAY:-foo} = foo ]; then - echo -n '^[[7n' # query the rxvt we are in for the DISPLAY string - read DISPLAY # set it in our local shell - fi - fi - - How do I compile the manual pages on my own? - You need to have a recent version of perl installed as /usr/bin/perl, - one that comes with pod2man, pod2text and pod2xhtml (from Pod::Xhtml). - Then go to the doc subdirectory and enter "make alldoc". - - Isn't rxvt-unicode supposed to be small? Don't all those features bloat? - I often get asked about this, and I think, no, they didn't cause extra - bloat. If you compare a minimal rxvt and a minimal urxvt, you can see - that the urxvt binary is larger (due to some encoding tables always - being compiled in), but it actually uses less memory (RSS) after - startup. Even with "--disable-everything", this comparison is a bit - unfair, as many features unique to urxvt (locale, encoding conversion, - iso14755 etc.) are already in use in this mode. - - text data bss drs rss filename - 98398 1664 24 15695 1824 rxvt --disable-everything - 188985 9048 66616 18222 1788 urxvt --disable-everything - - When you "--enable-everything" (which *is* unfair, as this involves xft - and full locale/XIM support which are quite bloaty inside libX11 and my - libc), the two diverge, but not unreasonably so. - - text data bss drs rss filename - 163431 2152 24 20123 2060 rxvt --enable-everything - 1035683 49680 66648 29096 3680 urxvt --enable-everything - - The very large size of the text section is explained by the east-asian - encoding tables, which, if unused, take up disk space but nothing else - and can be compiled out unless you rely on X11 core fonts that use those - encodings. The BSS size comes from the 64k emergency buffer that my c++ - compiler allocates (but of course doesn't use unless you are out of - memory). Also, using an xft font instead of a core font immediately adds - a few megabytes of RSS. Xft indeed is responsible for a lot of RSS even - when not used. - - Of course, due to every character using two or four bytes instead of - one, a large scrollback buffer will ultimately make rxvt-unicode use - more memory. - - Compared to e.g. Eterm (5112k), aterm (3132k) and xterm (4680k), this - still fares rather well. And compared to some monsters like - gnome-terminal (21152k + extra 4204k in separate processes) or konsole - (22200k + extra 43180k in daemons that stay around after exit, plus half - a minute of startup time, including the hundreds of warnings it spits - out), it fares extremely well *g*. - - Why C++, isn't that unportable/bloated/uncool? - Is this a question? :) It comes up very often. The simple answer is: I - had to write it, and C++ allowed me to write and maintain it in a - fraction of the time and effort (which is a scarce resource for me). Put - even shorter: It simply wouldn't exist without C++. - - My personal stance on this is that C++ is less portable than C, but in - the case of rxvt-unicode this hardly matters, as its portability limits - are defined by things like X11, pseudo terminals, locale support and - unix domain sockets, which are all less portable than C++ itself. - - Regarding the bloat, see the above question: It's easy to write programs - in C that use gobs of memory, an certainly possible to write programs in - C++ that don't. C++ also often comes with large libraries, but this is - not necessarily the case with GCC. Here is what rxvt links against on my - system with a minimal config: - - libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x00002aaaaabc3000) - libc.so.6 => /lib/libc.so.6 (0x00002aaaaadde000) - libdl.so.2 => /lib/libdl.so.2 (0x00002aaaab01d000) - /lib64/ld-linux-x86-64.so.2 (0x00002aaaaaaab000) - - And here is rxvt-unicode: - - libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x00002aaaaabc3000) - libgcc_s.so.1 => /lib/libgcc_s.so.1 (0x00002aaaaada2000) - libc.so.6 => /lib/libc.so.6 (0x00002aaaaaeb0000) - libdl.so.2 => /lib/libdl.so.2 (0x00002aaaab0ee000) - /lib64/ld-linux-x86-64.so.2 (0x00002aaaaaaab000) - - No large bloated libraries (of course, none were linked in statically), - except maybe libX11 :) - - Rendering, Font & Look and Feel Issues - I can't get transparency working, what am I doing wrong? - First of all, please address all transparency related issues to Sasha - Vasko at sasha@aftercode.net and do not bug the author about it. Also, - if you can't get it working consider it a rite of passage: ... and you - failed. - - Here are four ways to get transparency. Do read the manpage and option - descriptions for the programs mentioned and rxvt-unicode. Really, do it! - - 1. Use transparent mode: - - Esetroot wallpaper.jpg - urxvt -tr -tint red -sh 40 - - That works. If you think it doesn't, you lack transparency and tinting - support, or you are unable to read. - - 2. Use a simple pixmap and emulate pseudo-transparency. This enables you - to use effects other than tinting and shading: Just shade/tint/whatever - your picture with gimp or any other tool: - - convert wallpaper.jpg -blur 20x20 -modulate 30 background.jpg - urxvt -pixmap "background.jpg;:root" - - That works. If you think it doesn't, you lack AfterImage support, or you - are unable to read. - - 3. Use an ARGB visual: - - urxvt -depth 32 -fg grey90 -bg rgba:0000/0000/4444/cccc - - This requires XFT support, and the support of your X-server. If that - doesn't work for you, blame Xorg and Keith Packard. ARGB visuals aren't - there yet, no matter what they claim. Rxvt-Unicode contains the - necessary bugfixes and workarounds for Xft and Xlib to make it work, but - that doesn't mean that your WM has the required kludges in place. - - 4. Use xcompmgr and let it do the job: - - xprop -frame -f _NET_WM_WINDOW_OPACITY 32c \ - -set _NET_WM_WINDOW_OPACITY 0xc0000000 - - Then click on a window you want to make transparent. Replace 0xc0000000 - by other values to change the degree of opacity. If it doesn't work and - your server crashes, you got to keep the pieces. - - Why does rxvt-unicode sometimes leave pixel droppings? - Most fonts were not designed for terminal use, which means that - character size varies a lot. A font that is otherwise fine for terminal - use might contain some characters that are simply too wide. Rxvt-unicode - will avoid these characters. For characters that are just "a bit" too - wide a special "careful" rendering mode is used that redraws adjacent - characters. - - All of this requires that fonts do not lie about character sizes, - however: Xft fonts often draw glyphs larger than their acclaimed - bounding box, and rxvt-unicode has no way of detecting this (the correct - way is to ask for the character bounding box, which unfortunately is - wrong in these cases). - - It's not clear (to me at least), whether this is a bug in Xft, freetype, - or the respective font. If you encounter this problem you might try - using the "-lsp" option to give the font more height. If that doesn't - work, you might be forced to use a different font. - - All of this is not a problem when using X11 core fonts, as their - bounding box data is correct. - - How can I keep rxvt-unicode from using reverse video so much? - First of all, make sure you are running with the right terminal settings - ("TERM=rxvt-unicode"), which will get rid of most of these effects. Then - make sure you have specified colours for italic and bold, as otherwise - rxvt-unicode might use reverse video to simulate the effect: - - URxvt.colorBD: white - URxvt.colorIT: green - - Some programs assume totally weird colours (red instead of blue), how can I fix that? - For some unexplainable reason, some rare programs assume a very weird - colour palette when confronted with a terminal with more than the - standard 8 colours (rxvt-unicode supports 88). The right fix is, of - course, to fix these programs not to assume non-ISO colours without very - good reasons. - - In the meantime, you can either edit your "rxvt-unicode" terminfo - definition to only claim 8 colour support or use "TERM=rxvt", which will - fix colours but keep you from using other rxvt-unicode features. - - Can I switch the fonts at runtime? - Yes, using an escape sequence. Try something like this, which has the - same effect as using the "-fn" switch, and takes effect immediately: - - printf '\33]50;%s\007' "9x15bold,xft:Kochi Gothic" - - This is useful if you e.g. work primarily with japanese (and prefer a - japanese font), but you have to switch to chinese temporarily, where - japanese fonts would only be in your way. - - You can think of this as a kind of manual ISO-2022 switching. - - Why do italic characters look as if clipped? - Many fonts have difficulties with italic characters and hinting. For - example, the otherwise very nicely hinted font "xft:Bitstream Vera Sans - Mono" completely fails in its italic face. A workaround might be to - enable freetype autohinting, i.e. like this: - - URxvt.italicFont: xft:Bitstream Vera Sans Mono:italic:autohint=true - URxvt.boldItalicFont: xft:Bitstream Vera Sans Mono:bold:italic:autohint=true - - Can I speed up Xft rendering somehow? - Yes, the most obvious way to speed it up is to avoid Xft entirely, as it - is simply slow. If you still want Xft fonts you might try to disable - antialiasing (by appending ":antialias=false"), which saves lots of - memory and also speeds up rendering considerably. - - Rxvt-unicode doesn't seem to anti-alias its fonts, what is wrong? - Rxvt-unicode will use whatever you specify as a font. If it needs to - fall back to its default font search list it will prefer X11 core fonts, - because they are small and fast, and then use Xft fonts. It has - antialiasing disabled for most of them, because the author thinks they - look best that way. - - If you want antialiasing, you have to specify the fonts manually. - - What's with this bold/blink stuff? - If no bold colour is set via "colorBD:", bold will invert text using the - standard foreground colour. - - For the standard background colour, blinking will actually make the text - blink when compiled with "--enable-text-blink". Without - "--enable-text-blink", the blink attribute will be ignored. - - On ANSI colours, bold/blink attributes are used to set high-intensity - foreground/background colors. - - color0-7 are the low-intensity colors. - - color8-15 are the corresponding high-intensity colors. - - I don't like the screen colors. How do I change them? - You can change the screen colors at run-time using ~/.Xdefaults - resources (or as long-options). - - Here are values that are supposed to resemble a VGA screen, including - the murky brown that passes for low-intensity yellow: - - URxvt.color0: #000000 - URxvt.color1: #A80000 - URxvt.color2: #00A800 - URxvt.color3: #A8A800 - URxvt.color4: #0000A8 - URxvt.color5: #A800A8 - URxvt.color6: #00A8A8 - URxvt.color7: #A8A8A8 - - URxvt.color8: #000054 - URxvt.color9: #FF0054 - URxvt.color10: #00FF54 - URxvt.color11: #FFFF54 - URxvt.color12: #0000FF - URxvt.color13: #FF00FF - URxvt.color14: #00FFFF - URxvt.color15: #FFFFFF - - And here is a more complete set of non-standard colors. - - URxvt.cursorColor: #dc74d1 - URxvt.pointerColor: #dc74d1 - URxvt.background: #0e0e0e - URxvt.foreground: #4ad5e1 - URxvt.color0: #000000 - URxvt.color8: #8b8f93 - URxvt.color1: #dc74d1 - URxvt.color9: #dc74d1 - URxvt.color2: #0eb8c7 - URxvt.color10: #0eb8c7 - URxvt.color3: #dfe37e - URxvt.color11: #dfe37e - URxvt.color5: #9e88f0 - URxvt.color13: #9e88f0 - URxvt.color6: #73f7ff - URxvt.color14: #73f7ff - URxvt.color7: #e1dddd - URxvt.color15: #e1dddd - - They have been described (not by me) as "pretty girly". - - Why do some characters look so much different than others? - See next entry. - - How does rxvt-unicode choose fonts? - Most fonts do not contain the full range of Unicode, which is fine. - Chances are that the font you (or the admin/package maintainer of your - system/os) have specified does not cover all the characters you want to - display. - - rxvt-unicode makes a best-effort try at finding a replacement font. - Often the result is fine, but sometimes the chosen font looks - bad/ugly/wrong. Some fonts have totally strange characters that don't - resemble the correct glyph at all, and rxvt-unicode lacks the artificial - intelligence to detect that a specific glyph is wrong: it has to believe - the font that the characters it claims to contain indeed look correct. - - In that case, select a font of your taste and add it to the font list, - e.g.: - - urxvt -fn basefont,font2,font3... - - When rxvt-unicode sees a character, it will first look at the base font. - If the base font does not contain the character, it will go to the next - font, and so on. Specifying your own fonts will also speed up this - search and use less resources within rxvt-unicode and the X-server. - - The only limitation is that none of the fonts may be larger than the - base font, as the base font defines the terminal character cell size, - which must be the same due to the way terminals work. - - Why do some chinese characters look so different than others? - This is because there is a difference between script and language -- - rxvt-unicode does not know which language the text that is output is, as - it only knows the unicode character codes. If rxvt-unicode first sees a - japanese/chinese character, it might choose a japanese font for display. - Subsequent japanese characters will use that font. Now, many chinese - characters aren't represented in japanese fonts, so when the first - non-japanese character comes up, rxvt-unicode will look for a chinese - font -- unfortunately at this point, it will still use the japanese font - for chinese characters that are also in the japanese font. - - The workaround is easy: just tag a chinese font at the end of your font - list (see the previous question). The key is to view the font list as a - preference list: If you expect more japanese, list a japanese font - first. If you expect more chinese, put a chinese font first. - - In the future it might be possible to switch language preferences at - runtime (the internal data structure has no problem with using different - fonts for the same character at the same time, but no interface for this - has been designed yet). - - Until then, you might get away with switching fonts at runtime (see "Can - I switch the fonts at runtime?" later in this document). - - How can I make mplayer display video correctly? - We are working on it, in the meantime, as a workaround, use something - like: - - urxvt -b 600 -geometry 20x1 -e sh -c 'mplayer -wid $WINDOWID file...' - - Keyboard, Mouse & User Interaction - The new selection selects pieces that are too big, how can I select single words? - If you want to select e.g. alphanumeric words, you can use the following - setting: - - URxvt.selection.pattern-0: ([[:word:]]+) - - If you click more than twice, the selection will be extended more and - more. - - To get a selection that is very similar to the old code, try this - pattern: - - URxvt.selection.pattern-0: ([^"&'()*,;<=>?@[\\\\]^`{|})]+) - - Please also note that the *LeftClick Shift-LeftClik* combination also - selects words like the old code. - - I don't like the new selection/popups/hotkeys/perl, how do I change/disable it? - You can disable the perl extension completely by setting the - perl-ext-common resource to the empty string, which also keeps - rxvt-unicode from initialising perl, saving memory. - - If you only want to disable specific features, you first have to - identify which perl extension is responsible. For this, read the section - PREPACKAGED EXTENSIONS in the urxvtperl(3) manpage. For example, to - disable the selection-popup and option-popup, specify this - perl-ext-common resource: - - URxvt.perl-ext-common: default,-selection-popup,-option-popup - - This will keep the default extensions, but disable the two popup - extensions. Some extensions can also be configured, for example, - scrollback search mode is triggered by M-s. You can move it to any other - combination either by setting the searchable-scrollback resource: - - URxvt.searchable-scrollback: CM-s - - The cursor moves when selecting text in the current input line, how do I switch this off? - See next entry. - - During rlogin/ssh/telnet/etc. sessions, clicking near the cursor outputs strange escape sequences, how do I fix this? - These are caused by the "readline" perl extension. Under normal - circumstances, it will move your cursor around when you click into the - line that contains it. It tries hard not to do this at the wrong moment, - but when running a program that doesn't parse cursor movements or in - some cases during rlogin sessions, it fails to detect this properly. - - You can permanently switch this feature off by disabling the "readline" - extension: - - URxvt.perl-ext-common: default,-readline - - My numerical keypad acts weird and generates differing output? - Some Debian GNUL/Linux users seem to have this problem, although no - specific details were reported so far. It is possible that this is - caused by the wrong "TERM" setting, although the details of whether and - how this can happen are unknown, as "TERM=rxvt" should offer a - compatible keymap. See the answer to the previous question, and please - report if that helped. - - My Compose (Multi_key) key is no longer working. - The most common causes for this are that either your locale is not set - correctly, or you specified a preeditStyle that is not supported by your - input method. For example, if you specified OverTheSpot and your input - method (e.g. the default input method handling Compose keys) does not - support this (for instance because it is not visual), then rxvt-unicode - will continue without an input method. - - In this case either do not specify a preeditStyle or specify more than - one pre-edit style, such as OverTheSpot,Root,None. - - I cannot type "Ctrl-Shift-2" to get an ASCII NUL character due to ISO 14755 - Either try "Ctrl-2" alone (it often is mapped to ASCII NUL even on - international keyboards) or simply use ISO 14755 support to your - advantage, typing to get a ASCII NUL. This works for - other codes, too, such as "Ctrl-Shift-1-d" to type the default telnet - escape character and so on. - - Mouse cut/paste suddenly no longer works. - Make sure that mouse reporting is actually turned off since killing some - editors prematurely may leave the mouse in mouse report mode. I've heard - that tcsh may use mouse reporting unless it otherwise specified. A quick - check is to see if cut/paste works when the Alt or Shift keys are - depressed. - - What's with the strange Backspace/Delete key behaviour? - Assuming that the physical Backspace key corresponds to the Backspace - keysym (not likely for Linux ... see the following question) there are - two standard values that can be used for Backspace: "^H" and "^?". - - Historically, either value is correct, but rxvt-unicode adopts the - debian policy of using "^?" when unsure, because it's the one and only - correct choice :). - - Rxvt-unicode tries to inherit the current stty settings and uses the - value of `erase' to guess the value for backspace. If rxvt-unicode - wasn't started from a terminal (say, from a menu or by remote shell), - then the system value of `erase', which corresponds to CERASE in - , will be used (which may not be the same as your stty - setting). - - For starting a new rxvt-unicode: - - # use Backspace = ^H - $ stty erase ^H - $ urxvt - - # use Backspace = ^? - $ stty erase ^? - $ urxvt - - Toggle with "ESC [ 36 h" / "ESC [ 36 l". - - For an existing rxvt-unicode: - - # use Backspace = ^H - $ stty erase ^H - $ echo -n "^[[36h" - - # use Backspace = ^? - $ stty erase ^? - $ echo -n "^[[36l" - - This helps satisfy some of the Backspace discrepancies that occur, but - if you use Backspace = "^H", make sure that the termcap/terminfo value - properly reflects that. - - The Delete key is a another casualty of the ill-defined Backspace - problem. To avoid confusion between the Backspace and Delete keys, the - Delete key has been assigned an escape sequence to match the vt100 for - Execute ("ESC [ 3 ~") and is in the supplied termcap/terminfo. - - Some other Backspace problems: - - some editors use termcap/terminfo, some editors (vim I'm told) expect - Backspace = ^H, GNU Emacs (and Emacs-like editors) use ^H for help. - - Perhaps someday this will all be resolved in a consistent manner. - - I don't like the key-bindings. How do I change them? - There are some compile-time selections available via configure. Unless - you have run "configure" with the "--disable-resources" option you can - use the `keysym' resource to alter the keystrings associated with - keysyms. - - Here's an example for a URxvt session started using "urxvt -name URxvt" - - URxvt.keysym.Home: \033[1~ - URxvt.keysym.End: \033[4~ - URxvt.keysym.C-apostrophe: \033 - URxvt.keysym.C-slash: \033 - URxvt.keysym.C-semicolon: \033 - URxvt.keysym.C-grave: \033 - URxvt.keysym.C-comma: \033 - URxvt.keysym.C-period: \033 - URxvt.keysym.C-0x60: \033 - URxvt.keysym.C-Tab: \033 - URxvt.keysym.C-Return: \033 - URxvt.keysym.S-Return: \033 - URxvt.keysym.S-space: \033 - URxvt.keysym.M-Up: \033 - URxvt.keysym.M-Down: \033 - URxvt.keysym.M-Left: \033 - URxvt.keysym.M-Right: \033 - URxvt.keysym.M-C-0: list \033 - URxvt.keysym.M-C-a: list \033 - URxvt.keysym.F12: command:\033]701;zh_CN.GBK\007 - - See some more examples in the documentation for the keysym resource. - - I'm using keyboard model XXX that has extra Prior/Next/Insert keys. How do I make use of them? For example, the Sun Keyboard type 4 has the following map - KP_Insert == Insert - F22 == Print - F27 == Home - F29 == Prior - F33 == End - F35 == Next - - Rather than have rxvt-unicode try to accommodate all the various - possible keyboard mappings, it is better to use `xmodmap' to remap the - keys as required for your particular machine. - - Terminal Configuration - Can I see a typical configuration? - The default configuration tries to be xterm-like, which I don't like - that much, but it's least surprise to regular users. - - As a rxvt or rxvt-unicode user, you are practically supposed to invest - time into customising your terminal. To get you started, here is the - author's .Xdefaults entries, with comments on what they do. It's - certainly not *typical*, but what's typical... - - URxvt.cutchars: "()*,<>[]{}|' - URxvt.print-pipe: cat >/tmp/xxx - - These are just for testing stuff. - - URxvt.imLocale: ja_JP.UTF-8 - URxvt.preeditType: OnTheSpot,None - - This tells rxvt-unicode to use a special locale when communicating with - the X Input Method, and also tells it to only use the OnTheSpot pre-edit - type, which requires the "xim-onthespot" perl extension but rewards me - with correct-looking fonts. - - URxvt.perl-lib: /root/lib/urxvt - URxvt.perl-ext-common: default,selection-autotransform,selection-pastebin,xim-onthespot,remote-clipboard - URxvt.selection.pattern-0: ( at .*? line \\d+) - URxvt.selection.pattern-1: ^(/[^:]+):\ - URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/ - URxvt.selection-autotransform.1: s/^ at (.*?) line (\\d+)$/:e \\Q$1\\E\\x0d:$2\\x0d/ - - This is my perl configuration. The first two set the perl library - directory and also tells urxvt to use a large number of extensions. I - develop for myself mostly, so I actually use most of the extensions I - write. - - The selection stuff mainly makes the selection perl-error-message aware - and tells it to convert perl error messages into vi-commands to load the - relevant file and go tot he error line number. - - URxvt.scrollstyle: plain - URxvt.secondaryScroll: true - - As the documentation says: plain is the preferred scrollbar for the - author. The "secondaryScroll" configures urxvt to scroll in full-screen - apps, like screen, so lines scrolled out of screen end up in urxvt's - scrollback buffer. - - URxvt.background: #000000 - URxvt.foreground: gray90 - URxvt.color7: gray90 - URxvt.colorBD: #ffffff - URxvt.cursorColor: #e0e080 - URxvt.throughColor: #8080f0 - URxvt.highlightColor: #f0f0f0 - - Some colours. Not sure which ones are being used or even non-defaults, - but these are in my .Xdefaults. Most notably, they set - foreground/background to light gray/black, and also make sure that the - colour 7 matches the default foreground colour. - - URxvt.underlineColor: yellow - - Another colour, makes underline lines look different. Sometimes hurts, - but is mostly a nice effect. - - URxvt.geometry: 154x36 - URxvt.loginShell: false - URxvt.meta: ignore - URxvt.utmpInhibit: true - - Uh, well, should be mostly self-explanatory. By specifying some defaults - manually, I can quickly switch them for testing. - - URxvt.saveLines: 8192 - - A large scrollback buffer is essential. Really. - - URxvt.mapAlert: true - - The only case I use it is for my IRC window, which I like to keep - iconified till people msg me (which beeps). - - URxvt.visualBell: true - - The audible bell is often annoying, especially when in a crowd. - - URxvt.insecure: true - - Please don't hack my mutt! Ooops... - - URxvt.pastableTabs: false - - I once thought this is a great idea. - - urxvt.font: 9x15bold,\ - -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso10646-1,\ - -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1, \ - [codeset=JISX0208]xft:Kochi Gothic, \ - xft:Bitstream Vera Sans Mono:autohint=true, \ - xft:Code2000:antialias=false - urxvt.boldFont: -xos4-terminus-bold-r-normal--14-140-72-72-c-80-iso8859-15 - urxvt.italicFont: xft:Bitstream Vera Sans Mono:italic:autohint=true - urxvt.boldItalicFont: xft:Bitstream Vera Sans Mono:bold:italic:autohint=true - - I wrote rxvt-unicode to be able to specify fonts exactly. So don't be - overwhelmed. A special note: the "9x15bold" mentioned above is actually - the version from XFree-3.3, as XFree-4 replaced it by a totally - different font (different glyphs for ";" and many other harmless - characters), while the second font is actually the "9x15bold" from - XFree4/XOrg. The bold version has less chars than the medium version, so - I use it for rare characters, too. When editing sources with vim, I use - italic for comments and other stuff, which looks quite good with - Bitstream Vera anti-aliased. - - Terminus is a quite bad font (many very wrong glyphs), but for most of - my purposes, it works, and gives a different look, as my normal - (Non-bold) font is already bold, and I want to see a difference between - bold and normal fonts. - - Please note that I used the "urxvt" instance name and not the "URxvt" - class name. Thats because I use different configs for different - purposes, for example, my IRC window is started with "-name IRC", and - uses these defaults: - - IRC*title: IRC - IRC*geometry: 87x12+535+542 - IRC*saveLines: 0 - IRC*mapAlert: true - IRC*font: suxuseuro - IRC*boldFont: suxuseuro - IRC*colorBD: white - IRC*keysym.M-C-1: command:\033]710;suxuseuro\007\033]711;suxuseuro\007 - IRC*keysym.M-C-2: command:\033]710;9x15bold\007\033]711;9x15bold\007 - - "Alt-Shift-1" and "Alt-Shift-2" switch between two different font sizes. - "suxuseuro" allows me to keep an eye (and actually read) stuff while - keeping a very small window. If somebody pastes something complicated - (e.g. japanese), I temporarily switch to a larger font. - - The above is all in my ".Xdefaults" (I don't use ".Xresources" nor - "xrdb"). I also have some resources in a separate ".Xdefaults-hostname" - file for different hosts, for example, on ym main desktop, I use: - - URxvt.keysym.C-M-q: command:\033[3;5;5t - URxvt.keysym.C-M-y: command:\033[3;5;606t - URxvt.keysym.C-M-e: command:\033[3;1605;5t - URxvt.keysym.C-M-c: command:\033[3;1605;606t - URxvt.keysym.C-M-p: perl:test - - The first for keysym definitions allow me to quickly bring some windows - in the layout I like most. Ion users might start laughing but will stop - immediately when I tell them that I use my own Fvwm2 module for much the - same effect as Ion provides, and I only very rarely use the above key - combinations :-> - - Why doesn't rxvt-unicode read my resources? - Well, why, indeed? It does, in a way very similar to other X - applications. Most importantly, this means that if you or your OS loads - resources into the X display (the right way to do it), rxvt-unicode will - ignore any resource files in your home directory. It will only read - $HOME/.Xdefaults when no resources are attached to the display. - - If you have or use an $HOME/.Xresources file, chances are that resources - are loaded into your X-server. In this case, you have to re-login after - every change (or run xrdb -merge $HOME/.Xresources). - - Also consider the form resources have to use: - - URxvt.resource: value - - If you want to use another form (there are lots of different ways of - specifying resources), make sure you understand whether and why it - works. If unsure, use the form above. - - When I log-in to another system it tells me about missing terminfo data? - The terminal description used by rxvt-unicode is not as widely available - as that for xterm, or even rxvt (for which the same problem often - arises). - - The correct solution for this problem is to install the terminfo, this - can be done like this (with ncurses' infocmp and works as user and - admin): - - REMOTE=remotesystem.domain - infocmp rxvt-unicode | ssh $REMOTE "mkdir -p .terminfo && cat >/tmp/ti && tic /tmp/ti" - - ... or by installing rxvt-unicode normally on the remote system, - - One some systems you might need to set $TERMINFO to the full path of - $HOME/.terminfo for this to work. - - If you cannot or do not want to do this, then you can simply set - "TERM=rxvt" or even "TERM=xterm", and live with the small number of - problems arising, which includes wrong keymapping, less and different - colours and some refresh errors in fullscreen applications. It's a nice - quick-and-dirty workaround for rare cases, though. - - If you always want to do this (and are fine with the consequences) you - can either recompile rxvt-unicode with the desired TERM value or use a - resource to set it: - - URxvt.termName: rxvt - - If you don't plan to use rxvt (quite common...) you could also replace - the rxvt terminfo file with the rxvt-unicode one and use "TERM=rxvt". - - "tic" outputs some error when compiling the terminfo entry. - Most likely it's the empty definition for "enacs=". Just replace it by - "enacs=\E[0@" and try again. - - "bash"'s readline does not work correctly under urxvt. - See next entry. - - I need a termcap file entry. - One reason you might want this is that some distributions or operating - systems still compile some programs using the long-obsoleted termcap - library (Fedora Core's bash is one example) and rely on a termcap entry - for "rxvt-unicode". - - You could use rxvt's termcap entry with reasonable results in many - cases. You can also create a termcap entry by using terminfo's infocmp - program like this: - - infocmp -C rxvt-unicode - - Or you could use this termcap entry, generated by the command above: - - rxvt-unicode|rxvt-unicode terminal (X Window System):\ - :am:bw:eo:km:mi:ms:xn:xo:\ - :co#80:it#8:li#24:lm#0:\ - :AL=\E[%dL:DC=\E[%dP:DL=\E[%dM:DO=\E[%dB:IC=\E[%d@:\ - :K1=\EOw:K2=\EOu:K3=\EOy:K4=\EOq:K5=\EOs:LE=\E[%dD:\ - :RI=\E[%dC:SF=\E[%dS:SR=\E[%dT:UP=\E[%dA:ae=\E(B:al=\E[L:\ - :as=\E(0:bl=^G:cd=\E[J:ce=\E[K:cl=\E[H\E[2J:\ - :cm=\E[%i%d;%dH:cr=^M:cs=\E[%i%d;%dr:ct=\E[3g:dc=\E[P:\ - :dl=\E[M:do=^J:ec=\E[%dX:ei=\E[4l:ho=\E[H:\ - :i1=\E[?47l\E=\E[?1l:ic=\E[@:im=\E[4h:\ - :is=\E[r\E[m\E[2J\E[H\E[?7h\E[?1;3;4;6l\E[4l:\ - :k1=\E[11~:k2=\E[12~:k3=\E[13~:k4=\E[14~:k5=\E[15~:\ - :k6=\E[17~:k7=\E[18~:k8=\E[19~:k9=\E[20~:kD=\E[3~:\ - :kI=\E[2~:kN=\E[6~:kP=\E[5~:kb=\177:kd=\EOB:ke=\E[?1l\E>:\ - :kh=\E[7~:kl=\EOD:kr=\EOC:ks=\E[?1h\E=:ku=\EOA:le=^H:\ - :mb=\E[5m:md=\E[1m:me=\E[m\017:mr=\E[7m:nd=\E[C:rc=\E8:\ - :sc=\E7:se=\E[27m:sf=^J:so=\E[7m:sr=\EM:st=\EH:ta=^I:\ - :te=\E[r\E[?1049l:ti=\E[?1049h:ue=\E[24m:up=\E[A:\ - :us=\E[4m:vb=\E[?5h\E[?5l:ve=\E[?25h:vi=\E[?25l:\ - :vs=\E[?25h: - - Why does "ls" no longer have coloured output? - The "ls" in the GNU coreutils unfortunately doesn't use terminfo to - decide whether a terminal has colour, but uses its own configuration - file. Needless to say, "rxvt-unicode" is not in its default file (among - with most other terminals supporting colour). Either add: - - TERM rxvt-unicode - - to "/etc/DIR_COLORS" or simply add: - - alias ls='ls --color=auto' - - to your ".profile" or ".bashrc". - - Why doesn't vim/emacs etc. use the 88 colour mode? - See next entry. - - Why doesn't vim/emacs etc. make use of italic? - See next entry. - - Why are the secondary screen-related options not working properly? - Make sure you are using "TERM=rxvt-unicode". Some pre-packaged - distributions (most notably Debian GNU/Linux) break rxvt-unicode by - setting "TERM" to "rxvt", which doesn't have these extra features. - Unfortunately, some of these (most notably, again, Debian GNU/Linux) - furthermore fail to even install the "rxvt-unicode" terminfo file, so - you will need to install it on your own (See the question When I log-in - to another system it tells me about missing terminfo data? on how to do - this). - - Encoding / Locale / Input Method Issues - Rxvt-unicode does not seem to understand the selected encoding? - See next entry. - - Unicode does not seem to work? - If you encounter strange problems like typing an accented character but - getting two unrelated other characters or similar, or if program output - is subtly garbled, then you should check your locale settings. - - Rxvt-unicode must be started with the same "LC_CTYPE" setting as the - programs running in it. Often rxvt-unicode is started in the "C" locale, - while the login script running within the rxvt-unicode window changes - the locale to something else, e.g. "en_GB.UTF-8". Needless to say, this - is not going to work, and is the most common cause for problems. - - The best thing is to fix your startup environment, as you will likely - run into other problems. If nothing works you can try this in your - .profile. - - printf '\33]701;%s\007' "$LC_CTYPE" # $LANG or $LC_ALL are worth a try, too - - If this doesn't work, then maybe you use a "LC_CTYPE" specification not - supported on your systems. Some systems have a "locale" command which - displays this (also, "perl -e0" can be used to check locale settings, as - it will complain loudly if it cannot set the locale). If it displays - something like: - - locale: Cannot set LC_CTYPE to default locale: ... - - Then the locale you specified is not supported on your system. - - If nothing works and you are sure that everything is set correctly then - you will need to remember a little known fact: Some programs just don't - support locales :( - - How does rxvt-unicode determine the encoding to use? - See next entry. - - Is there an option to switch encodings? - Unlike some other terminals, rxvt-unicode has no encoding switch, and no - specific "utf-8" mode, such as xterm. In fact, it doesn't even know - about UTF-8 or any other encodings with respect to terminal I/O. - - The reasons is that there exists a perfectly fine mechanism for - selecting the encoding, doing I/O and (most important) communicating - this to all applications so everybody agrees on character properties - such as width and code number. This mechanism is the *locale*. - Applications not using that info will have problems (for example, - "xterm" gets the width of characters wrong as it uses its own, - locale-independent table under all locales). - - Rxvt-unicode uses the "LC_CTYPE" locale category to select encoding. All - programs doing the same (that is, most) will automatically agree in the - interpretation of characters. - - Unfortunately, there is no system-independent way to select locales, nor - is there a standard on how locale specifiers will look like. - - On most systems, the content of the "LC_CTYPE" environment variable - contains an arbitrary string which corresponds to an already-installed - locale. Common names for locales are "en_US.UTF-8", "de_DE.ISO-8859-15", - "ja_JP.EUC-JP", i.e. "language_country.encoding", but other forms (i.e. - "de" or "german") are also common. - - Rxvt-unicode ignores all other locale categories, and except for the - encoding, ignores country or language-specific settings, i.e. - "de_DE.UTF-8" and "ja_JP.UTF-8" are the normally same to rxvt-unicode. - - If you want to use a specific encoding you have to make sure you start - rxvt-unicode with the correct "LC_CTYPE" category. - - Can I switch locales at runtime? - Yes, using an escape sequence. Try something like this, which sets - rxvt-unicode's idea of "LC_CTYPE". - - printf '\33]701;%s\007' ja_JP.SJIS - - See also the previous answer. - - Sometimes this capability is rather handy when you want to work in one - locale (e.g. "de_DE.UTF-8") but some programs don't support it (e.g. - UTF-8). For example, I use this script to start "xjdic", which first - switches to a locale supported by xjdic and back later: - - printf '\33]701;%s\007' ja_JP.SJIS - xjdic -js - printf '\33]701;%s\007' de_DE.UTF-8 - - You can also use xterm's "luit" program, which usually works fine, - except for some locales where character width differs between program- - and rxvt-unicode-locales. - - I have problems getting my input method working. - Try a search engine, as this is slightly different for every input - method server. - - Here is a checklist: - - - Make sure your locale *and* the imLocale are supported on your OS. - Try "locale -a" or check the documentation for your OS. - - - Make sure your locale or imLocale matches a locale supported by your - XIM. - For example, kinput2 does not support UTF-8 locales, you should use - "ja_JP.EUC-JP" or equivalent. - - - Make sure your XIM server is actually running. - - Make sure the "XMODIFIERS" environment variable is set correctly when - *starting* rxvt-unicode. - When you want to use e.g. kinput2, it must be set to "@im=kinput2". - For scim, use "@im=SCIM". You can see what input method servers are - running with this command: - - xprop -root XIM_SERVERS - - * - - My input method wants but I want UTF-8, what can I do? - You can specify separate locales for the input method and the rest of - the terminal, using the resource "imlocale": - - URxvt.imlocale: ja_JP.EUC-JP - - Now you can start your terminal with "LC_CTYPE=ja_JP.UTF-8" and still - use your input method. Please note, however, that, depending on your - Xlib version, you may not be able to input characters outside "EUC-JP" - in a normal way then, as your input method limits you. - - Rxvt-unicode crashes when the X Input Method changes or exits. - Unfortunately, this is unavoidable, as the XIM protocol is racy by - design. Applications can avoid some crashes at the expense of memory - leaks, and Input Methods can avoid some crashes by careful ordering at - exit time. kinput2 (and derived input methods) generally succeeds, while - SCIM (or similar input methods) fails. In the end, however, crashes - cannot be completely avoided even if both sides cooperate. - - So the only workaround is not to kill your Input Method Servers. - - Operating Systems / Package Maintaining - I am using Debian GNU/Linux and have a problem... - The Debian GNU/Linux package of rxvt-unicode in sarge contains large - patches that considerably change the behaviour of rxvt-unicode (but - unfortunately this notice has been removed). Before reporting a bug to - the original rxvt-unicode author please download and install the genuine - version () and try to reproduce - the problem. If you cannot, chances are that the problems are specific - to Debian GNU/Linux, in which case it should be reported via the Debian - Bug Tracking System (use "reportbug" to report the bug). - - For other problems that also affect the Debian package, you can and - probably should use the Debian BTS, too, because, after all, it's also a - bug in the Debian version and it serves as a reminder for other users - that might encounter the same issue. - - I am maintaining rxvt-unicode for distribution/OS XXX, any recommendation? - You should build one binary with the default options. configure now - enables most useful options, and the trend goes to making them - runtime-switchable, too, so there is usually no drawback to enabling - them, except higher disk and possibly memory usage. The perl interpreter - should be enabled, as important functionality (menus, selection, likely - more in the future) depends on it. - - You should not overwrite the "perl-ext-common" snd "perl-ext" resources - system-wide (except maybe with "defaults"). This will result in useful - behaviour. If your distribution aims at low memory, add an empty - "perl-ext-common" resource to the app-defaults file. This will keep the - perl interpreter disabled until the user enables it. - - If you can/want build more binaries, I recommend building a minimal one - with "--disable-everything" (very useful) and a maximal one with - "--enable-everything" (less useful, it will be very big due to a lot of - encodings built-in that increase download times and are rarely used). - - I need to make it setuid/setgid to support utmp/ptys on my OS, is this safe? - It should be, starting with release 7.1. You are encouraged to properly - install urxvt with privileges necessary for your OS now. - - When rxvt-unicode detects that it runs setuid or setgid, it will fork - into a helper process for privileged operations (pty handling on some - systems, utmp/wtmp/lastlog handling on others) and drop privileges - immediately. This is much safer than most other terminals that keep - privileges while running (but is more relevant to urxvt, as it contains - things as perl interpreters, which might be "helpful" to attackers). - - This forking is done as the very first within main(), which is very - early and reduces possible bugs to initialisation code run before - main(), or things like the dynamic loader of your system, which should - result in very little risk. - - I am on FreeBSD and rxvt-unicode does not seem to work at all. - Rxvt-unicode requires the symbol "__STDC_ISO_10646__" to be defined in - your compile environment, or an implementation that implements it, - whether it defines the symbol or not. "__STDC_ISO_10646__" requires that - wchar_t is represented as unicode. - - As you might have guessed, FreeBSD does neither define this symbol nor - does it support it. Instead, it uses its own internal representation of - wchar_t. This is, of course, completely fine with respect to standards. - - However, that means rxvt-unicode only works in "POSIX", "ISO-8859-1" and - "UTF-8" locales under FreeBSD (which all use Unicode as wchar_t. - - "__STDC_ISO_10646__" is the only sane way to support multi-language apps - in an OS, as using a locale-dependent (and non-standardized) - representation of wchar_t makes it impossible to convert between wchar_t - (as used by X11 and your applications) and any other encoding without - implementing OS-specific-wrappers for each and every locale. There - simply are no APIs to convert wchar_t into anything except the current - locale encoding. - - Some applications (such as the formidable mlterm) work around this by - carrying their own replacement functions for character set handling with - them, and either implementing OS-dependent hacks or doing multiple - conversions (which is slow and unreliable in case the OS implements - encodings slightly different than the terminal emulator). - - The rxvt-unicode author insists that the right way to fix this is in the - system libraries once and for all, instead of forcing every app to carry - complete replacements for them :) - - How can I use rxvt-unicode under cygwin? - rxvt-unicode should compile and run out of the box on cygwin, using the - X11 libraries that come with cygwin. libW11 emulation is no longer - supported (and makes no sense, either, as it only supported a single - font). I recommend starting the X-server in "-multiwindow" or - "-rootless" mode instead, which will result in similar look&feel as the - old libW11 emulation. - - At the time of this writing, cygwin didn't seem to support any - multi-byte encodings (you might try "LC_CTYPE=C-UTF-8"), so you are - likely limited to 8-bit encodings. - - Character widths are not correct. - urxvt uses the system wcwidth function to know the information about the - width of characters, so on systems with incorrect locale data you will - likely get bad results. Two notorious examples are Solaris 9, where - single-width characters like U+2514 are reported as double-width, and - Darwin 8, where combining chars are reported having width 1. - - The solution is to upgrade your system or switch to a better one. A - possibly working workaround is to use a wcwidth implementation like - - http://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c - -RXVT-UNICODE TECHNICAL REFERENCE - The rest of this document describes various technical aspects of - rxvt-unicode. First the description of supported command sequences, - followed by pixmap support and last by a description of all features - selectable at "configure" time. - - Definitions - "c" The literal character c. - - "C" A single (required) character. - - "Ps" - A single (usually optional) numeric parameter, composed of one or - more digits. - - "Pm" - A multiple numeric parameter composed of any number of single - numeric parameters, separated by ";" character(s). - - "Pt" - A text parameter composed of printable characters. - - Values - "ENQ" - Enquiry (Ctrl-E) = Send Device Attributes (DA) request attributes - from terminal. See "ESC [ Ps c". - - "BEL" - Bell (Ctrl-G) - - "BS" - Backspace (Ctrl-H) - - "TAB" - Horizontal Tab (HT) (Ctrl-I) - - "LF" - Line Feed or New Line (NL) (Ctrl-J) - - "VT" - Vertical Tab (Ctrl-K) same as "LF" - - "FF" - Form Feed or New Page (NP) (Ctrl-L) same as "LF" - - "CR" - Carriage Return (Ctrl-M) - - "SO" - Shift Out (Ctrl-N), invokes the G1 character set. Switch to - Alternate Character Set - - "SI" - Shift In (Ctrl-O), invokes the G0 character set (the default). - Switch to Standard Character Set - - "SPC" - Space Character - - Escape Sequences - "ESC # 8" - DEC Screen Alignment Test (DECALN) - - "ESC 7" - Save Cursor (SC) - - "ESC 8" - Restore Cursor - - "ESC =" - Application Keypad (SMKX). See also next sequence. - - "ESC" - Normal Keypad (RMKX) - - Note: If the numeric keypad is activated, eg, Num_Lock has been - pressed, numbers or control functions are generated by the numeric - keypad (see Key Codes). - - "ESC D" - Index (IND) - - "ESC E" - Next Line (NEL) - - "ESC H" - Tab Set (HTS) - - "ESC M" - Reverse Index (RI) - - "ESC N" - Single Shift Select of G2 Character Set (SS2): affects next - character only *unimplemented* - - "ESC O" - Single Shift Select of G3 Character Set (SS3): affects next - character only *unimplemented* - - "ESC Z" - Obsolete form of returns: "ESC [ ? 1 ; 2 C" *rxvt-unicode - compile-time option* - - "ESC c" - Full reset (RIS) - - "ESC n" - Invoke the G2 Character Set (LS2) - - "ESC o" - Invoke the G3 Character Set (LS3) - - "ESC ( C" - Designate G0 Character Set (ISO 2022), see below for values of "C". - - "ESC ) C" - Designate G1 Character Set (ISO 2022), see below for values of "C". - - "ESC * C" - Designate G2 Character Set (ISO 2022), see below for values of "C". - - "ESC + C" - Designate G3 Character Set (ISO 2022), see below for values of "C". - - "ESC $ C" - Designate Kanji Character Set - - Where "C" is one of: - - C = 0 DEC Special Character and Line Drawing Set - C = A United Kingdom (UK) - C = B United States (USASCII) - C = < Multinational character set unimplemented - C = 5 Finnish character set unimplemented - C = C Finnish character set unimplemented - C = K German character set unimplemented - - - - CSI (Command Sequence Introducer) Sequences - "ESC [ Ps @" - Insert "Ps" (Blank) Character(s) [default: 1] (ICH) - - "ESC [ Ps A" - Cursor Up "Ps" Times [default: 1] (CUU) - - "ESC [ Ps B" - Cursor Down "Ps" Times [default: 1] (CUD) - - "ESC [ Ps C" - Cursor Forward "Ps" Times [default: 1] (CUF) - - "ESC [ Ps D" - Cursor Backward "Ps" Times [default: 1] (CUB) - - "ESC [ Ps E" - Cursor Down "Ps" Times [default: 1] and to first column - - "ESC [ Ps F" - Cursor Up "Ps" Times [default: 1] and to first column - - "ESC [ Ps G" - Cursor to Column "Ps" (HPA) - - "ESC [ Ps;Ps H" - Cursor Position [row;column] [default: 1;1] (CUP) - - "ESC [ Ps I" - Move forward "Ps" tab stops [default: 1] - - "ESC [ Ps J" - Erase in Display (ED) - - Ps = 0 Clear Below (default) - Ps = 1 Clear Above - Ps = 2 Clear All - - "ESC [ Ps K" - Erase in Line (EL) - - Ps = 0 Clear to Right (default) - Ps = 1 Clear to Left - Ps = 2 Clear All - - "ESC [ Ps L" - Insert "Ps" Line(s) [default: 1] (IL) - - "ESC [ Ps M" - Delete "Ps" Line(s) [default: 1] (DL) - - "ESC [ Ps P" - Delete "Ps" Character(s) [default: 1] (DCH) - - "ESC [ Ps;Ps;Ps;Ps;Ps T" - Initiate . *unimplemented* Parameters are - [func;startx;starty;firstrow;lastrow]. - - "ESC [ Ps W" - Tabulator functions - - Ps = 0 Tab Set (HTS) - Ps = 2 Tab Clear (TBC), Clear Current Column (default) - Ps = 5 Tab Clear (TBC), Clear All - - "ESC [ Ps X" - Erase "Ps" Character(s) [default: 1] (ECH) - - "ESC [ Ps Z" - Move backward "Ps" [default: 1] tab stops - - "ESC [ Ps '" - See "ESC [ Ps G" - - "ESC [ Ps a" - See "ESC [ Ps C" - - "ESC [ Ps c" - Send Device Attributes (DA) "Ps = 0" (or omitted): request - attributes from terminal returns: "ESC [ ? 1 ; 2 c" (``I am a VT100 - with Advanced Video Option'') - - "ESC [ Ps d" - Cursor to Line "Ps" (VPA) - - "ESC [ Ps e" - See "ESC [ Ps A" - - "ESC [ Ps;Ps f" - Horizontal and Vertical Position [row;column] (HVP) [default: 1;1] - - "ESC [ Ps g" - Tab Clear (TBC) - - Ps = 0 Clear Current Column (default) - Ps = 3 Clear All (TBC) - - "ESC [ Pm h" - Set Mode (SM). See "ESC [ Pm l" sequence for description of "Pm". - - "ESC [ Ps i" - Printing. See also the "print-pipe" resource. - - Ps = 0 print screen (MC0) - Ps = 4 disable transparent print mode (MC4) - Ps = 5 enable transparent print mode (MC5) - - "ESC [ Pm l" - Reset Mode (RM) - - "Ps = 4" - h Insert Mode (SMIR) - l Replace Mode (RMIR) - - "Ps = 20" (partially implemented) - h Automatic Newline (LNM) - l Normal Linefeed (LNM) - - "ESC [ Pm m" - Character Attributes (SGR) - - Ps = 0 Normal (default) - Ps = 1 / 21 On / Off Bold (bright fg) - Ps = 3 / 23 On / Off Italic - Ps = 4 / 24 On / Off Underline - Ps = 5 / 25 On / Off Slow Blink (bright bg) - Ps = 6 / 26 On / Off Rapid Blink (bright bg) - Ps = 7 / 27 On / Off Inverse - Ps = 8 / 27 On / Off Invisible (NYI) - Ps = 30 / 40 fg/bg Black - Ps = 31 / 41 fg/bg Red - Ps = 32 / 42 fg/bg Green - Ps = 33 / 43 fg/bg Yellow - Ps = 34 / 44 fg/bg Blue - Ps = 35 / 45 fg/bg Magenta - Ps = 36 / 46 fg/bg Cyan - Ps = 38;5 / 48;5 set fg/bg to color #m (ISO 8613-6) - Ps = 37 / 47 fg/bg White - Ps = 39 / 49 fg/bg Default - Ps = 90 / 100 fg/bg Bright Black - Ps = 91 / 101 fg/bg Bright Red - Ps = 92 / 102 fg/bg Bright Green - Ps = 93 / 103 fg/bg Bright Yellow - Ps = 94 / 104 fg/bg Bright Blue - Ps = 95 / 105 fg/bg Bright Magenta - Ps = 96 / 106 fg/bg Bright Cyan - Ps = 97 / 107 fg/bg Bright White - Ps = 99 / 109 fg/bg Bright Default - - "ESC [ Ps n" - Device Status Report (DSR) - - Ps = 5 Status Report ESC [ 0 n (``OK'') - Ps = 6 Report Cursor Position (CPR) [row;column] as ESC [ r ; c R - Ps = 7 Request Display Name - Ps = 8 Request Version Number (place in window title) - - "ESC [ Ps;Ps r" - Set Scrolling Region [top;bottom] [default: full size of window] - (CSR) - - "ESC [ s" - Save Cursor (SC) - - "ESC [ Ps;Pt t" - Window Operations - - Ps = 1 Deiconify (map) window - Ps = 2 Iconify window - Ps = 3 ESC [ 3 ; X ; Y t Move window to (X|Y) - Ps = 4 ESC [ 4 ; H ; W t Resize to WxH pixels - Ps = 5 Raise window - Ps = 6 Lower window - Ps = 7 Refresh screen once - Ps = 8 ESC [ 8 ; R ; C t Resize to R rows and C columns - Ps = 11 Report window state (responds with Ps = 1 or Ps = 2) - Ps = 13 Report window position (responds with Ps = 3) - Ps = 14 Report window pixel size (responds with Ps = 4) - Ps = 18 Report window text size (responds with Ps = 7) - Ps = 19 Currently the same as Ps = 18, but responds with Ps = 9 - Ps = 20 Reports icon label (ESC ] L NAME \234) - Ps = 21 Reports window title (ESC ] l NAME \234) - Ps = 24.. Set window height to Ps rows - - "ESC [ u" - Restore Cursor - - "ESC [ Ps x" - Request Terminal Parameters (DECREQTPARM) - - - - DEC Private Modes - "ESC [ ? Pm h" - DEC Private Mode Set (DECSET) - - "ESC [ ? Pm l" - DEC Private Mode Reset (DECRST) - - "ESC [ ? Pm r" - Restore previously saved DEC Private Mode Values. - - "ESC [ ? Pm s" - Save DEC Private Mode Values. - - "ESC [ ? Pm t" - Toggle DEC Private Mode Values (rxvt extension). *where* - - "Pm = 1" (DECCKM) - h Application Cursor Keys - l Normal Cursor Keys - - "Pm = 2" (ANSI/VT52 mode) - h Enter VT52 mode - l Enter VT52 mode - - "Pm = 3" - h 132 Column Mode (DECCOLM) - l 80 Column Mode (DECCOLM) - - "Pm = 4" - h Smooth (Slow) Scroll (DECSCLM) - l Jump (Fast) Scroll (DECSCLM) - - "Pm = 5" - h Reverse Video (DECSCNM) - l Normal Video (DECSCNM) - - "Pm = 6" - h Origin Mode (DECOM) - l Normal Cursor Mode (DECOM) - - "Pm = 7" - h Wraparound Mode (DECAWM) - l No Wraparound Mode (DECAWM) - - "Pm = 8" *unimplemented* - h Auto-repeat Keys (DECARM) - l No Auto-repeat Keys (DECARM) - - "Pm = 9" X10 XTerm - h Send Mouse X & Y on button press. - l No mouse reporting. - - "Pm = 25" - h Visible cursor {cnorm/cvvis} - l Invisible cursor {civis} - - "Pm = 30" - h scrollBar visisble - l scrollBar invisisble - - "Pm = 35" (rxvt) - h Allow XTerm Shift+key sequences - l Disallow XTerm Shift+key sequences - - "Pm = 38" *unimplemented* - Enter Tektronix Mode (DECTEK) - - "Pm = 40" - h Allow 80/132 Mode - l Disallow 80/132 Mode - - "Pm = 44" *unimplemented* - h Turn On Margin Bell - l Turn Off Margin Bell - - "Pm = 45" *unimplemented* - h Reverse-wraparound Mode - l No Reverse-wraparound Mode - - "Pm = 46" *unimplemented* - "Pm = 47" - h Use Alternate Screen Buffer - l Use Normal Screen Buffer - - - - "Pm = 66" - h Application Keypad (DECPAM) == ESC = - l Normal Keypad (DECPNM) == ESC > - - "Pm = 67" - h Backspace key sends BS (DECBKM) - l Backspace key sends DEL - - "Pm = 1000" (X11 XTerm) - h Send Mouse X & Y on button press and release. - l No mouse reporting. - - "Pm = 1001" (X11 XTerm) *unimplemented* - h Use Hilite Mouse Tracking. - l No mouse reporting. - - "Pm = 1002" (X11 XTerm) - h Send Mouse X & Y on button press and release, and motion with a button pressed. - l No mouse reporting. - - "Pm = 1003" (X11 XTerm) - h Send Mouse X & Y on button press and release, and motion. - l No mouse reporting. - - "Pm = 1010" (rxvt) - h Don't scroll to bottom on TTY output - l Scroll to bottom on TTY output - - "Pm = 1011" (rxvt) - h Scroll to bottom when a key is pressed - l Don't scroll to bottom when a key is pressed - - "Pm = 1021" (rxvt) - h Bold/italic implies high intensity (see option -is) - l Font styles have no effect on intensity (Compile styles) - - "Pm = 1047" - h Use Alternate Screen Buffer - l Use Normal Screen Buffer - clear Alternate Screen Buffer if returning from it - - "Pm = 1048" - h Save cursor position - l Restore cursor position - - "Pm = 1049" - h Use Alternate Screen Buffer - clear Alternate Screen Buffer if switching to it - l Use Normal Screen Buffer - - - - XTerm Operating System Commands - "ESC ] Ps;Pt ST" - Set XTerm Parameters. 8-bit ST: 0x9c, 7-bit ST sequence: ESC \ - (0x1b, 0x5c), backwards compatible terminator BEL (0x07) is also - accepted. any octet can be escaped by prefixing it with SYN (0x16, - ^V). - - Ps = 0 Change Icon Name and Window Title to Pt - Ps = 1 Change Icon Name to Pt - Ps = 2 Change Window Title to Pt - Ps = 3 If Pt starts with a ?, query the (STRING) property of the window and return it. If Pt contains a =, set the named property to the given value, else delete the specified property. - Ps = 4 Pt is a semi-colon separated sequence of one or more semi-colon separated number/name pairs, where number is an index to a colour and name is the name of a colour. Each pair causes the numbered colour to be changed to name. Numbers 0-7 corresponds to low-intensity (normal) colours and 8-15 corresponds to high-intensity colours. 0=black, 1=red, 2=green, 3=yellow, 4=blue, 5=magenta, 6=cyan, 7=white - Ps = 10 Change colour of text foreground to Pt (NB: may change in future) - Ps = 11 Change colour of text background to Pt (NB: may change in future) - Ps = 12 Change colour of text cursor foreground to Pt - Ps = 13 Change colour of mouse foreground to Pt - Ps = 17 Change colour of highlight characters to Pt - Ps = 18 Change colour of bold characters to Pt [deprecated, see 706] - Ps = 19 Change colour of underlined characters to Pt [deprecated, see 707] - Ps = 20 Change background pixmap parameters (see section BACKGROUND IMAGE) (Compile AfterImage). - Ps = 39 Change default foreground colour to Pt. - Ps = 46 Change Log File to Pt unimplemented - Ps = 49 Change default background colour to Pt. - Ps = 50 Set fontset to Pt, with the following special values of Pt (rxvt) #+n change up n #-n change down n if n is missing of 0, a value of 1 is used empty change to font0 n change to font n - Ps = 55 Log all scrollback buffer and all of screen to Pt - Ps = 701 Change current locale to Pt, or, if Pt is ?, return the current locale (Compile frills). - Ps = 702 Request version if Pt is ?, returning rxvt-unicode, the resource name, the major and minor version numbers, e.g. ESC ] 702 ; rxvt-unicode ; urxvt ; 7 ; 4 ST. - Ps = 704 Change colour of italic characters to Pt - Ps = 705 Change background pixmap tint colour to Pt (Compile transparency). - Ps = 706 Change colour of bold characters to Pt - Ps = 707 Change colour of underlined characters to Pt - Ps = 710 Set normal fontset to Pt. Same as Ps = 50. - Ps = 711 Set bold fontset to Pt. Similar to Ps = 50 (Compile styles). - Ps = 712 Set italic fontset to Pt. Similar to Ps = 50 (Compile styles). - Ps = 713 Set bold-italic fontset to Pt. Similar to Ps = 50 (Compile styles). - Ps = 720 Move viewing window up by Pt lines, or clear scrollback buffer if Pt = 0 (Compile frills). - Ps = 721 Move viewing window down by Pt lines, or clear scrollback buffer if Pt = 0 (Compile frills). - Ps = 777 Call the perl extension with the given string, which should be of the form extension:parameters (Compile perl). - -BACKGROUND IMAGE - For the BACGROUND IMAGE XTerm escape sequence "ESC ] 20 ; Pt ST" then - value of "Pt" can be the name of the background image file followed by a - sequence of scaling/positioning commands separated by semi-colons. The - scaling/positioning commands are as follows: - - query scale/position - ? - - change scale and position - WxH+X+Y - - WxH+X (== WxH+X+X) - - WxH (same as WxH+50+50) - - W+X+Y (same as WxW+X+Y) - - W+X (same as WxW+X+X) - - W (same as WxW+50+50) - - change position (absolute) - =+X+Y - - =+X (same as =+X+Y) - - change position (relative) - +X+Y - - +X (same as +X+Y) - - rescale (relative) - Wx0 -> W *= (W/100) - - 0xH -> H *= (H/100) - - For example: - - \E]20;funky.jpg\a - load funky.jpg as a tiled image - - \E]20;mona.jpg;100\a - load mona.jpg with a scaling of 100% - - \E]20;;200;?\a - rescale the current pixmap to 200% and display the image geometry in - the title - -Mouse Reporting - "ESC [ M " - report mouse position - - The lower 2 bits of "" indicate the button: - - Button = "( - SPACE) & 3" - 0 Button1 pressed - 1 Button2 pressed - 2 Button3 pressed - 3 button released (X11 mouse report) - - The upper bits of "" indicate the modifiers when the button was - pressed and are added together (X11 mouse report only): - - State = "( - SPACE) & 60" - 4 Shift - 8 Meta - 16 Control - 32 Double Click (rxvt extension) - - Col = " - SPACE" - - Row = " - SPACE" - -Key Codes - Note: Shift + F1-F10 generates F11-F20 - - For the keypad, use Shift to temporarily override Application-Keypad - setting use Num_Lock to toggle Application-Keypad setting if Num_Lock is - off, toggle Application-Keypad setting. Also note that values of Home, - End, Delete may have been compiled differently on your system. - - Normal Shift Control Ctrl+Shift - Tab ^I ESC [ Z ^I ESC [ Z - BackSpace ^H ^? ^? ^? - Find ESC [ 1 ~ ESC [ 1 $ ESC [ 1 ^ ESC [ 1 @ - Insert ESC [ 2 ~ paste ESC [ 2 ^ ESC [ 2 @ - Execute ESC [ 3 ~ ESC [ 3 $ ESC [ 3 ^ ESC [ 3 @ - Select ESC [ 4 ~ ESC [ 4 $ ESC [ 4 ^ ESC [ 4 @ - Prior ESC [ 5 ~ scroll-up ESC [ 5 ^ ESC [ 5 @ - Next ESC [ 6 ~ scroll-down ESC [ 6 ^ ESC [ 6 @ - Home ESC [ 7 ~ ESC [ 7 $ ESC [ 7 ^ ESC [ 7 @ - End ESC [ 8 ~ ESC [ 8 $ ESC [ 8 ^ ESC [ 8 @ - Delete ESC [ 3 ~ ESC [ 3 $ ESC [ 3 ^ ESC [ 3 @ - F1 ESC [ 11 ~ ESC [ 23 ~ ESC [ 11 ^ ESC [ 23 ^ - F2 ESC [ 12 ~ ESC [ 24 ~ ESC [ 12 ^ ESC [ 24 ^ - F3 ESC [ 13 ~ ESC [ 25 ~ ESC [ 13 ^ ESC [ 25 ^ - F4 ESC [ 14 ~ ESC [ 26 ~ ESC [ 14 ^ ESC [ 26 ^ - F5 ESC [ 15 ~ ESC [ 28 ~ ESC [ 15 ^ ESC [ 28 ^ - F6 ESC [ 17 ~ ESC [ 29 ~ ESC [ 17 ^ ESC [ 29 ^ - F7 ESC [ 18 ~ ESC [ 31 ~ ESC [ 18 ^ ESC [ 31 ^ - F8 ESC [ 19 ~ ESC [ 32 ~ ESC [ 19 ^ ESC [ 32 ^ - F9 ESC [ 20 ~ ESC [ 33 ~ ESC [ 20 ^ ESC [ 33 ^ - F10 ESC [ 21 ~ ESC [ 34 ~ ESC [ 21 ^ ESC [ 34 ^ - F11 ESC [ 23 ~ ESC [ 23 $ ESC [ 23 ^ ESC [ 23 @ - F12 ESC [ 24 ~ ESC [ 24 $ ESC [ 24 ^ ESC [ 24 @ - F13 ESC [ 25 ~ ESC [ 25 $ ESC [ 25 ^ ESC [ 25 @ - F14 ESC [ 26 ~ ESC [ 26 $ ESC [ 26 ^ ESC [ 26 @ - F15 (Help) ESC [ 28 ~ ESC [ 28 $ ESC [ 28 ^ ESC [ 28 @ - F16 (Menu) ESC [ 29 ~ ESC [ 29 $ ESC [ 29 ^ ESC [ 29 @ - F17 ESC [ 31 ~ ESC [ 31 $ ESC [ 31 ^ ESC [ 31 @ - F18 ESC [ 32 ~ ESC [ 32 $ ESC [ 32 ^ ESC [ 32 @ - F19 ESC [ 33 ~ ESC [ 33 $ ESC [ 33 ^ ESC [ 33 @ - F20 ESC [ 34 ~ ESC [ 34 $ ESC [ 34 ^ ESC [ 34 @ - Application - Up ESC [ A ESC [ a ESC O a ESC O A - Down ESC [ B ESC [ b ESC O b ESC O B - Right ESC [ C ESC [ c ESC O c ESC O C - Left ESC [ D ESC [ d ESC O d ESC O D - KP_Enter ^M ESC O M - KP_F1 ESC O P ESC O P - KP_F2 ESC O Q ESC O Q - KP_F3 ESC O R ESC O R - KP_F4 ESC O S ESC O S - XK_KP_Multiply * ESC O j - XK_KP_Add + ESC O k - XK_KP_Separator , ESC O l - XK_KP_Subtract - ESC O m - XK_KP_Decimal . ESC O n - XK_KP_Divide / ESC O o - XK_KP_0 0 ESC O p - XK_KP_1 1 ESC O q - XK_KP_2 2 ESC O r - XK_KP_3 3 ESC O s - XK_KP_4 4 ESC O t - XK_KP_5 5 ESC O u - XK_KP_6 6 ESC O v - XK_KP_7 7 ESC O w - XK_KP_8 8 ESC O x - XK_KP_9 9 ESC O y - -CONFIGURE OPTIONS - General hint: if you get compile errors, then likely your configuration - hasn't been tested well. Either try with "--enable-everything" or use - the default configuration (i.e. no "--enable-xxx" or "--disable-xxx" - switches). Of course, you should always report when a combination - doesn't work, so it can be fixed. Marc Lehmann . - - All - - --enable-everything - Add (or remove) support for all non-multichoice options listed in - "./configure --help". - - You can specify this and then disable options you do not like by - *following* this with the appropriate "--disable-..." arguments, or - you can start with a minimal configuration by specifying - "--disable-everything" and than adding just the "--enable-..." - arguments you want. - - --enable-xft (default: enabled) - Add support for Xft (anti-aliases, among others) fonts. Xft fonts - are slower and require lots of memory, but as long as you don't use - them, you don't pay for them. - - --enable-font-styles (default: on) - Add support for bold, *italic* and *bold italic* font styles. The - fonts can be set manually or automatically. - - --with-codesets=NAME,... (default: all) - Compile in support for additional codeset (encoding) groups ("eu", - "vn" are always compiled in, which includes most 8-bit character - sets). These codeset tables are used for driving X11 core fonts, - they are not required for Xft fonts, although having them compiled - in lets rxvt-unicode choose replacement fonts more intelligently. - Compiling them in will make your binary bigger (all of together cost - about 700kB), but it doesn't increase memory usage unless you use a - font requiring one of these encodings. - - all all available codeset groups - zh common chinese encodings - zh_ext rarely used but very big chinese encodings - jp common japanese encodings - jp_ext rarely used but big japanese encodings - kr korean encodings - - --enable-xim (default: on) - Add support for XIM (X Input Method) protocol. This allows using - alternative input methods (e.g. kinput2) and will also correctly set - up the input for people using dead keys or compose keys. - - --enable-unicode3 (default: off) - Recommended to stay off unless you really need non-BMP characters. - - Enable direct support for displaying unicode codepoints above 65535 - (the basic multilingual page). This increases storage requirements - per character from 2 to 4 bytes. X11 fonts do not yet support these - extra characters, but Xft does. - - Please note that rxvt-unicode can store unicode code points >65535 - even without this flag, but the number of such characters is limited - to a few thousand (shared with combining characters, see next - switch), and right now rxvt-unicode cannot display them - (input/output and cut&paste still work, though). - - --enable-combining (default: on) - Enable automatic composition of combining characters into composite - characters. This is required for proper viewing of text where - accents are encoded as seperate unicode characters. This is done by - using precomposited characters when available or creating new - pseudo-characters when no precomposed form exists. - - Without --enable-unicode3, the number of additional precomposed - characters is somewhat limited (the 6400 private use characters will - be (ab-)used). With --enable-unicode3, no practical limit exists. - - This option will also enable storage (but not display) of characters - beyond plane 0 (>65535) when --enable-unicode3 was not specified. - - The combining table also contains entries for arabic presentation - forms, but these are not currently used. Bug me if you want these to - be used (and tell me how these are to be used...). - - --enable-fallback(=CLASS) (default: Rxvt) - When reading resource settings, also read settings for class CLASS. - To disable resource fallback use --disable-fallback. - - --with-res-name=NAME (default: urxvt) - Use the given name as default application name when reading - resources. Specify --with-res-name=rxvt to replace rxvt. - - --with-res-class=CLASS /default: URxvt) - Use the given class as default application class when reading - resources. Specify --with-res-class=Rxvt to replace rxvt. - - --enable-utmp (default: on) - Write user and tty to utmp file (used by programs like w) at start - of rxvt execution and delete information when rxvt exits. - - --enable-wtmp (default: on) - Write user and tty to wtmp file (used by programs like last) at - start of rxvt execution and write logout when rxvt exits. This - option requires --enable-utmp to also be specified. - - --enable-lastlog (default: on) - Write user and tty to lastlog file (used by programs like lastlogin) - at start of rxvt execution. This option requires --enable-utmp to - also be specified. - - --enable-afterimage (default: on) - Add support for libAfterImage to be used for transparency and - background images. It adds support for many file formats including - JPG, PNG, SVG, TIFF, GIF, XPM, BMP, ICO, XCF, TGA and AfterStep - image XML - (). - - This option also adds such eye candy as blending an image over the - root background, as well as dynamic scaling and bluring of - background images. - - Note that with this option enabled, rxvt's memory footprint might - increase by a few megabytes even if no extra features are used - (mostly due to third-party libraries used by libAI). Memory - footprint may somewhat be lowered if libAfterImage is configured - without support for SVG. - - --enable-transparency (default: on) - Add support for backgrounds, creating illusion of transparency in - the term. - - --enable-fading (default: on) - Add support for fading the text when focus is lost. - - --enable-rxvt-scroll (default: on) - Add support for the original rxvt scrollbar. - - --enable-next-scroll (default: on) - Add support for a NeXT-like scrollbar. - - --enable-xterm-scroll (default: on) - Add support for an Xterm-like scrollbar. - - --enable-plain-scroll (default: on) - Add support for a very unobtrusive, plain-looking scrollbar that is - the favourite of the rxvt-unicode author, having used it for many - years. - - --enable-ttygid (default: off) - Change tty device setting to group "tty" - only use this if your - system uses this type of security. - - --disable-backspace-key - Removes any handling of the backspace key by us - let the X server - do it. - - --disable-delete-key - Removes any handling of the delete key by us - let the X server do - it. - - --disable-resources - Removes any support for resource checking. - - --disable-swapscreen - Remove support for secondary/swap screen. - - --enable-frills (default: on) - Add support for many small features that are not essential but nice - to have. Normally you want this, but for very small binaries you may - want to disable this. - - A non-exhaustive list of features enabled by "--enable-frills" - (possibly in combination with other switches) is: - - MWM-hints - EWMH-hints (pid, utf8 names) and protocols (ping) - urgency hint - seperate underline colour (-underlineColor) - settable border widths and borderless switch (-w, -b, -bl) - visual depth selection (-depth) - settable extra linespacing /-lsp) - iso-14755 5.1 (basic) support - tripleclickwords (-tcw) - settable insecure mode (-insecure) - keysym remapping support - cursor blinking and underline cursor (-cb, -uc) - XEmbed support (-embed) - user-pty (-pty-fd) - hold on exit (-hold) - compile in built-in block graphics - skip builtin block graphics (-sbg) - separate highlightcolor support (-hc) - - It also enables some non-essential features otherwise disabled, such - as: - - some round-trip time optimisations - nearest color allocation on pseudocolor screens - UTF8_STRING support for selection - sgr modes 90..97 and 100..107 - backindex and forwardindex escape sequences - view change/zero scrollback escape sequences - locale switching escape sequence - window op and some xterm/OSC escape sequences - rectangular selections - trailing space removal for selections - verbose X error handling - - --enable-iso14755 (default: on) - Enable extended ISO 14755 support (see rxvt(1), or doc/rxvt.1.txt). - Basic support (section 5.1) is enabled by "--enable-frills", while - support for 5.2, 5.3 and 5.4 is enabled with this switch. - - --enable-keepscrolling (default: on) - Add support for continual scrolling of the display when you hold the - mouse button down on a scrollbar arrow. - - --enable-selectionscrolling (default: on) - Add support for scrolling when the selection moves to the top or - bottom of the screen. - - --enable-mousewheel (default: on) - Add support for scrolling via mouse wheel or buttons 4 & 5. - - --enable-slipwheeling (default: on) - Add support for continual scrolling (using the mouse wheel as an - accelerator) while the control key is held down. This option - requires --enable-mousewheel to also be specified. - - --enable-smart-resize (default: off) - Add smart growth/shrink behaviour when resizing. This should keep - the window corner which is closest to a corner of the screen in a - fixed position. - - --enable-pointer-blank (default: on) - Add support to have the pointer disappear when typing or inactive. - - --enable-perl (default: on) - Enable an embedded perl interpreter. See the rxvtperl(3) manpage - (doc/rxvtperl.txt) for more info on this feature, or the files in - src/perl-ext/ for the extensions that are installed by default. The - perl interpreter that is used can be specified via the "PERL" - environment variable when running configure. Even when compiled in, - perl will *not* be initialised when all extensions have been - disabled "-pe "" --perl-ext-common """, so it should be safe to - enable from a resource standpoint. - - --with-afterimage-config=DIR - Look for the libAfterImage config script in DIR. - - --with-name=NAME (default: urxvt) - Set the basename for the installed binaries, resulting in "urxvt", - "urxvtd" etc.). Specify "--with-name=rxvt" to replace with "rxvt". - - --with-term=NAME (default: rxvt-unicode) - Change the environmental variable for the terminal to NAME. - - --with-terminfo=PATH - Change the environmental variable for the path to the terminfo tree - to PATH. - - --with-x - Use the X Window System (pretty much default, eh?). - -AUTHORS - Marc Lehmann converted this document to pod and - reworked it from the original Rxvt documentation, which was done by - Geoff Wing , who in turn used the XTerm documentation and - other sources. - diff --git a/doc/rxvtc.1.html b/doc/rxvtc.1.html deleted file mode 100644 index 21148f8a..00000000 --- a/doc/rxvtc.1.html +++ /dev/null @@ -1,97 +0,0 @@ - - - - - urxvtc - - - - - - - -
- -

Index

- -
- - -

NAME

Top

-
-

urxvtc - control the urxvtd daemon

- -
-

SYNOPSIS

Top

-
-

urxvtc [same options as for urxvt]

- -
-

DESCRIPTION

Top

-
-

This manpage describes the urxvtc client program. It connects -to the urxvtd daemon and requests a new terminal window. It -takes the same arguments as the urxvt program. The environment -will also be respected. Currently, it always returns immediately after -contacting the daemon.

- -
-

OPTIONS

Top

-
-

All options that are valid for urxvt are valid for -urxvtc, too. Please note that options are interpreted in the -context of the daemon process. However, as current working directory, -process environment and any file descriptor (e.g. for -pty-fd) are -preserved, this rarely makes a difference.

- -
-

EXIT STATUS

Top

-
-

If everything went well, urxvtc returns with an exit status of 0. -If contacting the daemon fails, it exits with the exit status 2. In all other error -cases it returns with status 1.

-

This can be used to implement auto-starting behaviour, by checking for an -exit status of 2, running urxvtd -f -q and retrying the call -to urxvtc, like this:

-
   #!/bin/sh
-   urxvtc "$@"
-   if [ $? -eq 2 ]; then
-      urxvtd -q -o -f
-      urxvtc "$@"
-   fi
-
-
- -
-

ENVIRONMENT

Top

-
-

All environment variables of the current process will be made available -to the new instance, and will be interpreted as if urxvt were -started directly.

-
-
RXVT_SOCKET
-
-

Both urxvtc and urxvtd use the environment variable -RXVT_SOCKET to create a listening socket and to contact the -urxvtd, respectively. If the variable is missing, -$HOME/.rxvt-unicode-<nodename> is used. The variable must -specify the absolute path of the socket to create.

-
-
- -
-

SEE ALSO

Top

-
-

urxvt(7), urxvtd(1)

- -
-
- diff --git a/doc/rxvtc.1.txt b/doc/rxvtc.1.txt deleted file mode 100644 index 88ceb4bf..00000000 --- a/doc/rxvtc.1.txt +++ /dev/null @@ -1,50 +0,0 @@ -NAME - urxvtc - control the urxvtd daemon - -SYNOPSIS - urxvtc [same options as for urxvt] - -DESCRIPTION - This manpage describes the urxvtc client program. It connects to the - urxvtd daemon and requests a new terminal window. It takes the same - arguments as the urxvt program. The environment will also be respected. - Currently, it always returns immediately after contacting the daemon. - -OPTIONS - All options that are valid for urxvt are valid for urxvtc, too. Please - note that options are interpreted in the context of the daemon process. - However, as current working directory, process environment and any file - descriptor (e.g. for "-pty-fd") are preserved, this rarely makes a - difference. - -EXIT STATUS - If everything went well, urxvtc returns with an exit status of 0. If - contacting the daemon fails, it exits with the exit status 2. In all - other error cases it returns with status 1. - - This can be used to implement auto-starting behaviour, by checking for - an exit status of 2, running "urxvtd -f -q" and retrying the call to - urxvtc, like this: - - #!/bin/sh - urxvtc "$@" - if [ $? -eq 2 ]; then - urxvtd -q -o -f - urxvtc "$@" - fi - -ENVIRONMENT - All environment variables of the current process will be made available - to the new instance, and will be interpreted as if urxvt were started - directly. - - RXVT_SOCKET - Both urxvtc and urxvtd use the environment variable RXVT_SOCKET to - create a listening socket and to contact the urxvtd, respectively. - If the variable is missing, $HOME/.rxvt-unicode-** is - used. The variable must specify the absolute path of the socket to - create. - -SEE ALSO - urxvt(7), urxvtd(1) - diff --git a/doc/rxvtd.1.html b/doc/rxvtd.1.html deleted file mode 100644 index 5ef0a4a1..00000000 --- a/doc/rxvtd.1.html +++ /dev/null @@ -1,121 +0,0 @@ - - - - - urxvtd - - - - - - - -
- -

Index

- -
- - -

NAME

Top

-
-

urxvtd - urxvt terminal daemon

- -
-

SYNOPSIS

Top

-
-

urxvtd [-q|--quiet] [-o|--opendisplay] [-f|--fork]

-

urxvtd -q -o -f # for .xsession use

- -
-

DESCRIPTION

Top

-
-

This manpage describes the urxvtd daemon, which is the same vt102 -terminal emulator as urxvt, but runs as a daemon that can open -multiple terminal windows within the same process.

-

You can run it from your X startup scripts, for example, although it is -not dependent on a working DISPLAY and, in fact, can open windows on -multiple X displays on the same time.

-

Advantages of running a urxvt daemon include faster creation time -for terminal windows and a lot of saved memory.

-

The disadvantage is a possible impact on stability - if the -main program crashes, all processes in the terminal windows are -terminated. For example, as there is no way to cleanly react to abnormal -connection closes, xkill and server resets/restarts will kill the -urxvtd instance including all windows it has opened.

- -
-

OPTIONS

Top

-
-

urxvtd currently understands a few options only. Bundling of -options is not yet supported.

-
-
-q, --quiet
-
-

Normally, urxvtd outputs the message rxvt-unicode daemon -listening on <path> after binding to its control socket. This option -will suppress this message (errors and warnings will still be logged).

-
-
-o, --opendisplay
-
-

This forces urxvtd to open a connection to the current -$DISPLAY and keep it open.

-

This is useful if you want to bind an instance of urxvtd to -the lifetime of a specific display/server. If the server does a reset, -urxvtd will be killed automatically.

-
-
-f, --fork
-
-

This makes urxvtd fork after it has bound itself to its control -socket.

-
-
- -
-

EXAMPLES

Top

-
-

This is a useful invocation of urxvtd in a .xsession-style -script:

-
   urxvtd -q -f -o
-
-
-

This waits till the control socket is available, opens the current display -and forks into the background. When you log-out, the server is reset and -urxvtd is killed.

- -
-

ENVIRONMENT

Top

-
-
-
RXVT_SOCKET
-
-

Both urxvtc and urxvtd use the environment -variable RXVT_SOCKET to create a listening socket and to contact -the urxvtd, respectively. If the variable is missing, -$HOME/.rxvt-unicode-<nodename> is used. The variable must -specify the absolute path of the socket to create.

-
-
DISPLAY
-
-

Only used when the --opendisplay option is specified. Must contain a -valid X display name.

-
-
- -
-

SEE ALSO

Top

-
-

urxvt(7), urxvtc(1) -

- -
-
- diff --git a/doc/rxvtd.1.txt b/doc/rxvtd.1.txt deleted file mode 100644 index bbe2408f..00000000 --- a/doc/rxvtd.1.txt +++ /dev/null @@ -1,71 +0,0 @@ -NAME - urxvtd - urxvt terminal daemon - -SYNOPSIS - urxvtd [-q|--quiet] [-o|--opendisplay] [-f|--fork] - - urxvtd -q -o -f # for .xsession use - -DESCRIPTION - This manpage describes the urxvtd daemon, which is the same vt102 - terminal emulator as urxvt, but runs as a daemon that can open multiple - terminal windows within the same process. - - You can run it from your X startup scripts, for example, although it is - not dependent on a working DISPLAY and, in fact, can open windows on - multiple X displays on the same time. - - Advantages of running a urxvt daemon include faster creation time for - terminal windows and a lot of saved memory. - - The disadvantage is a possible impact on stability - if the main program - crashes, all processes in the terminal windows are terminated. For - example, as there is no way to cleanly react to abnormal connection - closes, "xkill" and server resets/restarts will kill the urxvtd instance - including all windows it has opened. - -OPTIONS - urxvtd currently understands a few options only. Bundling of options is - not yet supported. - - -q, --quiet - Normally, urxvtd outputs the message "rxvt-unicode daemon listening - on " after binding to its control socket. This option will - suppress this message (errors and warnings will still be logged). - - -o, --opendisplay - This forces urxvtd to open a connection to the current $DISPLAY and - keep it open. - - This is useful if you want to bind an instance of urxvtd to the - lifetime of a specific display/server. If the server does a reset, - urxvtd will be killed automatically. - - -f, --fork - This makes urxvtd fork after it has bound itself to its control - socket. - -EXAMPLES - This is a useful invocation of urxvtd in a .xsession-style script: - - urxvtd -q -f -o - - This waits till the control socket is available, opens the current - display and forks into the background. When you log-out, the server is - reset and urxvtd is killed. - -ENVIRONMENT - RXVT_SOCKET - Both urxvtc and urxvtd use the environment variable RXVT_SOCKET to - create a listening socket and to contact the urxvtd, respectively. - If the variable is missing, $HOME/.rxvt-unicode-** is - used. The variable must specify the absolute path of the socket to - create. - - DISPLAY - Only used when the "--opendisplay" option is specified. Must contain - a valid X display name. - -SEE ALSO - urxvt(7), urxvtc(1) - diff --git a/doc/rxvtperl.3.html b/doc/rxvtperl.3.html deleted file mode 100644 index a91d2e8d..00000000 --- a/doc/rxvtperl.3.html +++ /dev/null @@ -1,1504 +0,0 @@ - - - - - rxvtperl - - - - - - - -
- -

Index

- -
- - -

NAME

Top

-
-

rxvtperl - rxvt-unicode's embedded perl interpreter

- -
-

SYNOPSIS

Top

-
-
   # create a file grab_test in $HOME:
-
-   sub on_sel_grab {
-      warn "you selected ", $_[0]->selection;
-      ()
-   }
-
-   # start a rxvt using it:
-
-   rxvt --perl-lib $HOME -pe grab_test
-
-
- -
-

DESCRIPTION

Top

-
-

Every time a terminal object gets created, extension scripts specified via -the perl resource are loaded and associated with it.

-

Scripts are compiled in a 'use strict' and 'use utf8' environment, and -thus must be encoded as UTF-8.

-

Each script will only ever be loaded once, even in rxvtd, where -scripts will be shared (but not enabled) for all terminals.

-

You can disable the embedded perl interpreter by setting both "perl-ext" -and "perl-ext-common" resources to the empty string.

- -
-

PREPACKAGED EXTENSIONS

Top

-
-

This section describes the extensions delivered with this release. You can -find them in /opt/rxvt/lib/urxvt/perl/.

-

You can activate them like this:

-
  rxvt -pe <extensionname>
-
-
-

Or by adding them to the resource for extensions loaded by default:

-
  URxvt.perl-ext-common: default,selection-autotransform
-
-
-
-
selection (enabled by default)
-
-

(More) intelligent selection. This extension tries to be more intelligent -when the user extends selections (double-click and further clicks). Right -now, it tries to select words, urls and complete shell-quoted -arguments, which is very convenient, too, if your ls supports ---quoting-style=shell.

-

A double-click usually selects the word under the cursor, further clicks -will enlarge the selection.

-

The selection works by trying to match a number of regexes and displaying -them in increasing order of length. You can add your own regexes by -specifying resources of the form:

-
   URxvt.selection.pattern-0: perl-regex
-   URxvt.selection.pattern-1: perl-regex
-   ...
-
-
-

The index number (0, 1...) must not have any holes, and each regex must -contain at least one pair of capturing parentheses, which will be used for -the match. For example, the following adds a regex that matches everything -between two vertical bars:

-
   URxvt.selection.pattern-0: \\|([^|]+)\\|
-
-
-

Another example: Programs I use often output "absolute path: " at the -beginning of a line when they process multiple files. The following -pattern matches the filename (note, there is a single space at the very -end):

-
   URxvt.selection.pattern-0: ^(/[^:]+):\ 
-
-
-

You can look at the source of the selection extension to see more -interesting uses, such as parsing a line from beginning to end.

-

This extension also offers following bindable keyboard commands:

-

-

-
rot13
-
-

Rot-13 the selection when activated. Used via keyboard trigger:

-
   URxvt.keysym.C-M-r: perl:selection:rot13
-
-
-
-
-

-
-
option-popup (enabled by default)
-
-

Binds a popup menu to Ctrl-Button2 that lets you toggle (some) options at -runtime.

-

Other extensions can extend this popup menu by pushing a code reference -onto @{ $term-{option_popup_hook} }>, which gets called whenever the -popup is being displayed.

-

Its sole argument is the popup menu, which can be modified. It should -either return nothing or a string, the initial boolean value and a code -reference. The string will be used as button text and the code reference -will be called when the toggle changes, with the new boolean value as -first argument.

-

The following will add an entry myoption that changes -$self-{myoption}>:

-
   push @{ $self->{term}{option_popup_hook} }, sub {
-      ("my option" => $myoption, sub { $self->{myoption} = $_[0] })
-   };
-
-
-
-
selection-popup (enabled by default)
-
-

Binds a popup menu to Ctrl-Button3 that lets you convert the selection -text into various other formats/action (such as uri unescaping, perl -evaluation, web-browser starting etc.), depending on content.

-

Other extensions can extend this popup menu by pushing a code reference -onto @{ $term-{selection_popup_hook} }>, which gets called whenever the -popup is being displayed.

-

Its sole argument is the popup menu, which can be modified. The selection -is in $_, which can be used to decide whether to add something or not. -It should either return nothing or a string and a code reference. The -string will be used as button text and the code reference will be called -when the button gets activated and should transform $_.

-

The following will add an entry a to b that transforms all as in -the selection to bs, but only if the selection currently contains any -as:

-
   push @{ $self->{term}{selection_popup_hook} }, sub {
-      /a/ ? ("a to b" => sub { s/a/b/g }
-          : ()
-   };
-
-
-
-
searchable-scrollback<hotkey> (enabled by default)
-
-

Adds regex search functionality to the scrollback buffer, triggered -by a hotkey (default: M-s). While in search mode, normal terminal -input/output is suspended and a regex is displayed at the bottom of the -screen.

-

Inputting characters appends them to the regex and continues incremental -search. BackSpace removes a character from the regex, Up and Down -search upwards/downwards in the scrollback buffer, End jumps to the -bottom. Escape leaves search mode and returns to the point where search -was started, while Enter or Return stay at the current position and -additionally stores the first match in the current line into the primary -selection if the Shift modifier is active.

-

The regex defaults to "(?i)", resulting in a case-insensitive search. To -get a case-sensitive search you can delete this prefix using BackSpace -or simply use an uppercase character which removes the "(?i)" prefix.

-

See perlre for more info about perl regular expression syntax.

-
-
readline (enabled by default)
-
-

A support package that tries to make editing with readline easier. At -the moment, it reacts to clicking shift-left mouse button by trying to -move the text cursor to this position. It does so by generating as many -cursor-left or cursor-right keypresses as required (the this only works -for programs that correctly support wide characters).

-

To avoid too many false positives, this is only done when:

-

-

-
- the tty is in ICANON state.
-
- the text cursor is visible.
-
- the primary screen is currently being displayed.
-
- the mouse is on the same (multi-row-) line as the text cursor.
-
-

-

The normal selection mechanism isn't disabled, so quick successive clicks -might interfere with selection creation in harmless ways.

-
-
selection-autotransform
-
-

This selection allows you to do automatic transforms on a selection -whenever a selection is made.

-

It works by specifying perl snippets (most useful is a single s/// -operator) that modify $_ as resources:

-
   URxvt.selection-autotransform.0: transform
-   URxvt.selection-autotransform.1: transform
-   ...
-
-
-

For example, the following will transform selections of the form -filename:number, often seen in compiler messages, into vi +$filename -$word:

-
   URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/
-
-
-

And this example matches the same,but replaces it with vi-commands you can -paste directly into your (vi :) editor:

-
   URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
-
-
-

Of course, this can be modified to suit your needs and your editor :)

-

To expand the example above to typical perl error messages ("XXX at -FILENAME line YYY."), you need a slightly more elaborate solution:

-
   URxvt.selection.pattern-0: ( at .*? line \\d+[,.])
-   URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/
-
-
-

The first line tells the selection code to treat the unchanging part of -every error message as a selection pattern, and the second line transforms -the message into vi commands to load the file.

-
-
tabbed
-
-

This transforms the terminal into a tabbar with additional terminals, that -is, it implements what is commonly referred to as "tabbed terminal". The topmost line -displays a "[NEW]" button, which, when clicked, will add a new tab, followed by one -button per tab.

-

Clicking a button will activate that tab. Pressing Shift-Left and -Shift-Right will switch to the tab left or right of the current one, -while Shift-Down creates a new tab.

-

The tabbar itself can be configured similarly to a normal terminal, but -with a resource class of URxvt.tabbed. In addition, it supports the -following four resources (shown with defaults):

-
   URxvt.tabbed.tabbar-fg: <colour-index, default 3>
-   URxvt.tabbed.tabbar-bg: <colour-index, default 0>
-   URxvt.tabbed.tab-fg:    <colour-index, default 0>
-   URxvt.tabbed.tab-bg:    <colour-index, default 1>
-
-
-

See COLOR AND GRAPHICS in the rxvt(1) manpage for valid -indices.

-
-
matcher
-
-

Uses per-line display filtering (on_line_update) to underline text -matching a certain pattern and make it clickable. When clicked with the -mouse button specified in the matcher.button resource (default 2, or -middle), the program specified in the matcher.launcher resource -(default, the urlLauncher resource, sensible-browser) will be started -with the matched text as first argument. The default configuration is -suitable for matching URLs and launching a web browser, like the -former "mark-urls" extension.

-

The default pattern to match URLs can be overridden with the -matcher.pattern.0 resource, and additional patterns can be specified -with numbered patterns, in a manner similar to the "selection" extension. -The launcher can also be overridden on a per-pattern basis.

-

It is possible to activate the most recently seen match from the keyboard. -Simply bind a keysym to "perl:matcher" as seen in the example below.

-

Example configuration:

-
    URxvt.perl-ext:           default,matcher
-    URxvt.urlLauncher:        sensible-browser
-    URxvt.keysym.C-Delete:    perl:matcher
-    URxvt.matcher.button:     1
-    URxvt.matcher.pattern.1:  \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-]
-    URxvt.matcher.pattern.2:  \\B(/\\S+?):(\\d+)(?=:|$)
-    URxvt.matcher.launcher.2: gvim +$2 $1
-
-
-
-
xim-onthespot
-
-

This (experimental) perl extension implements OnTheSpot editing. It does -not work perfectly, and some input methods don't seem to work well with -OnTheSpot editing in general, but it seems to work at least for SCIM and -kinput2.

-

You enable it by specifying this extension and a preedit style of -OnTheSpot, i.e.:

-
   rxvt -pt OnTheSpot -pe xim-onthespot
-
-
-
-
kuake<hotkey>
-
-

A very primitive quake-console-like extension. It was inspired by a -description of how the programs kuake and yakuake work: Whenever the -user presses a global accelerator key (by default F10), the terminal -will show or hide itself. Another press of the accelerator key will hide -or show it again.

-

Initially, the window will not be shown when using this extension.

-

This is useful if you need a single terminal that is not using any desktop -space most of the time but is quickly available at the press of a key.

-

The accelerator key is grabbed regardless of any modifiers, so this -extension will actually grab a physical key just for this function.

-

If you want a quake-like animation, tell your window manager to do so -(fvwm can do it).

-
-
block-graphics-to-ascii
-
-

A not very useful example of filtering all text output to the terminal -by replacing all line-drawing characters (U+2500 .. U+259F) by a -similar-looking ascii character.

-
-
digital-clock
-
-

Displays a digital clock using the built-in overlay.

-
-
remote-clipboard
-
-

Somewhat of a misnomer, this extension adds two menu entries to the -selection popup that allows one to run external commands to store the -selection somewhere and fetch it again.

-

We use it to implement a "distributed selection mechanism", which just -means that one command uploads the file to a remote server, and another -reads it.

-

The commands can be set using the URxvt.remote-selection.store and -URxvt.remote-selection.fetch resources. The first should read the -selection to store from STDIN (always in UTF-8), the second should provide -the selection data on STDOUT (also in UTF-8).

-

The defaults (which are likely useless to you) use rsh and cat:

-
   URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection'
-   URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection'
-
-
-
-
selection-pastebin
-
-

This is a little rarely useful extension that Uploads the selection as -textfile to a remote site (or does other things). (The implementation is -not currently secure for use in a multiuser environment as it writes to -/tmp directly.).

-

It listens to the selection-pastebin:remote-pastebin keyboard command, -i.e.

-
   URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin
-
-
-

Pressing this combination runs a command with % replaced by the name of -the textfile. This command can be set via a resource:

-
   URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/.
-
-
-

And the default is likely not useful to anybody but the few people around -here :)

-

The name of the textfile is the hex encoded md5 sum of the selection, so -the same content should lead to the same filename.

-

After a successful upload the selection will be replaced by the text given -in the selection-pastebin-url resource (again, the % is the placeholder -for the filename):

-
   URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/%
-
-
-

Note to xrdb users: xrdb uses the C preprocessor, which might interpret -the double / characters as comment start. Use \057\057 instead, -which works regardless of wether xrdb is used to parse the resource file -or not.

-
-
example-refresh-hooks
-
-

Displays a very simple digital clock in the upper right corner of the -window. Illustrates overwriting the refresh callbacks to create your own -overlays or changes.

-
-
- -
-

API DOCUMENTATION

Top

-
- -
-

General API Considerations

-
-

All objects (such as terminals, time watchers etc.) are typical -reference-to-hash objects. The hash can be used to store anything you -like. All members starting with an underscore (such as _ptr or -_hook) are reserved for internal uses and MUST NOT be accessed or -modified).

-

When objects are destroyed on the C++ side, the perl object hashes are -emptied, so its best to store related objects such as time watchers and -the like inside the terminal object so they get destroyed as soon as the -terminal is destroyed.

-

Argument names also often indicate the type of a parameter. Here are some -hints on what they mean:

-
-
$text
-
-

Rxvt-unicodes special way of encoding text, where one "unicode" character -always represents one screen cell. See ROW_t for a discussion of this format.

-
-
$string
-
-

A perl text string, with an emphasis on text. It can store all unicode -characters and is to be distinguished with text encoded in a specific -encoding (often locale-specific) and binary data.

-
-
$octets
-
-

Either binary data or - more common - a text string encoded in a -locale-specific way.

-
-
- -
-

Extension Objects

-
-

Every perl extension is a perl class. A separate perl object is created -for each terminal, and each terminal has its own set of extenion objects, -which are passed as the first parameter to hooks. So extensions can use -their $self object without having to think about clashes with other -extensions or other terminals, with the exception of methods and members -that begin with an underscore character _: these are reserved for -internal use.

-

Although it isn't a urxvt::term object, you can call all methods of the -urxvt::term class on this object.

-

It has the following methods and data members:

-
-
$urxvt_term = $self->{term}
-
-

Returns the urxvt::term object associated with this instance of the -extension. This member must not be changed in any way.

-
-
$self->enable ($hook_name => $cb, [$hook_name => $cb..])
-
-

Dynamically enable the given hooks (named without the on_ prefix) for -this extension, replacing any previous hook. This is useful when you want -to overwrite time-critical hooks only temporarily.

-
-
$self->disable ($hook_name[, $hook_name..])
-
-

Dynamically disable the given hooks.

-
-
- -
-

Hooks

-
-

The following subroutines can be declared in extension files, and will be -called whenever the relevant event happens.

-

The first argument passed to them is an extension object as described in -the in the Extension Objects section.

-

All of these hooks must return a boolean value. If any of the called -hooks returns true, then the event counts as being consumed, and the -relevant action might not be carried out by the C++ code.

-

When in doubt, return a false value (preferably ()).

-
-
on_init $term
-
-

Called after a new terminal object has been initialized, but before -windows are created or the command gets run. Most methods are unsafe to -call or deliver senseless data, as terminal size and other characteristics -have not yet been determined. You can safely query and change resources -and options, though. For many purposes the on_start hook is a better -place.

-
-
on_start $term
-
-

Called at the very end of initialisation of a new terminal, just before -trying to map (display) the toplevel and returning to the main loop.

-
-
on_destroy $term
-
-

Called whenever something tries to destroy terminal, when the terminal is -still fully functional (not for long, though).

-
-
on_reset $term
-
-

Called after the screen is "reset" for any reason, such as resizing or -control sequences. Here is where you can react on changes to size-related -variables.

-
-
on_child_start $term, $pid
-
-

Called just after the child process has been forked.

-
-
on_child_exit $term, $status
-
-

Called just after the child process has exited. $status is the status -from waitpid.

-
-
on_sel_make $term, $eventtime
-
-

Called whenever a selection has been made by the user, but before the -selection text is copied, so changes to the beginning, end or type of the -selection will be honored.

-

Returning a true value aborts selection making by urxvt, in which case you -have to make a selection yourself by calling $term->selection_grab.

-
-
on_sel_grab $term, $eventtime
-
-

Called whenever a selection has been copied, but before the selection is -requested from the server. The selection text can be queried and changed -by calling $term->selection.

-

Returning a true value aborts selection grabbing. It will still be highlighted.

-
-
on_sel_extend $term
-
-

Called whenever the user tries to extend the selection (e.g. with a double -click) and is either supposed to return false (normal operation), or -should extend the selection itself and return true to suppress the built-in -processing. This can happen multiple times, as long as the callback -returns true, it will be called on every further click by the user and is -supposed to enlarge the selection more and more, if possible.

-

See the selection example extension.

-
-
on_view_change $term, $offset
-
-

Called whenever the view offset changes, i.e. the user or program -scrolls. Offset 0 means display the normal terminal, positive values -show this many lines of scrollback.

-
-
on_scroll_back $term, $lines, $saved
-
-

Called whenever lines scroll out of the terminal area into the scrollback -buffer. $lines is the number of lines scrolled out and may be larger -than the scroll back buffer or the terminal.

-

It is called before lines are scrolled out (so rows 0 .. min ($lines - 1, -$nrow - 1) represent the lines to be scrolled out). $saved is the total -number of lines that will be in the scrollback buffer.

-
-
on_osc_seq $term, $op, $args
-
-

Called on every OSC sequence and can be used to suppress it or modify its -behaviour. The default should be to return an empty list. A true value -suppresses execution of the request completely. Make sure you don't get -confused by recursive invocations when you output an osc sequence within -this callback.

-

on_osc_seq_perl should be used for new behaviour.

-
-
on_osc_seq_perl $term, $string
-
-

Called whenever the ESC ] 777 ; string ST command sequence (OSC = -operating system command) is processed. Cursor position and other state -information is up-to-date when this happens. For interoperability, the -string should start with the extension name and a colon, to distinguish -it from commands for other extensions, and this might be enforced in the -future.

-

Be careful not ever to trust (in a security sense) the data you receive, -as its source can not easily be controlled (e-mail content, messages from -other users on the same system etc.).

-
-
on_add_lines $term, $string
-
-

Called whenever text is about to be output, with the text as argument. You -can filter/change and output the text yourself by returning a true value -and calling $term->scr_add_lines yourself. Please note that this -might be very slow, however, as your hook is called for all text being -output.

-
-
on_tt_write $term, $octets
-
-

Called whenever some data is written to the tty/pty and can be used to -suppress or filter tty input.

-
-
on_line_update $term, $row
-
-

Called whenever a line was updated or changed. Can be used to filter -screen output (e.g. underline urls or other useless stuff). Only lines -that are being shown will be filtered, and, due to performance reasons, -not always immediately.

-

The row number is always the topmost row of the line if the line spans -multiple rows.

-

Please note that, if you change the line, then the hook might get called -later with the already-modified line (e.g. if unrelated parts change), so -you cannot just toggle rendition bits, but only set them.

-
-
on_refresh_begin $term
-
-

Called just before the screen gets redrawn. Can be used for overlay -or similar effects by modify terminal contents in refresh_begin, and -restoring them in refresh_end. The built-in overlay and selection display -code is run after this hook, and takes precedence.

-
-
on_refresh_end $term
-
-

Called just after the screen gets redrawn. See on_refresh_begin.

-
-
on_user_command $term, $string
-
-

Called whenever a user-configured event is being activated (e.g. via -a perl:string action bound to a key, see description of the keysym -resource in the rxvt(1) manpage).

-

The event is simply the action string. This interface is assumed to change -slightly in the future.

-
-
on_resize_all_windows $tern, $new_width, $new_height
-
-

Called just after the new window size has been calculated, but before -windows are actually being resized or hints are being set. If this hook -returns TRUE, setting of the window hints is being skipped.

-
-
on_x_event $term, $event
-
-

Called on every X event received on the vt window (and possibly other -windows). Should only be used as a last resort. Most event structure -members are not passed.

-
-
on_root_event $term, $event
-
-

Like on_x_event, but is called for events on the root window.

-
-
on_focus_in $term
-
-

Called whenever the window gets the keyboard focus, before rxvt-unicode -does focus in processing.

-
-
on_focus_out $term
-
-

Called whenever the window loses keyboard focus, before rxvt-unicode does -focus out processing.

-
-
on_configure_notify $term, $event
-
on_property_notify $term, $event
-
on_key_press $term, $event, $keysym, $octets
-
on_key_release $term, $event, $keysym
-
on_button_press $term, $event
-
on_button_release $term, $event
-
on_motion_notify $term, $event
-
on_map_notify $term, $event
-
on_unmap_notify $term, $event
-
-

Called whenever the corresponding X event is received for the terminal If -the hook returns true, then the even will be ignored by rxvt-unicode.

-

The event is a hash with most values as named by Xlib (see the XEvent -manpage), with the additional members row and col, which are the -(real, not screen-based) row and column under the mouse cursor.

-

on_key_press additionally receives the string rxvt-unicode would -output, if any, in locale-specific encoding.

-

subwindow.

-
-
on_client_message $term, $event
-
on_wm_protocols $term, $event
-
on_wm_delete_window $term, $event
-
-

Called when various types of ClientMessage events are received (all with -format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW).

-
-
- -
-

Variables in the urxvt Package

-
-
-
$urxvt::LIBDIR
-
-

The rxvt-unicode library directory, where, among other things, the perl -modules and scripts are stored.

-
-
$urxvt::RESCLASS, $urxvt::RESCLASS
-
-

The resource class and name rxvt-unicode uses to look up X resources.

-
-
$urxvt::RXVTNAME
-
-

The basename of the installed binaries, usually urxvt.

-
-
$urxvt::TERM
-
-

The current terminal. This variable stores the current urxvt::term -object, whenever a callback/hook is executing.

-
-
@urxvt::TERM_INIT
-
-

All code references in this array will be called as methods of the next newly -created urxvt::term object (during the on_init phase). The array -gets cleared before the code references that were in it are being executed, -so references can push themselves onto it again if they so desire.

-

This complements to the perl-eval command line option, but gets executed -first.

-
-
@urxvt::TERM_EXT
-
-

Works similar to @TERM_INIT, but contains perl package/class names, which -get registered as normal extensions after calling the hooks in @TERM_INIT -but before other extensions. Gets cleared just like @TERM_INIT.

-
-
- -
-

Functions in the urxvt Package

-
-
-
urxvt::fatal $errormessage
-
-

Fatally aborts execution with the given error message. Avoid at all -costs! The only time this is acceptable is when the terminal process -starts up.

-
-
urxvt::warn $string
-
-

Calls rxvt_warn with the given string which should not include a -newline. The module also overwrites the warn builtin with a function -that calls this function.

-

Using this function has the advantage that its output ends up in the -correct place, e.g. on stderr of the connecting urxvtc client.

-

Messages have a size limit of 1023 bytes currently.

-
-
@terms = urxvt::termlist
-
-

Returns all urxvt::term objects that exist in this process, regardless of -whether they are started, being destroyed etc., so be careful. Only term -objects that have perl extensions attached will be returned (because there -is no urxvt::term objet associated with others).

-
-
$time = urxvt::NOW
-
-

Returns the "current time" (as per the event loop).

-
-
urxvt::CurrentTime
-
urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, -Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, -Button4Mask, Button5Mask, AnyModifier
-
urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, -ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, -PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask, -Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask, -KeymapStateMask, ExposureMask, VisibilityChangeMask, StructureNotifyMask, -ResizeRedirectMask, SubstructureNotifyMask, SubstructureRedirectMask, -FocusChangeMask, PropertyChangeMask, ColormapChangeMask, OwnerGrabButtonMask
-
urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify, -EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose, -GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify, -UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify, -ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify, -CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest, -SelectionNotify, ColormapNotify, ClientMessage, MappingNotify
-
-

Various constants for use in X calls and event processing.

-
-
- -
-

RENDITION

-
-

Rendition bitsets contain information about colour, font, font styles and -similar information for each screen cell.

-

The following "macros" deal with changes in rendition sets. You should -never just create a bitset, you should always modify an existing one, -as they contain important information required for correct operation of -rxvt-unicode.

-
-
$rend = urxvt::DEFAULT_RSTYLE
-
-

Returns the default rendition, as used when the terminal is starting up or -being reset. Useful as a base to start when creating renditions.

-
-
$rend = urxvt::OVERLAY_RSTYLE
-
-

Return the rendition mask used for overlays by default.

-
-
$rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline
-
-

Return the bit that enabled bold, italic, blink, reverse-video and -underline, respectively. To enable such a style, just logically OR it into -the bitset.

-
-
$foreground = urxvt::GET_BASEFG $rend
-
$background = urxvt::GET_BASEBG $rend
-
-

Return the foreground/background colour index, respectively.

-
-
$rend = urxvt::SET_FGCOLOR $rend, $new_colour
-
$rend = urxvt::SET_BGCOLOR $rend, $new_colour
-
$rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg
-
-

Replace the foreground/background colour in the rendition mask with the -specified one.

-
-
$value = urxvt::GET_CUSTOM $rend
-
-

Return the "custom" value: Every rendition has 5 bits for use by -extensions. They can be set and changed as you like and are initially -zero.

-
-
$rend = urxvt::SET_CUSTOM $rend, $new_value
-
-

Change the custom value.

-
-
- -
-

The urxvt::anyevent Class

-
-

The sole purpose of this class is to deliver an interface to the -AnyEvent module - any module using it will work inside urxvt without -further programming. The only exception is that you cannot wait on -condition variables, but non-blocking condvar use is ok. What this means -is that you cannot use blocking APIs, but the non-blocking variant should -work.

- -
-

The urxvt::term Class

-
-
-
$term = new urxvt::term $envhashref, $rxvtname, [arg...]
-
-

Creates a new terminal, very similar as if you had started it with system -$rxvtname, arg.... $envhashref must be a reference to a %ENV-like -hash which defines the environment of the new terminal.

-

Croaks (and probably outputs an error message) if the new instance -couldn't be created. Returns undef if the new instance didn't -initialise perl, and the terminal object otherwise. The init and -start hooks will be called before this call returns, and are free to -refer to global data (which is race free).

-
-
$term->destroy
-
-

Destroy the terminal object (close the window, free resources -etc.). Please note that rxvt will not exit as long as any event -watchers (timers, io watchers) are still active.

-
-
$term->exec_async ($cmd[, @args])
-
-

Works like the combination of the fork/exec builtins, which executes -("starts") programs in the background. This function takes care of setting -the user environment before exec'ing the command (e.g. PATH) and should -be preferred over explicit calls to exec or system.

-

Returns the pid of the subprocess or undef on error.

-
-
$isset = $term->option ($optval[, $set])
-
-

Returns true if the option specified by $optval is enabled, and -optionally change it. All option values are stored by name in the hash -%urxvt::OPTION. Options not enabled in this binary are not in the hash.

-

Here is a likely non-exhaustive list of option names, please see the -source file /src/optinc.h to see the actual list:

-
 borderLess console cursorBlink cursorUnderline hold iconic insecure
- intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage
- override-redirect pastableTabs pointerBlank reverseVideo scrollBar
- scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput
- scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs
- transparent tripleclickwords utmpInhibit visualBell
-
-
-
-
$value = $term->resource ($name[, $newval])
-
-

Returns the current resource value associated with a given name and -optionally sets a new value. Setting values is most useful in the init -hook. Unset resources are returned and accepted as undef.

-

The new value must be properly encoded to a suitable character encoding -before passing it to this method. Similarly, the returned value may need -to be converted from the used encoding to text.

-

Resource names are as defined in src/rsinc.h. Colours can be specified -as resource names of the form color+<index>, e.g. color+5. (will -likely change).

-

Please note that resource strings will currently only be freed when the -terminal is destroyed, so changing options frequently will eat memory.

-

Here is a likely non-exhaustive list of resource names, not all of which -are supported in every build, please see the source file /src/rsinc.h -to see the actual list:

-
  answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont
-  borderLess color cursorBlink cursorUnderline cutchars delete_key
-  display_name embed ext_bwidth fade font geometry hold iconName
-  imFont imLocale inputMethod insecure int_bwidth intensityStyles
-  italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier
-  mouseWheelScrollPage name override_redirect pastableTabs path perl_eval
-  perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay
-  preeditType print_pipe pty_fd reverseVideo saveLines scrollBar
-  scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness
-  scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle
-  secondaryScreen secondaryScroll selectstyle shade term_name title
-  transient_for transparent transparent_all tripleclickwords utmpInhibit
-  visualBell
-
-
-
-
$value = $term->x_resource ($pattern)
-
-

Returns the X-Resource for the given pattern, excluding the program or -class name, i.e. $term->x_resource ("boldFont") should return the -same value as used by this instance of rxvt-unicode. Returns undef if no -resource with that pattern exists.

-

This method should only be called during the on_start hook, as there is -only one resource database per display, and later invocations might return -the wrong resources.

-
-
$success = $term->parse_keysym ($keysym_spec, $command_string)
-
-

Adds a keymap translation exactly as specified via a resource. See the -keysym resource in the rxvt(1) manpage.

-
-
$rend = $term->rstyle ([$new_rstyle])
-
-

Return and optionally change the current rendition. Text that is output by -the terminal application will use this style.

-
-
($row, $col) = $term->screen_cur ([$row, $col])
-
-

Return the current coordinates of the text cursor position and optionally -set it (which is usually bad as applications don't expect that).

-
-
($row, $col) = $term->selection_mark ([$row, $col])
-
($row, $col) = $term->selection_beg ([$row, $col])
-
($row, $col) = $term->selection_end ([$row, $col])
-
-

Return the current values of the selection mark, begin or end positions, -and optionally set them to new values.

-
-
$term->selection_make ($eventtime[, $rectangular])
-
-

Tries to make a selection as set by selection_beg and -selection_end. If $rectangular is true (default: false), a -rectangular selection will be made. This is the prefered function to make -a selection.

-
-
$success = $term->selection_grab ($eventtime)
-
-

Try to request the primary selection text from the server (for example, as -set by the next method). No visual feedback will be given. This function -is mostly useful from within on_sel_grab hooks.

-
-
$oldtext = $term->selection ([$newtext])
-
-

Return the current selection text and optionally replace it by $newtext.

-
-
$term->overlay_simple ($x, $y, $text)
-
-

Create a simple multi-line overlay box. See the next method for details.

-
-
$term->overlay ($x, $y, $width, $height[, $rstyle[, $border]])
-
-

Create a new (empty) overlay at the given position with the given -width/height. $rstyle defines the initial rendition style -(default: OVERLAY_RSTYLE).

-

If $border is 2 (default), then a decorative border will be put -around the box.

-

If either $x or $y is negative, then this is counted from the -right/bottom side, respectively.

-

This method returns an urxvt::overlay object. The overlay will be visible -as long as the perl object is referenced.

-

The methods currently supported on urxvt::overlay objects are:

-

-

-
$overlay->set ($x, $y, $text, $rend)
-
-

Similar to $term->ROW_t and $term->ROW_r in that it puts -text in rxvt-unicode's special encoding and an array of rendition values -at a specific position inside the overlay.

-
-
$overlay->hide
-
-

If visible, hide the overlay, but do not destroy it.

-
-
$overlay->show
-
-

If hidden, display the overlay again.

-
-
-

-
-
$popup = $term->popup ($event)
-
-

Creates a new urxvt::popup object that implements a popup menu. The -$event must be the event causing the menu to pop up (a button event, -currently).

-
-
$cellwidth = $term->strwidth ($string)
-
-

Returns the number of screen-cells this string would need. Correctly -accounts for wide and combining characters.

-
-
$octets = $term->locale_encode ($string)
-
-

Convert the given text string into the corresponding locale encoding.

-
-
$string = $term->locale_decode ($octets)
-
-

Convert the given locale-encoded octets into a perl string.

-
-
$term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle])
-
-

XORs the rendition values in the given span with the provided value -(default: RS_RVid), which MUST NOT contain font styles. Useful in -refresh hooks to provide effects similar to the selection.

-
-
$term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, $rstyle2]])
-
-

Similar to scr_xor_span, but xors a rectangle instead. Trailing -whitespace will additionally be xored with the $rstyle2, which defaults -to RS_RVid | RS_Uline, which removes reverse video again and underlines -it instead. Both styles MUST NOT contain font styles.

-
-
$term->scr_bell
-
-

Ring the bell!

-
-
$term->scr_add_lines ($string)
-
-

Write the given text string to the screen, as if output by the application -running inside the terminal. It may not contain command sequences (escape -codes), but is free to use line feeds, carriage returns and tabs. The -string is a normal text string, not in locale-dependent encoding.

-

Normally its not a good idea to use this function, as programs might be -confused by changes in cursor position or scrolling. Its useful inside a -on_add_lines hook, though.

-
-
$term->scr_change_screen ($screen)
-
-

Switch to given screen - 0 primary, 1 secondary.

-
-
$term->cmd_parse ($octets)
-
-

Similar to scr_add_lines, but the argument must be in the -locale-specific encoding of the terminal and can contain command sequences -(escape codes) that will be interpreted.

-
-
$term->tt_write ($octets)
-
-

Write the octets given in $data to the tty (i.e. as program input). To -pass characters instead of octets, you should convert your strings first -to the locale-specific encoding using $term->locale_encode.

-
-
$old_events = $term->pty_ev_events ([$new_events])
-
-

Replaces the event mask of the pty watcher by the given event mask. Can -be used to suppress input and output handling to the pty/tty. See the -description of urxvt::timer->events. Make sure to always restore -the previous value.

-
-
$fd = $term->pty_fd
-
-

Returns the master file descriptor for the pty in use, or -1 if no pty -is used.

-
-
$windowid = $term->parent
-
-

Return the window id of the toplevel window.

-
-
$windowid = $term->vt
-
-

Return the window id of the terminal window.

-
-
$term->vt_emask_add ($x_event_mask)
-
-

Adds the specified events to the vt event mask. Useful e.g. when you want -to receive pointer events all the times:

-
   $term->vt_emask_add (urxvt::PointerMotionMask);
-
-
-
-
$term->focus_in
-
$term->focus_out
-
$term->key_press ($state, $keycode[, $time])
-
$term->key_release ($state, $keycode[, $time])
-
-

Deliver various fake events to to terminal.

-
-
$window_width = $term->width
-
$window_height = $term->height
-
$font_width = $term->fwidth
-
$font_height = $term->fheight
-
$font_ascent = $term->fbase
-
$terminal_rows = $term->nrow
-
$terminal_columns = $term->ncol
-
$has_focus = $term->focus
-
$is_mapped = $term->mapped
-
$max_scrollback = $term->saveLines
-
$nrow_plus_saveLines = $term->total_rows
-
$topmost_scrollback_row = $term->top_row
-
-

Return various integers describing terminal characteristics.

-
-
$x_display = $term->display_id
-
-

Return the DISPLAY used by rxvt-unicode.

-
-
$lc_ctype = $term->locale
-
-

Returns the LC_CTYPE category string used by this rxvt-unicode.

-
-
$env = $term->env
-
-

Returns a copy of the environment in effect for the terminal as a hashref -similar to \%ENV.

-
-
@envv = $term->envv
-
-

Returns the environment as array of strings of the form VAR=VALUE.

-
-
@argv = $term->argv
-
-

Return the argument vector as this terminal, similar to @ARGV, but -includes the program name as first element.

-
-
$modifiermask = $term->ModLevel3Mask
-
$modifiermask = $term->ModMetaMask
-
$modifiermask = $term->ModNumLockMask
-
-

Return the modifier masks corresponding to the "ISO Level 3 Shift" (often -AltGr), the meta key (often Alt) and the num lock key, if applicable.

-
-
$screen = $term->current_screen
-
-

Returns the currently displayed screen (0 primary, 1 secondary).

-
-
$cursor_is_hidden = $term->hidden_cursor
-
-

Returns whether the cursor is currently hidden or not.

-
-
$view_start = $term->view_start ([$newvalue])
-
-

Returns the row number of the topmost displayed line. Maximum value is -0, which displays the normal terminal contents. Lower values scroll -this many lines into the scrollback buffer.

-
-
$term->want_refresh
-
-

Requests a screen refresh. At the next opportunity, rxvt-unicode will -compare the on-screen display with its stored representation. If they -differ, it redraws the differences.

-

Used after changing terminal contents to display them.

-
-
$text = $term->ROW_t ($row_number[, $new_text[, $start_col]])
-
-

Returns the text of the entire row with number $row_number. Row 0 -is the topmost terminal line, row $term->$ncol-1 is the bottommost -terminal line. The scrollback buffer starts at line -1 and extends to -line -$term->nsaved. Nothing will be returned if a nonexistent line -is requested.

-

If $new_text is specified, it will replace characters in the current -line, starting at column $start_col (default 0), which is useful -to replace only parts of a line. The font index in the rendition will -automatically be updated.

-

$text is in a special encoding: tabs and wide characters that use more -than one cell when displayed are padded with $urxvt::NOCHAR (chr 65535) -characters. Characters with combining characters and other characters that -do not fit into the normal tetx encoding will be replaced with characters -in the private use area.

-

You have to obey this encoding when changing text. The advantage is -that substr and similar functions work on screen cells and not on -characters.

-

The methods $term->special_encode and $term->special_decode -can be used to convert normal strings into this encoding and vice versa.

-
-
$rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]])
-
-

Like $term->ROW_t, but returns an arrayref with rendition -bitsets. Rendition bitsets contain information about colour, font, font -styles and similar information. See also $term->ROW_t.

-

When setting rendition, the font mask will be ignored.

-

See the section on RENDITION, above.

-
-
$length = $term->ROW_l ($row_number[, $new_length])
-
-

Returns the number of screen cells that are in use ("the line -length"). Unlike the urxvt core, this returns $term->ncol if the -line is joined with the following one.

-
-
$bool = $term->is_longer ($row_number)
-
-

Returns true if the row is part of a multiple-row logical "line" (i.e. -joined with the following row), which means all characters are in use -and it is continued on the next row (and possibly a continuation of the -previous row(s)).

-
-
$line = $term->line ($row_number)
-
-

Create and return a new urxvt::line object that stores information -about the logical line that row $row_number is part of. It supports the -following methods:

-

-

-
$text = $line->t ([$new_text])
-
-

Returns or replaces the full text of the line, similar to ROW_t

-
-
$rend = $line->r ([$new_rend])
-
-

Returns or replaces the full rendition array of the line, similar to ROW_r

-
-
$length = $line->l
-
-

Returns the length of the line in cells, similar to ROW_l.

-
-
$rownum = $line->beg
-
$rownum = $line->end
-
-

Return the row number of the first/last row of the line, respectively.

-
-
$offset = $line->offset_of ($row, $col)
-
-

Returns the character offset of the given row|col pair within the logical -line. Works for rows outside the line, too, and returns corresponding -offsets outside the string.

-
-
($row, $col) = $line->coord_of ($offset)
-
-

Translates a string offset into terminal coordinates again.

-
-
-

-
-
$text = $term->special_encode $string
-
-

Converts a perl string into the special encoding used by rxvt-unicode, -where one character corresponds to one screen cell. See -$term->ROW_t for details.

-
-
$string = $term->special_decode $text
-
-

Converts rxvt-unicodes text representation into a perl string. See -$term->ROW_t for details.

-
-
$success = $term->grab_button ($button, $modifiermask[, $window = $term->vt])
-
$term->ungrab_button ($button, $modifiermask[, $window = $term->vt])
-
-

Register/unregister a synchronous button grab. See the XGrabButton -manpage.

-
-
$success = $term->grab ($eventtime[, $sync])
-
-

Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or -synchronous ($sync is true). Also remembers the grab timestamp.

-
-
$term->allow_events_async
-
-

Calls XAllowEvents with AsyncBoth for the most recent grab.

-
-
$term->allow_events_sync
-
-

Calls XAllowEvents with SyncBoth for the most recent grab.

-
-
$term->allow_events_replay
-
-

Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for the most -recent grab.

-
-
$term->ungrab
-
-

Calls XUngrab for the most recent grab. Is called automatically on -evaluation errors, as it is better to lose the grab in the error case as -the session.

-
-
$atom = $term->XInternAtom ($atom_name[, $only_if_exists])
-
$atom_name = $term->XGetAtomName ($atom)
-
@atoms = $term->XListProperties ($window)
-
($type,$format,$octets) = $term->XGetWindowProperty ($window, $property)
-
$term->XChangeWindowProperty ($window, $property, $type, $format, $octets)
-
$term->XDeleteProperty ($window, $property)
-
$window = $term->DefaultRootWindow
-
$term->XReparentWindow ($window, $parent, [$x, $y])
-
$term->XMapWindow ($window)
-
$term->XUnmapWindow ($window)
-
$term->XMoveResizeWindow ($window, $x, $y, $width, $height)
-
($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, $y)
-
$term->XChangeInput ($window, $add_events[, $del_events])
-
-

Various X or X-related functions. The $term object only serves as -the source of the display, otherwise those functions map more-or-less -directory onto the X functions of the same name.

-
-
- -
-

The urxvt::popup Class

-
-
-
$popup->add_title ($title)
-
-

Adds a non-clickable title to the popup.

-
-
$popup->add_separator ([$sepchr])
-
-

Creates a separator, optionally using the character given as $sepchr.

-
-
$popup->add_button ($text, $cb)
-
-

Adds a clickable button to the popup. $cb is called whenever it is -selected.

-
-
$popup->add_toggle ($text, $initial_value, $cb)
-
-

Adds a toggle/checkbox item to the popup. The callback gets called -whenever it gets toggled, with a boolean indicating its new value as its -first argument.

-
-
$popup->show
-
-

Displays the popup (which is initially hidden).

-
-
- -
-

The urxvt::timer Class

-
-

This class implements timer watchers/events. Time is represented as a -fractional number of seconds since the epoch. Example:

-
   $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0);
-   $term->{timer} = urxvt::timer
-                    ->new
-                    ->interval (1)
-                    ->cb (sub {
-                       $term->{overlay}->set (0, 0,
-                          sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]);
-                    });
-
-
-
-
$timer = new urxvt::timer
-
-

Create a new timer object in started state. It is scheduled to fire -immediately.

-
-
$timer = $timer->cb (sub { my ($timer) = @_; ... })
-
-

Set the callback to be called when the timer triggers.

-
-
$tstamp = $timer->at
-
-

Return the time this watcher will fire next.

-
-
$timer = $timer->set ($tstamp)
-
-

Set the time the event is generated to $tstamp.

-
-
$timer = $timer->interval ($interval)
-
-

Normally (and when $interval is 0), the timer will automatically -stop after it has fired once. If $interval is non-zero, then the timer -is automatically rescheduled at the given intervals.

-
-
$timer = $timer->start
-
-

Start the timer.

-
-
$timer = $timer->start ($tstamp)
-
-

Set the event trigger time to $tstamp and start the timer.

-
-
$timer = $timer->after ($delay)
-
-

Like start, but sets the expiry timer to c<urxvt::NOW + $delay>.

-
-
$timer = $timer->stop
-
-

Stop the timer.

-
-
- -
-

The urxvt::iow Class

-
-

This class implements io watchers/events. Example:

-
  $term->{socket} = ...
-  $term->{iow} = urxvt::iow
-                 ->new
-                 ->fd (fileno $term->{socket})
-                 ->events (urxvt::EV_READ)
-                 ->start
-                 ->cb (sub {
-                   my ($iow, $revents) = @_;
-                   # $revents must be 1 here, no need to check
-                   sysread $term->{socket}, my $buf, 8192
-                      or end-of-file;
-                 });
-
-
-
-
-
-
-
$iow = new urxvt::iow
-
-

Create a new io watcher object in stopped state.

-
-
$iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... })
-
-

Set the callback to be called when io events are triggered. $reventmask -is a bitset as described in the events method.

-
-
$iow = $iow->fd ($fd)
-
-

Set the file descriptor (not handle) to watch.

-
-
$iow = $iow->events ($eventmask)
-
-

Set the event mask to watch. The only allowed values are -urxvt::EV_READ and urxvt::EV_WRITE, which might be ORed -together, or urxvt::EV_NONE.

-
-
$iow = $iow->start
-
-

Start watching for requested events on the given handle.

-
-
$iow = $iow->stop
-
-

Stop watching for events on the given file handle.

-
-
- -
-

The urxvt::iw Class

-
-

This class implements idle watchers, that get called automatically when -the process is idle. They should return as fast as possible, after doing -some useful work.

-
-
$iw = new urxvt::iw
-
-

Create a new idle watcher object in stopped state.

-
-
$iw = $iw->cb (sub { my ($iw) = @_; ... })
-
-

Set the callback to be called when the watcher triggers.

-
-
$timer = $timer->start
-
-

Start the watcher.

-
-
$timer = $timer->stop
-
-

Stop the watcher.

-
-
- -
-

The urxvt::pw Class

-
-

This class implements process watchers. They create an event whenever a -process exits, after which they stop automatically.

-
   my $pid = fork;
-   ...
-   $term->{pw} = urxvt::pw
-                    ->new
-                    ->start ($pid)
-                    ->cb (sub {
-                       my ($pw, $exit_status) = @_;
-                       ...
-                    });
-
-
-
-
$pw = new urxvt::pw
-
-

Create a new process watcher in stopped state.

-
-
$pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... })
-
-

Set the callback to be called when the timer triggers.

-
-
$pw = $timer->start ($pid)
-
-

Tells the watcher to start watching for process $pid.

-
-
$pw = $pw->stop
-
-

Stop the watcher.

-
-
- -
-

ENVIRONMENT

Top

-
- -
-

URXVT_PERL_VERBOSITY

-
-

This variable controls the verbosity level of the perl extension. Higher -numbers indicate more verbose output.

-
-
== 0 - fatal messages
-
>= 3 - script loading and management
-
>=10 - all called hooks
-
>=11 - hook return values
-
- -
-

AUTHOR

Top

-
-
 Marc Lehmann <pcg@goof.com>
- http://software.schmorp.de/pkg/rxvt-unicode
-
-
- -
-
- diff --git a/doc/rxvtperl.3.txt b/doc/rxvtperl.3.txt deleted file mode 100644 index 9db61955..00000000 --- a/doc/rxvtperl.3.txt +++ /dev/null @@ -1,1310 +0,0 @@ -NAME - rxvtperl - rxvt-unicode's embedded perl interpreter - -SYNOPSIS - # create a file grab_test in $HOME: - - sub on_sel_grab { - warn "you selected ", $_[0]->selection; - () - } - - # start a rxvt using it: - - rxvt --perl-lib $HOME -pe grab_test - -DESCRIPTION - Every time a terminal object gets created, extension scripts specified - via the "perl" resource are loaded and associated with it. - - Scripts are compiled in a 'use strict' and 'use utf8' environment, and - thus must be encoded as UTF-8. - - Each script will only ever be loaded once, even in rxvtd, where scripts - will be shared (but not enabled) for all terminals. - - You can disable the embedded perl interpreter by setting both "perl-ext" - and "perl-ext-common" resources to the empty string. - -PREPACKAGED EXTENSIONS - This section describes the extensions delivered with this release. You - can find them in /opt/rxvt/lib/urxvt/perl/. - - You can activate them like this: - - rxvt -pe - - Or by adding them to the resource for extensions loaded by default: - - URxvt.perl-ext-common: default,selection-autotransform - - selection (enabled by default) - (More) intelligent selection. This extension tries to be more - intelligent when the user extends selections (double-click and - further clicks). Right now, it tries to select words, urls and - complete shell-quoted arguments, which is very convenient, too, if - your ls supports "--quoting-style=shell". - - A double-click usually selects the word under the cursor, further - clicks will enlarge the selection. - - The selection works by trying to match a number of regexes and - displaying them in increasing order of length. You can add your own - regexes by specifying resources of the form: - - URxvt.selection.pattern-0: perl-regex - URxvt.selection.pattern-1: perl-regex - ... - - The index number (0, 1...) must not have any holes, and each regex - must contain at least one pair of capturing parentheses, which will - be used for the match. For example, the following adds a regex that - matches everything between two vertical bars: - - URxvt.selection.pattern-0: \\|([^|]+)\\| - - Another example: Programs I use often output "absolute path: " at - the beginning of a line when they process multiple files. The - following pattern matches the filename (note, there is a single - space at the very end): - - URxvt.selection.pattern-0: ^(/[^:]+):\ - - You can look at the source of the selection extension to see more - interesting uses, such as parsing a line from beginning to end. - - This extension also offers following bindable keyboard commands: - - rot13 - Rot-13 the selection when activated. Used via keyboard trigger: - - URxvt.keysym.C-M-r: perl:selection:rot13 - - option-popup (enabled by default) - Binds a popup menu to Ctrl-Button2 that lets you toggle (some) - options at runtime. - - Other extensions can extend this popup menu by pushing a code - reference onto "@{ $term-"{option_popup_hook} }>, which gets called - whenever the popup is being displayed. - - Its sole argument is the popup menu, which can be modified. It - should either return nothing or a string, the initial boolean value - and a code reference. The string will be used as button text and the - code reference will be called when the toggle changes, with the new - boolean value as first argument. - - The following will add an entry "myoption" that changes - "$self-"{myoption}>: - - push @{ $self->{term}{option_popup_hook} }, sub { - ("my option" => $myoption, sub { $self->{myoption} = $_[0] }) - }; - - selection-popup (enabled by default) - Binds a popup menu to Ctrl-Button3 that lets you convert the - selection text into various other formats/action (such as uri - unescaping, perl evaluation, web-browser starting etc.), depending - on content. - - Other extensions can extend this popup menu by pushing a code - reference onto "@{ $term-"{selection_popup_hook} }>, which gets - called whenever the popup is being displayed. - - Its sole argument is the popup menu, which can be modified. The - selection is in $_, which can be used to decide whether to add - something or not. It should either return nothing or a string and a - code reference. The string will be used as button text and the code - reference will be called when the button gets activated and should - transform $_. - - The following will add an entry "a to b" that transforms all "a"s in - the selection to "b"s, but only if the selection currently contains - any "a"s: - - push @{ $self->{term}{selection_popup_hook} }, sub { - /a/ ? ("a to b" => sub { s/a/b/g } - : () - }; - - searchable-scrollback (enabled by default) - Adds regex search functionality to the scrollback buffer, triggered - by a hotkey (default: "M-s"). While in search mode, normal terminal - input/output is suspended and a regex is displayed at the bottom of - the screen. - - Inputting characters appends them to the regex and continues - incremental search. "BackSpace" removes a character from the regex, - "Up" and "Down" search upwards/downwards in the scrollback buffer, - "End" jumps to the bottom. "Escape" leaves search mode and returns - to the point where search was started, while "Enter" or "Return" - stay at the current position and additionally stores the first match - in the current line into the primary selection if the "Shift" - modifier is active. - - The regex defaults to "(?i)", resulting in a case-insensitive - search. To get a case-sensitive search you can delete this prefix - using "BackSpace" or simply use an uppercase character which removes - the "(?i)" prefix. - - See perlre for more info about perl regular expression syntax. - - readline (enabled by default) - A support package that tries to make editing with readline easier. - At the moment, it reacts to clicking shift-left mouse button by - trying to move the text cursor to this position. It does so by - generating as many cursor-left or cursor-right keypresses as - required (the this only works for programs that correctly support - wide characters). - - To avoid too many false positives, this is only done when: - - - the tty is in ICANON state. - - the text cursor is visible. - - the primary screen is currently being displayed. - - the mouse is on the same (multi-row-) line as the text cursor. - - The normal selection mechanism isn't disabled, so quick successive - clicks might interfere with selection creation in harmless ways. - - selection-autotransform - This selection allows you to do automatic transforms on a selection - whenever a selection is made. - - It works by specifying perl snippets (most useful is a single "s///" - operator) that modify $_ as resources: - - URxvt.selection-autotransform.0: transform - URxvt.selection-autotransform.1: transform - ... - - For example, the following will transform selections of the form - "filename:number", often seen in compiler messages, into "vi - +$filename $word": - - URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/vi +$2 \\Q$1\\E\\x0d/ - - And this example matches the same,but replaces it with vi-commands - you can paste directly into your (vi :) editor: - - URxvt.selection-autotransform.0: s/^([^:[:space:]]+(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/ - - Of course, this can be modified to suit your needs and your editor - :) - - To expand the example above to typical perl error messages ("XXX at - FILENAME line YYY."), you need a slightly more elaborate solution: - - URxvt.selection.pattern-0: ( at .*? line \\d+[,.]) - URxvt.selection-autotransform.0: s/^ at (.*?) line (\\d+)[,.]$/:e \\Q$1\E\\x0d:$2\\x0d/ - - The first line tells the selection code to treat the unchanging part - of every error message as a selection pattern, and the second line - transforms the message into vi commands to load the file. - - tabbed - This transforms the terminal into a tabbar with additional - terminals, that is, it implements what is commonly referred to as - "tabbed terminal". The topmost line displays a "[NEW]" button, - which, when clicked, will add a new tab, followed by one button per - tab. - - Clicking a button will activate that tab. Pressing Shift-Left and - Shift-Right will switch to the tab left or right of the current one, - while Shift-Down creates a new tab. - - The tabbar itself can be configured similarly to a normal terminal, - but with a resource class of "URxvt.tabbed". In addition, it - supports the following four resources (shown with defaults): - - URxvt.tabbed.tabbar-fg: - URxvt.tabbed.tabbar-bg: - URxvt.tabbed.tab-fg: - URxvt.tabbed.tab-bg: - - See *COLOR AND GRAPHICS* in the rxvt(1) manpage for valid indices. - - matcher - Uses per-line display filtering ("on_line_update") to underline text - matching a certain pattern and make it clickable. When clicked with - the mouse button specified in the "matcher.button" resource (default - 2, or middle), the program specified in the "matcher.launcher" - resource (default, the "urlLauncher" resource, "sensible-browser") - will be started with the matched text as first argument. The default - configuration is suitable for matching URLs and launching a web - browser, like the former "mark-urls" extension. - - The default pattern to match URLs can be overridden with the - "matcher.pattern.0" resource, and additional patterns can be - specified with numbered patterns, in a manner similar to the - "selection" extension. The launcher can also be overridden on a - per-pattern basis. - - It is possible to activate the most recently seen match from the - keyboard. Simply bind a keysym to "perl:matcher" as seen in the - example below. - - Example configuration: - - URxvt.perl-ext: default,matcher - URxvt.urlLauncher: sensible-browser - URxvt.keysym.C-Delete: perl:matcher - URxvt.matcher.button: 1 - URxvt.matcher.pattern.1: \\bwww\\.[\\w-]+\\.[\\w./?&@#-]*[\\w/-] - URxvt.matcher.pattern.2: \\B(/\\S+?):(\\d+)(?=:|$) - URxvt.matcher.launcher.2: gvim +$2 $1 - - xim-onthespot - This (experimental) perl extension implements OnTheSpot editing. It - does not work perfectly, and some input methods don't seem to work - well with OnTheSpot editing in general, but it seems to work at - least for SCIM and kinput2. - - You enable it by specifying this extension and a preedit style of - "OnTheSpot", i.e.: - - rxvt -pt OnTheSpot -pe xim-onthespot - - kuake - A very primitive quake-console-like extension. It was inspired by a - description of how the programs "kuake" and "yakuake" work: Whenever - the user presses a global accelerator key (by default "F10"), the - terminal will show or hide itself. Another press of the accelerator - key will hide or show it again. - - Initially, the window will not be shown when using this extension. - - This is useful if you need a single terminal that is not using any - desktop space most of the time but is quickly available at the press - of a key. - - The accelerator key is grabbed regardless of any modifiers, so this - extension will actually grab a physical key just for this function. - - If you want a quake-like animation, tell your window manager to do - so (fvwm can do it). - - block-graphics-to-ascii - A not very useful example of filtering all text output to the - terminal by replacing all line-drawing characters (U+2500 .. U+259F) - by a similar-looking ascii character. - - digital-clock - Displays a digital clock using the built-in overlay. - - remote-clipboard - Somewhat of a misnomer, this extension adds two menu entries to the - selection popup that allows one to run external commands to store - the selection somewhere and fetch it again. - - We use it to implement a "distributed selection mechanism", which - just means that one command uploads the file to a remote server, and - another reads it. - - The commands can be set using the "URxvt.remote-selection.store" and - "URxvt.remote-selection.fetch" resources. The first should read the - selection to store from STDIN (always in UTF-8), the second should - provide the selection data on STDOUT (also in UTF-8). - - The defaults (which are likely useless to you) use rsh and cat: - - URxvt.remote-selection.store: rsh ruth 'cat >/tmp/distributed-selection' - URxvt.remote-selection.fetch: rsh ruth 'cat /tmp/distributed-selection' - - selection-pastebin - This is a little rarely useful extension that Uploads the selection - as textfile to a remote site (or does other things). (The - implementation is not currently secure for use in a multiuser - environment as it writes to /tmp directly.). - - It listens to the "selection-pastebin:remote-pastebin" keyboard - command, i.e. - - URxvt.keysym.C-M-e: perl:selection-pastebin:remote-pastebin - - Pressing this combination runs a command with "%" replaced by the - name of the textfile. This command can be set via a resource: - - URxvt.selection-pastebin.cmd: rsync -apP % ruth:/var/www/www.ta-sa.org/files/txt/. - - And the default is likely not useful to anybody but the few people - around here :) - - The name of the textfile is the hex encoded md5 sum of the - selection, so the same content should lead to the same filename. - - After a successful upload the selection will be replaced by the text - given in the "selection-pastebin-url" resource (again, the % is the - placeholder for the filename): - - URxvt.selection-pastebin.url: http://www.ta-sa.org/files/txt/% - - *Note to xrdb users:* xrdb uses the C preprocessor, which might - interpret the double "/" characters as comment start. Use "\057\057" - instead, which works regardless of wether xrdb is used to parse the - resource file or not. - - example-refresh-hooks - Displays a very simple digital clock in the upper right corner of - the window. Illustrates overwriting the refresh callbacks to create - your own overlays or changes. - -API DOCUMENTATION - General API Considerations - All objects (such as terminals, time watchers etc.) are typical - reference-to-hash objects. The hash can be used to store anything you - like. All members starting with an underscore (such as "_ptr" or - "_hook") are reserved for internal uses and MUST NOT be accessed or - modified). - - When objects are destroyed on the C++ side, the perl object hashes are - emptied, so its best to store related objects such as time watchers and - the like inside the terminal object so they get destroyed as soon as the - terminal is destroyed. - - Argument names also often indicate the type of a parameter. Here are - some hints on what they mean: - - $text - Rxvt-unicodes special way of encoding text, where one "unicode" - character always represents one screen cell. See ROW_t for a - discussion of this format. - - $string - A perl text string, with an emphasis on *text*. It can store all - unicode characters and is to be distinguished with text encoded in a - specific encoding (often locale-specific) and binary data. - - $octets - Either binary data or - more common - a text string encoded in a - locale-specific way. - - Extension Objects - Every perl extension is a perl class. A separate perl object is created - for each terminal, and each terminal has its own set of extenion - objects, which are passed as the first parameter to hooks. So extensions - can use their $self object without having to think about clashes with - other extensions or other terminals, with the exception of methods and - members that begin with an underscore character "_": these are reserved - for internal use. - - Although it isn't a "urxvt::term" object, you can call all methods of - the "urxvt::term" class on this object. - - It has the following methods and data members: - - $urxvt_term = $self->{term} - Returns the "urxvt::term" object associated with this instance of - the extension. This member *must not* be changed in any way. - - $self->enable ($hook_name => $cb, [$hook_name => $cb..]) - Dynamically enable the given hooks (named without the "on_" prefix) - for this extension, replacing any previous hook. This is useful when - you want to overwrite time-critical hooks only temporarily. - - $self->disable ($hook_name[, $hook_name..]) - Dynamically disable the given hooks. - - Hooks - The following subroutines can be declared in extension files, and will - be called whenever the relevant event happens. - - The first argument passed to them is an extension object as described in - the in the "Extension Objects" section. - - All of these hooks must return a boolean value. If any of the called - hooks returns true, then the event counts as being *consumed*, and the - relevant action might not be carried out by the C++ code. - - *When in doubt, return a false value (preferably "()").* - - on_init $term - Called after a new terminal object has been initialized, but before - windows are created or the command gets run. Most methods are unsafe - to call or deliver senseless data, as terminal size and other - characteristics have not yet been determined. You can safely query - and change resources and options, though. For many purposes the - "on_start" hook is a better place. - - on_start $term - Called at the very end of initialisation of a new terminal, just - before trying to map (display) the toplevel and returning to the - main loop. - - on_destroy $term - Called whenever something tries to destroy terminal, when the - terminal is still fully functional (not for long, though). - - on_reset $term - Called after the screen is "reset" for any reason, such as resizing - or control sequences. Here is where you can react on changes to - size-related variables. - - on_child_start $term, $pid - Called just after the child process has been "fork"ed. - - on_child_exit $term, $status - Called just after the child process has exited. $status is the - status from "waitpid". - - on_sel_make $term, $eventtime - Called whenever a selection has been made by the user, but before - the selection text is copied, so changes to the beginning, end or - type of the selection will be honored. - - Returning a true value aborts selection making by urxvt, in which - case you have to make a selection yourself by calling - "$term->selection_grab". - - on_sel_grab $term, $eventtime - Called whenever a selection has been copied, but before the - selection is requested from the server. The selection text can be - queried and changed by calling "$term->selection". - - Returning a true value aborts selection grabbing. It will still be - highlighted. - - on_sel_extend $term - Called whenever the user tries to extend the selection (e.g. with a - double click) and is either supposed to return false (normal - operation), or should extend the selection itself and return true to - suppress the built-in processing. This can happen multiple times, as - long as the callback returns true, it will be called on every - further click by the user and is supposed to enlarge the selection - more and more, if possible. - - See the selection example extension. - - on_view_change $term, $offset - Called whenever the view offset changes, i.e. the user or program - scrolls. Offset 0 means display the normal terminal, positive values - show this many lines of scrollback. - - on_scroll_back $term, $lines, $saved - Called whenever lines scroll out of the terminal area into the - scrollback buffer. $lines is the number of lines scrolled out and - may be larger than the scroll back buffer or the terminal. - - It is called before lines are scrolled out (so rows 0 .. min ($lines - - 1, $nrow - 1) represent the lines to be scrolled out). $saved is - the total number of lines that will be in the scrollback buffer. - - on_osc_seq $term, $op, $args - Called on every OSC sequence and can be used to suppress it or - modify its behaviour. The default should be to return an empty list. - A true value suppresses execution of the request completely. Make - sure you don't get confused by recursive invocations when you output - an osc sequence within this callback. - - "on_osc_seq_perl" should be used for new behaviour. - - on_osc_seq_perl $term, $string - Called whenever the ESC ] 777 ; string ST command sequence (OSC = - operating system command) is processed. Cursor position and other - state information is up-to-date when this happens. For - interoperability, the string should start with the extension name - and a colon, to distinguish it from commands for other extensions, - and this might be enforced in the future. - - Be careful not ever to trust (in a security sense) the data you - receive, as its source can not easily be controlled (e-mail content, - messages from other users on the same system etc.). - - on_add_lines $term, $string - Called whenever text is about to be output, with the text as - argument. You can filter/change and output the text yourself by - returning a true value and calling "$term->scr_add_lines" yourself. - Please note that this might be very slow, however, as your hook is - called for all text being output. - - on_tt_write $term, $octets - Called whenever some data is written to the tty/pty and can be used - to suppress or filter tty input. - - on_line_update $term, $row - Called whenever a line was updated or changed. Can be used to filter - screen output (e.g. underline urls or other useless stuff). Only - lines that are being shown will be filtered, and, due to performance - reasons, not always immediately. - - The row number is always the topmost row of the line if the line - spans multiple rows. - - Please note that, if you change the line, then the hook might get - called later with the already-modified line (e.g. if unrelated parts - change), so you cannot just toggle rendition bits, but only set - them. - - on_refresh_begin $term - Called just before the screen gets redrawn. Can be used for overlay - or similar effects by modify terminal contents in refresh_begin, and - restoring them in refresh_end. The built-in overlay and selection - display code is run after this hook, and takes precedence. - - on_refresh_end $term - Called just after the screen gets redrawn. See "on_refresh_begin". - - on_user_command $term, $string - Called whenever a user-configured event is being activated (e.g. via - a "perl:string" action bound to a key, see description of the keysym - resource in the rxvt(1) manpage). - - The event is simply the action string. This interface is assumed to - change slightly in the future. - - on_resize_all_windows $tern, $new_width, $new_height - Called just after the new window size has been calculated, but - before windows are actually being resized or hints are being set. If - this hook returns TRUE, setting of the window hints is being - skipped. - - on_x_event $term, $event - Called on every X event received on the vt window (and possibly - other windows). Should only be used as a last resort. Most event - structure members are not passed. - - on_root_event $term, $event - Like "on_x_event", but is called for events on the root window. - - on_focus_in $term - Called whenever the window gets the keyboard focus, before - rxvt-unicode does focus in processing. - - on_focus_out $term - Called whenever the window loses keyboard focus, before rxvt-unicode - does focus out processing. - - on_configure_notify $term, $event - on_property_notify $term, $event - on_key_press $term, $event, $keysym, $octets - on_key_release $term, $event, $keysym - on_button_press $term, $event - on_button_release $term, $event - on_motion_notify $term, $event - on_map_notify $term, $event - on_unmap_notify $term, $event - Called whenever the corresponding X event is received for the - terminal If the hook returns true, then the even will be ignored by - rxvt-unicode. - - The event is a hash with most values as named by Xlib (see the - XEvent manpage), with the additional members "row" and "col", which - are the (real, not screen-based) row and column under the mouse - cursor. - - "on_key_press" additionally receives the string rxvt-unicode would - output, if any, in locale-specific encoding. - - subwindow. - - on_client_message $term, $event - on_wm_protocols $term, $event - on_wm_delete_window $term, $event - Called when various types of ClientMessage events are received (all - with format=32, WM_PROTOCOLS or WM_PROTOCOLS:WM_DELETE_WINDOW). - - Variables in the "urxvt" Package - $urxvt::LIBDIR - The rxvt-unicode library directory, where, among other things, the - perl modules and scripts are stored. - - $urxvt::RESCLASS, $urxvt::RESCLASS - The resource class and name rxvt-unicode uses to look up X - resources. - - $urxvt::RXVTNAME - The basename of the installed binaries, usually "urxvt". - - $urxvt::TERM - The current terminal. This variable stores the current "urxvt::term" - object, whenever a callback/hook is executing. - - @urxvt::TERM_INIT - All code references in this array will be called as methods of the - next newly created "urxvt::term" object (during the "on_init" - phase). The array gets cleared before the code references that were - in it are being executed, so references can push themselves onto it - again if they so desire. - - This complements to the perl-eval command line option, but gets - executed first. - - @urxvt::TERM_EXT - Works similar to @TERM_INIT, but contains perl package/class names, - which get registered as normal extensions after calling the hooks in - @TERM_INIT but before other extensions. Gets cleared just like - @TERM_INIT. - - Functions in the "urxvt" Package - urxvt::fatal $errormessage - Fatally aborts execution with the given error message. Avoid at all - costs! The only time this is acceptable is when the terminal process - starts up. - - urxvt::warn $string - Calls "rxvt_warn" with the given string which should not include a - newline. The module also overwrites the "warn" builtin with a - function that calls this function. - - Using this function has the advantage that its output ends up in the - correct place, e.g. on stderr of the connecting urxvtc client. - - Messages have a size limit of 1023 bytes currently. - - @terms = urxvt::termlist - Returns all urxvt::term objects that exist in this process, - regardless of whether they are started, being destroyed etc., so be - careful. Only term objects that have perl extensions attached will - be returned (because there is no urxvt::term objet associated with - others). - - $time = urxvt::NOW - Returns the "current time" (as per the event loop). - - urxvt::CurrentTime - urxvt::ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, - Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, - Button5Mask, AnyModifier - urxvt::NoEventMask, KeyPressMask, KeyReleaseMask, ButtonPressMask, - ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask, - PointerMotionHintMask, Button1MotionMask, Button2MotionMask, - Button3MotionMask, Button4MotionMask, Button5MotionMask, - ButtonMotionMask, KeymapStateMask, ExposureMask, VisibilityChangeMask, - StructureNotifyMask, ResizeRedirectMask, SubstructureNotifyMask, - SubstructureRedirectMask, FocusChangeMask, PropertyChangeMask, - ColormapChangeMask, OwnerGrabButtonMask - urxvt::KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify, - EnterNotify, LeaveNotify, FocusIn, FocusOut, KeymapNotify, Expose, - GraphicsExpose, NoExpose, VisibilityNotify, CreateNotify, DestroyNotify, - UnmapNotify, MapNotify, MapRequest, ReparentNotify, ConfigureNotify, - ConfigureRequest, GravityNotify, ResizeRequest, CirculateNotify, - CirculateRequest, PropertyNotify, SelectionClear, SelectionRequest, - SelectionNotify, ColormapNotify, ClientMessage, MappingNotify - Various constants for use in X calls and event processing. - - RENDITION - Rendition bitsets contain information about colour, font, font styles - and similar information for each screen cell. - - The following "macros" deal with changes in rendition sets. You should - never just create a bitset, you should always modify an existing one, as - they contain important information required for correct operation of - rxvt-unicode. - - $rend = urxvt::DEFAULT_RSTYLE - Returns the default rendition, as used when the terminal is starting - up or being reset. Useful as a base to start when creating - renditions. - - $rend = urxvt::OVERLAY_RSTYLE - Return the rendition mask used for overlays by default. - - $rendbit = urxvt::RS_Bold, RS_Italic, RS_Blink, RS_RVid, RS_Uline - Return the bit that enabled bold, italic, blink, reverse-video and - underline, respectively. To enable such a style, just logically OR - it into the bitset. - - $foreground = urxvt::GET_BASEFG $rend - $background = urxvt::GET_BASEBG $rend - Return the foreground/background colour index, respectively. - - $rend = urxvt::SET_FGCOLOR $rend, $new_colour - $rend = urxvt::SET_BGCOLOR $rend, $new_colour - $rend = urxvt::SET_COLOR $rend, $new_fg, $new_bg - Replace the foreground/background colour in the rendition mask with - the specified one. - - $value = urxvt::GET_CUSTOM $rend - Return the "custom" value: Every rendition has 5 bits for use by - extensions. They can be set and changed as you like and are - initially zero. - - $rend = urxvt::SET_CUSTOM $rend, $new_value - Change the custom value. - - The "urxvt::anyevent" Class - The sole purpose of this class is to deliver an interface to the - "AnyEvent" module - any module using it will work inside urxvt without - further programming. The only exception is that you cannot wait on - condition variables, but non-blocking condvar use is ok. What this means - is that you cannot use blocking APIs, but the non-blocking variant - should work. - - The "urxvt::term" Class - $term = new urxvt::term $envhashref, $rxvtname, [arg...] - Creates a new terminal, very similar as if you had started it with - system "$rxvtname, arg...". $envhashref must be a reference to a - %ENV-like hash which defines the environment of the new terminal. - - Croaks (and probably outputs an error message) if the new instance - couldn't be created. Returns "undef" if the new instance didn't - initialise perl, and the terminal object otherwise. The "init" and - "start" hooks will be called before this call returns, and are free - to refer to global data (which is race free). - - $term->destroy - Destroy the terminal object (close the window, free resources etc.). - Please note that rxvt will not exit as long as any event watchers - (timers, io watchers) are still active. - - $term->exec_async ($cmd[, @args]) - Works like the combination of the "fork"/"exec" builtins, which - executes ("starts") programs in the background. This function takes - care of setting the user environment before exec'ing the command - (e.g. "PATH") and should be preferred over explicit calls to "exec" - or "system". - - Returns the pid of the subprocess or "undef" on error. - - $isset = $term->option ($optval[, $set]) - Returns true if the option specified by $optval is enabled, and - optionally change it. All option values are stored by name in the - hash %urxvt::OPTION. Options not enabled in this binary are not in - the hash. - - Here is a likely non-exhaustive list of option names, please see the - source file /src/optinc.h to see the actual list: - - borderLess console cursorBlink cursorUnderline hold iconic insecure - intensityStyles jumpScroll loginShell mapAlert meta8 mouseWheelScrollPage - override-redirect pastableTabs pointerBlank reverseVideo scrollBar - scrollBar_floating scrollBar_right scrollTtyKeypress scrollTtyOutput - scrollWithBuffer secondaryScreen secondaryScroll skipBuiltinGlyphs - transparent tripleclickwords utmpInhibit visualBell - - $value = $term->resource ($name[, $newval]) - Returns the current resource value associated with a given name and - optionally sets a new value. Setting values is most useful in the - "init" hook. Unset resources are returned and accepted as "undef". - - The new value must be properly encoded to a suitable character - encoding before passing it to this method. Similarly, the returned - value may need to be converted from the used encoding to text. - - Resource names are as defined in src/rsinc.h. Colours can be - specified as resource names of the form "color+", e.g. - "color+5". (will likely change). - - Please note that resource strings will currently only be freed when - the terminal is destroyed, so changing options frequently will eat - memory. - - Here is a likely non-exhaustive list of resource names, not all of - which are supported in every build, please see the source file - /src/rsinc.h to see the actual list: - - answerbackstring backgroundPixmap backspace_key boldFont boldItalicFont - borderLess color cursorBlink cursorUnderline cutchars delete_key - display_name embed ext_bwidth fade font geometry hold iconName - imFont imLocale inputMethod insecure int_bwidth intensityStyles - italicFont jumpScroll lineSpace loginShell mapAlert meta8 modifier - mouseWheelScrollPage name override_redirect pastableTabs path perl_eval - perl_ext_1 perl_ext_2 perl_lib pointerBlank pointerBlankDelay - preeditType print_pipe pty_fd reverseVideo saveLines scrollBar - scrollBar_align scrollBar_floating scrollBar_right scrollBar_thickness - scrollTtyKeypress scrollTtyOutput scrollWithBuffer scrollstyle - secondaryScreen secondaryScroll selectstyle shade term_name title - transient_for transparent transparent_all tripleclickwords utmpInhibit - visualBell - - $value = $term->x_resource ($pattern) - Returns the X-Resource for the given pattern, excluding the program - or class name, i.e. "$term->x_resource ("boldFont")" should return - the same value as used by this instance of rxvt-unicode. Returns - "undef" if no resource with that pattern exists. - - This method should only be called during the "on_start" hook, as - there is only one resource database per display, and later - invocations might return the wrong resources. - - $success = $term->parse_keysym ($keysym_spec, $command_string) - Adds a keymap translation exactly as specified via a resource. See - the "keysym" resource in the rxvt(1) manpage. - - $rend = $term->rstyle ([$new_rstyle]) - Return and optionally change the current rendition. Text that is - output by the terminal application will use this style. - - ($row, $col) = $term->screen_cur ([$row, $col]) - Return the current coordinates of the text cursor position and - optionally set it (which is usually bad as applications don't expect - that). - - ($row, $col) = $term->selection_mark ([$row, $col]) - ($row, $col) = $term->selection_beg ([$row, $col]) - ($row, $col) = $term->selection_end ([$row, $col]) - Return the current values of the selection mark, begin or end - positions, and optionally set them to new values. - - $term->selection_make ($eventtime[, $rectangular]) - Tries to make a selection as set by "selection_beg" and - "selection_end". If $rectangular is true (default: false), a - rectangular selection will be made. This is the prefered function to - make a selection. - - $success = $term->selection_grab ($eventtime) - Try to request the primary selection text from the server (for - example, as set by the next method). No visual feedback will be - given. This function is mostly useful from within "on_sel_grab" - hooks. - - $oldtext = $term->selection ([$newtext]) - Return the current selection text and optionally replace it by - $newtext. - - $term->overlay_simple ($x, $y, $text) - Create a simple multi-line overlay box. See the next method for - details. - - $term->overlay ($x, $y, $width, $height[, $rstyle[, $border]]) - Create a new (empty) overlay at the given position with the given - width/height. $rstyle defines the initial rendition style (default: - "OVERLAY_RSTYLE"). - - If $border is 2 (default), then a decorative border will be put - around the box. - - If either $x or $y is negative, then this is counted from the - right/bottom side, respectively. - - This method returns an urxvt::overlay object. The overlay will be - visible as long as the perl object is referenced. - - The methods currently supported on "urxvt::overlay" objects are: - - $overlay->set ($x, $y, $text, $rend) - Similar to "$term->ROW_t" and "$term->ROW_r" in that it puts - text in rxvt-unicode's special encoding and an array of - rendition values at a specific position inside the overlay. - - $overlay->hide - If visible, hide the overlay, but do not destroy it. - - $overlay->show - If hidden, display the overlay again. - - $popup = $term->popup ($event) - Creates a new "urxvt::popup" object that implements a popup menu. - The $event *must* be the event causing the menu to pop up (a button - event, currently). - - $cellwidth = $term->strwidth ($string) - Returns the number of screen-cells this string would need. Correctly - accounts for wide and combining characters. - - $octets = $term->locale_encode ($string) - Convert the given text string into the corresponding locale - encoding. - - $string = $term->locale_decode ($octets) - Convert the given locale-encoded octets into a perl string. - - $term->scr_xor_span ($beg_row, $beg_col, $end_row, $end_col[, $rstyle]) - XORs the rendition values in the given span with the provided value - (default: "RS_RVid"), which *MUST NOT* contain font styles. Useful - in refresh hooks to provide effects similar to the selection. - - $term->scr_xor_rect ($beg_row, $beg_col, $end_row, $end_col[, $rstyle1[, - $rstyle2]]) - Similar to "scr_xor_span", but xors a rectangle instead. Trailing - whitespace will additionally be xored with the $rstyle2, which - defaults to "RS_RVid | RS_Uline", which removes reverse video again - and underlines it instead. Both styles *MUST NOT* contain font - styles. - - $term->scr_bell - Ring the bell! - - $term->scr_add_lines ($string) - Write the given text string to the screen, as if output by the - application running inside the terminal. It may not contain command - sequences (escape codes), but is free to use line feeds, carriage - returns and tabs. The string is a normal text string, not in - locale-dependent encoding. - - Normally its not a good idea to use this function, as programs might - be confused by changes in cursor position or scrolling. Its useful - inside a "on_add_lines" hook, though. - - $term->scr_change_screen ($screen) - Switch to given screen - 0 primary, 1 secondary. - - $term->cmd_parse ($octets) - Similar to "scr_add_lines", but the argument must be in the - locale-specific encoding of the terminal and can contain command - sequences (escape codes) that will be interpreted. - - $term->tt_write ($octets) - Write the octets given in $data to the tty (i.e. as program input). - To pass characters instead of octets, you should convert your - strings first to the locale-specific encoding using - "$term->locale_encode". - - $old_events = $term->pty_ev_events ([$new_events]) - Replaces the event mask of the pty watcher by the given event mask. - Can be used to suppress input and output handling to the pty/tty. - See the description of "urxvt::timer->events". Make sure to always - restore the previous value. - - $fd = $term->pty_fd - Returns the master file descriptor for the pty in use, or -1 if no - pty is used. - - $windowid = $term->parent - Return the window id of the toplevel window. - - $windowid = $term->vt - Return the window id of the terminal window. - - $term->vt_emask_add ($x_event_mask) - Adds the specified events to the vt event mask. Useful e.g. when you - want to receive pointer events all the times: - - $term->vt_emask_add (urxvt::PointerMotionMask); - - $term->focus_in - $term->focus_out - $term->key_press ($state, $keycode[, $time]) - $term->key_release ($state, $keycode[, $time]) - Deliver various fake events to to terminal. - - $window_width = $term->width - $window_height = $term->height - $font_width = $term->fwidth - $font_height = $term->fheight - $font_ascent = $term->fbase - $terminal_rows = $term->nrow - $terminal_columns = $term->ncol - $has_focus = $term->focus - $is_mapped = $term->mapped - $max_scrollback = $term->saveLines - $nrow_plus_saveLines = $term->total_rows - $topmost_scrollback_row = $term->top_row - Return various integers describing terminal characteristics. - - $x_display = $term->display_id - Return the DISPLAY used by rxvt-unicode. - - $lc_ctype = $term->locale - Returns the LC_CTYPE category string used by this rxvt-unicode. - - $env = $term->env - Returns a copy of the environment in effect for the terminal as a - hashref similar to "\%ENV". - - @envv = $term->envv - Returns the environment as array of strings of the form "VAR=VALUE". - - @argv = $term->argv - Return the argument vector as this terminal, similar to @ARGV, but - includes the program name as first element. - - $modifiermask = $term->ModLevel3Mask - $modifiermask = $term->ModMetaMask - $modifiermask = $term->ModNumLockMask - Return the modifier masks corresponding to the "ISO Level 3 Shift" - (often AltGr), the meta key (often Alt) and the num lock key, if - applicable. - - $screen = $term->current_screen - Returns the currently displayed screen (0 primary, 1 secondary). - - $cursor_is_hidden = $term->hidden_cursor - Returns whether the cursor is currently hidden or not. - - $view_start = $term->view_start ([$newvalue]) - Returns the row number of the topmost displayed line. Maximum value - is 0, which displays the normal terminal contents. Lower values - scroll this many lines into the scrollback buffer. - - $term->want_refresh - Requests a screen refresh. At the next opportunity, rxvt-unicode - will compare the on-screen display with its stored representation. - If they differ, it redraws the differences. - - Used after changing terminal contents to display them. - - $text = $term->ROW_t ($row_number[, $new_text[, $start_col]]) - Returns the text of the entire row with number $row_number. Row 0 is - the topmost terminal line, row "$term->$ncol-1" is the bottommost - terminal line. The scrollback buffer starts at line -1 and extends - to line "-$term->nsaved". Nothing will be returned if a nonexistent - line is requested. - - If $new_text is specified, it will replace characters in the current - line, starting at column $start_col (default 0), which is useful to - replace only parts of a line. The font index in the rendition will - automatically be updated. - - $text is in a special encoding: tabs and wide characters that use - more than one cell when displayed are padded with $urxvt::NOCHAR - (chr 65535) characters. Characters with combining characters and - other characters that do not fit into the normal tetx encoding will - be replaced with characters in the private use area. - - You have to obey this encoding when changing text. The advantage is - that "substr" and similar functions work on screen cells and not on - characters. - - The methods "$term->special_encode" and "$term->special_decode" can - be used to convert normal strings into this encoding and vice versa. - - $rend = $term->ROW_r ($row_number[, $new_rend[, $start_col]]) - Like "$term->ROW_t", but returns an arrayref with rendition bitsets. - Rendition bitsets contain information about colour, font, font - styles and similar information. See also "$term->ROW_t". - - When setting rendition, the font mask will be ignored. - - See the section on RENDITION, above. - - $length = $term->ROW_l ($row_number[, $new_length]) - Returns the number of screen cells that are in use ("the line - length"). Unlike the urxvt core, this returns "$term->ncol" if the - line is joined with the following one. - - $bool = $term->is_longer ($row_number) - Returns true if the row is part of a multiple-row logical "line" - (i.e. joined with the following row), which means all characters are - in use and it is continued on the next row (and possibly a - continuation of the previous row(s)). - - $line = $term->line ($row_number) - Create and return a new "urxvt::line" object that stores information - about the logical line that row $row_number is part of. It supports - the following methods: - - $text = $line->t ([$new_text]) - Returns or replaces the full text of the line, similar to - "ROW_t" - - $rend = $line->r ([$new_rend]) - Returns or replaces the full rendition array of the line, - similar to "ROW_r" - - $length = $line->l - Returns the length of the line in cells, similar to "ROW_l". - - $rownum = $line->beg - $rownum = $line->end - Return the row number of the first/last row of the line, - respectively. - - $offset = $line->offset_of ($row, $col) - Returns the character offset of the given row|col pair within - the logical line. Works for rows outside the line, too, and - returns corresponding offsets outside the string. - - ($row, $col) = $line->coord_of ($offset) - Translates a string offset into terminal coordinates again. - - $text = $term->special_encode $string - Converts a perl string into the special encoding used by - rxvt-unicode, where one character corresponds to one screen cell. - See "$term->ROW_t" for details. - - $string = $term->special_decode $text - Converts rxvt-unicodes text representation into a perl string. See - "$term->ROW_t" for details. - - $success = $term->grab_button ($button, $modifiermask[, $window = - $term->vt]) - $term->ungrab_button ($button, $modifiermask[, $window = $term->vt]) - Register/unregister a synchronous button grab. See the XGrabButton - manpage. - - $success = $term->grab ($eventtime[, $sync]) - Calls XGrabPointer and XGrabKeyboard in asynchronous (default) or - synchronous ($sync is true). Also remembers the grab timestamp. - - $term->allow_events_async - Calls XAllowEvents with AsyncBoth for the most recent grab. - - $term->allow_events_sync - Calls XAllowEvents with SyncBoth for the most recent grab. - - $term->allow_events_replay - Calls XAllowEvents with both ReplayPointer and ReplayKeyboard for - the most recent grab. - - $term->ungrab - Calls XUngrab for the most recent grab. Is called automatically on - evaluation errors, as it is better to lose the grab in the error - case as the session. - - $atom = $term->XInternAtom ($atom_name[, $only_if_exists]) - $atom_name = $term->XGetAtomName ($atom) - @atoms = $term->XListProperties ($window) - ($type,$format,$octets) = $term->XGetWindowProperty ($window, $property) - $term->XChangeWindowProperty ($window, $property, $type, $format, - $octets) - $term->XDeleteProperty ($window, $property) - $window = $term->DefaultRootWindow - $term->XReparentWindow ($window, $parent, [$x, $y]) - $term->XMapWindow ($window) - $term->XUnmapWindow ($window) - $term->XMoveResizeWindow ($window, $x, $y, $width, $height) - ($x, $y, $child_window) = $term->XTranslateCoordinates ($src, $dst, $x, - $y) - $term->XChangeInput ($window, $add_events[, $del_events]) - Various X or X-related functions. The $term object only serves as - the source of the display, otherwise those functions map - more-or-less directory onto the X functions of the same name. - - The "urxvt::popup" Class - $popup->add_title ($title) - Adds a non-clickable title to the popup. - - $popup->add_separator ([$sepchr]) - Creates a separator, optionally using the character given as - $sepchr. - - $popup->add_button ($text, $cb) - Adds a clickable button to the popup. $cb is called whenever it is - selected. - - $popup->add_toggle ($text, $initial_value, $cb) - Adds a toggle/checkbox item to the popup. The callback gets called - whenever it gets toggled, with a boolean indicating its new value as - its first argument. - - $popup->show - Displays the popup (which is initially hidden). - - The "urxvt::timer" Class - This class implements timer watchers/events. Time is represented as a - fractional number of seconds since the epoch. Example: - - $term->{overlay} = $term->overlay (-1, 0, 8, 1, urxvt::OVERLAY_RSTYLE, 0); - $term->{timer} = urxvt::timer - ->new - ->interval (1) - ->cb (sub { - $term->{overlay}->set (0, 0, - sprintf "%2d:%02d:%02d", (localtime urxvt::NOW)[2,1,0]); - }); - - $timer = new urxvt::timer - Create a new timer object in started state. It is scheduled to fire - immediately. - - $timer = $timer->cb (sub { my ($timer) = @_; ... }) - Set the callback to be called when the timer triggers. - - $tstamp = $timer->at - Return the time this watcher will fire next. - - $timer = $timer->set ($tstamp) - Set the time the event is generated to $tstamp. - - $timer = $timer->interval ($interval) - Normally (and when $interval is 0), the timer will automatically - stop after it has fired once. If $interval is non-zero, then the - timer is automatically rescheduled at the given intervals. - - $timer = $timer->start - Start the timer. - - $timer = $timer->start ($tstamp) - Set the event trigger time to $tstamp and start the timer. - - $timer = $timer->after ($delay) - Like "start", but sets the expiry timer to c. - - $timer = $timer->stop - Stop the timer. - - The "urxvt::iow" Class - This class implements io watchers/events. Example: - - $term->{socket} = ... - $term->{iow} = urxvt::iow - ->new - ->fd (fileno $term->{socket}) - ->events (urxvt::EV_READ) - ->start - ->cb (sub { - my ($iow, $revents) = @_; - # $revents must be 1 here, no need to check - sysread $term->{socket}, my $buf, 8192 - or end-of-file; - }); - - $iow = new urxvt::iow - Create a new io watcher object in stopped state. - - $iow = $iow->cb (sub { my ($iow, $reventmask) = @_; ... }) - Set the callback to be called when io events are triggered. - $reventmask is a bitset as described in the "events" method. - - $iow = $iow->fd ($fd) - Set the file descriptor (not handle) to watch. - - $iow = $iow->events ($eventmask) - Set the event mask to watch. The only allowed values are - "urxvt::EV_READ" and "urxvt::EV_WRITE", which might be ORed - together, or "urxvt::EV_NONE". - - $iow = $iow->start - Start watching for requested events on the given handle. - - $iow = $iow->stop - Stop watching for events on the given file handle. - - The "urxvt::iw" Class - This class implements idle watchers, that get called automatically when - the process is idle. They should return as fast as possible, after doing - some useful work. - - $iw = new urxvt::iw - Create a new idle watcher object in stopped state. - - $iw = $iw->cb (sub { my ($iw) = @_; ... }) - Set the callback to be called when the watcher triggers. - - $timer = $timer->start - Start the watcher. - - $timer = $timer->stop - Stop the watcher. - - The "urxvt::pw" Class - This class implements process watchers. They create an event whenever a - process exits, after which they stop automatically. - - my $pid = fork; - ... - $term->{pw} = urxvt::pw - ->new - ->start ($pid) - ->cb (sub { - my ($pw, $exit_status) = @_; - ... - }); - - $pw = new urxvt::pw - Create a new process watcher in stopped state. - - $pw = $pw->cb (sub { my ($pw, $exit_status) = @_; ... }) - Set the callback to be called when the timer triggers. - - $pw = $timer->start ($pid) - Tells the watcher to start watching for process $pid. - - $pw = $pw->stop - Stop the watcher. - -ENVIRONMENT - URXVT_PERL_VERBOSITY - This variable controls the verbosity level of the perl extension. Higher - numbers indicate more verbose output. - - == 0 - fatal messages - >= 3 - script loading and management - >=10 - all called hooks - >=11 - hook return values - -AUTHOR - Marc Lehmann - http://software.schmorp.de/pkg/rxvt-unicode -