PROBLEMS 154 KB
Newer Older
1 2 3 4 5 6
Copyright (C) 1987, 1988, 1989, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
  2001, 2002, 2003, 2004, 2005, 2006, 2007
  Free Software Foundation, Inc.
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
in compiling, installing and running GNU Emacs.  Try doing Ctl-C Ctl-t
9
and browsing through the outline headers.
Dave Love's avatar
#  
Dave Love committed
10

11
* Emacs startup failures
12

13
** Emacs fails to start, complaining about missing fonts.
14

15
A typical error message might be something like
16

17
  No fonts match `-*-fixed-medium-r-*--6-*-*-*-*-*-iso8859-1'
18

19 20 21
This happens because some X resource specifies a bad font family for
Emacs to use.  The possible places where this specification might be
are:
22

23
  - in your ~/.Xdefaults file
24

25 26 27
  - client-side X resource file, such as  ~/Emacs or
    /usr/X11R6/lib/app-defaults/Emacs or
    /usr/X11R6/lib/X11/app-defaults/Emacs
28

29 30 31
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.
32

33
** Emacs aborts while starting up, only when run without X.
34

35 36 37 38 39 40 41 42 43
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.
44

45 46 47 48
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.
49

50
** Emacs does not start, complaining that it cannot open termcap database file.
51

52 53 54 55 56 57
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.
58

59 60 61 62
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.
63

64
** Emacs 20 and later fails to load Lisp files at startup.
65

66
The typical error message might be like this:
67

68
  "Cannot open load file: fontset"
69

70 71 72 73 74 75 76
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.)
77

78 79
Similarly, any other .el file for which there's no corresponding .elc
file could fail to load if it is compressed.
80

81 82
The solution is to uncompress all .el files which don't have a .elc
file.
Dave Love's avatar
Dave Love committed
83

84 85 86
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:
Dave Love's avatar
Dave Love committed
87

88
    emacs -q -batch -f list-load-path-shadows
Dave Love's avatar
Dave Love committed
89

90 91 92
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
93

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

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

98
  x-complement-fontset-spec: "Wrong type argument: stringp, nil"
Simon Josefsson's avatar
Simon Josefsson committed
99

100 101 102
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:
103

104
    emacs -q -batch -f list-load-path-shadows
105

106 107 108
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.
109

110
** With X11R6.4, public-patch-3, Emacs crashes at startup.
111

112
Reportedly this patch in X fixes the problem.
113

114 115 116 117 118 119
    --- 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 $  */
     /******************************************************************
120

121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145
		Copyright 1992, 1993, 1994 by FUJITSU LIMITED
    @@ -166,8 +166,8 @@
     _XimMakeImName(lcd)
	 XLCd	   lcd;
     {
    -    char* begin;
    -    char* end;
    +    char* begin = NULL;
    +    char* end = NULL;
	 char* ret;
	 int	i = 0;
	 char* ximmodifier = XIMMODIFIER;
    @@ -182,7 +182,11 @@
	 }
	 ret = Xmalloc(end - begin + 2);
	 if (ret != NULL) {
    -    	(void)strncpy(ret, begin, end - begin + 1);
    +	if (begin != NULL) {
    +      	  (void)strncpy(ret, begin, end - begin + 1);
    +        } else {
    +	  ret[0] = '\0';
    +	}
	    ret[end - begin + 1] = '\0';
	 }
	 return ret;
Dave Love's avatar
Dave Love committed
146

147 148 149 150 151 152
** 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
153
This problem was first seen in pre-release versions of Fedora 7, and
154 155 156 157 158 159 160
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

161
* Crash bugs
Dave Love's avatar
Dave Love committed
162

163
** Emacs crashes in x-popup-dialog.
164

165 166 167 168
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
169

170
** Emacs crashes when you use Bibtex mode.
Dave Love's avatar
Dave Love committed
171

172 173 174
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.
Eli Zaretskii's avatar
Eli Zaretskii committed
175

176 177
Patches to raise the stack size limit automatically in `main'
(src/emacs.c) on various systems would be greatly appreciated.
Eli Zaretskii's avatar
Eli Zaretskii committed
178

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

182 183
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:
184

185
   x FILENAME, N bytes, B tape blocks
186

187 188
If your tar has this problem, install GNU tar--if you can manage to
untar it :-).
189

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

196
** Emacs aborts inside the function `tparam1'.
197

198 199 200 201 202
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.
203

204 205 206
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.
207

208
** Emacs crashes when using the Exceed 6.0 X server.
209

210 211
If you are using Exceed 6.1, upgrade to a later version.  This was
reported to prevent the crashes.
212

213
** Emacs crashes with SIGSEGV in XtInitializeWidgetClass.
214

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

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

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

225 226 227 228 229
** Emacs compiled with Gtk+ crashes when closing a display (x-close-connection).

This happens because of bugs in Gtk+.  Gtk+ 2.10 seems to be OK.  See bug
http://bugzilla.gnome.org/show_bug.cgi?id=85715.

230
** Emacs compiled with Gtk+ crashes on startup on Cygwin.
231 232

A typical error message is
233
  ***MEMORY-ERROR***: emacs[5172]: GSlice: failed to allocate 504 bytes
234 235 236
  (alignment: 512): Function not implemented

Emacs supplies its own malloc, but glib (part of Gtk+) calls memalign and on
237 238
Cygwin, that becomes the Cygwin supplied memalign.  As malloc is not the
Cygwin malloc, the Cygwin memalign always returns ENOSYS.  A fix for this
239 240
problem would be welcome.

241
* General runtime problems
242

243
** Lisp problems
244

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

247 248 249 250
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.
251

252 253
Emacs should print a warning when loading a .elc file which is older
than the corresponding .el file.
Dave Love's avatar
Dave Love committed
254

255
*** Watch out for .emacs files and EMACSLOADPATH environment vars.
Dave Love's avatar
Dave Love committed
256

257 258 259 260
These control the actions of Emacs.
~/.emacs is your Emacs init file.
EMACSLOADPATH overrides which directories the function
"load" will search.
261

262 263
If you observe strange problems, check for these and get rid
of them, then try again.
264

265
*** Using epop3.el package causes Emacs to signal an error.
266

267
The error message might be something like this:
268

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

271 272 273 274
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.
275

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

278 279 280
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.
281

282 283 284 285
*** 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.
286

287
** Keyboard problems
288

289
*** "Compose Character" key does strange things when used as a Meta key.
290

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

298 299
You can use both functions (Meta, and Compose Character) if you assign
them to two different keys.
300

301
*** C-z just refreshes the screen instead of suspending Emacs.
302

303 304 305
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.
306

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

310 311 312
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
313

314
   set escape-character 17
315

316
in his .kermrc file, to make C-q the kermit escape character.
317

318
** Mailers and other helper programs
319

320
*** movemail compiled with POP support can't connect to the POP server.
321

322 323 324 325 326 327
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.
328

329
*** RMAIL gets error getting new mail.
330

331 332 333
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.
334

335 336 337 338 339 340 341
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!
342

343 344 345 346 347
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.
348

349 350
	chgrp mail movemail
	chmod 2755 movemail
351

352 353 354 355 356 357
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.
358

359
*** rcs2log gives you the awk error message "too many fields".
360

361 362
This is due to an arbitrary limit in certain versions of awk.
The solution is to use gawk (GNU awk).
363

364
** Problems with hostname resolution
365

366 367 368
*** 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.
369
*** Gnus can't make contact with the specified host for nntp.
Gerd Moellmann's avatar
Gerd Moellmann committed
370

371 372 373 374
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.
375

376 377
The result is that most programs, using the shared library, work with
the nameserver, but Emacs does not.
378

379 380
The fix is to install an unshared library that corresponds to what you
installed in the shared library, and then relink Emacs.
381

382 383 384 385 386 387 388 389
On SunOS 4.1, simply define HAVE_RES_INIT.

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.
390

391
Thus, you could start by adding this to config.h:
392

393
#define LIBS_SYSTEM -lresolv
394

395 396 397
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:
398

399
#define LIBS_SYSTEM -lresolv -lfoo -lbar
400

401 402
*** Emacs does not know your host's fully-qualified domain name.

403 404 405
For example, (system-name) returns some variation on
"localhost.localdomain", rather the name you were expecting.

406
You need to configure your machine with a fully qualified domain name,
407 408 409
(i.e. a name with at least one ".") either in /etc/hosts,
/etc/hostname, the NIS, or wherever your system calls for specifying
this.
410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507

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

** NFS and RFS

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

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.

*** 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.

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

    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.

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

    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.

    (as always, your line numbers may vary)

    % 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 ****
	    /*
	     * No return sent for close or fsync!
	     */
    !       if (syscall == RSYS_close || syscall == RSYS_fsync)
		    proc->p_returnval = deallocate_fd(proc, msg->m_args[0]);
	    else
	    {
    --- 166,172 ----
	    /*
	     * No return sent for close or fsync!
	     */
    !       if (syscall == RSYS_close)
		    proc->p_returnval = deallocate_fd(proc, msg->m_args[0]);
	    else
	    {

** PSGML

*** 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.

*** PSGML conflicts with sgml-mode.

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.

*** 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.

--- 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))

David Kastrup's avatar
David Kastrup committed
508
** AUCTeX
509

David Kastrup's avatar
David Kastrup committed
510 511
You should not be using a version older than 11.52 if you can avoid
it.
512

David Kastrup's avatar
David Kastrup committed
513 514 515
*** Emacs 21 freezes when visiting a TeX file with AUCTeX installed.

Emacs 21 needs version 10 or later of AUCTeX; upgrading should solve
516 517
these problems.

David Kastrup's avatar
David Kastrup committed
518
*** No colors in AUCTeX with Emacs 21.
519 520 521 522

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

523 524 525 526 527 528 529 530 531 532 533 534 535 536
** 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.

537 538
** Miscellaneous problems

539 540 541
*** Emacs uses 100% of CPU time

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

545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575
*** Self-documentation messages are garbled.

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.

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

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.

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.

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

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

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

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:

    if ($?EMACS) then
576
        if ("$EMACS" =~ /*) then
577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738
            unset edit
            stty  -icrnl -onlcr -echo susp ^Z
        endif
    endif

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

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:

127.0.0.1	localhost
129.187.137.82	nuc04.t30.physik.tu-muenchen.de	nuc04

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

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

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

  update-alternatives --config ftp

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

*** JPEG images aren't displayed.

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.

*** Dired is very slow.

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.

*** Versions of the W3 package released before Emacs 21.1 don't run
under Emacs 21.  This fixed in W3 version 4.0pre.47.

*** The LDAP support rely on ldapsearch program from OpenLDAP version 2.

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'.

*** ps-print commands fail to find prologue files ps-prin*.ps.

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.

*** On systems with shared libraries you might encounter run-time errors
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.

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

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.

On some systems, Emacs can crash due to problems with dynamic
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]

(`rld' is the dynamic linker.)  We don't know yet why this
happens, but setting the environment variable LD_BIND_NOW to 1 (which
forces the dynamic linker to bind all shared objects early on) seems
to work around the problem.

Please refer to the documentation of your dynamic linker for details.

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

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.

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

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.

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

     ispell -vv

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

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.

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

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.

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.

* Runtime problems related to font handling

** Under X11, some characters appear as hollow boxes.

Each X11 font covers just a fraction of the characters that Emacs
supports.  To display the whole range of Emacs characters requires
many different fonts, collected into a fontset.

If some of the fonts called for in your fontset do not exist on your X
server, then the characters that have no font appear as hollow boxes.
You can remedy the problem by installing additional fonts.
739

740
The intlfonts distribution includes a full spectrum of fonts that can
741 742 743 744 745
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.
746

747 748 749 750 751
Another cause of this for specific characters is fonts which 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.
752

753
** Under X11, some characters appear improperly aligned in their lines.
754

755 756
You may have bad X11 fonts; try installing the intlfonts distribution
or the etl-unicode collection (see the previous entry).
757

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

760 761 762
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.
763

764
** Loading fonts is very slow.
765

766 767 768 769
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".
770

771 772
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.
773

774 775 776
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.
777

778
** Font Lock displays portions of the buffer in incorrect faces.
779

780 781 782 783 784 785 786 787 788 789
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.
790

791
Beginning with version 22.1, a parenthesis or a brace in column zero
792 793 794
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.
795

796 797 798 799 800
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.)
801

802 803
Another alternative is to avoid a paren in column zero.  For example,
in a Lisp string you could precede the paren with a backslash.
804

805 806
** With certain fonts, when the cursor appears on a character, the
character doesn't appear--you get a solid box instead.
807

808 809 810
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.
811

812
** Characters are displayed as empty boxes or with wrong font under X.
813

814 815 816 817 818 819 820 821 822 823 824
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 --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.
825

826
** Emacs pauses for several seconds when changing the default font.
827

828 829 830 831
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.
832

833
A workaround for this is to add something like
834

835
emacs.waitForWM: false
836

837 838
to your X resources.  Alternatively, add `(wait-for-wm . nil)' to a
frame's parameter list, like this:
Jason Rumney's avatar
Jason Rumney committed
839

840
   (modify-frame-parameters nil '((wait-for-wm . nil)))
841

842
(this should go into your `.emacs' file).
843

844
** Underlines appear at the wrong position.
845

846 847 848 849 850
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
neep font from the Debian xfonts-jmk package.  To circumvent this
problem, set x-use-underline-position-properties to nil in your
`.emacs'.
851

852 853 854
To see what is the value of UNDERLINE_POSITION defined by the font,
type `xlsfonts -lll FONT' and look at the font's UNDERLINE_POSITION
property.
855

856
** When using Exceed, fonts sometimes appear too tall.
857

858 859 860 861 862
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".
863

864 865
To prevent this, turn off the Exceed's "automatic font substitution"
feature (in the font part of the configuration window).
866

867 868 869 870 871 872 873 874 875 876
** Subscript/superscript text in TeX is hard to read.

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 subscript and superscript
faces to increase their height.

877
* Internationalization problems
878

879 880 881 882 883
** M-{ does not work on a Spanish PC keyboard.

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

884
** Characters from the mule-unicode charsets aren't displayed under X.
885

886 887 888 889 890 891 892 893 894
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:
895

896 897 898
mule-unicode-2500-33ff:-gnu-unifont-*-iso10646-1,\
mule-unicode-e000-ffff:-gnu-unifont-*-iso10646-1,\
mule-unicode-0100-24ff:-gnu-unifont-*-iso10646-1
Eli Zaretskii's avatar
Eli Zaretskii committed
899

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

902 903 904 905 906 907 908 909 910 911
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.
912

913 914 915 916 917 918 919
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.
920

921
** Mule-UCS loads very slowly.
922

923 924 925 926 927
Changes to Emacs internals interact badly with Mule-UCS's `un-define'
library, which is the usual interface to Mule-UCS.  Apply the
following patch to Mule-UCS 0.84 and rebuild it.  That will help,
though loading will still be slower than in Emacs 20.  (Some
distributions, such as Debian, may already have applied such a patch.)
928

929 930 931
--- lisp/un-define.el	6 Mar 2001 22:41:38 -0000	1.30
+++ lisp/un-define.el	19 Apr 2002 18:34:26 -0000
@@ -610,13 +624,21 @@ by calling post-read-conversion and pre-
932

933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959
  (mapcar
   (lambda (x)
-    (mapcar
-     (lambda (y)
-       (mucs-define-coding-system
-	(nth 0 y) (nth 1 y) (nth 2 y)
-	(nth 3 y) (nth 4 y) (nth 5 y) (nth 6 y))
-       (coding-system-put (car y) 'alias-coding-systems (list (car x))))
-     (cdr x)))
+    (if (fboundp 'register-char-codings)
+	;; Mule 5, where we don't need the eol-type specified and
+	;; register-char-codings may be very slow for these coding
+	;; system definitions.
+	(let ((y (cadr x)))
+	  (mucs-define-coding-system
+	   (car x) (nth 1 y) (nth 2 y)
+	   (nth 3 y) (nth 4 y) (nth 5 y)))
+      (mapcar
+       (lambda (y)
+	 (mucs-define-coding-system
+	  (nth 0 y) (nth 1 y) (nth 2 y)
+	  (nth 3 y) (nth 4 y) (nth 5 y) (nth 6 y))
+	 (coding-system-put (car y) 'alias-coding-systems (list (car x)))))
+      (cdr x)))
   `((utf-8
      (utf-8-unix
       ?u "UTF-8 coding system"
960

961 962
Note that Emacs has native support for Unicode, roughly equivalent to
Mule-UCS's, so you may not need it.
963

964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984
** Mule-UCS compilation problem.

Emacs of old versions and XEmacs byte-compile the form `(progn progn
...)' the same way as `(progn ...)', but Emacs of version 21.3 and the
later process that form just as interpreter does, that is, as `progn'
variable reference.  Apply the following patch to Mule-UCS 0.84 to
make it compiled by the latest Emacs.

--- mucs-ccl.el	2 Sep 2005 00:42:23 -0000	1.1.1.1
+++ mucs-ccl.el	2 Sep 2005 01:31:51 -0000	1.3
@@ -639,10 +639,14 @@
       (mucs-notify-embedment 'mucs-ccl-required name)
       (setq ccl-pgm-list (cdr ccl-pgm-list)))
 ;   (message "MCCLREGFIN:%S" result)
-    `(progn
-       (setq mucs-ccl-facility-alist
-	     (quote ,mucs-ccl-facility-alist))
-       ,@result)))
+    ;; The only way the function is used in this package is included
+    ;; in `mucs-package-definition-end-hook' value, where it must
+    ;; return (possibly empty) *list* of forms.  Do this.  Do not rely
985
+    ;; on byte compiler to remove extra `progn's in `(progn ...)'
986 987 988 989
+    ;; form.
+    `((setq mucs-ccl-facility-alist
+	    (quote ,mucs-ccl-facility-alist))
+      ,@result)))
990

991 992 993
 ;;; Add hook for embedding translation informations to a package.
 (add-hook 'mucs-package-definition-end-hook

994
** Accented ISO-8859-1 characters are displayed as | or _.
995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013

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.

To see what glyphs are included in a font, use `xfd', like this:

  xfd -fn -schumacher-clean-medium-r-normal--12-120-75-75-c-60-iso8859-1

If this shows only ASCII glyphs, the font is indeed the source of the
problem.

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'.

1014
** The `oc-unicode' package doesn't work with Emacs 21.
1015

1016 1017 1018 1019 1020
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.
1021

1022
** After a while, Emacs slips into unibyte mode.
1023

1024 1025 1026 1027
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)
1028

1029
* X runtime problems
1030

1031
** X keyboard problems
1032

1033
*** You "lose characters" after typing Compose Character key.
1034

1035 1036 1037 1038
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.
1039

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

1042
    xmodmap -e "keysym Multi_key = Meta_L"
1043

1044 1045 1046
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.
1047

1048
*** Using X Windows, control-shift-leftbutton makes Emacs hang.
1049

1050
Use the shell command `xset bc' to make the old X Menu package work.
1051

1052
*** C-SPC fails to work on Fedora GNU/Linux (or with fcitx input method).
1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065

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.

1066 1067 1068 1069 1070 1071
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'.

1072
*** M-SPC seems to be ignored as input.
1073

1074 1075
See if your X server is set up to use this as a command
for character composition.
Dave Love's avatar
Dave Love committed
1076

1077
*** The S-C-t key combination doesn't get passed to Emacs on X.
Gerd Moellmann's avatar
Gerd Moellmann committed
1078

1079 1080 1081 1082 1083
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.
Eli Zaretskii's avatar
Eli Zaretskii committed
1084

1085 1086
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.
1087

1088
*** Under X, C-v and/or other keys don't work.
1089

1090 1091 1092 1093 1094
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.
1095

1096