1RXVT-UNICODE/URXVT FREQUENTLY ASKED QUESTIONS
2 Meta, Features & Commandline Issues
3 My question isn't answered here, can I ask a human?
4 Before sending me mail, you could go to IRC: "irc.libera.chat", channel
5 "#rxvt-unicode" has some rxvt-unicode enthusiasts that might be
6 interested in learning about new and exciting problems (but not FAQs :).
7
8 I use Gentoo, and I have a problem...
9 There are two big problems with Gentoo Linux: first, most if not all
10 Gentoo systems are completely broken (missing or mismatched header
11 files, broken compiler etc. are just the tip of the iceberg); secondly,
12 it should be called Gentoo GNU/Linux.
13
14 For these reasons, it is impossible to support rxvt-unicode on Gentoo.
15 Problems appearing on Gentoo systems will usually simply be ignored
16 unless they can be reproduced on non-Gentoo systems.
17
18 Does it support tabs, can I have a tabbed rxvt-unicode?
19 Beginning with version 7.3, there is a perl extension that implements a
20 simple tabbed terminal. It is installed by default, so any of these
21 should give you tabs:
22
23 urxvt -pe tabbed
24
25 URxvt.perl-ext-common: default,tabbed
26
27 It will also work fine with tabbing functionality of many window
28 managers or similar tabbing programs, and its embedding-features allow
29 it to be embedded into other programs, as witnessed by doc/rxvt-tabbed
30 or the upcoming "Gtk2::URxvt" perl module, which features a tabbed urxvt
31 (murxvt) terminal as an example embedding application.
32
33 How do I know which rxvt-unicode version I'm using?
34 The version number is displayed with the usage (-h). Also the escape
35 sequence "ESC [ 8 n" sets the window title to the version number. When
36 using the urxvtc client, the version displayed is that of the daemon.
37
38 Rxvt-unicode uses gobs of memory, how can I reduce that?
39 Rxvt-unicode tries to obey the rule of not charging you for something
40 you don't use. One thing you should try is to configure out all settings
41 that you don't need, for example, Xft support is a resource hog by
42 design, when used. Compiling it out ensures that no Xft font will be
43 loaded accidentally when rxvt-unicode tries to find a font for your
44 characters.
45
46 Also, many people (me included) like large windows and even larger
47 scrollback buffers: Without "--enable-unicode3", rxvt-unicode will use 6
48 bytes per screen cell. For a 160x?? window this amounts to almost a
49 kilobyte per line. A scrollback buffer of 10000 lines will then (if
50 full) use 10 Megabytes of memory. With "--enable-unicode3" it gets
51 worse, as rxvt-unicode then uses 8 bytes per screen cell.
52
53 How can I start urxvtd in a race-free way?
54 Try "urxvtd -f -o", which tells urxvtd to open the display, create the
55 listening socket and then fork.
56
57 How can I start urxvtd automatically when I run urxvtc?
58 If you want to start urxvtd automatically whenever you run urxvtc and
59 the daemon isn't running yet, use this script:
60
61 #!/bin/sh
62 urxvtc "$@"
63 if [ $? -eq 2 ]; then
64 urxvtd -q -o -f
65 urxvtc "$@"
66 fi
67
68 This tries to create a new terminal, and if fails with exit status 2,
69 meaning it couldn't connect to the daemon, it will start the daemon and
70 re-run the command. Subsequent invocations of the script will re-use the
71 existing daemon.
72
73 Another option is to use systemd socket-based activation (see
74 systemd.socket(5)). Here is an example of a service unit file and of a
75 socket unit file for the default socket path:
76
77 urxvtd.service
78 [Unit]
79 Description=urxvt terminal daemon
80 Requires=urxvtd.socket
81
82 [Service]
83 ExecStart=/usr/bin/urxvtd -o
84
85 urxvtd.socket
86 [Unit]
87 Description=urxvt terminal daemon socket
88
89 [Socket]
90 ListenStream=%h/.urxvt/urxvtd-%H
91
92 [Install]
93 WantedBy=sockets.target
94
95 How do I distinguish whether I'm running rxvt-unicode or a regular
96xterm? I need this to decide about setting colours etc.
97 The original rxvt and rxvt-unicode always export the variable
98 "COLORTERM", so you can check and see if that is set. Note that several
99 programs, JED, slrn, Midnight Commander automatically check this
100 variable to decide whether or not to use colour.
101
102 How do I set the correct, full IP address for the DISPLAY variable?
103 If you've compiled rxvt-unicode with DISPLAY_IS_IP and have enabled
104 insecure mode then it is possible to use the following shell script
105 snippets to correctly set the display. If your version of rxvt-unicode
106 wasn't also compiled with ESCZ_ANSWER (as assumed in these snippets)
107 then the COLORTERM variable can be used to distinguish rxvt-unicode from
108 a regular xterm.
109
110 Courtesy of Chuck Blake <cblake@BBN.COM> with the following shell script
111 snippets:
112
113 # Bourne/Korn/POSIX family of shells:
114 [ ${TERM:-foo} = foo ] && TERM=xterm # assume an xterm if we don't know
115 if [ ${TERM:-foo} = xterm ]; then
116 stty -icanon -echo min 0 time 15 # see if enhanced rxvt or not
117 printf "\eZ"
118 read term_id
119 stty icanon echo
120 if [ ""${term_id} = '^[[?1;2C' -a ${DISPLAY:-foo} = foo ]; then
121 printf '\e[7n' # query the rxvt we are in for the DISPLAY string
122 read DISPLAY # set it in our local shell
123 fi
124 fi
125
126 How do I compile the manual pages on my own?
127 You need to have a recent version of perl installed as /usr/bin/perl,
128 one that comes with pod2man, pod2text and pod2xhtml (from Pod::Xhtml).
129 Then go to the doc subdirectory and enter "make alldoc".
130
131 Isn't rxvt-unicode supposed to be small? Don't all those features bloat?
132 I often get asked about this, and I think, no, they didn't cause extra
133 bloat. If you compare a minimal rxvt and a minimal urxvt, you can see
134 that the urxvt binary is larger (due to some encoding tables always
135 being compiled in), but it actually uses less memory (RSS) after
136 startup. Even with "--disable-everything", this comparison is a bit
137 unfair, as many features unique to urxvt (locale, encoding conversion,
138 iso14755 etc.) are already in use in this mode.
139
140 text data bss drs rss filename
141 98398 1664 24 15695 1824 rxvt --disable-everything
142 188985 9048 66616 18222 1788 urxvt --disable-everything
143
144 When you "--enable-everything" (which *is* unfair, as this involves xft
145 and full locale/XIM support which are quite bloaty inside libX11 and my
146 libc), the two diverge, but not unreasonably so.
147
148 text data bss drs rss filename
149 163431 2152 24 20123 2060 rxvt --enable-everything
150 1035683 49680 66648 29096 3680 urxvt --enable-everything
151
152 The very large size of the text section is explained by the east-asian
153 encoding tables, which, if unused, take up disk space but nothing else
154 and can be compiled out unless you rely on X11 core fonts that use those
155 encodings. The BSS size comes from the 64k emergency buffer that my c++
156 compiler allocates (but of course doesn't use unless you are out of
157 memory). Also, using an xft font instead of a core font immediately adds
158 a few megabytes of RSS. Xft indeed is responsible for a lot of RSS even
159 when not used.
160
161 Of course, due to every character using two or four bytes instead of
162 one, a large scrollback buffer will ultimately make rxvt-unicode use
163 more memory.
164
165 Compared to e.g. Eterm (5112k), aterm (3132k) and xterm (4680k), this
166 still fares rather well. And compared to some monsters like
167 gnome-terminal (21152k + extra 4204k in separate processes) or konsole
168 (22200k + extra 43180k in daemons that stay around after exit, plus half
169 a minute of startup time, including the hundreds of warnings it spits
170 out), it fares extremely well *g*.
171
172 Why C++, isn't that unportable/bloated/uncool?
173 Is this a question? :) It comes up very often. The simple answer is: I
174 had to write it, and C++ allowed me to write and maintain it in a
175 fraction of the time and effort (which is a scarce resource for me). Put
176 even shorter: It simply wouldn't exist without C++.
177
178 My personal stance on this is that C++ is less portable than C, but in
179 the case of rxvt-unicode this hardly matters, as its portability limits
180 are defined by things like X11, pseudo terminals, locale support and
181 unix domain sockets, which are all less portable than C++ itself.
182
183 Regarding the bloat, see the above question: It's easy to write programs
184 in C that use gobs of memory, and certainly possible to write programs
185 in C++ that don't. C++ also often comes with large libraries, but this
186 is not necessarily the case with GCC. Here is what rxvt links against on
187 my system with a minimal config:
188
189 libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x00002aaaaabc3000)
190 libc.so.6 => /lib/libc.so.6 (0x00002aaaaadde000)
191 libdl.so.2 => /lib/libdl.so.2 (0x00002aaaab01d000)
192 /lib64/ld-linux-x86-64.so.2 (0x00002aaaaaaab000)
193
194 And here is rxvt-unicode:
195
196 libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x00002aaaaabc3000)
197 libgcc_s.so.1 => /lib/libgcc_s.so.1 (0x00002aaaaada2000)
198 libc.so.6 => /lib/libc.so.6 (0x00002aaaaaeb0000)
199 libdl.so.2 => /lib/libdl.so.2 (0x00002aaaab0ee000)
200 /lib64/ld-linux-x86-64.so.2 (0x00002aaaaaaab000)
201
202 No large bloated libraries (of course, none were linked in statically),
203 except maybe libX11 :)
204
205 Rendering, Font & Look and Feel Issues
206 I can't get transparency working, what am I doing wrong?
207 First of all, transparency isn't officially supported in rxvt-unicode,
208 so you are mostly on your own. Do not bug the author about it (but you
209 may bug everybody else). Also, if you can't get it working consider it a
210 rite of passage: ... and you failed.
211
212 Here are four ways to get transparency. Do read the manpage and option
213 descriptions for the programs mentioned and rxvt-unicode. Really, do it!
214
215 1. Use pseudo-transparency:
216
217 Esetroot wallpaper.jpg
218 urxvt -tr -tint red -sh 40
219
220 That works. If you think it doesn't, you lack transparency and tinting
221 support, or you are unable to read. This method requires that the
222 background-setting program sets the _XROOTPMAP_ID or ESETROOT_PMAP_ID
223 property. Compatible programs are Esetroot, hsetroot and feh.
224
225 2. Use a simple pixmap and emulate pseudo-transparency. This enables you
226 to use effects other than tinting and shading: Just shade/tint/whatever
227 your picture with gimp or any other tool:
228
229 convert wallpaper.jpg -blur 20x20 -modulate 30 background.jpg
230 urxvt -pixmap "background.jpg;:root"
231
232 That works. If you think it doesn't, you lack GDK-PixBuf support, or you
233 are unable to read.
234
235 3. Use an ARGB visual:
236
237 urxvt -depth 32 -fg grey90 -bg rgba:0000/0000/4444/cccc
238
239 This requires XFT support, and the support of your X-server. If that
240 doesn't work for you, find a working composite manager or window
241 manager, both are required to support ARGB visuals for client windows.
242
243 4. Use xcompmgr and let it do the job:
244
245 xprop -frame -f _NET_WM_WINDOW_OPACITY 32c \
246 -set _NET_WM_WINDOW_OPACITY 0xc0000000
247
248 Then click on a window you want to make transparent. Replace 0xc0000000
249 by other values to change the degree of opacity. If it doesn't work and
250 your server crashes, you got to keep the pieces.
251
252 Why does rxvt-unicode sometimes leave pixel droppings?
253 Most fonts were not designed for terminal use, which means that
254 character size varies a lot. A font that is otherwise fine for terminal
255 use might contain some characters that are simply too wide. Rxvt-unicode
256 will avoid these characters. For characters that are just "a bit" too
257 wide a special "careful" rendering mode is used that redraws adjacent
258 characters.
259
260 All of this requires that fonts do not lie about character sizes,
261 however: Xft fonts often draw glyphs larger than their acclaimed
262 bounding box, and rxvt-unicode has no way of detecting this (the correct
263 way is to ask for the character bounding box, which unfortunately is
264 wrong in these cases).
265
266 It's not clear (to me at least), whether this is a bug in Xft, freetype,
267 or the respective font. If you encounter this problem you might try
268 using the "-lsp" option to give the font more height. If that doesn't
269 work, you might be forced to use a different font.
270
271 All of this is not a problem when using X11 core fonts, as their
272 bounding box data is correct.
273
274 How can I keep rxvt-unicode from using reverse video so much?
275 First of all, make sure you are running with the right terminal settings
276 ("TERM=rxvt-unicode"), which will get rid of most of these effects. Then
277 make sure you have specified colours for italic and bold, as otherwise
278 rxvt-unicode might use reverse video to simulate the effect:
279
280 URxvt.colorBD: white
281 URxvt.colorIT: green
282
283 Some programs assume totally weird colours (red instead of blue), how can I fix that?
284 For some unexplainable reason, some rare programs assume a very weird
285 colour palette when confronted with a terminal with more than the
286 standard 8 colours (rxvt-unicode supports 88). The right fix is, of
287 course, to fix these programs not to assume non-ISO colours without very
288 good reasons.
289
290 In the meantime, you can either edit your "rxvt-unicode" terminfo
291 definition to only claim 8 colour support or use "TERM=rxvt", which will
292 fix colours but keep you from using other rxvt-unicode features.
293
294 Can I switch the fonts at runtime?
295 Yes, using an escape sequence. Try something like this, which has the
296 same effect as using the "-fn" switch, and takes effect immediately:
297
298 printf '\33]50;%s\007' "9x15bold,xft:Kochi Gothic"
299
300 This is useful if you e.g. work primarily with japanese (and prefer a
301 japanese font), but you have to switch to chinese temporarily, where
302 japanese fonts would only be in your way.
303
304 You can think of this as a kind of manual ISO-2022 switching.
305
306 Why do italic characters look as if clipped?
307 Many fonts have difficulties with italic characters and hinting. For
308 example, the otherwise very nicely hinted font "xft:Bitstream Vera Sans
309 Mono" completely fails in its italic face. A workaround might be to
310 enable freetype autohinting, i.e. like this:
311
312 URxvt.italicFont: xft:Bitstream Vera Sans Mono:italic:autohint=true
313 URxvt.boldItalicFont: xft:Bitstream Vera Sans Mono:bold:italic:autohint=true
314
315 Can I speed up Xft rendering somehow?
316 Yes, the most obvious way to speed it up is to avoid Xft entirely, as it
317 is simply slow. If you still want Xft fonts you might try to disable
318 antialiasing (by appending ":antialias=false"), which saves lots of
319 memory and also speeds up rendering considerably.
320
321 Rxvt-unicode doesn't seem to anti-alias its fonts, what is wrong?
322 Rxvt-unicode will use whatever you specify as a font. If it needs to
323 fall back to its default font search list it will prefer X11 core fonts,
324 because they are small and fast, and then use Xft fonts. It has
325 antialiasing disabled for most of them, because the author thinks they
326 look best that way.
327
328 If you want antialiasing, you have to specify the fonts manually.
329
330 What's with this bold/blink stuff?
331 If no bold colour is set via "colorBD:", bold will invert text using the
332 standard foreground colour.
333
334 For the standard background colour, blinking will actually make the text
335 blink when compiled with "--enable-text-blink". Without
336 "--enable-text-blink", the blink attribute will be ignored.
337
338 On ANSI colours, bold/blink attributes are used to set high-intensity
339 foreground/background colours.
340
341 color0-7 are the low-intensity colours.
342
343 color8-15 are the corresponding high-intensity colours.
344
345 I don't like the screen colours. How do I change them?
346 You can change the screen colours at run-time using ~/.Xdefaults
347 resources (or as long-options).
348
349 Here are values that are supposed to resemble a VGA screen, including
350 the murky brown that passes for low-intensity yellow:
351
352 URxvt.color0: #000000
353 URxvt.color1: #A80000
354 URxvt.color2: #00A800
355 URxvt.color3: #A8A800
356 URxvt.color4: #0000A8
357 URxvt.color5: #A800A8
358 URxvt.color6: #00A8A8
359 URxvt.color7: #A8A8A8
360
361 URxvt.color8: #000054
362 URxvt.color9: #FF0054
363 URxvt.color10: #00FF54
364 URxvt.color11: #FFFF54
365 URxvt.color12: #0000FF
366 URxvt.color13: #FF00FF
367 URxvt.color14: #00FFFF
368 URxvt.color15: #FFFFFF
369
370 And here is a more complete set of non-standard colours.
371
372 URxvt.cursorColor: #dc74d1
373 URxvt.pointerColor: #dc74d1
374 URxvt.background: #0e0e0e
375 URxvt.foreground: #4ad5e1
376 URxvt.color0: #000000
377 URxvt.color8: #8b8f93
378 URxvt.color1: #dc74d1
379 URxvt.color9: #dc74d1
380 URxvt.color2: #0eb8c7
381 URxvt.color10: #0eb8c7
382 URxvt.color3: #dfe37e
383 URxvt.color11: #dfe37e
384 URxvt.color5: #9e88f0
385 URxvt.color13: #9e88f0
386 URxvt.color6: #73f7ff
387 URxvt.color14: #73f7ff
388 URxvt.color7: #e1dddd
389 URxvt.color15: #e1dddd
390
391 They have been described (not by me) as "pretty girly".
392
393 Why do some characters look so much different than others?
394 See next entry.
395
396 How does rxvt-unicode choose fonts?
397 Most fonts do not contain the full range of Unicode, which is fine.
398 Chances are that the font you (or the admin/package maintainer of your
399 system/os) have specified does not cover all the characters you want to
400 display.
401
402 rxvt-unicode makes a best-effort try at finding a replacement font.
403 Often the result is fine, but sometimes the chosen font looks
404 bad/ugly/wrong. Some fonts have totally strange characters that don't
405 resemble the correct glyph at all, and rxvt-unicode lacks the artificial
406 intelligence to detect that a specific glyph is wrong: it has to believe
407 the font that the characters it claims to contain indeed look correct.
408
409 In that case, select a font of your taste and add it to the font list,
410 e.g.:
411
412 urxvt -fn basefont,font2,font3...
413
414 When rxvt-unicode sees a character, it will first look at the base font.
415 If the base font does not contain the character, it will go to the next
416 font, and so on. Specifying your own fonts will also speed up this
417 search and use less resources within rxvt-unicode and the X-server.
418
419 The only limitation is that none of the fonts may be larger than the
420 base font, as the base font defines the terminal character cell size,
421 which must be the same due to the way terminals work.
422
423 Why do some chinese characters look so different than others?
424 This is because there is a difference between script and language --
425 rxvt-unicode does not know which language the text that is output is, as
426 it only knows the unicode character codes. If rxvt-unicode first sees a
427 japanese/chinese character, it might choose a japanese font for display.
428 Subsequent japanese characters will use that font. Now, many chinese
429 characters aren't represented in japanese fonts, so when the first
430 non-japanese character comes up, rxvt-unicode will look for a chinese
431 font -- unfortunately at this point, it will still use the japanese font
432 for chinese characters that are also in the japanese font.
433
434 The workaround is easy: just tag a chinese font at the end of your font
435 list (see the previous question). The key is to view the font list as a
436 preference list: If you expect more japanese, list a japanese font
437 first. If you expect more chinese, put a chinese font first.
438
439 In the future it might be possible to switch language preferences at
440 runtime (the internal data structure has no problem with using different
441 fonts for the same character at the same time, but no interface for this
442 has been designed yet).
443
444 Until then, you might get away with switching fonts at runtime (see "Can
445 I switch the fonts at runtime?" later in this document).
446
447 How can I make mplayer display video correctly?
448 We are working on it, in the meantime, as a workaround, use something
449 like:
450
451 urxvt -b 600 -geometry 20x1 -e sh -c 'mplayer -wid $WINDOWID file...'
452
453 Why is the cursor now blinking in emacs/vi/...?
454 This is likely caused by your editor/program's use of the "cvvis"
455 terminfo capability. Emacs uses it by default, as well as some versions
456 of vi and possibly other programs.
457
458 In emacs, you can switch that off by adding this to your ".emacs" file:
459
460 (setq visible-cursor nil)
461
462 For other programs, if they do not have an option, your have to remove
463 the "cvvis" capability from the terminfo description.
464
465 When urxvt first added the blinking cursor option, it didn't add a
466 "cvvis" capability, which served no purpose before. Version 9.21
467 introduced "cvvis" (and the ability to control blinking independent of
468 cursor shape) for compatibility with other terminals, which
469 traditionally use a blinking cursor for "cvvis". This also reflects the
470 intent of programs such as emacs, who expect "cvvis" to enable a
471 blinking cursor.
472
473 Keyboard, Mouse & User Interaction
474 The new selection selects pieces that are too big, how can I select single words?
475 If you want to select e.g. alphanumeric words, you can use the following
476 setting:
477
478 URxvt.selection.pattern-0: ([[:word:]]+)
479
480 If you click more than twice, the selection will be extended more and
481 more.
482
483 To get a selection that is very similar to the old code, try this
484 pattern:
485
486 URxvt.selection.pattern-0: ([^"&'()*,;<=>?@[\\\\]^`{|})]+)
487
488 Please also note that the *LeftClick Shift-LeftClick* combination also
489 selects words like the old code.
490
491 I don't like the new selection/popups/hotkeys/perl, how do I change/disable it?
492 You can disable the perl extension completely by setting the
493 perl-ext-common resource to the empty string, which also keeps
494 rxvt-unicode from initialising perl, saving memory.
495
496 If you only want to disable specific features, you first have to
497 identify which perl extension is responsible. For this, read the section
498 PREPACKAGED EXTENSIONS in the urxvtperl(3) manpage. For example, to
499 disable the selection-popup and option-popup, specify this
500 perl-ext-common resource:
501
502 URxvt.perl-ext-common: default,-selection-popup,-option-popup
503
504 This will keep the default extensions, but disable the two popup
505 extensions. Some extensions can also be configured, for example,
506 scrollback search mode is triggered by M-s. You can move it to any other
507 combination by adding a keysym resource that binds the desired
508 combination to the "start" action of "searchable-scrollback" and another
509 one that binds M-s to the "builtin:" action:
510
511 URxvt.keysym.CM-s: searchable-scrollback:start
512 URxvt.keysym.M-s: builtin:
513
514 The cursor moves when selecting text in the current input line, how do I switch this off?
515 See next entry.
516
517 During rlogin/ssh/telnet/etc. sessions, clicking near the cursor outputs strange escape sequences, how do I fix this?
518 These are caused by the "readline" perl extension. Under normal
519 circumstances, it will move your cursor around when you click into the
520 line that contains it. It tries hard not to do this at the wrong moment,
521 but when running a program that doesn't parse cursor movements or in
522 some cases during rlogin sessions, it fails to detect this properly.
523
524 You can permanently switch this feature off by disabling the "readline"
525 extension:
526
527 URxvt.perl-ext-common: default,-readline
528
529 My numeric keypad acts weird and generates differing output?
530 Some Debian GNU/Linux users seem to have this problem, although no
531 specific details were reported so far. It is possible that this is
532 caused by the wrong "TERM" setting, although the details of whether and
533 how this can happen are unknown, as "TERM=rxvt" should offer a
534 compatible keymap. See the answer to the previous question, and please
535 report if that helped.
536
537 My Compose (Multi_key) key is no longer working.
538 The most common causes for this are that either your locale is not set
539 correctly, or you specified a preeditType that is not supported by your
540 input method. For example, if you specified OverTheSpot and your input
541 method (e.g. the default input method handling Compose keys) does not
542 support this (for instance because it is not visual), then rxvt-unicode
543 will continue without an input method.
544
545 In this case either do not specify a preeditType or specify more than
546 one pre-edit style, such as OverTheSpot,Root,None.
547
548 If it still doesn't work, then maybe your input method doesn't support
549 compose sequences - to fall back to the built-in one, make sure you
550 don't specify an input method via "-im" or "XMODIFIERS".
551
552 I cannot type "Ctrl-Shift-2" to get an ASCII NUL character due to ISO 14755
553 Either try "Ctrl-2" alone (it often is mapped to ASCII NUL even on
554 international keyboards) or simply use ISO 14755 support to your
555 advantage, typing <Ctrl-Shift-0> to get a ASCII NUL. This works for
556 other codes, too, such as "Ctrl-Shift-1-d" to type the default telnet
557 escape character and so on.
558
559 Mouse cut/paste suddenly no longer works.
560 Make sure that mouse reporting is actually turned off since killing some
561 editors prematurely may leave it active. I've heard that tcsh may use
562 mouse reporting unless it is otherwise specified. A quick check is to
563 see if cut/paste works when the Alt or Shift keys are pressed.
564
565 What's with the strange Backspace/Delete key behaviour?
566 Assuming that the physical Backspace key corresponds to the Backspace
567 keysym (not likely for Linux ... see the following question) there are
568 two standard values that can be used for Backspace: "^H" and "^?".
569
570 Historically, either value is correct, but rxvt-unicode adopts the
571 debian policy of using "^?" when unsure, because it's the one and only
572 correct choice :).
573
574 It is possible to toggle between "^H" and "^?" with the DECBKM private
575 mode:
576
577 # use Backspace = ^H
578 $ stty erase ^H
579 $ printf "\e[?67h"
580
581 # use Backspace = ^?
582 $ stty erase ^?
583 $ printf "\e[?67l"
584
585 This helps satisfy some of the Backspace discrepancies that occur, but
586 if you use Backspace = "^H", make sure that the termcap/terminfo value
587 properly reflects that.
588
589 The Delete key is a another casualty of the ill-defined Backspace
590 problem. To avoid confusion between the Backspace and Delete keys, the
591 Delete key has been assigned an escape sequence to match the vt100 for
592 Execute ("ESC [ 3 ~") and is in the supplied termcap/terminfo.
593
594 Some other Backspace problems:
595
596 some editors use termcap/terminfo, some editors (vim I'm told) expect
597 Backspace = ^H, GNU Emacs (and Emacs-like editors) use ^H for help.
598
599 Perhaps someday this will all be resolved in a consistent manner.
600
601 I don't like the key-bindings. How do I change them?
602 There are some compile-time selections available via configure. Unless
603 you have run "configure" with the "--disable-resources" option you can
604 use the `keysym' resource to alter the keystrings associated with
605 keysyms.
606
607 Here's an example for a URxvt session started using "urxvt -name URxvt"
608
609 URxvt.keysym.Prior: \033[5~
610 URxvt.keysym.Next: \033[6~
611 URxvt.keysym.Home: \033[7~
612 URxvt.keysym.End: \033[8~
613 URxvt.keysym.Up: \033[A
614 URxvt.keysym.Down: \033[B
615 URxvt.keysym.Right: \033[C
616 URxvt.keysym.Left: \033[D
617
618 See some more examples in the documentation for the keysym resource.
619
620 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
621 KP_Insert == Insert
622 F22 == Print
623 F27 == Home
624 F29 == Prior
625 F33 == End
626 F35 == Next
627
628 Rather than have rxvt-unicode try to accommodate all the various
629 possible keyboard mappings, it is better to use `xmodmap' to remap the
630 keys as required for your particular machine.
631
632 Terminal Configuration
633 Can I see a typical configuration?
634 The default configuration tries to be xterm-like, which I don't like
635 that much, but it's least surprise to regular users.
636
637 As a rxvt or rxvt-unicode user, you are practically supposed to invest
638 time into customising your terminal. To get you started, here is the
639 author's .Xdefaults entries, with comments on what they do. It's
640 certainly not *typical*, but what's typical...
641
642 URxvt.cutchars: "()*,<>[]{}|'
643 URxvt.print-pipe: cat >/some/path
644
645 These are just for testing stuff.
646
647 URxvt.imLocale: ja_JP.UTF-8
648 URxvt.preeditType: OnTheSpot,None
649
650 This tells rxvt-unicode to use a special locale when communicating with
651 the X Input Method, and also tells it to only use the OnTheSpot pre-edit
652 type, which requires the "xim-onthespot" perl extension but rewards me
653 with correct-looking fonts.
654
655 URxvt.perl-lib: /root/lib/urxvt
656 URxvt.perl-ext-common: default,selection-autotransform,selection-pastebin,xim-onthespot,remote-clipboard
657 URxvt.selection.pattern-0: ( at .*? line \\d+)
658 URxvt.selection.pattern-1: ^(/[^:]+):\
659 URxvt.selection-autotransform.0: s/^([^:[:space:]]+):(\\d+):?$/:e \\Q$1\\E\\x0d:$2\\x0d/
660 URxvt.selection-autotransform.1: s/^ at (.*?) line (\\d+)$/:e \\Q$1\\E\\x0d:$2\\x0d/
661
662 This is my perl configuration. The first two set the perl library
663 directory and also tells urxvt to use a large number of extensions. I
664 develop for myself mostly, so I actually use most of the extensions I
665 write.
666
667 The selection stuff mainly makes the selection perl-error-message aware
668 and tells it to convert perl error messages into vi-commands to load the
669 relevant file and go to the error line number.
670
671 URxvt.scrollstyle: plain
672 URxvt.secondaryScroll: true
673
674 As the documentation says: plain is the preferred scrollbar for the
675 author. The "secondaryScroll" configures urxvt to scroll in full-screen
676 apps, like screen, so lines scrolled out of screen end up in urxvt's
677 scrollback buffer.
678
679 URxvt.background: #000000
680 URxvt.foreground: gray90
681 URxvt.color7: gray90
682 URxvt.colorBD: #ffffff
683 URxvt.cursorColor: #e0e080
684 URxvt.throughColor: #8080f0
685 URxvt.highlightColor: #f0f0f0
686
687 Some colours. Not sure which ones are being used or even non-defaults,
688 but these are in my .Xdefaults. Most notably, they set
689 foreground/background to light gray/black, and also make sure that the
690 colour 7 matches the default foreground colour.
691
692 URxvt.underlineColor: yellow
693
694 Another colour, makes underline lines look different. Sometimes hurts,
695 but is mostly a nice effect.
696
697 URxvt.geometry: 154x36
698 URxvt.loginShell: false
699 URxvt.meta: ignore
700 URxvt.utmpInhibit: true
701
702 Uh, well, should be mostly self-explanatory. By specifying some defaults
703 manually, I can quickly switch them for testing.
704
705 URxvt.saveLines: 8192
706
707 A large scrollback buffer is essential. Really.
708
709 URxvt.mapAlert: true
710
711 The only case I use it is for my IRC window, which I like to keep
712 iconified till people msg me (which beeps).
713
714 URxvt.visualBell: true
715
716 The audible bell is often annoying, especially when in a crowd.
717
718 URxvt.insecure: true
719
720 Please don't hack my mutt! Ooops...
721
722 URxvt.pastableTabs: false
723
724 I once thought this is a great idea.
725
726 urxvt.font: 9x15bold,\
727 -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso10646-1,\
728 -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso10646-1, \
729 [codeset=JISX0208]xft:Kochi Gothic, \
730 xft:Bitstream Vera Sans Mono:autohint=true, \
731 xft:Code2000:antialias=false
732 urxvt.boldFont: -xos4-terminus-bold-r-normal--14-140-72-72-c-80-iso8859-15
733 urxvt.italicFont: xft:Bitstream Vera Sans Mono:italic:autohint=true
734 urxvt.boldItalicFont: xft:Bitstream Vera Sans Mono:bold:italic:autohint=true
735
736 I wrote rxvt-unicode to be able to specify fonts exactly. So don't be
737 overwhelmed. A special note: the "9x15bold" mentioned above is actually
738 the version from XFree-3.3, as XFree-4 replaced it by a totally
739 different font (different glyphs for ";" and many other harmless
740 characters), while the second font is actually the "9x15bold" from
741 XFree4/XOrg. The bold version has less chars than the medium version, so
742 I use it for rare characters, too. When editing sources with vim, I use
743 italic for comments and other stuff, which looks quite good with
744 Bitstream Vera anti-aliased.
745
746 Terminus is a quite bad font (many very wrong glyphs), but for most of
747 my purposes, it works, and gives a different look, as my normal
748 (Non-bold) font is already bold, and I want to see a difference between
749 bold and normal fonts.
750
751 Please note that I used the "urxvt" instance name and not the "URxvt"
752 class name. That is because I use different configs for different
753 purposes, for example, my IRC window is started with "-name IRC", and
754 uses these defaults:
755
756 IRC*title: IRC
757 IRC*geometry: 87x12+535+542
758 IRC*saveLines: 0
759 IRC*mapAlert: true
760 IRC*font: suxuseuro
761 IRC*boldFont: suxuseuro
762 IRC*colorBD: white
763 IRC*keysym.M-C-1: command:\033]710;suxuseuro\007\033]711;suxuseuro\007
764 IRC*keysym.M-C-2: command:\033]710;9x15bold\007\033]711;9x15bold\007
765
766 "Alt-Ctrl-1" and "Alt-Ctrl-2" switch between two different font sizes.
767 "suxuseuro" allows me to keep an eye (and actually read) stuff while
768 keeping a very small window. If somebody pastes something complicated
769 (e.g. japanese), I temporarily switch to a larger font.
770
771 The above is all in my ".Xdefaults" (I don't use ".Xresources" nor
772 "xrdb"). I also have some resources in a separate ".Xdefaults-hostname"
773 file for different hosts, for example, on my main desktop, I use:
774
775 URxvt.keysym.C-M-q: command:\033[3;5;5t
776 URxvt.keysym.C-M-y: command:\033[3;5;606t
777 URxvt.keysym.C-M-e: command:\033[3;1605;5t
778 URxvt.keysym.C-M-c: command:\033[3;1605;606t
779 URxvt.keysym.C-M-p: perl:test
780
781 The first for keysym definitions allow me to quickly bring some windows
782 in the layout I like most. Ion users might start laughing but will stop
783 immediately when I tell them that I use my own Fvwm2 module for much the
784 same effect as Ion provides, and I only very rarely use the above key
785 combinations :->
786
787 Why doesn't rxvt-unicode read my resources?
788 Well, why, indeed? It does, in a way very similar to other X
789 applications. Most importantly, this means that if you or your OS loads
790 resources into the X display (the right way to do it), rxvt-unicode will
791 ignore any resource files in your home directory. It will only read
792 $HOME/.Xdefaults when no resources are attached to the display.
793
794 If you have or use an $HOME/.Xresources file, chances are that resources
795 are loaded into your X-server. In this case, you have to re-login after
796 every change (or run xrdb -merge $HOME/.Xresources).
797
798 Also consider the form resources have to use:
799
800 URxvt.resource: value
801
802 If you want to use another form (there are lots of different ways of
803 specifying resources), make sure you understand whether and why it
804 works. If unsure, use the form above.
805
806 When I log-in to another system it tells me about missing terminfo data?
807 The terminal description used by rxvt-unicode is not as widely available
808 as that for xterm, or even rxvt (for which the same problem often
809 arises).
810
811 The correct solution for this problem is to install the terminfo, this
812 can be done by simply installing rxvt-unicode on the remote system as
813 well (in case you have a nice package manager ready), or you can install
814 the terminfo database manually like this (with ncurses infocmp. works as
815 user and root):
816
817 REMOTE=remotesystem.domain
818 infocmp rxvt-unicode | ssh $REMOTE "mkdir -p .terminfo && cat >/tmp/ti && tic /tmp/ti"
819
820 One some systems you might need to set $TERMINFO to the full path of
821 $HOME/.terminfo for this to work.
822
823 If you cannot or do not want to do this, then you can simply set
824 "TERM=rxvt" or even "TERM=xterm", and live with the small number of
825 problems arising, which includes wrong keymapping, less and different
826 colours and some refresh errors in fullscreen applications. It's a nice
827 quick-and-dirty workaround for rare cases, though.
828
829 If you always want to do this (and are fine with the consequences) you
830 can either recompile rxvt-unicode with the desired TERM value or use a
831 resource to set it:
832
833 URxvt.termName: rxvt
834
835 If you don't plan to use rxvt (quite common...) you could also replace
836 the rxvt terminfo file with the rxvt-unicode one and use "TERM=rxvt".
837
838 nano fails with "Error opening terminal: rxvt-unicode"
839 This exceptionally confusing and useless error message is printed by
840 nano when it can't find the terminfo database. Nothing is wrong with
841 your terminal, read the previous answer for a solution.
842
843 "tic" outputs some error when compiling the terminfo entry.
844 Most likely it's the empty definition for "enacs=". Just replace it by
845 "enacs=\E[0@" and try again.
846
847 "bash"'s readline does not work correctly under urxvt.
848 See next entry.
849
850 I need a termcap file entry.
851 One reason you might want this is that some distributions or operating
852 systems still compile some programs using the long-obsoleted termcap
853 library (Fedora's bash is one example) and rely on a termcap entry for
854 "rxvt-unicode".
855
856 You could use rxvt's termcap entry with reasonable results in many
857 cases. You can also create a termcap entry by using terminfo's infocmp
858 program like this:
859
860 infocmp -C rxvt-unicode
861
862 Or you could use the termcap entry in doc/etc/rxvt-unicode.termcap,
863 generated by the command above.
864
865 Why does "ls" no longer have coloured output?
866 The "ls" in the GNU coreutils unfortunately doesn't use terminfo to
867 decide whether a terminal has colour, but uses its own configuration
868 file. Needless to say, "rxvt-unicode" is not in its default file (among
869 with most other terminals supporting colour). Either add:
870
871 TERM rxvt-unicode
872
873 to "/etc/DIR_COLORS" or simply add:
874
875 alias ls='ls --color=auto'
876
877 to your ".profile" or ".bashrc".
878
879 Why doesn't vim/emacs etc. use the 88 colour mode?
880 See next entry.
881
882 Why doesn't vim/emacs etc. make use of italic?
883 See next entry.
884
885 Why are the secondary screen-related options not working properly?
886 Make sure you are using "TERM=rxvt-unicode". Some pre-packaged
887 distributions break rxvt-unicode by setting "TERM" to "rxvt", which
888 doesn't have these extra features. Unfortunately, some of these
889 furthermore fail to even install the "rxvt-unicode" terminfo file, so
890 you will need to install it on your own (See the question When I log-in
891 to another system it tells me about missing terminfo data? on how to do
892 this).
893
894 Encoding / Locale / Input Method Issues
895 Rxvt-unicode does not seem to understand the selected encoding?
896 See next entry.
897
898 Unicode does not seem to work?
899 If you encounter strange problems like typing an accented character but
900 getting two unrelated other characters or similar, or if program output
901 is subtly garbled, then you should check your locale settings.
902
903 Rxvt-unicode must be started with the same "LC_CTYPE" setting as the
904 programs running in it. Often rxvt-unicode is started in the "C" locale,
905 while the login script running within the rxvt-unicode window changes
906 the locale to something else, e.g. "en_GB.UTF-8". Needless to say, this
907 is not going to work, and is the most common cause for problems.
908
909 The best thing is to fix your startup environment, as you will likely
910 run into other problems. If nothing works you can try this in your
911 .profile.
912
913 printf '\33]701;%s\007' "$LC_CTYPE" # $LANG or $LC_ALL are worth a try, too
914
915 If this doesn't work, then maybe you use a "LC_CTYPE" specification not
916 supported on your systems. Some systems have a "locale" command which
917 displays this (also, "perl -e0" can be used to check locale settings, as
918 it will complain loudly if it cannot set the locale). If it displays
919 something like:
920
921 locale: Cannot set LC_CTYPE to default locale: ...
922
923 Then the locale you specified is not supported on your system.
924
925 If nothing works and you are sure that everything is set correctly then
926 you will need to remember a little known fact: Some programs just don't
927 support locales :(
928
929 How does rxvt-unicode determine the encoding to use?
930 See next entry.
931
932 Is there an option to switch encodings?
933 Unlike some other terminals, rxvt-unicode has no encoding switch, and no
934 specific "utf-8" mode, such as xterm. In fact, it doesn't even know
935 about UTF-8 or any other encodings with respect to terminal I/O.
936
937 The reasons is that there exists a perfectly fine mechanism for
938 selecting the encoding, doing I/O and (most important) communicating
939 this to all applications so everybody agrees on character properties
940 such as width and code number. This mechanism is the *locale*.
941 Applications not using that info will have problems (for example,
942 "xterm" gets the width of characters wrong as it uses its own,
943 locale-independent table under all locales).
944
945 Rxvt-unicode uses the "LC_CTYPE" locale category to select encoding. All
946 programs doing the same (that is, most) will automatically agree in the
947 interpretation of characters.
948
949 Unfortunately, there is no system-independent way to select locales, nor
950 is there a standard on how locale specifiers will look like.
951
952 On most systems, the content of the "LC_CTYPE" environment variable
953 contains an arbitrary string which corresponds to an already-installed
954 locale. Common names for locales are "en_US.UTF-8", "de_DE.ISO-8859-15",
955 "ja_JP.EUC-JP", i.e. "language_country.encoding", but other forms (i.e.
956 "de" or "german") are also common.
957
958 Rxvt-unicode ignores all other locale categories, and except for the
959 encoding, ignores country or language-specific settings, i.e.
960 "de_DE.UTF-8" and "ja_JP.UTF-8" are the normally same to rxvt-unicode.
961
962 If you want to use a specific encoding you have to make sure you start
963 rxvt-unicode with the correct "LC_CTYPE" category.
964
965 Can I switch locales at runtime?
966 Yes, using an escape sequence. Try something like this, which sets
967 rxvt-unicode's idea of "LC_CTYPE".
968
969 printf '\33]701;%s\007' ja_JP.SJIS
970
971 See also the previous answer.
972
973 Sometimes this capability is rather handy when you want to work in one
974 locale (e.g. "de_DE.UTF-8") but some programs don't support it (e.g.
975 UTF-8). For example, I use this script to start "xjdic", which first
976 switches to a locale supported by xjdic and back later:
977
978 printf '\33]701;%s\007' ja_JP.SJIS
979 xjdic -js
980 printf '\33]701;%s\007' de_DE.UTF-8
981
982 You can also use xterm's "luit" program, which usually works fine,
983 except for some locales where character width differs between program-
984 and rxvt-unicode-locales.
985
986 I have problems getting my input method working.
987 Try a search engine, as this is slightly different for every input
988 method server.
989
990 Here is a checklist:
991
992 - Make sure your locale *and* the imLocale are supported on your OS.
993 Try "locale -a" or check the documentation for your OS.
994
995 - Make sure your locale or imLocale matches a locale supported by your
996 XIM.
997 For example, kinput2 does not support UTF-8 locales, you should use
998 "ja_JP.EUC-JP" or equivalent.
999
1000 - Make sure your XIM server is actually running.
1001 - Make sure the "XMODIFIERS" environment variable is set correctly when
1002 *starting* rxvt-unicode.
1003 When you want to use e.g. kinput2, it must be set to "@im=kinput2".
1004 For scim, use "@im=SCIM". You can see what input method servers are
1005 running with this command:
1006
1007 xprop -root XIM_SERVERS
1008
1009 My input method wants <some encoding> but I want UTF-8, what can I do?
1010 You can specify separate locales for the input method and the rest of
1011 the terminal, using the resource "imlocale":
1012
1013 URxvt.imlocale: ja_JP.EUC-JP
1014
1015 Now you can start your terminal with "LC_CTYPE=ja_JP.UTF-8" and still
1016 use your input method. Please note, however, that, depending on your
1017 Xlib version, you may not be able to input characters outside "EUC-JP"
1018 in a normal way then, as your input method limits you.
1019
1020 Rxvt-unicode crashes when the X Input Method changes or exits.
1021 Unfortunately, this is unavoidable, as the XIM protocol is racy by
1022 design. Applications can avoid some crashes at the expense of memory
1023 leaks, and Input Methods can avoid some crashes by careful ordering at
1024 exit time. kinput2 (and derived input methods) generally succeeds, while
1025 SCIM (or similar input methods) fails. In the end, however, crashes
1026 cannot be completely avoided even if both sides cooperate.
1027
1028 So the only workaround is not to kill your Input Method Servers.
1029
1030 Operating Systems / Package Maintaining
1031 I am maintaining rxvt-unicode for distribution/OS XXX, any recommendation?
1032 You should build one binary with the default options. configure now
1033 enables most useful options, and the trend goes to making them
1034 runtime-switchable, too, so there is usually no drawback to enabling
1035 them, except higher disk and possibly memory usage. The perl interpreter
1036 should be enabled, as important functionality (menus, selection, likely
1037 more in the future) depends on it.
1038
1039 You should not overwrite the "perl-ext-common" and "perl-ext" resources
1040 system-wide (except maybe with "defaults"). This will result in useful
1041 behaviour. If your distribution aims at low memory, add an empty
1042 "perl-ext-common" resource to the app-defaults file. This will keep the
1043 perl interpreter disabled until the user enables it.
1044
1045 If you can/want build more binaries, I recommend building a minimal one
1046 with "--disable-everything" (very useful) and a maximal one with
1047 "--enable-everything" (less useful, it will be very big due to a lot of
1048 encodings built-in that increase download times and are rarely used).
1049
1050 I need to make it setuid/setgid to support utmp/ptys on my OS, is this safe?
1051 It should be, starting with release 7.1. You are encouraged to properly
1052 install urxvt with privileges necessary for your OS now.
1053
1054 When rxvt-unicode detects that it runs setuid or setgid, it will fork
1055 into a helper process for privileged operations (pty handling on some
1056 systems, utmp/wtmp/lastlog handling on others) and drop privileges
1057 immediately. This is much safer than most other terminals that keep
1058 privileges while running (but is more relevant to urxvt, as it contains
1059 things as perl interpreters, which might be "helpful" to attackers).
1060
1061 This forking is done as the very first within main(), which is very
1062 early and reduces possible bugs to initialisation code run before
1063 main(), or things like the dynamic loader of your system, which should
1064 result in very little risk.
1065
1066 I am on FreeBSD and rxvt-unicode does not seem to work at all.
1067 Rxvt-unicode requires the symbol "__STDC_ISO_10646__" to be defined in
1068 your compile environment, or an implementation that implements it,
1069 whether it defines the symbol or not. "__STDC_ISO_10646__" requires that
1070 wchar_t is represented as unicode.
1071
1072 As you might have guessed, FreeBSD does neither define this symbol nor
1073 does it support it. Instead, it uses its own internal representation of
1074 wchar_t. This is, of course, completely fine with respect to standards.
1075
1076 However, that means rxvt-unicode only works in "POSIX", "ISO-8859-1" and
1077 "UTF-8" locales under FreeBSD (which all use Unicode as wchar_t).
1078
1079 "__STDC_ISO_10646__" is the only sane way to support multi-language apps
1080 in an OS, as using a locale-dependent (and non-standardized)
1081 representation of wchar_t makes it impossible to convert between wchar_t
1082 (as used by X11 and your applications) and any other encoding without
1083 implementing OS-specific-wrappers for each and every locale. There
1084 simply are no APIs to convert wchar_t into anything except the current
1085 locale encoding.
1086
1087 Some applications (such as the formidable mlterm) work around this by
1088 carrying their own replacement functions for character set handling with
1089 them, and either implementing OS-dependent hacks or doing multiple
1090 conversions (which is slow and unreliable in case the OS implements
1091 encodings slightly different than the terminal emulator).
1092
1093 The rxvt-unicode author insists that the right way to fix this is in the
1094 system libraries once and for all, instead of forcing every app to carry
1095 complete replacements for them :)
1096
1097 How can I use rxvt-unicode under cygwin?
1098 rxvt-unicode should compile and run out of the box on cygwin, using the
1099 X11 libraries that come with cygwin. libW11 emulation is no longer
1100 supported (and makes no sense, either, as it only supported a single
1101 font). I recommend starting the X-server in "-multiwindow" or
1102 "-rootless" mode instead, which will result in similar look&feel as the
1103 old libW11 emulation.
1104
1105 At the time of this writing, cygwin didn't seem to support any
1106 multi-byte encodings (you might try "LC_CTYPE=C-UTF-8"), so you are
1107 likely limited to 8-bit encodings.
1108
1109 Character widths are not correct.
1110 urxvt uses the system wcwidth function to know the information about the
1111 width of characters, so on systems with incorrect locale data you will
1112 likely get bad results. Two notorious examples are Solaris 9, where
1113 single-width characters like U+2514 are reported as double-width, and
1114 Darwin 8, where combining chars are reported having width 1.
1115
1116 The solution is to upgrade your system or switch to a better one. A
1117 possibly working workaround is to use a wcwidth implementation like
1118
1119 http://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c
1120
1121
