PROBLEMS 123 KB
Newer Older
Kim F. Storm's avatar
Kim F. Storm committed
1 2
Known Problems with GNU Emacs

3
Copyright (C) 1987-1989, 1993-1999, 2001-2014 Free Software Foundation, Inc.
4 5 6
See the end of the file for license conditions.


Dave Love's avatar
#  
Dave Love committed
7
This file describes various problems that have been encountered
8 9
in compiling, installing and running GNU Emacs.  Try doing C-c C-t
and browsing through the outline headers.  (See C-h m for help on
10 11 12
Outline mode.)  Information about systems that are no longer supported,
and old Emacs releases, has been removed.  Consult older versions of
this file if you are interested in that information.
Dave Love's avatar
#  
Dave Love committed
13

14
* Mule-UCS doesn't work in Emacs 23 onwards
Dave Love's avatar
Dave Love committed
15 16 17

It's completely redundant now, as far as we know.

18
* Emacs startup failures
19

20
** Emacs fails to start, complaining about missing fonts.
21

22
A typical error message might be something like
23

24
  No fonts match `-*-fixed-medium-r-*--6-*-*-*-*-*-iso8859-1'
Kenichi Handa's avatar
Kenichi Handa committed
25

26 27 28
This happens because some X resource specifies a bad font family for
Emacs to use.  The possible places where this specification might be
are:
Kenichi Handa's avatar
Kenichi Handa committed
29

30
  - in your ~/.Xdefaults file
Kenichi Handa's avatar
Kenichi Handa committed
31

32 33 34
  - client-side X resource file, such as  ~/Emacs or
    /usr/X11R6/lib/app-defaults/Emacs or
    /usr/X11R6/lib/X11/app-defaults/Emacs
Kenichi Handa's avatar
Kenichi Handa committed
35

36 37 38
One of these files might have bad or malformed specification of a
fontset that Emacs should use.  To fix the problem, you need to find
the problematic line(s) and correct them.
Kenichi Handa's avatar
Kenichi Handa committed
39

40
** Emacs aborts while starting up, only when run without X.
Kenichi Handa's avatar
Kenichi Handa committed
41

42 43 44 45 46 47 48 49 50
This problem often results from compiling Emacs with GCC when GCC was
installed incorrectly.  The usual error in installing GCC is to
specify --includedir=/usr/include.  Installation of GCC makes
corrected copies of the system header files.  GCC is supposed to use
the corrected copies in preference to the original system headers.
Specifying --includedir=/usr/include causes the original system header
files to be used.  On some systems, the definition of ioctl in the
original system header files is invalid for ANSI C and causes Emacs
not to work.
Kenichi Handa's avatar
Kenichi Handa committed
51

52 53 54 55
The fix is to reinstall GCC, and this time do not specify --includedir
when you configure it.  Then recompile Emacs.  Specifying --includedir
is appropriate only in very special cases and it should *never* be the
same directory where system header files are kept.
Kenichi Handa's avatar
Kenichi Handa committed
56

57
** Emacs does not start, complaining that it cannot open termcap database file.
Kenichi Handa's avatar
Kenichi Handa committed
58

59 60 61 62 63 64
If your system uses Terminfo rather than termcap (most modern
systems do), this could happen if the proper version of
ncurses is not visible to the Emacs configure script (i.e. it
cannot be found along the usual path the linker looks for
libraries). It can happen because your version of ncurses is
obsolete, or is available only in form of binaries.
Kenichi Handa's avatar
Kenichi Handa committed
65

66 67 68 69
The solution is to install an up-to-date version of ncurses in
the developer's form (header files, static libraries and
symbolic links); in some GNU/Linux distributions (e.g. Debian)
it constitutes a separate package.
Kenichi Handa's avatar
Kenichi Handa committed
70

71
** Emacs 20 and later fails to load Lisp files at startup.
72

73
The typical error message might be like this:
74

75
  "Cannot open load file: fontset"
76

77 78 79 80 81 82 83
This could happen if you compress the file lisp/subdirs.el.  That file
tells Emacs what are the directories where it should look for Lisp
files.  Emacs cannot work with subdirs.el compressed, since the
Auto-compress mode it needs for this will not be loaded until later,
when your .emacs file is processed.  (The package `fontset.el' is
required to set up fonts used to display text on window systems, and
it's loaded very early in the startup procedure.)
84

85 86
Similarly, any other .el file for which there's no corresponding .elc
file could fail to load if it is compressed.
Dave Love's avatar
Dave Love committed
87

88
The solution is to uncompress all .el files that don't have a .elc file.
Kenichi Handa's avatar
Kenichi Handa committed
89

90
Another possible reason for such failures is stale *.elc files
91
lurking somewhere on your load-path -- see the next section.
Dave Love's avatar
Dave Love committed
92

93
** Emacs prints an error at startup after upgrading from an earlier version.
Dave Love's avatar
Dave Love committed
94

95
An example of such an error is:
Dave Love's avatar
Dave Love committed
96

97
  x-complement-fontset-spec: "Wrong type argument: stringp, nil"
Dave Love's avatar
Dave Love committed
98

99 100 101
This can be another symptom of stale *.elc files in your load-path.
The following command will print any duplicate Lisp files that are
present in load-path:
Dave Love's avatar
Dave Love committed
102

Glenn Morris's avatar
Glenn Morris committed
103
    emacs -batch -f list-load-path-shadows
Dave Love's avatar
Dave Love committed
104

105 106 107
If this command prints any file names, some of these files are stale,
and should be deleted or their directories removed from your
load-path.
Simon Josefsson's avatar
Simon Josefsson committed
108

109
* Crash bugs
110

111
** Emacs crashes when running in a terminal, if compiled with GCC 4.5.0
112 113
This version of GCC is buggy: see

114
  http://debbugs.gnu.org/6031
115 116 117 118 119 120 121
  http://gcc.gnu.org/bugzilla/show_bug.cgi?id=43904

You can work around this error in gcc-4.5 by omitting sibling call
optimization.  To do this, configure Emacs with

 CFLAGS="-g -O2 -fno-optimize-sibling-calls" ./configure

122 123 124 125 126 127 128 129
** Emacs compiled with GCC 4.6.1 crashes on MS-Windows when C-g is pressed

This is known to happen when Emacs is compiled with MinGW GCC 4.6.1
with the -O2 option (which is the default in the Windows build).  The
reason is a bug in MinGW GCC 4.6.1; to work around, either add the
`-fno-omit-frame-pointer' switch to GCC or compile without
optimizations (`--no-opt' switch to the configure.bat script).

130
** Emacs crashes in x-popup-dialog.
131

132 133 134 135
This can happen if the dialog widget cannot find the font it wants to
use.  You can work around the problem by specifying another font with
an X resource--for example, `Emacs.dialog*.font: 9x15' (or any font that
happens to exist on your X server).
Dave Love's avatar
Dave Love committed
136

137
** Emacs crashes when you use Bibtex mode.
Dave Love's avatar
Dave Love committed
138

139 140 141
This happens if your system puts a small limit on stack size.  You can
prevent the problem by using a suitable shell command (often `ulimit')
to raise the stack size limit before you run Emacs.
142

143 144
Patches to raise the stack size limit automatically in `main'
(src/emacs.c) on various systems would be greatly appreciated.
Dave Love's avatar
Dave Love committed
145

146 147
** Error message `Symbol's value as variable is void: x', followed by
a segmentation fault and core dump.
148

149 150
This has been tracked to a bug in tar!  People report that tar erroneously
added a line like this at the beginning of files of Lisp code:
151

152
   x FILENAME, N bytes, B tape blocks
153

154 155
If your tar has this problem, install GNU tar--if you can manage to
untar it :-).
156

157
** Emacs can crash when displaying PNG images with transparency.
158 159
This is due to a bug introduced in ImageMagick 6.8.2-3.  The bug should
be fixed in ImageMagick 6.8.3-10.  See <URL:http://debbugs.gnu.org/13867>.
160

161 162 163 164 165
** Crashes when displaying GIF images in Emacs built with version
libungif-4.1.0 are resolved by using version libungif-4.1.0b1.
Configure checks for the correct version, but this problem could occur
if a binary built against a shared libungif is run on a system with an
older version.
166

167
** Emacs aborts inside the function `tparam1'.
168

169 170 171 172 173
This can happen if Emacs was built without terminfo support, but the
terminal's capabilities use format that is only supported by terminfo.
If your system has ncurses installed, this might happen if your
version of ncurses is broken; upgrading to a newer version of ncurses
and reconfiguring and rebuilding Emacs should solve this.
174

175 176 177
All modern systems support terminfo, so even if ncurses is not the
problem, you should look for a way to configure Emacs so that it uses
terminfo when built.
178

179
** Emacs crashes when using some version of the Exceed X server.
180

181 182 183
Upgrading to a newer version of Exceed has been reported to prevent
these crashes.  You should consider switching to a free X server, such
as Xming or Cygwin/X.
184

185
** Emacs crashes with SIGSEGV in XtInitializeWidgetClass.
186

187
It crashes on X, but runs fine when called with option "-nw".
188

189 190 191 192
This has been observed when Emacs is linked with GNU ld but without passing
the -z nocombreloc flag.  Emacs normally knows to pass the -z nocombreloc
flag when needed, so if you come across a situation where the flag is
necessary but missing, please report it via M-x report-emacs-bug.
193

194 195
On platforms such as Solaris, you can also work around this problem by
configuring your compiler to use the native linker instead of GNU ld.
196

197
** When Emacs is compiled with Gtk+, closing a display kills Emacs.
198

199 200
There is a long-standing bug in GTK that prevents it from recovering
from disconnects: http://bugzilla.gnome.org/show_bug.cgi?id=85715.
201

202 203 204 205
Thus, for instance, when Emacs is run as a server on a text terminal,
and an X frame is created, and the X server for that frame crashes or
exits unexpectedly, Emacs must exit to prevent a GTK error that would
result in an endless loop.
206

207 208
If you need Emacs to be able to recover from closing displays, compile
it with the Lucid toolkit instead of GTK.
209

210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230
** Emacs crashes when you try to view a file with complex characters.
For example, the etc/HELLO file (as shown by C-h h).
The message "symbol lookup error: /usr/bin/emacs: undefined symbol: OTF_open"
is shown in the terminal from which you launched Emacs.
This problem only happens when you use a graphical display (ie not
with -nw) and compiled Emacs with the "libotf" library for complex
text handling.

This problem occurs because unfortunately there are two libraries
called "libotf".  One is the library for handling OpenType fonts,
http://www.m17n.org/libotf/, which is the one that Emacs expects.
The other is a library for Open Trace Format, and is used by some
versions of the MPI message passing interface for parallel
programming.

For example, on RHEL6 GNU/Linux, the OpenMPI rpm provides a version
of "libotf.so" in /usr/lib/openmpi/lib.  This directory is not
normally in the ld search path, but if you want to use OpenMPI,
you must issue the command "module load openmpi".  This adds
/usr/lib/openmpi/lib to LD_LIBRARY_PATH.  If you then start Emacs from
the same shell, you will encounter this crash.
231
Ref: <URL:https://bugzilla.redhat.com/show_bug.cgi?id=844776>
232 233 234 235 236 237 238 239

There is no good solution to this problem if you need to use both
OpenMPI and Emacs with libotf support.  The best you can do is use a
wrapper shell script (or function) "emacs" that removes the offending
element from LD_LIBRARY_PATH before starting emacs proper.
Or you could recompile Emacs with an -Wl,-rpath option that
gives the location of the correct libotf.

240
* General runtime problems
241

242
** Lisp problems
243

244
*** Changes made to .el files do not take effect.
245

246 247 248 249
You may have forgotten to recompile them into .elc files.
Then the old .elc files will be loaded, and your changes
will not be seen.  To fix this, do M-x byte-recompile-directory
and specify the directory that contains the Lisp files.
250

251
Emacs prints a warning when loading a .elc file which is older
252
than the corresponding .el file.
253

254 255 256 257
Alternatively, if you set the option `load-prefer-newer' non-nil,
Emacs will load whichever version of a file is the newest.

*** Watch out for the EMACSLOADPATH environment variable
258

259
EMACSLOADPATH overrides which directories the function "load" will search.
260

261 262
If you observe strange problems, check for this variable in your
environment.
Dave Love's avatar
Dave Love committed
263

264
*** Using epop3.el package causes Emacs to signal an error.
Dave Love's avatar
Dave Love committed
265

266
The error message might be something like this:
267

268
  "Lisp nesting exceeds max-lisp-eval-depth"
269

270 271 272 273
This happens because epop3 redefines the function gethash, which is a
built-in primitive beginning with Emacs 21.1.  We don't have a patch
for epop3 that fixes this, but perhaps a newer version of epop3
corrects that.
274

275
*** Buffers from `with-output-to-temp-buffer' get set up in Help mode.
276

277 278 279
Changes in Emacs 20.4 to the hooks used by that function cause
problems for some packages, specifically BBDB.  See the function's
documentation for the hooks involved.  BBDB 2.00.06 fixes the problem.
280

281 282 283 284
*** The Hyperbole package causes *Help* buffers not to be displayed in
Help mode due to setting `temp-buffer-show-hook' rather than using
`add-hook'.  Using `(add-hook 'temp-buffer-show-hook
'help-mode-maybe)' after loading Hyperbole should fix this.
285

286
** Keyboard problems
287

288 289 290 291 292 293
*** Unable to enter the M-| key on some German keyboards.
Some users have reported that M-| suffers from "keyboard ghosting".
This can't be fixed by Emacs, as the keypress never gets passed to it
at all (as can be verified using "xev").  You can work around this by
typing `ESC |' instead.

294
*** "Compose Character" key does strange things when used as a Meta key.
295

296 297 298 299 300 301
If you define one key to serve as both Meta and Compose Character, you
will get strange results.  In previous Emacs versions, this "worked"
in that the key acted as Meta--that's because the older Emacs versions
did not try to support Compose Character.  Now Emacs tries to do
character composition in the standard X way.  This means that you
must pick one meaning or the other for any given key.
302

303 304
You can use both functions (Meta, and Compose Character) if you assign
them to two different keys.
305

306
*** C-z just refreshes the screen instead of suspending Emacs.
307

308 309 310
You are probably using a shell that doesn't support job control, even
though the system itself is capable of it.  Either use a different shell,
or set the variable `cannot-suspend' to a non-nil value.
311

312
** Mailers and other helper programs
313

314
*** movemail compiled with POP support can't connect to the POP server.
315

316 317 318 319 320 321
Make sure that the `pop' entry in /etc/services, or in the services
NIS map if your machine uses NIS, has the same port number as the
entry on the POP server.  A common error is for the POP server to be
listening on port 110, the assigned port for the POP3 protocol, while
the client is trying to connect on port 109, the assigned port for the
old POP protocol.
322

323
*** RMAIL gets error getting new mail.
324

325 326 327
RMAIL gets new mail from /usr/spool/mail/$USER using a program
called `movemail'.  This program interlocks with /bin/mail using
the protocol defined by /bin/mail.
328

329 330 331 332
There are two different protocols in general use.  One of them uses
the `flock' system call.  The other involves creating a lock file;
`movemail' must be able to write in /usr/spool/mail in order to do
this.  You control which one is used by defining, or not defining,
Glenn Morris's avatar
Glenn Morris committed
333
the macro MAIL_USE_FLOCK in config.h.
334 335
IF YOU DON'T USE THE FORM OF INTERLOCKING THAT IS NORMAL ON YOUR
SYSTEM, YOU CAN LOSE MAIL!
336

337 338 339 340 341
If your system uses the lock file protocol, and fascist restrictions
prevent ordinary users from writing the lock files in /usr/spool/mail,
you may need to make `movemail' setgid to a suitable group such as
`mail'.  To do this,  use the following commands (as root) after doing the
make install.
342

343 344
        chgrp mail movemail
        chmod 2755 movemail
345

346 347 348 349 350 351
Installation normally copies movemail from the build directory to an
installation directory which is usually under /usr/local/lib.  The
installed copy of movemail is usually in the directory
/usr/local/lib/emacs/VERSION/TARGET.  You must change the group and
mode of the installed copy; changing the group and mode of the build
directory copy is ineffective.
352

353
*** rcs2log gives you the awk error message "too many fields".
354

355 356
This is due to an arbitrary limit in certain versions of awk.
The solution is to use gawk (GNU awk).
357

358
** Problems with hostname resolution
359

360
*** Emacs does not know your host's fully-qualified domain name.
361

362 363 364
For example, (system-name) returns some variation on
"localhost.localdomain", rather the name you were expecting.

365
You need to configure your machine with a fully qualified domain name,
366
(i.e. a name with at least one ".") either in /etc/hosts,
367
/etc/hostname, the NIS, or wherever your system calls for specifying this.
368

369 370
If you cannot fix the configuration, you can set the Lisp variable
mail-host-address to the value you want.
371

372
** NFS
373

374 375
*** Emacs says it has saved a file, but the file does not actually
appear on disk.
376

377 378 379 380 381 382
This can happen on certain systems when you are using NFS, if the
remote disk is full.  It is due to a bug in NFS (or certain NFS
implementations), and there is apparently nothing Emacs can do to
detect the problem.  Emacs checks the failure codes of all the system
calls involved in writing a file, including `close'; but in the case
where the problem occurs, none of those system calls fails.
383

384
** PSGML conflicts with sgml-mode.
385

386 387 388 389 390 391 392
PSGML package uses the same names of some variables (like keymap)
as built-in sgml-mode.el because it was created as a replacement
of that package.  The conflict will be shown if you load
sgml-mode.el before psgml.el.  E.g. this could happen if you edit
HTML page and then start to work with SGML or XML file.  html-mode
(from sgml-mode.el) is used for HTML file and loading of psgml.el
(for sgml-mode or xml-mode) will cause an error.
393

394 395 396 397 398 399 400 401 402 403 404 405 406 407
** PCL-CVS

*** Lines are not updated or new lines are added in the buffer upon commit.

When committing files located higher in the hierarchy than the examined
directory, some versions of the CVS program return an ambiguous message
from which PCL-CVS cannot extract the full location of the committed
files.  As a result, the corresponding lines in the PCL-CVS buffer are
not updated with the new revision of these files, and new lines are
added to the top-level directory.

This can happen with CVS versions 1.12.8 and 1.12.9.  Upgrade to CVS
1.12.10 or newer to fix this problem.

408
** Miscellaneous problems
409

410 411 412 413 414 415
*** Editing files with very long lines is slow.

For example, simply moving through a file that contains hundreds of
thousands of characters per line is slow, and consumes a lot of CPU.
This is a known limitation of Emacs with no solution at this time.

416 417
*** Emacs uses 100% of CPU time

418 419 420 421
This was a known problem with some old versions of the Semantic package.
The solution was to upgrade Semantic to version 2.0pre4 (distributed
with CEDET 1.0pre4) or later.  Note that Emacs includes Semantic since
23.2, and this issue does not apply to the included version.
422

423
*** Self-documentation messages are garbled.
Jason Rumney's avatar
Jason Rumney committed
424

425
This means that the file `etc/DOC' doesn't properly correspond
426 427
with the Emacs executable.  Redumping Emacs and then installing the
corresponding pair of files should fix the problem.
428

429 430
*** Programs running under terminal emulator do not recognize `emacs'
terminal type.
431

432 433
The cause of this is a shell startup file that sets the TERMCAP
environment variable.  The terminal emulator uses that variable to
434
provide the information on the special terminal type that Emacs emulates.
435

436 437 438
Rewrite your shell startup file so that it does not change TERMCAP
in such a case.  You could use the following conditional which sets
it only if it is undefined.
439

440
    if ( ! ${?TERMCAP} ) setenv TERMCAP ~/my-termcap-file
441

442 443
Or you could set TERMCAP only when you set TERM--which should not
happen in a non-login shell.
444

445
*** In Shell mode, you get a ^M at the end of every line.
446

447 448 449 450
This happens to people who use tcsh, because it is trying to be too
smart.  It sees that the Shell uses terminal type `unknown' and turns
on the flag to output ^M at the end of each line.  You can fix the
problem by adding this to your .cshrc file:
451

452
    if ($?EMACS) then
453
        if ("$EMACS" =~ /*) then
454 455 456 457
            unset edit
            stty  -icrnl -onlcr -echo susp ^Z
        endif
    endif
458

459
*** Emacs startup on GNU/Linux systems (and possibly other systems) is slow.
460

461 462 463
This can happen if the system is misconfigured and Emacs can't get the
full qualified domain name, FQDN.  You should have your FQDN in the
/etc/hosts file, something like this:
464

465 466
127.0.0.1	localhost
129.187.137.82	nuc04.t30.physik.tu-muenchen.de	nuc04
467

468
The way to set this up may vary on non-GNU systems.
469

470
*** Attempting to visit remote files via ange-ftp fails.
471

472 473 474 475 476 477
If the error message is "ange-ftp-file-modtime: Specified time is not
representable", then this could happen when `lukemftp' is used as the
ftp client.  This was reported to happen on Debian GNU/Linux, kernel
version 2.4.3, with `lukemftp' 1.5-5, but might happen on other
systems as well.  To avoid this problem, switch to using the standard
ftp client.  On a Debian system, type
478

479
  update-alternatives --config ftp
480

481
and then choose /usr/bin/netkit-ftp.
482

483
*** Dired is very slow.
484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499

This could happen if invocation of the `df' program takes a long
time.  Possible reasons for this include:

  - ClearCase mounted filesystems (VOBs) that sometimes make `df'
    response time extremely slow (dozens of seconds);

  - slow automounters on some old versions of Unix;

  - slow operation of some versions of `df'.

To work around the problem, you could either (a) set the variable
`directory-free-space-program' to nil, and thus prevent Emacs from
invoking `df'; (b) use `df' from the GNU Fileutils package; or
(c) use CVS, which is Free Software, instead of ClearCase.

500
*** ps-print commands fail to find prologue files ps-prin*.ps.
501 502 503 504 505 506 507

This can happen if you use an old version of X-Symbol package: it
defines compatibility functions which trick ps-print into thinking it
runs in XEmacs, and look for the prologue files in a wrong directory.

The solution is to upgrade X-Symbol to a later version.

508
*** On systems with shared libraries you might encounter run-time errors
Gerd Moellmann's avatar
Gerd Moellmann committed
509 510 511 512 513
from the dynamic linker telling you that it is unable to find some
shared libraries, for instance those for Xaw3d or image support.
These errors mean Emacs has been linked with a library whose shared
library is not in the default search path of the dynamic linker.

514 515 516
Similar problems could prevent Emacs from building, since the build
process invokes Emacs several times.

Gerd Moellmann's avatar
Gerd Moellmann committed
517 518 519 520 521 522 523 524
On many systems, it is possible to set LD_LIBRARY_PATH in your
environment to specify additional directories where shared libraries
can be found.

Other systems allow to set LD_RUN_PATH in a similar way, but before
Emacs is linked.  With LD_RUN_PATH set, the linker will include a
specified run-time search path in the executable.

Richard M. Stallman's avatar
Richard M. Stallman committed
525
On some systems, Emacs can crash due to problems with dynamic
526 527 528 529 530 531 532 533 534 535 536 537 538 539
linking.  Specifically, on SGI Irix 6.5, crashes were reported with
backtraces like this:

  (dbx) where
   0 strcmp(0xf49239d, 0x4031184, 0x40302b4, 0x12, 0xf0000000, 0xf4923aa, 0x0, 0x492ddb2) ["/xlv22/ficus-jan23/work/irix/lib/libc/libc_n32_M3_ns/strings/strcmp.s":35, 0xfb7e480]
   1 general_find_symbol(0xf49239d, 0x0, 0x0, 0x0, 0xf0000000, 0xf4923aa, 0x0, 0x492ddb2)
 ["/comp2/mtibuild/v73/workarea/v7.3/rld/rld.c":2140, 0xfb65a98]
   2 resolve_symbol(0xf49239d, 0x4031184, 0x0, 0xfbdd438, 0x0, 0xf4923aa, 0x0, 0x492ddb2)
 ["/comp2/mtibuild/v73/workarea/v7.3/rld/rld.c":1947, 0xfb657e4]
   3 lazy_text_resolve(0xd18, 0x1a3, 0x40302b4, 0x12, 0xf0000000, 0xf4923aa, 0x0, 0x492ddb2)
 ["/comp2/mtibuild/v73/workarea/v7.3/rld/rld.c":997, 0xfb64d44]
   4 _rld_text_resolve(0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0)
 ["/comp2/mtibuild/v73/workarea/v7.3/rld/rld_bridge.s":175, 0xfb6032c]

Richard M. Stallman's avatar
Richard M. Stallman committed
540 541
(`rld' is the dynamic linker.)  We don't know yet why this
happens, but setting the environment variable LD_BIND_NOW to 1 (which
542 543 544
forces the dynamic linker to bind all shared objects early on) seems
to work around the problem.

Gerd Moellmann's avatar
Gerd Moellmann committed
545 546
Please refer to the documentation of your dynamic linker for details.

547
*** When you run Ispell from Emacs, it reports a "misalignment" error.
548

549 550 551 552
This can happen if you compiled the Ispell program to use ASCII
characters only and then try to use it from Emacs with non-ASCII
characters, like Latin-1.  The solution is to recompile Ispell with
support for 8-bit characters.
553

554 555
To see whether your Ispell program supports 8-bit characters, type
this at your shell's prompt:
556

557
     ispell -vv
558

559 560 561
and look in the output for the string "NO8BIT".  If Ispell says
"!NO8BIT (8BIT)", your speller supports 8-bit characters; otherwise it
does not.
562

563 564 565
To rebuild Ispell with 8-bit character support, edit the local.h file
in the Ispell distribution and make sure it does _not_ define NO8BIT.
Then rebuild the speller.
566

567 568
Another possible cause for "misalignment" error messages is that the
version of Ispell installed on your machine is old.  Upgrade.
569

570 571 572 573 574
Yet another possibility is that you are trying to spell-check a word
in a language that doesn't fit the dictionary you choose for use by
Ispell.  (Ispell can only spell-check one language at a time, because
it uses a single dictionary.)  Make sure that the text you are
spelling and the dictionary used by Ispell conform to each other.
575

576 577 578 579
If your spell-checking program is Aspell, it has been reported that if
you have a personal configuration file (normally ~/.aspell.conf), it
can cause this error.  Remove that file, execute `ispell-kill-ispell'
in Emacs, and then try spell-checking again.
580

581
* Runtime problems related to font handling
582

583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602
** Characters are displayed as empty boxes or with wrong font under X.

*** This can occur when two different versions of FontConfig are used.
For example, XFree86 4.3.0 has one version and Gnome usually comes
with a newer version.  Emacs compiled with Gtk+ will then use the
newer version.  In most cases the problem can be temporarily fixed by
stopping the application that has the error (it can be Emacs or any
other application), removing ~/.fonts.cache-1, and then start the
application again.  If removing ~/.fonts.cache-1 and restarting
doesn't help, the application with problem must be recompiled with the
same version of FontConfig as the rest of the system uses.  For KDE,
it is sufficient to recompile Qt.

*** Some fonts have a missing glyph and no default character.  This is
known to occur for character number 160 (no-break space) in some
fonts, such as Lucida but Emacs sets the display table for the unibyte
and Latin-1 version of this character to display a space.

*** Some of the fonts called for in your fontset may not exist on your
X server.
603

604 605
Each X11 font covers just a fraction of the characters that Emacs
supports.  To display the whole range of Emacs characters requires
606 607
many different fonts, collected into a fontset.  You can remedy the
problem by installing additional fonts.
608

609
The intlfonts distribution includes a full spectrum of fonts that can
610 611 612 613 614
display all the characters Emacs supports.  The etl-unicode collection
of fonts (available from <URL:ftp://ftp.x.org/contrib/fonts/> and
<URL:ftp://ftp.xfree86.org/pub/mirror/X.Org/contrib/fonts/>) includes
fonts that can display many Unicode characters; they can also be used
by ps-print and ps-mule to print Unicode characters.
615

616
** Under X11, some characters appear improperly aligned in their lines.
617

618
You may have bad X11 fonts; try installing the intlfonts distribution
619 620 621 622 623 624 625 626 627 628
or the etl-unicode collection (see above).

** Under X, an unexpected monospace font is used as the default font.

When compiled with XFT, Emacs tries to use a default font named
"monospace".  This is a "virtual font", which the operating system
(Fontconfig) redirects to a suitable font such as DejaVu Sans Mono.
On some systems, there exists a font that is actually named Monospace,
which takes over the virtual font.  This is considered an operating
system bug; see
629

630
http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00696.html
631

632 633 634 635 636 637 638 639 640 641 642
If you encounter this problem, set the default font to a specific font
in your .Xresources or initialization file.  For instance, you can put
the following in your .Xresources:

Emacs.font: DejaVu Sans Mono 12

** Certain fonts make each line take one pixel more than it should.

This is because these fonts contain characters a little taller than
the font's nominal height.  Emacs needs to make sure that lines do not
overlap.
643

644
** Font Lock displays portions of the buffer in incorrect faces.
Jason Rumney's avatar
Jason Rumney committed
645

646 647 648 649 650 651 652 653 654 655
By far the most frequent cause of this is a parenthesis `(' or a brace
`{' in column zero.  Font Lock assumes that such a paren is outside of
any comment or string.  This is of course not true in general, but the
vast majority of well-formatted program source files don't have such
parens, and therefore this assumption is used to allow optimizations
in Font Lock's syntactical analysis.  These optimizations avoid some
pathological cases where jit-lock, the Just-in-Time fontification
introduced with Emacs 21.1, could significantly slow down scrolling
through the buffer, especially scrolling backwards, and also jumping
to the end of a very large buffer.
Jason Rumney's avatar
Jason Rumney committed
656

657
Beginning with version 22.1, a parenthesis or a brace in column zero
658 659 660
is highlighted in bold-red face if it is inside a string or a comment,
to indicate that it could interfere with Font Lock (and also with
indentation) and should be moved or escaped with a backslash.
Jason Rumney's avatar
Jason Rumney committed
661

662 663 664 665 666
If you don't use large buffers, or have a very fast machine which
makes the delays insignificant, you can avoid the incorrect
fontification by setting the variable
`font-lock-beginning-of-syntax-function' to a nil value.  (This must
be done _after_ turning on Font Lock.)
667

668 669
Another alternative is to avoid a paren in column zero.  For example,
in a Lisp string you could precede the paren with a backslash.
670

671 672
** With certain fonts, when the cursor appears on a character, the
character doesn't appear--you get a solid box instead.
673

674 675 676
One user on a Linux-based GNU system reported that this problem went
away with installation of a new X server.  The failing server was
XFree86 3.1.1.  XFree86 3.1.2 works.
677

678
** Emacs pauses for several seconds when changing the default font.
679

680 681 682 683
This has been reported for fvwm 2.2.5 and the window manager of KDE
2.1.  The reason for the pause is Xt waiting for a ConfigureNotify
event from the window manager, which the window manager doesn't send.
Xt stops waiting after a default timeout of usually 5 seconds.
684

685
A workaround for this is to add something like
686

687
emacs.waitForWM: false
688

689 690
to your X resources.  Alternatively, add `(wait-for-wm . nil)' to a
frame's parameter list, like this:
691

692
   (modify-frame-parameters nil '((wait-for-wm . nil)))
693

694
(this should go into your `.emacs' file).
695

696
** Underlines appear at the wrong position.
697

698 699
This is caused by fonts having a wrong UNDERLINE_POSITION property.
Examples are the font 7x13 on XFree prior to version 4.1, or the jmk
700 701 702
neep font from the Debian xfonts-jmk package prior to version 3.0.17.
To circumvent this problem, set x-use-underline-position-properties
to nil in your `.emacs'.
703

704
To see what is the value of UNDERLINE_POSITION defined by the font,
705
type `xlsfonts -lll FONT' and look at the font's UNDERLINE_POSITION property.
Dave Love's avatar
Dave Love committed
706

707
** When using Exceed, fonts sometimes appear too tall.
708

709 710 711 712 713
When the display is set to an Exceed X-server and fonts are specified
(either explicitly with the -fn option or implicitly with X resources)
then the fonts may appear "too tall".  The actual character sizes are
correct but there is too much vertical spacing between rows,  which
gives the appearance of "double spacing".
714

715 716
To prevent this, turn off the Exceed's "automatic font substitution"
feature (in the font part of the configuration window).
717

718 719 720 721 722 723 724 725 726 727 728 729
** Subscript/superscript text in TeX is hard to read.

If `tex-fontify-script' is non-nil, tex-mode displays
subscript/superscript text in the faces subscript/superscript, which
are smaller than the normal font and lowered/raised.  With some fonts,
nested superscripts (say) can be hard to read.  Switching to a
different font, or changing your antialiasing setting (on an LCD
screen), can both make the problem disappear.  Alternatively, customize
the following variables: tex-font-script-display (how much to
lower/raise); tex-suscript-height-ratio (how much smaller than
normal); tex-suscript-height-minimum (minimum height).

730
* Internationalization problems
731

732 733 734 735 736
** M-{ does not work on a Spanish PC keyboard.

Many Spanish keyboards seem to ignore that combination.  Emacs can't
do anything about it.

737 738 739
** International characters aren't displayed under X.

*** Missing X fonts
740

741 742 743 744 745 746 747 748 749
XFree86 4 contains many fonts in iso10646-1 encoding which have
minimal character repertoires (whereas the encoding part of the font
name is meant to be a reasonable indication of the repertoire
according to the XLFD spec).  Emacs may choose one of these to display
characters from the mule-unicode charsets and then typically won't be
able to find the glyphs to display many characters.  (Check with C-u
C-x = .)  To avoid this, you may need to use a fontset which sets the
font for the mule-unicode sets explicitly.  E.g. to use GNU unifont,
include in the fontset spec:
750

751 752 753
mule-unicode-2500-33ff:-gnu-unifont-*-iso10646-1,\
mule-unicode-e000-ffff:-gnu-unifont-*-iso10646-1,\
mule-unicode-0100-24ff:-gnu-unifont-*-iso10646-1
754

755
** The UTF-8/16/7 coding systems don't encode CJK (Far Eastern) characters.
756

757 758 759 760 761 762 763 764 765 766
Emacs directly supports the Unicode BMP whose code points are in the
ranges 0000-33ff and e000-ffff, and indirectly supports the parts of
CJK characters belonging to these legacy charsets:

    GB2312, Big5, JISX0208, JISX0212, JISX0213-1, JISX0213-2, KSC5601

The latter support is done in Utf-Translate-Cjk mode (turned on by
default).   Which Unicode CJK characters are decoded into which Emacs
charset is decided by the current language environment.  For instance,
in Chinese-GB, most of them are decoded into chinese-gb2312.
Dave Love's avatar
Dave Love committed
767

768 769 770 771 772 773 774
If you read UTF-8 data with code points outside these ranges, the
characters appear in the buffer as raw bytes of the original UTF-8
(composed into a single quasi-character) and they will be written back
correctly as UTF-8, assuming you don't break the composed sequences.
If you read such characters from UTF-16 or UTF-7 data, they are
substituted with the Unicode `replacement character', and you lose
information.
Dave Love's avatar
Dave Love committed
775

776
** Accented ISO-8859-1 characters are displayed as | or _.
Dave Love's avatar
#  
Dave Love committed
777

778 779 780 781 782 783
Try other font set sizes (S-mouse-1).  If the problem persists with
other sizes as well, your text is corrupted, probably through software
that is not 8-bit clean.  If the problem goes away with another font
size, it's probably because some fonts pretend to be ISO-8859-1 fonts
when they are really ASCII fonts. In particular the schumacher-clean
fonts have this bug in some versions of X.
Dave Love's avatar
#  
Dave Love committed
784

785
To see what glyphs are included in a font, use `xfd', like this:
Dave Love's avatar
#  
Dave Love committed
786

787
  xfd -fn -schumacher-clean-medium-r-normal--12-120-75-75-c-60-iso8859-1
Dave Love's avatar
#  
Dave Love committed
788

789
If this shows only ASCII glyphs, the font is indeed the source of the problem.
Dave Love's avatar
#  
Dave Love committed
790

791 792 793
The solution is to remove the corresponding lines from the appropriate
`fonts.alias' file, then run `mkfontdir' in that directory, and then run
`xset fp rehash'.
794

795
** The `oc-unicode' package doesn't work with Emacs 21.
Dave Love's avatar
#  
Dave Love committed
796

797 798 799 800 801
This package tries to define more private charsets than there are free
slots now.  The current built-in Unicode support is actually more
flexible.  (Use option `utf-translate-cjk-mode' if you need CJK
support.)  Files encoded as emacs-mule using oc-unicode aren't
generally read correctly by Emacs 21.
Dave Love's avatar
#  
Dave Love committed
802

803
** After a while, Emacs slips into unibyte mode.
Dave Love's avatar
#  
Dave Love committed
804

805 806 807 808
The VM mail package, which is not part of Emacs, sometimes does
  (standard-display-european t)
That should be changed to
  (standard-display-european 1 t)
809

810
* X runtime problems
811

812
** X keyboard problems
813

814
*** You "lose characters" after typing Compose Character key.
Dave Love's avatar
#  
Dave Love committed
815

816 817 818 819
This is because the Compose Character key is defined as the keysym
Multi_key, and Emacs (seeing that) does the proper X11
character-composition processing.  If you don't want your Compose key
to do that, you can redefine it with xmodmap.
Dave Love's avatar
#  
Dave Love committed
820

821
For example, here's one way to turn it into a Meta key:
822

823
    xmodmap -e "keysym Multi_key = Meta_L"
Dave Love's avatar
#  
Dave Love committed
824

825 826 827
If all users at your site of a particular keyboard prefer Meta to
Compose, you can make the remapping happen automatically by adding the
xmodmap command to the xdm setup script for that display.
Dave Love's avatar
#  
Dave Love committed
828

829
*** Using X Windows, control-shift-leftbutton makes Emacs hang.
Dave Love's avatar
#  
Dave Love committed
830

831
Use the shell command `xset bc' to make the old X Menu package work.
Dave Love's avatar
#  
Dave Love committed
832

833
*** C-SPC fails to work on Fedora GNU/Linux (or with fcitx input method).
834 835 836 837 838 839 840 841 842 843 844 845 846

Fedora Core 4 steals the C-SPC key by default for the `iiimx' program
which is the input method for some languages.  It blocks Emacs users
from using the C-SPC key for `set-mark-command'.

One solutions is to remove the `<Ctrl>space' from the `Iiimx' file
which can be found in the `/usr/lib/X11/app-defaults' directory.
However, that requires root access.

Another is to specify `Emacs*useXIM: false' in your X resources.

Another is to build Emacs with the `--without-xim' configure option.

847 848 849 850 851 852
The same problem happens on any other system if you are using fcitx
(Chinese input method) which by default use C-SPC for toggling.  If
you want to use fcitx with Emacs, you have two choices.  Toggle fcitx
by another key (e.g. C-\) by modifying ~/.fcitx/config, or be
accustomed to use C-@ for `set-mark-command'.

853
*** M-SPC seems to be ignored as input.
Dave Love's avatar
#  
Dave Love committed
854

855 856
See if your X server is set up to use this as a command
for character composition.
Dave Love's avatar
#  
Dave Love committed
857

858
*** The S-C-t key combination doesn't get passed to Emacs on X.
Dave Love's avatar
#  
Dave Love committed
859

860 861 862 863 864
This happens because some X configurations assign the Ctrl-Shift-t
combination the same meaning as the Multi_key.  The offending
definition is in the file `...lib/X11/locale/iso8859-1/Compose'; there
might be other similar combinations which are grabbed by X for similar
purposes.
Dave Love's avatar
#  
Dave Love committed
865

866 867
We think that this can be countermanded with the `xmodmap' utility, if
you want to be able to bind one of these key sequences within Emacs.
Dave Love's avatar
#  
Dave Love committed
868

869
*** Under X, C-v and/or other keys don't work.
Dave Love's avatar
#  
Dave Love committed
870 871 872 873 874 875 876

These may have been intercepted by your window manager.  In
particular, AfterStep 1.6 is reported to steal C-v in its default
configuration.  Various Meta keys are also likely to be taken by the
configuration of the `feel'.  See the WM's documentation for how to
change this.

877
*** Clicking C-mouse-2 in the scroll bar doesn't split the window.
Dave Love's avatar
#  
Dave Love committed
878

879 880 881
This currently doesn't work with scroll-bar widgets (and we don't know
a good way of implementing it with widgets).  If Emacs is configured
--without-toolkit-scroll-bars, C-mouse-2 on the scroll bar does work.
Dave Love's avatar
#  
Dave Love committed
882

883 884
*** Inability to send an Alt-modified key, when Emacs is communicating
directly with an X server.
Dave Love's avatar
#  
Dave Love committed
885

886 887 888 889 890 891
If you have tried to bind an Alt-modified key as a command, and it
does not work to type the command, the first thing you should check is
whether the key is getting through to Emacs.  To do this, type C-h c
followed by the Alt-modified key.  C-h c should say what kind of event
it read.  If it says it read an Alt-modified key, then make sure you
have made the key binding correctly.
Dave Love's avatar
#  
Dave Love committed
892

893 894
If C-h c reports an event that doesn't have the Alt modifier, it may
be because your X server has no key for the Alt modifier.  The X
895
server that comes from MIT does not set up the Alt modifier by default.
Dave Love's avatar
#  
Dave Love committed
896

897
If your keyboard has keys named Alt, you can enable them as follows:
Dave Love's avatar
#  
Dave Love committed
898