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

3
Copyright (C) 1987, 1988, 1989, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
4
  2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
5 6 7 8
  Free Software Foundation, Inc.
See the end of the file for license conditions.


Dave Love's avatar
#  
Dave Love committed
9
This file describes various problems that have been encountered
10 11 12
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
Outline mode.)
Dave Love's avatar
#  
Dave Love committed
13

14
* Mule-UCS doesn't work in Emacs 23.
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 89
The solution is to uncompress all .el files which don't have a .elc
file.
Kenichi Handa's avatar
Kenichi Handa committed
90

91 92 93
Another possible reason for such failures is stale *.elc files
lurking somewhere on your load-path.  The following command will
print any duplicate Lisp files that are present in load-path:
Kenichi Handa's avatar
Kenichi Handa committed
94

95
    emacs -q -batch -f list-load-path-shadows
Kenichi Handa's avatar
Kenichi Handa committed
96

97 98 99
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.
Dave Love's avatar
Dave Love committed
100

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

103
An example of such an error is:
Dave Love's avatar
Dave Love committed
104

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

107 108 109
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
110

111
    emacs -q -batch -f list-load-path-shadows
Dave Love's avatar
Dave Love committed
112

113 114 115
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
116

117
** With X11R6.4, public-patch-3, Emacs crashes at startup.
118

119
Reportedly this patch in X fixes the problem.
120

121 122 123 124 125 126
    --- xc/lib/X11/imInt.c~	Wed Jun 30 13:31:56 1999
    +++ xc/lib/X11/imInt.c	Thu Jul  1 15:10:27 1999
    @@ -1,4 +1,4 @@
    -/* $TOG: imInt.c /main/5 1998/05/30 21:11:16 kaleb $ */
    +/* $TOG: imInt.c /main/5 1998/05/30 21:11:16 kaleb $  */
     /******************************************************************
127

128
                Copyright 1992, 1993, 1994 by FUJITSU LIMITED
129 130
    @@ -166,8 +166,8 @@
     _XimMakeImName(lcd)
131
         XLCd      lcd;
132 133 134 135 136
     {
    -    char* begin;
    -    char* end;
    +    char* begin = NULL;
    +    char* end = NULL;
137 138 139
         char* ret;
         int	i = 0;
         char* ximmodifier = XIMMODIFIER;
140
    @@ -182,7 +182,11 @@
141 142 143 144
         }
         ret = Xmalloc(end - begin + 2);
         if (ret != NULL) {
    -           (void)strncpy(ret, begin, end - begin + 1);
145
    +	if (begin != NULL) {
146
    +             (void)strncpy(ret, begin, end - begin + 1);
147
    +        } else {
148
    +     ret[0] = '\0';
149
    +	}
150 151 152
            ret[end - begin + 1] = '\0';
         }
         return ret;
153

154 155 156 157 158 159
** Emacs crashes on startup after a glibc upgrade.

This is caused by a binary incompatible change to the malloc
implementation in glibc 2.5.90-22.  As a result, Emacs binaries built
using prior versions of glibc crash when run under 2.5.90-22.

Chong Yidong's avatar
Chong Yidong committed
160
This problem was first seen in pre-release versions of Fedora 7, and
161 162 163 164 165 166 167
may be fixed in the final Fedora 7 release.  To stop the crash from
happening, first try upgrading to the newest version of glibc; if this
does not work, rebuild Emacs with the same version of glibc that you
will run it under.  For details, see

https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=239344

168
* Crash bugs
169

170
** Emacs crashes when running in a terminal, if compiled with GCC 4.5.0
171 172 173 174 175 176 177 178 179 180
This version of GCC is buggy: see

  http://debbugs.gnu.org/cgi/bugreport.cgi?bug=6031
  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

181
** Emacs crashes in x-popup-dialog.
182

183 184 185 186
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
187

188
** Emacs crashes when you use Bibtex mode.
Dave Love's avatar
Dave Love committed
189

190 191 192
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.
193

194 195
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
196

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

200 201
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:
202

203
   x FILENAME, N bytes, B tape blocks
204

205 206
If your tar has this problem, install GNU tar--if you can manage to
untar it :-).
207

208 209 210 211 212
** 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.
213

214
** Emacs aborts inside the function `tparam1'.
215

216 217 218 219 220
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.
221

222 223 224
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.
225

226
** Emacs crashes when using some version of the Exceed X server.
227

228 229 230
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.
231

232
** Emacs crashes with SIGSEGV in XtInitializeWidgetClass.
233

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

236 237 238 239
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.
240

241 242
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.
243

244
** When Emacs is compiled with Gtk+, closing a display kills Emacs.
245

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

249 250 251 252
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.
253

254 255
If you need Emacs to be able to recover from closing displays, compile
it with the Lucid toolkit instead of GTK.
256

257
* General runtime problems
258

259
** Lisp problems
260

261
*** Changes made to .el files do not take effect.
262

263 264 265 266
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.
267

268 269
Emacs should print a warning when loading a .elc file which is older
than the corresponding .el file.
270

271
*** Watch out for .emacs files and EMACSLOADPATH environment vars.
272

273 274 275 276
These control the actions of Emacs.
~/.emacs is your Emacs init file.
EMACSLOADPATH overrides which directories the function
"load" will search.
277

278 279
If you observe strange problems, check for these and get rid
of them, then try again.
Dave Love's avatar
Dave Love committed
280

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

283
The error message might be something like this:
284

285
  "Lisp nesting exceeds max-lisp-eval-depth"
286

287 288 289 290
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.
291

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

294 295 296
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.
297

298 299 300 301
*** 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.
302

303
** Keyboard problems
304

305
*** "Compose Character" key does strange things when used as a Meta key.
306

307 308 309 310 311 312
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.
313

314 315
You can use both functions (Meta, and Compose Character) if you assign
them to two different keys.
316

317
*** C-z just refreshes the screen instead of suspending Emacs.
318

319 320 321
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.
322

323 324
*** With M-x enable-flow-control, you need to type C-\ twice
to do incremental search--a single C-\ gets no response.
325

326 327 328
This has been traced to communicating with your machine via kermit,
with C-\ as the kermit escape character.  One solution is to use
another escape character in kermit.  One user did
329

330
   set escape-character 17
331

332
in his .kermrc file, to make C-q the kermit escape character.
333

334
** Mailers and other helper programs
335

336
*** movemail compiled with POP support can't connect to the POP server.
337

338 339 340 341 342 343
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.
344

345
*** RMAIL gets error getting new mail.
346

347 348 349
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.
350

351 352 353 354 355 356 357
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,
the macro MAIL_USE_FLOCK in config.h or the m- or s- file it includes.
IF YOU DON'T USE THE FORM OF INTERLOCKING THAT IS NORMAL ON YOUR
SYSTEM, YOU CAN LOSE MAIL!
358

359 360 361 362 363
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.
364

365 366
        chgrp mail movemail
        chmod 2755 movemail
367

368 369 370 371 372 373
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.
374

375
*** rcs2log gives you the awk error message "too many fields".
376

377 378
This is due to an arbitrary limit in certain versions of awk.
The solution is to use gawk (GNU awk).
379

380
** Problems with hostname resolution
381

382 383 384
*** Emacs fails to understand most Internet host names, even though
the names work properly with other programs on the same system.
*** Emacs won't work with X-windows if the value of DISPLAY is HOSTNAME:0.
385
*** Gnus can't make contact with the specified host for nntp.
386

387 388 389 390
This typically happens on Suns and other systems that use shared
libraries.  The cause is that the site has installed a version of the
shared library which uses a name server--but has not installed a
similar version of the unshared library which Emacs uses.
391

392 393
The result is that most programs, using the shared library, work with
the nameserver, but Emacs does not.
394

395 396
The fix is to install an unshared library that corresponds to what you
installed in the shared library, and then relink Emacs.
Gerd Moellmann's avatar
Gerd Moellmann committed
397

398 399 400 401 402 403
If you have already installed the name resolver in the file libresolv.a,
then you need to compile Emacs to use that library.  The easiest way to
do this is to add to config.h a definition of LIBS_SYSTEM, LIBS_MACHINE
or LIB_STANDARD which uses -lresolv.  Watch out!  If you redefine a macro
that is already in use in your configuration to supply some other libraries,
be careful not to lose the others.
404

405
Thus, you could start by adding this to config.h:
406

407
#define LIBS_SYSTEM -lresolv
408

409 410 411
Then if this gives you an error for redefining a macro, and you see that
the s- file defines LIBS_SYSTEM as -lfoo -lbar, you could change config.h
again to say this:
412

413
#define LIBS_SYSTEM -lresolv -lfoo -lbar
414

415
*** Emacs does not know your host's fully-qualified domain name.
416

417 418 419
For example, (system-name) returns some variation on
"localhost.localdomain", rather the name you were expecting.

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

425 426
If you cannot fix the configuration, you can set the Lisp variable
mail-host-address to the value you want.
427

428
** NFS and RFS
429

430 431
*** Emacs says it has saved a file, but the file does not actually
appear on disk.
432

433 434 435 436 437 438
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.
439

440 441 442 443
*** Editing files through RFS gives spurious "file has changed" warnings.
It is possible that a change in Emacs 18.37 gets around this problem,
but in case not, here is a description of how to fix the RFS bug that
causes it.
444

445 446
    There was a serious pair of bugs in the handling of the fsync() system
    call in the RFS server.
447

448 449 450 451
    The first is that the fsync() call is handled as another name for the
    close() system call (!!).  It appears that fsync() is not used by very
    many programs; Emacs version 18 does an fsync() before closing files
    to make sure that the bits are on the disk.
452

453
    This is fixed by the enclosed patch to the RFS server.
454

455 456 457 458 459 460 461
    The second, more serious problem, is that fsync() is treated as a
    non-blocking system call (i.e., it's implemented as a message that
    gets sent to the remote system without waiting for a reply).  Fsync is
    a useful tool for building atomic file transactions.  Implementing it
    as a non-blocking RPC call (when the local call blocks until the sync
    is done) is a bad idea; unfortunately, changing it will break the RFS
    protocol.  No fix was supplied for this problem.
462

463
    (as always, your line numbers may vary)
464

465 466 467 468 469 470 471 472
    % rcsdiff -c -r1.2 serversyscall.c
    RCS file: RCS/serversyscall.c,v
    retrieving revision 1.2
    diff -c -r1.2 serversyscall.c
    *** /tmp/,RCSt1003677   Wed Jan 28 15:15:02 1987
    --- serversyscall.c     Wed Jan 28 15:14:48 1987
    ***************
    *** 163,169 ****
473 474 475
            /*
             * No return sent for close or fsync!
             */
476
    !       if (syscall == RSYS_close || syscall == RSYS_fsync)
477 478 479
                    proc->p_returnval = deallocate_fd(proc, msg->m_args[0]);
            else
            {
480
    --- 166,172 ----
481 482 483
            /*
             * No return sent for close or fsync!
             */
484
    !       if (syscall == RSYS_close)
485 486 487
                    proc->p_returnval = deallocate_fd(proc, msg->m_args[0]);
            else
            {
488

489
** PSGML
490

491 492 493
*** Old versions of the PSGML package use the obsolete variables
`before-change-function' and `after-change-function', which are no
longer used by Emacs.  Please use PSGML 1.2.3 or later.
494

495
*** PSGML conflicts with sgml-mode.
496

497 498 499 500 501 502 503
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.
504

505 506 507 508
*** Versions of the PSGML package earlier than 1.0.3 (stable) or 1.1.2
(alpha) fail to parse DTD files correctly in Emacs 20.3 and later.
Here is a patch for psgml-parse.el from PSGML 1.0.1 and, probably,
earlier versions.
509

510 511 512 513 514 515 516 517 518 519 520
--- psgml-parse.el	1998/08/21 19:18:18	1.1
+++ psgml-parse.el	1998/08/21 19:20:00
@@ -2383,7 +2383,7 @@ (defun sgml-push-to-entity (entity &opti
       (setq sgml-buffer-parse-state nil))
     (cond
      ((stringp entity)			; a file name
-      (save-excursion (insert-file-contents entity))
+      (insert-file-contents entity)
       (setq default-directory (file-name-directory entity)))
      ((consp (sgml-entity-text entity)) ; external id?
       (let* ((extid (sgml-entity-text entity))
521

David Kastrup's avatar
David Kastrup committed
522
** AUCTeX
523

David Kastrup's avatar
David Kastrup committed
524 525
You should not be using a version older than 11.52 if you can avoid
it.
526

David Kastrup's avatar
David Kastrup committed
527
*** Emacs 21 freezes when visiting a TeX file with AUCTeX installed.
528

David Kastrup's avatar
David Kastrup committed
529
Emacs 21 needs version 10 or later of AUCTeX; upgrading should solve
530
these problems.
531

David Kastrup's avatar
David Kastrup committed
532
*** No colors in AUCTeX with Emacs 21.
533

534 535
Upgrade to AUC TeX version 10 or later, and make sure it is
byte-compiled with Emacs 21.
536

537 538 539 540 541 542 543 544 545 546 547 548 549 550
** 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.

551
** Miscellaneous problems
552

553 554 555
*** Emacs uses 100% of CPU time

This is a known problem with some versions of the Semantic package.
556 557
The solution is to upgrade Semantic to version 2.0pre4 (distributed
with CEDET 1.0pre4) or later.
558

559
*** Self-documentation messages are garbled.
Jason Rumney's avatar
Jason Rumney committed
560

561 562 563
This means that the file `etc/DOC-...' doesn't properly correspond
with the Emacs executable.  Redumping Emacs and then installing the
corresponding pair of files should fix the problem.
564

565 566
*** Programs running under terminal emulator do not recognize `emacs'
terminal type.
567

568 569 570 571
The cause of this is a shell startup file that sets the TERMCAP
environment variable.  The terminal emulator uses that variable to
provide the information on the special terminal type that Emacs
emulates.
572

573 574 575
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.
576

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

579 580
Or you could set TERMCAP only when you set TERM--which should not
happen in a non-login shell.
581

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

584 585 586 587
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:
588

589
    if ($?EMACS) then
590
        if ("$EMACS" =~ /*) then
591 592 593 594
            unset edit
            stty  -icrnl -onlcr -echo susp ^Z
        endif
    endif
595

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

598 599 600
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:
601

602 603
127.0.0.1	localhost
129.187.137.82	nuc04.t30.physik.tu-muenchen.de	nuc04
604

605
The way to set this up may vary on non-GNU systems.
606

607
*** Attempting to visit remote files via ange-ftp fails.
608

609 610 611 612 613 614
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
615

616
  update-alternatives --config ftp
617

618
and then choose /usr/bin/netkit-ftp.
619

620
*** JPEG images aren't displayed.
621

622 623 624 625
This has been reported when Emacs is built with jpeg-6a library.
Upgrading to jpeg-6b solves the problem.  Configure checks for the
correct version, but this problem could occur if a binary built
against a shared libjpeg is run on a system with an older version.
626

627
*** Dired is very slow.
628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643

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.

644
*** Versions of the W3 package released before Emacs 21.1 don't run
Dave Love's avatar
Dave Love committed
645
under Emacs 21.  This fixed in W3 version 4.0pre.47.
Dave Love's avatar
Dave Love committed
646

647
*** The LDAP support rely on ldapsearch program from OpenLDAP version 2.
648 649 650 651 652 653

It can fail to work with ldapsearch program from OpenLDAP version 1.
Version 1 of OpenLDAP is now deprecated.  If you are still using it,
please upgrade to version 2.  As a temporary workaround, remove
argument "-x" from the variable `ldap-ldapsearch-args'.

654
*** ps-print commands fail to find prologue files ps-prin*.ps.
655 656 657 658 659 660 661

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.

662
*** On systems with shared libraries you might encounter run-time errors
Gerd Moellmann's avatar
Gerd Moellmann committed
663 664 665 666 667
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.

668 669 670
Similar problems could prevent Emacs from building, since the build
process invokes Emacs several times.

Gerd Moellmann's avatar
Gerd Moellmann committed
671 672 673 674 675 676 677 678
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
679
On some systems, Emacs can crash due to problems with dynamic
680 681 682 683 684 685 686 687 688 689 690 691 692 693
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
694 695
(`rld' is the dynamic linker.)  We don't know yet why this
happens, but setting the environment variable LD_BIND_NOW to 1 (which
696 697 698
forces the dynamic linker to bind all shared objects early on) seems
to work around the problem.

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

701 702
*** You request inverse video, and the first Emacs frame is in inverse
video, but later frames are not in inverse video.
703

704 705 706
This can happen if you have an old version of the custom library in
your search path for Lisp packages.  Use M-x list-load-path-shadows to
check whether this is true.  If it is, delete the old custom library.
707

708
*** When you run Ispell from Emacs, it reports a "misalignment" error.
709

710 711 712 713
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.
714

715 716
To see whether your Ispell program supports 8-bit characters, type
this at your shell's prompt:
717

718
     ispell -vv
719

720 721 722
and look in the output for the string "NO8BIT".  If Ispell says
"!NO8BIT (8BIT)", your speller supports 8-bit characters; otherwise it
does not.
723

724 725 726
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.
727

728 729
Another possible cause for "misalignment" error messages is that the
version of Ispell installed on your machine is old.  Upgrade.
730

731 732 733 734 735
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.
736

737 738 739 740
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.
741

742
* Runtime problems related to font handling
743

744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763
** 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.
764

765 766
Each X11 font covers just a fraction of the characters that Emacs
supports.  To display the whole range of Emacs characters requires
767 768
many different fonts, collected into a fontset.  You can remedy the
problem by installing additional fonts.
769

770
The intlfonts distribution includes a full spectrum of fonts that can
771 772 773 774 775
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.
776

777
** Under X11, some characters appear improperly aligned in their lines.
778

779
You may have bad X11 fonts; try installing the intlfonts distribution
780 781 782 783 784 785 786 787 788 789
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
790

791
http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00696.html
792

793 794 795 796 797 798 799 800 801 802 803
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.
804

805
** Loading fonts is very slow.
806

807 808 809 810
You might be getting scalable fonts instead of precomputed bitmaps.
Known scalable font directories are "Type1" and "Speedo".  A font
directory contains scalable fonts if it contains the file
"fonts.scale".
Jason Rumney's avatar
Jason Rumney committed
811

812 813
If this is so, re-order your X windows font path to put the scalable
font directories last.  See the documentation of `xset' for details.
Jason Rumney's avatar
Jason Rumney committed
814

815 816 817
With some X servers, it may be necessary to take the scalable font
directories out of your path entirely, at least for Emacs 19.26.
Changes in the future may make this unnecessary.
Jason Rumney's avatar
Jason Rumney committed
818

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

821 822 823 824 825 826 827 828 829 830
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
831

832
Beginning with version 22.1, a parenthesis or a brace in column zero
833 834 835
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
836

837 838 839 840 841
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.)
842

843 844
Another alternative is to avoid a paren in column zero.  For example,
in a Lisp string you could precede the paren with a backslash.
845

846 847
** With certain fonts, when the cursor appears on a character, the
character doesn't appear--you get a solid box instead.
848

849 850 851
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.
852

853
** Emacs pauses for several seconds when changing the default font.
854

855 856 857 858
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.
859

860
A workaround for this is to add something like
861

862
emacs.waitForWM: false
863

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

867
   (modify-frame-parameters nil '((wait-for-wm . nil)))
868

869
(this should go into your `.emacs' file).
870

871
** Underlines appear at the wrong position.