"Fossies" - the Fresh Open Source Software Archive

Member "emacs-28.2/etc/PROBLEMS" (6 Sep 2022, 159312 Bytes) of package /linux/misc/emacs-28.2.tar.xz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "PROBLEMS": 28.1_vs_28.2.

    1 Known Problems with GNU Emacs
    3 Copyright (C) 1987-1989, 1993-1999, 2001-2022 Free Software Foundation,
    4 Inc.
    5 See the end of the file for license conditions.
    8 This file describes various problems that have been encountered
    9 in compiling, installing and running GNU Emacs.  Try doing C-c C-t
   10 and browsing through the outline headers.  (See C-h m for help on
   11 Outline mode.)  Information about systems that are no longer supported,
   12 and old Emacs releases, has been removed.  Consult older versions of
   13 this file if you are interested in that information.
   15 * Mule-UCS doesn't work in Emacs 23 onwards
   17 It's completely redundant now, as far as we know.
   19 * Emacs startup failures
   21 ** Emacs fails to start, complaining about missing fonts.
   23 A typical error message might be something like
   25   No fonts match ‘-*-fixed-medium-r-*--6-*-*-*-*-*-iso8859-1’
   27 This happens because some X resource specifies a bad font family for
   28 Emacs to use.  The possible places where this specification might be are:
   30   - in the X server resources database, often initialized from
   31     ~/.Xresources (use $ xrdb -query to find out the current state)
   33   - in your ~/.Xdefaults file
   35   - client-side X resource file, such as  ~/Emacs or
   36     /usr/share/X11/app-defaults/Emacs
   38 One of these files might have bad or malformed specification of a
   39 fontset that Emacs should use.  To fix the problem, you need to find
   40 the problematic line(s) and correct them.
   42 After correcting ~/.Xresources, the new data has to be merged into the
   43 X server resources database.  Depending on the circumstances, the
   44 following command may do the trick.  See xrdb(1) for more information.
   46   $ xrdb -merge ~/.Xresources
   48 ** Emacs compiled with Cairo crashes when restoring session from desktop file.
   50 This can happen if the '.emacs.desktop' file contains setting for
   51 'font-backend' frame parameter.  A workaround is to delete the
   52 offending '.emacs.desktop' file, or edit it to remove the setting of
   53 'font-backend'.
   55 ** Emacs aborts while starting up, only when run without X.
   57 This problem often results from compiling Emacs with GCC when GCC was
   58 installed incorrectly.  The usual error in installing GCC is to
   59 specify --includedir=/usr/include.  Installation of GCC makes
   60 corrected copies of the system header files.  GCC is supposed to use
   61 the corrected copies in preference to the original system headers.
   62 Specifying --includedir=/usr/include causes the original system header
   63 files to be used.  On some systems, the definition of ioctl in the
   64 original system header files is invalid for ANSI C and causes Emacs
   65 not to work.
   67 The fix is to reinstall GCC, and this time do not specify --includedir
   68 when you configure it.  Then recompile Emacs.  Specifying --includedir
   69 is appropriate only in very special cases and it should *never* be the
   70 same directory where system header files are kept.
   72 ** Emacs does not start, complaining that it cannot open termcap database file.
   74 If your system uses Terminfo rather than termcap (most modern
   75 systems do), this could happen if the proper version of
   76 ncurses is not visible to the Emacs configure script (i.e. it
   77 cannot be found along the usual path the linker looks for
   78 libraries).  It can happen because your version of ncurses is
   79 obsolete, or is available only in form of binaries.
   81 The solution is to install an up-to-date version of ncurses in
   82 the developer's form (header files, static libraries and
   83 symbolic links); in some GNU/Linux distributions (e.g. Debian)
   84 it constitutes a separate package.
   86 ** Emacs 20 and later fails to load Lisp files at startup.
   88 The typical error message might be like this:
   90   "Cannot open load file: fontset"
   92 This could happen if you compress the file lisp/subdirs.el.  That file
   93 tells Emacs what are the directories where it should look for Lisp
   94 files.  Emacs cannot work with subdirs.el compressed, since the
   95 Auto-compress mode it needs for this will not be loaded until later,
   96 when your .emacs file is processed.  (The package 'fontset.el' is
   97 required to set up fonts used to display text on window systems, and
   98 it's loaded very early in the startup procedure.)
  100 Similarly, any other .el file for which there's no corresponding .elc
  101 file could fail to load if it is compressed.
  103 The solution is to uncompress all .el files that don't have a .elc file.
  105 Another possible reason for such failures is stale *.elc files
  106 lurking somewhere on your load-path -- see the next section.
  108 ** Emacs prints an error at startup after upgrading from an earlier version.
  110 An example of such an error is:
  112   x-complement-fontset-spec: "Wrong type argument: stringp, nil"
  114 This can be another symptom of stale *.elc files in your load-path.
  115 The following command will print any duplicate Lisp files that are
  116 present in load-path:
  118     emacs -batch -f list-load-path-shadows
  120 If this command prints any file names, some of these files are stale,
  121 and should be deleted or their directories removed from your
  122 load-path.
  124 * Crash bugs
  126 ** When Emacs is compiled with Gtk+, closing a display kills Emacs.
  128 There is a long-standing bug in GTK that prevents it from recovering
  129 from disconnects: https://gitlab.gnome.org/GNOME/gtk/issues/221
  131 Thus, for instance, when Emacs is run as a server on a text terminal,
  132 and an X frame is created, and the X server for that frame crashes or
  133 exits unexpectedly, Emacs must exit to prevent a GTK error that would
  134 result in an endless loop.
  136 If you need Emacs to be able to recover from closing displays, compile
  137 it with the Lucid toolkit instead of GTK.
  139 ** Emacs compiled with GTK+ 3 crashes when run under some X servers.
  140 This happens when the X server does not provide certain display
  141 features that the underlying GTK+ 3 toolkit assumes.  For example, this
  142 issue has been seen with remote X servers like X2Go.  The symptoms
  143 are an Emacs crash, possibly triggered by the mouse entering the Emacs
  144 window, or an attempt to resize the Emacs window.  The crash backtrace
  145 contains a call to XQueryPointer.
  147 This issue was fixed in the GTK+ 3 toolkit in commit 4b1c0256 in February 2018.
  149 If your GTK+ 3 is still affected, you can avoid the issue by recompiling
  150 Emacs with a different X toolkit, eg --with-toolkit=gtk2.
  152 References:
  153 https://gitlab.gnome.org/GNOME/gtk/commit/4b1c02560f0d8097bf5a11932e52fb72f3e9e94b
  154 https://debbugs.gnu.org/24280
  155 https://bugs.debian.org/901038
  156 https://bugzilla.redhat.com/1483942
  157 https://access.redhat.com/solutions/3410101
  159 ** Emacs compiled with GTK crashes at startup due to X protocol error.
  161 This is known to happen on elementary OS GNU/Linux systems.
  163 The error message is:
  165   X protocol error: BadMatch (invalid parameter attributes) on protocol request 140
  166   When compiled with GTK, Emacs cannot recover from X disconnects.
  167   This is a GTK bug: https://gitlab.gnome.org/GNOME/gtk/issues/221
  168   For details, see etc/PROBLEMS.
  169   Fatal error 6: Aborted
  171 followed by a C backtrace.  (Sometimes the offending protocol request
  172 number is 139.)
  174 The relevant bug report is here:
  176   https://bugs.launchpad.net/elementaryos/+bug/1355274
  178 A workaround is to set XLIB_SKIP_ARGB_VISUALS=1 in the environment
  179 before starting Emacs, or run Emacs as root.
  181 ** Emacs crashes with SIGTRAP when trying to start a WebKit xwidget.
  183 This could happen if the version of WebKitGTK installed on your system
  184 is buggy, and errors out trying to start a subprocess through
  185 Bubblewrap sandboxing.  You can avoid the crash by setting the
  186 environment variables SNAP, SNAP_NAME and SNAP_REVISION, which will
  187 make WebKit use GLib to launch subprocesses instead.  For example,
  188 invoke Emacs like this (where "..." stands for the other command-line
  189 arguments you intend to pass to Emacs):
  191   $ SNAP=1 SNAP_NAME=1 SNAP_REVISION=1 emacs ...
  193 ** Emacs crashes when you try to view a file with complex characters.
  195 One possible reason for this could be a bug in the libotf or the
  196 libm17n-flt/m17n-db libraries Emacs uses for displaying complex
  197 scripts.
  199 The easiest and the recommended way of solving these crashes is to
  200 build Emacs with HarfBuzz as the shaping engine library instead of
  201 libm17n-flt.  Building with HarfBuzz is the default since Emacs 27.1.
  203 If you must use libm17n-flt, read on.
  205 Make sure you have the latest versions of these libraries
  206 installed.  If the problem still persists with the latest released
  207 versions of these libraries, you can try building these libraries from
  208 their CVS repository:
  210   cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/m17n co libotf
  211   cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/m17n co m17n-db
  212   cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/m17n co m17n-lib
  214 One known problem that causes such crashes is with using Noto Serif
  215 Kannada fonts.  To work around that, force Emacs not to select these
  216 fonts, by adding the following to your ~/.emacs init file:
  218   (push "Noto Serif Kannada" face-ignored-fonts)
  220 You can try this interactively in a running Emacs session like this:
  222   M-: (push "Noto Serif Kannada" face-ignored-fonts) RET
  224 Another set of problems is caused by an incompatible libotf library.
  225 In this case, displaying the etc/HELLO file (as shown by C-h h)
  226 triggers the following message to be shown in the terminal from which
  227 you launched Emacs:
  229   symbol lookup error: /usr/bin/emacs: undefined symbol: OTF_open
  231 This problem occurs because unfortunately there are two libraries
  232 called "libotf".  One is the library for handling OpenType fonts,
  233 https://www.nongnu.org/m17n/, which is the one that Emacs expects.
  234 The other is a library for Open Trace Format, and is used by some
  235 versions of the MPI message passing interface for parallel
  236 programming.
  238 For example, on RHEL6 GNU/Linux, the OpenMPI rpm provides a version
  239 of "libotf.so" in /usr/lib/openmpi/lib.  This directory is not
  240 normally in the ld search path, but if you want to use OpenMPI,
  241 you must issue the command "module load openmpi".  This adds
  242 /usr/lib/openmpi/lib to LD_LIBRARY_PATH.  If you then start Emacs from
  243 the same shell, you will encounter this crash.
  244 Ref: <URL:https://bugzilla.redhat.com/show_bug.cgi?id=844776>
  246 There is no good solution to this problem if you need to use both
  247 OpenMPI and Emacs with libotf support.  The best you can do is use a
  248 wrapper shell script (or function) "emacs" that removes the offending
  249 element from LD_LIBRARY_PATH before starting emacs proper.
  250 Or you could recompile Emacs with an -Wl,-rpath option that
  251 gives the location of the correct libotf.
  253 ** Emacs crashes in x-popup-dialog.
  255 This can happen if the dialog widget cannot find the font it wants to
  256 use.  You can work around the problem by specifying another font with
  257 an X resource--for example, 'Emacs.dialog*.font: 9x15' (or any font that
  258 happens to exist on your X server).
  260 ** Emacs crashes when you use Bibtex mode.
  262 This happens if your system puts a small limit on stack size.  You can
  263 prevent the problem by using a suitable shell command (often 'ulimit')
  264 to raise the stack size limit before you run Emacs.
  266 Patches to raise the stack size limit automatically in 'main'
  267 (src/emacs.c) on various systems would be greatly appreciated.
  269 ** Error message 'Symbol’s value as variable is void: x', followed by
  270 a segmentation fault and core dump.
  272 This has been tracked to a bug in tar!  People report that tar erroneously
  273 added a line like this at the beginning of files of Lisp code:
  275    x FILENAME, N bytes, B tape blocks
  277 If your tar has this problem, install GNU tar--if you can manage to
  278 untar it :-).
  280 ** Emacs crashes when running in a terminal, if compiled with GCC 4.5.0
  282 This version of GCC is buggy: see
  284   https://debbugs.gnu.org/6031
  285   https://gcc.gnu.org/bugzilla/show_bug.cgi?id=43904
  287 You can work around this error in gcc-4.5 by omitting sibling call
  288 optimization.  To do this, configure Emacs with
  290  ./configure CFLAGS="-g -O2 -fno-optimize-sibling-calls"
  292 ** Emacs compiled with GCC 4.6.1 crashes on MS-Windows when C-g is pressed
  294 This is known to happen when Emacs is compiled with MinGW GCC 4.6.1
  295 with the -O2 option (which is the default in the Windows build).  The
  296 reason is a bug in MinGW GCC 4.6.1; to work around, either add the
  297 '-fno-omit-frame-pointer' switch to GCC or compile without
  298 optimizations ('--no-opt' switch to the configure.bat script).
  300 ** Emacs can crash when displaying PNG images with transparency.
  302 This is due to a bug introduced in ImageMagick 6.8.2-3.  The bug should
  303 be fixed in ImageMagick 6.8.3-10.  See <URL:https://debbugs.gnu.org/13867>.
  305 ** Crashes when displaying GIF images in Emacs built with version
  306 libungif-4.1.0 are resolved by using version libungif-4.1.0b1.
  307 Configure checks for the correct version, but this problem could occur
  308 if a binary built against a shared libungif is run on a system with an
  309 older version.
  311 ** Emacs aborts inside the function 'tparam1'.
  313 This can happen if Emacs was built without terminfo support, but the
  314 terminal's capabilities use format that is only supported by terminfo.
  315 If your system has ncurses installed, this might happen if your
  316 version of ncurses is broken; upgrading to a newer version of ncurses
  317 and reconfiguring and rebuilding Emacs should solve this.
  319 All modern systems support terminfo, so even if ncurses is not the
  320 problem, you should look for a way to configure Emacs so that it uses
  321 terminfo when built.
  323 ** Emacs crashes when using some version of the Exceed X server.
  325 Upgrading to a newer version of Exceed has been reported to prevent
  326 these crashes.  You should consider switching to a free X server, such
  327 as Xming or Cygwin/X.
  329 ** Emacs crashes with SIGSEGV in XtInitializeWidgetClass.
  331 It crashes on X, but runs fine when called with option "-nw".
  333 This has been observed when Emacs is linked with GNU ld but without passing
  334 the -z nocombreloc flag.  Emacs normally knows to pass the -z nocombreloc
  335 flag when needed, so if you come across a situation where the flag is
  336 necessary but missing, please report it via M-x report-emacs-bug.
  338 On platforms such as Solaris, you can also work around this problem by
  339 configuring your compiler to use the native linker instead of GNU ld.
  341 * Problems when reading or debugging Emacs C code
  343 Because Emacs does not install a copy of its C source code, users
  344 normally cannot easily read that code via commands like 'M-x
  345 describe-function' (C-h f) that display the definition of a function.
  346 However, some GNU/Linux systems provide separate packages containing
  347 this source code which can get C-h f to work if you are willing to do
  348 some tinkering, and some systems also provide packages containing
  349 debug info, which when combined with the source can be used to debug
  350 Emacs at the C level.
  352 ** Debian-based source and debuginfo
  354 On recent Debian-based systems, you can obtain and use a source
  355 package of Emacs as follows.
  357 *** Add the appropriate URI to /etc/apt/sources.list.
  359 To do this, become superuser and uncomment or add the appropriate
  360 'deb-src' line.  Details depend on the distribution.
  362 *** Execute a command like 'apt-get source emacs'.
  364 On older systems, append the top-level version number, e.g., 'apt-get
  365 source emacs25'.  The target directory for unpacking the source tree
  366 is the current directory.
  368 *** Set find-function-C-source-directory accordingly.
  370 Once you have installed the source package, for example at
  371 /home/myself/deb-src/emacs-27.1, add the following line to your
  372 startup file:
  374      (setq find-function-C-source-directory
  375            "/home/myself/deb-src/emacs-27.1/src/")
  377 The installation directory of the Emacs source package will contain
  378 the exact package name and version number of Emacs that is installed
  379 on your system.  If a new Emacs package is installed, the source
  380 package must be reinstalled as well, and the setting in your startup
  381 file must be updated.
  383 *** Debian-based debuginfo
  385 You can also install a debug package of Emacs with a command like
  386 'apt-get install emacs-dbg' (on older systems, 'apt-get install
  387 emacs25-dbg').  You need to arrange for GDB to find where you
  388 installed the source code, e.g., by using GDB's 'directory' command.
  390 ** Red Hat-based source and debuginfo
  392 On recent Red Hat-based systems, you can install source and debug info
  393 via superuser commands like the following:
  395   # Add the *-debuginfo repositories (exact command depends on system).
  396   dnf config-manager --set-enabled fedora-debuginfo updates-debuginfo'
  398   # Install Emacs source and debug info.
  399   dnf install emacs-debugsource
  401 To get describe-function and similar commands to work, you can then
  402 add something like the following to your startup file:
  404      (setq find-function-C-source-directory
  405            "/usr/src/debug/emacs-27.1-1.fc31.x86_64/src/")
  407 However, the exact directory name will depend on the system, and you
  408 will need to both upgrade source and debug info when your system
  409 upgrades or patches Emacs, and change your startup file accordingly.
  411 ** Source and debuginfo for other systems
  413 If your system follows neither the Debian nor the Red Hat patterns,
  414 you can obtain the source and debuginfo by obtaining the source code
  415 of Emacs, building Emacs with the appropriate debug flags enabled, and
  416 running the just-built Emacs.
  418 * General runtime problems
  420 ** Lisp problems
  422 *** Changes made to .el files do not take effect.
  424 You may have forgotten to recompile them into .elc files.
  425 Then the old .elc files will be loaded, and your changes
  426 will not be seen.  To fix this, do M-x byte-recompile-directory
  427 and specify the directory that contains the Lisp files.
  429 Emacs prints a warning when loading a .elc file which is older
  430 than the corresponding .el file.
  432 Alternatively, if you set the option 'load-prefer-newer' non-nil,
  433 Emacs will load whichever version of a file is the newest.
  435 *** Watch out for the EMACSLOADPATH environment variable
  437 EMACSLOADPATH overrides which directories the function "load" will search.
  439 If you observe strange problems, check for this variable in your
  440 environment.
  442 ** Keyboard problems
  444 *** Unable to enter the M-| key on some German keyboards.
  445 Some users have reported that M-| suffers from "keyboard ghosting".
  446 This can't be fixed by Emacs, as the keypress never gets passed to it
  447 at all (as can be verified using "xev").  You can work around this by
  448 typing 'ESC |' instead.
  450 *** "Compose Character" key does strange things when used as a Meta key.
  452 If you define one key to serve as both Meta and Compose Character, you
  453 will get strange results.  In previous Emacs versions, this "worked"
  454 in that the key acted as Meta--that's because the older Emacs versions
  455 did not try to support Compose Character.  Now Emacs tries to do
  456 character composition in the standard X way.  This means that you
  457 must pick one meaning or the other for any given key.
  459 You can use both functions (Meta, and Compose Character) if you assign
  460 them to two different keys.
  462 *** C-z just refreshes the screen instead of suspending Emacs.
  464 You are probably using a shell that doesn't support job control, even
  465 though the system itself is capable of it.  Either use a different shell,
  466 or set the variable 'cannot-suspend' to a non-nil value.
  468 ** Mailers and other helper programs
  470 *** movemail compiled with POP support can't connect to the POP server.
  472 This problem can occur if you do not configure --with-mailutils,
  473 and don't have GNU Mailutils installed.  Then Emacs uses its own
  474 version of movemail, which doesn't support secure POP connections.
  475 To solve this, install GNU Mailutils.
  477 Also, make sure that the 'pop' entry in /etc/services, or in the
  478 services NIS map if your machine uses NIS, has the same port number as
  479 the entry on the POP server.  A common error is for the POP server to
  480 be listening on port 110, the assigned port for the POP3 protocol,
  481 while the client is trying to connect on port 109, the assigned port
  482 for the old POP protocol.
  484 *** RMAIL gets error getting new mail.
  486 RMAIL gets new mail from /usr/spool/mail/$USER using a program
  487 called 'movemail'.  This program interlocks with /bin/mail using
  488 the protocol defined by /bin/mail.
  490 There are two different protocols in general use.  One of them uses
  491 the 'flock' system call.  The other involves creating a lock file;
  492 'movemail' must be able to write in /usr/spool/mail in order to do
  493 this.  You control which one is used by defining, or not defining,
  494 the macro MAIL_USE_FLOCK in config.h.
  498 If your system uses the lock file protocol, and fascist restrictions
  499 prevent ordinary users from writing the lock files in /usr/spool/mail,
  500 you may need to make 'movemail' setgid to a suitable group such as
  501 'mail'.  To do this,  use the following commands (as root) after doing the
  502 make install.
  504         chgrp mail movemail
  505         chmod 2755 movemail
  507 Installation normally copies movemail from the build directory to an
  508 installation directory which is usually under /usr/local/lib.  The
  509 installed copy of movemail is usually in the directory
  510 /usr/local/lib/emacs/VERSION/TARGET.  You must change the group and
  511 mode of the installed copy; changing the group and mode of the build
  512 directory copy is ineffective.
  514 *** rcs2log gives you the awk error message "too many fields".
  516 This is due to an arbitrary limit in certain versions of awk.
  517 The solution is to use gawk (GNU awk).
  519 ** Problems with hostname resolution
  521 *** Emacs does not know your host's fully-qualified domain name.
  523 For example, (system-name) returns some variation on
  524 "localhost.localdomain", rather the name you were expecting.
  526 You need to configure your machine with a fully qualified domain name,
  527 (i.e., a name with at least one "."), either in /etc/hostname
  528 or wherever your system calls for specifying this.
  530 If you cannot fix the configuration, you can set the Lisp variable
  531 mail-host-address to the value you want.
  533 ** NFS
  535 *** Emacs says it has saved a file, but the file does not actually
  536 appear on disk.
  538 This can happen on certain systems when you are using NFS, if the
  539 remote disk is full.  It is due to a bug in NFS (or certain NFS
  540 implementations), and there is apparently nothing Emacs can do to
  541 detect the problem.  Emacs checks the failure codes of all the system
  542 calls involved in writing a file, including 'close'; but in the case
  543 where the problem occurs, none of those system calls fails.
  545 ** PSGML conflicts with sgml-mode.
  547 PSGML package uses the same names of some variables (like keymap)
  548 as built-in sgml-mode.el because it was created as a replacement
  549 of that package.  The conflict will be shown if you load
  550 sgml-mode.el before psgml.el.  E.g. this could happen if you edit
  551 HTML page and then start to work with SGML or XML file.  html-mode
  552 (from sgml-mode.el) is used for HTML file and loading of psgml.el
  553 (for sgml-mode or xml-mode) will cause an error.
  555 ** PCL-CVS
  557 *** Lines are not updated or new lines are added in the buffer upon commit.
  559 When committing files located higher in the hierarchy than the examined
  560 directory, some versions of the CVS program return an ambiguous message
  561 from which PCL-CVS cannot extract the full location of the committed
  562 files.  As a result, the corresponding lines in the PCL-CVS buffer are
  563 not updated with the new revision of these files, and new lines are
  564 added to the top-level directory.
  566 This can happen with CVS versions 1.12.8 and 1.12.9.  Upgrade to CVS
  567 1.12.10 or newer to fix this problem.
  569 ** Miscellaneous problems
  571 *** Editing files with very long lines is slow.
  573 For example, simply moving through a file that contains hundreds of
  574 thousands of characters per line is slow, and consumes a lot of CPU.
  575 This is a known limitation of Emacs with no solution at this time.
  577 *** Display artifacts on GUI frames on X-based systems.
  579 This is known to be caused by using double-buffering (which is enabled
  580 by default in Emacs 26 and later).  The artifacts typically appear
  581 after commands that cause Emacs to scroll the display.
  583 You can disable double-buffering by evaluating the following form:
  585   (modify-all-frames-parameters '((inhibit-double-buffering . t)))
  587 To make this permanent, add it to your ~/.emacs init file.
  589 Note that disabling double-buffering will cause flickering of the
  590 display in some situations.
  592 *** Self-documentation messages are garbled.
  594 This means that the file 'etc/DOC' doesn't properly correspond
  595 with the Emacs executable.  Redumping Emacs and then installing the
  596 corresponding pair of files should fix the problem.
  598 *** Programs running under terminal emulator do not recognize 'emacs'
  599 terminal type.
  601 The cause of this is a shell startup file that sets the TERMCAP
  602 environment variable.  The terminal emulator uses that variable to
  603 provide the information on the special terminal type that Emacs emulates.
  605 Rewrite your shell startup file so that it does not change TERMCAP
  606 in such a case.  You could use the following conditional which sets
  607 it only if it is undefined.
  609     if ( ! ${?TERMCAP} ) setenv TERMCAP ~/my-termcap-file
  611 Or you could set TERMCAP only when you set TERM--which should not
  612 happen in a non-login shell.
  614 *** In Shell mode, you get a ^M at the end of every line.
  616 This happens to people who use tcsh, because it is trying to be too
  617 smart.  It sees that the Shell uses terminal type 'unknown' and turns
  618 on the flag to output ^M at the end of each line.  You can fix the
  619 problem by adding this to your .cshrc file:
  621     if ($?INSIDE_EMACS && $?tcsh)
  622         unset edit
  623         stty -icrnl -onlcr -echo susp ^Z
  624     endif
  626 *** In Shell buffers using ksh, resizing a window inserts random characters.
  628 The characters come from the PS2 prompt, but they are not followed by
  629 a newline, which messes up the next command you type.  This strange
  630 effect is caused by Emacs 25 and later telling the shell that its
  631 screen size changed.
  633 To work around the problem, customize the option
  634 'window-adjust-process-window-size-function' to "Do not adjust process
  635 window sizes" (Lisp value 'ignore').
  637 *** In Inferior Python mode, input is echoed and native completion doesn't work.
  638 <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=25753>
  640 This happens when python uses a libedit based readline module, which
  641 is the default on macOS.  This can be worked around by installing a
  642 GNU readline based module instead, for example, using setuptools
  644     sudo easy_install gnureadline
  646 And then rename the system's readline so that it won't be loaded:
  648     cd /Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/lib-dynload
  649     mv readline.so readline.so.bak
  651 See <https://pypi.python.org/pypi/gnureadline> for more details on
  652 installation.
  654 *** On MS-Windows, invoking "M-x run-python" signals an error.
  656 If the error says something like this:
  658   Python was not found; run with arguments to install
  659   from the Microsoft Store, or disable this shortcut
  660   from Settings > Manage App Execution Aliases.
  662   Process Python exited abnormally with code 49
  664 then this is due to the MS-Windows "feature" that is intended to
  665 encourage you to install the latest available Python version.  It
  666 works by placing "fake" python.exe and python3.exe executables in a
  667 special directory, and having that directory on your Path _before_ the
  668 directory where the real Python executable is installed.  That "fake"
  669 Python then decides whether to redirect you to the Microsoft Store or
  670 invoke the actual Python.  The directory where Windows keeps those
  671 "fake" executables is under your Windows user's 'AppData' directory,
  672 typically 'C:\Users\<user>\AppData\Local\Microsoft\WindowsApps', where
  673 "<user>" is the user name of your Windows user.
  675 To solve this, you have several alternatives:
  677   . Go to "Settings > Manage App Execution Aliases" and turn OFF the
  678     aliases for python.exe and/or python3.exe.  This will affect only
  679     Python, and may require you to manage upgrades to your Python
  680     installation manually, instead of being automatically prompted by
  681     MS-Windows.
  682   . Move the directory with the "fake" executables to the end of Path,
  683     or at least after the directory where the real Python is
  684     installed.  Depending on the position in Path where you move it,
  685     it will affect Python and/or other programs which Windows monitors
  686     via the "App Execution Aliases" feature.
  687   . Manually remove python.exe and/or python3.exe from the above
  688     directory.  Again, this affects only your Python installation.
  690 Whatever you do, you will need to restart Emacs to refresh its notion
  691 of the directory where python.exe/python3.exe lives, because that is
  692 recorded when Python mode is started.
  694 *** Visiting files in some auto-mounted directories causes Emacs to print
  695 'Error reading dir-locals: (file-error "Read error" "is a directory" ...'
  697 This can happen if the auto-mounter mistakenly reports that
  698 .dir-locals.el exists and is a directory.  There is nothing Emacs can
  699 do about this, but you can avoid the issue by adding a suitable entry
  700 to the variable 'locate-dominating-stop-dir-regexp'.  For example, if
  701 the problem relates to "/smb/.dir-locals.el", set that variable
  702 to a new value where you replace "net\\|afs" with "net\\|afs\\|smb".
  703 (The default value already matches common auto-mount prefixes.)
  704 See https://lists.gnu.org/r/help-gnu-emacs/2015-02/msg00461.html .
  706 *** Attempting to visit remote files via ange-ftp fails.
  708 If the error message is "ange-ftp-file-modtime: Specified time is not
  709 representable", then this could happen when 'lukemftp' is used as the
  710 ftp client.  This was reported to happen on Debian GNU/Linux, kernel
  711 version 2.4.3, with 'lukemftp' 1.5-5, but might happen on other
  712 systems as well.  To avoid this problem, switch to using the standard
  713 ftp client.  On a Debian system, type
  715   update-alternatives --config ftp
  717 and then choose /usr/bin/netkit-ftp.
  719 *** Dired is very slow.
  721 This could happen if getting a file system's status takes a long
  722 time.  Possible reasons for this include:
  724   - ClearCase mounted filesystems (VOBs) that sometimes make 'df'
  725     response time extremely slow (dozens of seconds);
  727   - slow automounters on some old versions of Unix;
  729 To work around the problem, you could use Git or some other
  730 free-software program, instead of ClearCase.
  732 *** Various commands that visit files on networked filesystems fail.
  734 This could happen if the filesystem of those files is mounted in a way
  735 that causes the files to be accessed via a symlink.  One such example
  736 is the 'amd' automounter, which unmounts the filesystem after some
  737 period of lack of use.  Another example is Emacs running on MS-Windows
  738 that accesses files on remote server via symlinks whose target is a
  739 UNC of the form '\\server\share'.
  741 The reason for these problems is that some Emacs commands visit files
  742 via their truename, resolving the symlink, which causes these files'
  743 default-directory to also have the symlink resolved.  If the resolved
  744 directory has access problems, subsequent commands from that file's
  745 buffer could fail.  For example, the stock MS-Windows shell 'cmd.exe'
  746 is unable to use a UNC-form directory as the current directory, so
  747 'shell-command' and its callers will typically fail.  Similarly with
  748 using targets of symlinks which no longer mount the remote filesystem
  749 will fail.
  751 You can solve these problems in several ways:
  753   - Write a 'find-file'hook' function which will change the value of
  754     'default-directory' to reference the symlink instead of its
  755     target.
  757   - Set up 'directory-abbrev-alist' to automatically convert the
  758     'default-directory' of such files in the same manner.
  760   - On MS-Windows, map a drive letter to the '\\server\share'
  761     directory and point your symlinks to a directory name that uses
  762     the drive letter.
  764 *** On MS-Windows, visiting files in OneDrive fails.
  766 This is known to happen when OneDrive is accessed via the so-called
  767 "metered connections", whose use is charged by the volume of
  768 transferred data.  Those are typically wireless links using a modem or
  769 a mobile phone.  In these cases, files that are left in the cloud and
  770 not downloaded to the local computer can produce various failures in
  771 system calls that access the files or their meta-data.
  773 The solution is to disable the "metered connection" status from the
  774 WiFi properties (reachable from the Windows Settings menu).  This will
  775 cause files to be downloaded to the local computer when they are
  776 accessed (which could take some time, and Emacs functions accessing
  777 the file will wait for that), avoiding the errors.
  779 *** ps-print commands fail to find prologue files ps-prin*.ps.
  781 This can happen if you use an old version of X-Symbol package: it
  782 defines compatibility functions which trick ps-print into thinking it
  783 runs in XEmacs, and look for the prologue files in a wrong directory.
  785 The solution is to upgrade X-Symbol to a later version.
  787 *** On systems with shared libraries you might encounter run-time errors
  788 from the dynamic linker telling you that it is unable to find some
  789 shared libraries, for instance those for Xaw3d or image support.
  790 These errors mean Emacs has been linked with a library whose shared
  791 library is not in the default search path of the dynamic linker.
  793 Similar problems could prevent Emacs from building, since the build
  794 process invokes Emacs several times.
  796 On many systems, it is possible to set LD_LIBRARY_PATH in your
  797 environment to specify additional directories where shared libraries
  798 can be found.
  800 Other systems allow to set LD_RUN_PATH in a similar way, but before
  801 Emacs is linked.  With LD_RUN_PATH set, the linker will include a
  802 specified run-time search path in the executable.
  804 Please refer to the documentation of your dynamic linker for details.
  806 *** When you run Ispell from Emacs, it reports a "misalignment" error.
  808 This can happen if you compiled the Ispell program to use ASCII
  809 characters only and then try to use it from Emacs with non-ASCII
  810 characters, like Latin-1.  The solution is to recompile Ispell with
  811 support for 8-bit characters.
  813 To see whether your Ispell program supports 8-bit characters, type
  814 this at your shell's prompt:
  816      ispell -vv
  818 and look in the output for the string "NO8BIT".  If Ispell says
  819 "!NO8BIT (8BIT)", your speller supports 8-bit characters; otherwise it
  820 does not.
  822 To rebuild Ispell with 8-bit character support, edit the local.h file
  823 in the Ispell distribution and make sure it does _not_ define NO8BIT.
  824 Then rebuild the speller.
  826 Another possible cause for "misalignment" error messages is that the
  827 version of Ispell installed on your machine is old.  Upgrade.
  829 Yet another possibility is that you are trying to spell-check a word
  830 in a language that doesn't fit the dictionary you choose for use by
  831 Ispell.  (Ispell can only spell-check one language at a time, because
  832 it uses a single dictionary.)  Make sure that the text you are
  833 spelling and the dictionary used by Ispell conform to each other.
  835 If your spell-checking program is Aspell, it has been reported that if
  836 you have a personal configuration file (normally ~/.aspell.conf), it
  837 can cause this error.  Remove that file, execute 'ispell-kill-ispell'
  838 in Emacs, and then try spell-checking again.
  840 *** TLS problems, e.g., Gnus hangs when fetching via imaps
  841 https://debbugs.gnu.org/24247
  843 gnutls-cli 3.5.3 (2016-08-09) does not generate a "- Handshake was
  844 completed" message that tls.el relies upon, causing affected Emacs
  845 functions to hang.  To work around the problem, use older or newer
  846 versions of gnutls-cli, or use Emacs's built-in gnutls support.
  848 *** SVG images may be cropped incorrectly with librsvg 2.45 or older.
  850 Librsvg 2.46 and above have improved geometry code which Emacs is able
  851 to take advantage of.
  853 * Runtime problems related to font handling
  855 ** Characters are displayed as empty boxes or with wrong font under X.
  857 *** This may be due to your local fontconfig customization.
  858 Try removing or moving aside "$XDG_CONFIG_HOME/fontconfig/conf.d" and
  859 "$XDG_CONFIG_HOME/fontconfig/fonts.conf"
  860 ($XDG_CONFIG_HOME is treated as "~/.config" if not set)
  862 Running Emacs as
  864     FC_DEBUG=1024 emacs
  866 will cause fontconfig to output information about which configuration
  867 files it is reading.  Running Emacs as
  869     FC_DEBUG=1 emacs
  871 will result in information about the results of fontconfig's font
  872 matching (including the filename(s) of the resulting fonts).
  874 *** This can occur when two different versions of FontConfig are used.
  875 For example, XFree86 4.3.0 has one version and Gnome usually comes
  876 with a newer version.  Emacs compiled with Gtk+ will then use the
  877 newer version.  In most cases the problem can be temporarily fixed by
  878 stopping the application that has the error (it can be Emacs or any
  879 other application), removing ~/.fonts.cache-1, and then starting the
  880 application again.  If removing ~/.fonts.cache-1 and restarting
  881 doesn't help, the application with problem must be recompiled with the
  882 same version of FontConfig as the rest of the system uses.  For KDE,
  883 it is sufficient to recompile Qt.
  885 *** Some fonts have a missing glyph and no default character.  This is
  886 known to occur for character number 160 (no-break space, U+A0) in some
  887 fonts, such as Lucida but Emacs sets the display table for the unibyte
  888 and Latin-1 version of this character to display a space.
  890 *** Some of the fonts called for in your fontset may not exist on your
  891 X server.
  893 Each X font covers just a fraction of the characters that Emacs
  894 supports.  To display the whole range of Emacs characters requires
  895 many different fonts, collected into a fontset.  You can remedy the
  896 problem by installing additional fonts.
  898 The intlfonts distribution includes a full spectrum of fonts that can
  899 display all the characters Emacs supports.  The etl-unicode collection
  900 of fonts (available from
  901 <https://ftp.nluug.nl/windowing/X/contrib/fonts/>) includes fonts that
  902 can display many Unicode characters; they can also be used by ps-print
  903 and ps-mule to print Unicode characters.
  905 ** Under X, some characters appear improperly aligned in their lines.
  907 You may have bad fonts.
  909 ** Under X, some characters are unexpectedly wide.
  911 e.g. recent versions of Inconsolata show this issue for almost all of
  912 its characters.  Due to what is probably an Xft bug, the determination
  913 of the width of some characters is incorrect.  One workaround is to
  914 build emacs with Cairo enabled ("configure --with-cairo" and have the
  915 appropriate Cairo development packages installed) as this
  916 configuration does not suffer from this problem.  See
  917 <https://github.com/googlefonts/Inconsolata/issues/42> and
  918 <https://lists.gnu.org/r/bug-gnu-emacs/2020-01/msg00456.html>
  919 for more discussion.
  921 ** Under X, an unexpected monospace font is used as the default font.
  923 When compiled with XFT, Emacs tries to use a default font named
  924 "monospace".  This is a "virtual font", which the operating system
  925 (Fontconfig) redirects to a suitable font such as DejaVu Sans Mono.
  926 On some systems, there exists a font that is actually named Monospace,
  927 which takes over the virtual font.  This is considered an operating
  928 system bug; see
  930 https://lists.gnu.org/r/emacs-devel/2008-10/msg00696.html
  932 If you encounter this problem, set the default font to a specific font
  933 in your .Xresources or initialization file.  For instance, you can put
  934 the following in your .Xresources:
  936 Emacs.font: DejaVu Sans Mono 12
  938 ** Certain fonts make each line take one pixel more than it should.
  940 This is because these fonts contain characters a little taller than
  941 the font's nominal height.  Emacs needs to make sure that lines do not
  942 overlap.
  944 ** Font Lock displays portions of the buffer in incorrect faces.
  946 By far the most frequent cause of this is a parenthesis '(' or a brace
  947 '{' in column zero.  Font Lock assumes that such a paren is outside of
  948 any comment or string.  This is of course not true in general, but the
  949 vast majority of well-formatted program source files don't have such
  950 parens, and therefore this assumption is used to allow optimizations
  951 in Font Lock's syntactical analysis.  These optimizations avoid some
  952 pathological cases where jit-lock, the Just-in-Time fontification
  953 introduced with Emacs 21.1, could significantly slow down scrolling
  954 through the buffer, especially scrolling backwards, and also jumping
  955 to the end of a very large buffer.
  957 Beginning with version 22.1, a parenthesis or a brace in column zero
  958 is highlighted in bold-red face if it is inside a string or a comment,
  959 to indicate that it could interfere with Font Lock (and also with
  960 indentation) and should be moved or escaped with a backslash.
  962 If you don't use large buffers, or have a very fast machine which
  963 makes the delays insignificant, you can avoid the incorrect
  964 fontification by setting the variable
  965 'font-lock-beginning-of-syntax-function' to a nil value.  (This must
  966 be done _after_ turning on Font Lock.)
  968 Another alternative is to avoid a paren in column zero.  For example,
  969 in a Lisp string you could precede the paren with a backslash.
  971 ** Emacs pauses for several seconds when changing the default font.
  973 This has been reported for fvwm 2.2.5 and the window manager of KDE
  974 2.1.  The reason for the pause is Xt waiting for a ConfigureNotify
  975 event from the window manager, which the window manager doesn't send.
  976 Xt stops waiting after a default timeout of usually 5 seconds.
  978 A workaround for this is to add something like
  980 emacs.waitForWM: false
  982 to your X resources.  Alternatively, add '(wait-for-wm . nil)' to a
  983 frame's parameter list, like this:
  985    (modify-frame-parameters nil '((wait-for-wm . nil)))
  987 (this should go into your '.emacs' file).
  989 ** Underlines appear at the wrong position.
  991 This is caused by fonts having a wrong UNDERLINE_POSITION property.
  992 To avoid this problem (seen in some very old X releases and font packages),
  993 set x-use-underline-position-properties to nil.
  995 To see what is the value of UNDERLINE_POSITION defined by the font,
  996 type 'xlsfonts -lll FONT' and look at the font's UNDERLINE_POSITION property.
  998 ** When using Exceed, fonts sometimes appear too tall.
 1000 When the display is set to an Exceed X-server and fonts are specified
 1001 (either explicitly with the -fn option or implicitly with X resources)
 1002 then the fonts may appear "too tall".  The actual character sizes are
 1003 correct but there is too much vertical spacing between rows,  which
 1004 gives the appearance of "double spacing".
 1006 To prevent this, turn off the Exceed's "automatic font substitution"
 1007 feature (in the font part of the configuration window).
 1009 ** Subscript/superscript text in TeX is hard to read.
 1011 If 'tex-fontify-script' is non-nil, tex-mode displays
 1012 subscript/superscript text in the faces subscript/superscript, which
 1013 are smaller than the normal font and lowered/raised.  With some fonts,
 1014 nested superscripts (say) can be hard to read.  Switching to a
 1015 different font, or changing your antialiasing setting (on an LCD
 1016 screen), can both make the problem disappear.  Alternatively, customize
 1017 the following variables: tex-font-script-display (how much to
 1018 lower/raise); tex-suscript-height-ratio (how much smaller than
 1019 normal); tex-suscript-height-minimum (minimum height).
 1021 ** Screen refresh is slow when there are special characters for which no suitable font is available
 1023 If the display is too slow in refreshing when you scroll to a new
 1024 region, or when you edit the buffer, it might be due to the fact that
 1025 some characters cannot be displayed in the default font, and Emacs is
 1026 spending too much time in looking for a suitable font to display them.
 1028 You can suspect this if you have several characters that are displayed
 1029 as small rectangles containing a hexadecimal code inside.
 1031 The solution is to install the appropriate fonts on your machine. For
 1032 instance if you are editing a text with a lot of math symbols, then
 1033 installing a font like 'Symbola' should solve this problem.
 1035 Another reason for slow display is reportedly the nerd-fonts
 1036 installation, even when Symbola is installed as well.  Uninstalling
 1037 nerd-fonts was reported to solve the problem in that case.
 1039 ** Emacs running on GNU/Linux system with the m17n library Ver.1.7.1 or the
 1040 earlier version has a problem with rendering Bengali script.
 1042 The problem can be fixed by installing the newer version of the m17n
 1043 library (if any), or by following this procedure:
 1045 1. Locate the file BENG-OTF.flt installed on your system as part of the
 1046 m17n library.  Usually it is under the directory /usr/share/m17n.
 1048 2. Apply the following patch to BENG-OTF.flt
 1050 ------------------------------------------------------------
 1051 diff --git a/FLT/BENG-OTF.flt b/FLT/BENG-OTF.flt
 1052 index 45cc554..0cc5e76 100644
 1053 --- a/FLT/BENG-OTF.flt
 1054 +++ b/FLT/BENG-OTF.flt
 1055 @@ -232,7 +232,7 @@
 1056   (lang-forms
 1057    (cond
 1058     ("(.H)J" (1 :otf=beng=half+))
 1059 -   (".H" :otf=beng=blwf,half,vatu+)
 1060 +   (".+H" :otf=beng=blwf,half,vatu+)
 1061     ("." =)))
 1063   (post
 1064 ------------------------------------------------------------
 1066 If you can't modify that file directly, copy it to the directory
 1067 ~/.m17n.d/ (create it if it doesn't exist), and apply the patch.
 1069 ** Emacs running on GNU/Linux system with the m17n library Ver.1.7.1 or the
 1070 earlier version has a problem with rendering Lao script with OpenType font.
 1072 The problem can be fixed by installing the newer version of the m17n
 1073 library (if any), or by following this procedure:
 1075 1. Locate the file LAOO-OTF.flt installed on your system as part of the
 1076 m17n library.  Usually it is under the directory /usr/share/m17n.
 1078 2. Apply the following patch to LAOO-OTF.flt
 1080 ------------------------------------------------------------
 1081 diff --git a/FLT/LAOO-OTF.flt b/FLT/LAOO-OTF.flt
 1082 index 5504171..431adf8 100644
 1083 --- a/FLT/LAOO-OTF.flt
 1084 +++ b/FLT/LAOO-OTF.flt
 1085 @@ -3,7 +3,7 @@
 1086  ;; See the end for copying conditions.
 1088  (font layouter laoo-otf nil
 1089 -      (font (nil phetsarath\ ot unicode-bmp)))
 1090 +      (font (nil nil unicode-bmp :otf=lao\ )))
 1092  ;;; <li> LAOO-OTF.flt
 1094 ------------------------------------------------------------
 1096 If you can't modify that file directly, copy it to the directory
 1097 ~/.m17n.d/ (create it if it doesn't exist), and apply the patch.
 1099 ** On MS-Windows, some characters display as boxes with hex code.
 1101 Also, some characters could display with wrong fonts.
 1103 This can happen if Emacs was compiled without HarfBuzz support, and/or
 1104 if the HarfBuzz DLLs are not available at run time.  Emacs will then
 1105 fall back to the Uniscribe as its shaping engine; Uniscribe was
 1106 deprecated by Microsoft, and sometimes fails to display correctly when
 1107 modern fonts are used, such as Noto Emoji or Ebrima.
 1109 The solution is to switch to a configuration that uses HarfBuzz as its
 1110 shaping engine, where these problems don't exist.
 1112 ** On MS-Windows, selecting some fonts as the default font doesn't work.
 1114 This can happen if you select font variants such as "Light" or "Thin"
 1115 or "Semibold" or "Heavy", and some others.  The APIs used by Emacs on
 1116 Windows to enumerate fonts in a font family consider only 4 font
 1117 variants to belong to the same family: Regular, Italic, Bold, and
 1118 Bold-Italic.  All the other variants aren't returned by those APIs
 1119 when we request to list all the fonts in a family, and thus aren't
 1120 considered by Emacs to belong to the family.  So any font variant that
 1121 is not one of those 4 will likely not work as expected; in most cases
 1122 Emacs will select some other font instead.
 1124 The only workaround is not to choose such font variants as the default
 1125 font when running Emacs on MS-Windows.
 1127 * Internationalization problems
 1129 ** M-{ does not work on a Spanish PC keyboard.
 1131 Many Spanish keyboards seem to ignore that combination.  Emacs can't
 1132 do anything about it.
 1134 ** International characters aren't displayed under X.
 1136 *** Missing X fonts
 1138 XFree86 4 contains many fonts in iso10646-1 encoding which have
 1139 minimal character repertoires (whereas the encoding part of the font
 1140 name is meant to be a reasonable indication of the repertoire
 1141 according to the XLFD spec).  Emacs may choose one of these to display
 1142 characters from the mule-unicode charsets and then typically won't be
 1143 able to find the glyphs to display many characters.  (Check with C-u
 1144 C-x = .)  To avoid this, you may need to use a fontset which sets the
 1145 font for the mule-unicode sets explicitly.  E.g. to use GNU unifont,
 1146 include in the fontset spec:
 1148 mule-unicode-2500-33ff:-gnu-unifont-*-iso10646-1,\
 1149 mule-unicode-e000-ffff:-gnu-unifont-*-iso10646-1,\
 1150 mule-unicode-0100-24ff:-gnu-unifont-*-iso10646-1
 1152 ** The UTF-8/16/7 coding systems don't encode CJK (Far Eastern) characters.
 1154 Emacs directly supports the Unicode BMP whose code points are in the
 1155 ranges 0000-33ff and e000-ffff, and indirectly supports the parts of
 1156 CJK characters belonging to these legacy charsets:
 1158     GB2312, Big5, JISX0208, JISX0212, JISX0213-1, JISX0213-2, KSC5601
 1160 The latter support is done in Utf-Translate-Cjk mode (turned on by
 1161 default).   Which Unicode CJK characters are decoded into which Emacs
 1162 charset is decided by the current language environment.  For instance,
 1163 in Chinese-GB, most of them are decoded into chinese-gb2312.
 1165 If you read UTF-8 data with code points outside these ranges, the
 1166 characters appear in the buffer as raw bytes of the original UTF-8
 1167 (composed into a single quasi-character) and they will be written back
 1168 correctly as UTF-8, assuming you don't break the composed sequences.
 1169 If you read such characters from UTF-16 or UTF-7 data, they are
 1170 substituted with the Unicode 'replacement character', and you lose
 1171 information.
 1173 ** Accented ISO-8859-1 characters are displayed as | or _.
 1175 Try other font set sizes (S-mouse-1).  If the problem persists with
 1176 other sizes as well, your text is corrupted, probably through software
 1177 that is not 8-bit clean.  If the problem goes away with another font
 1178 size, it's probably because some fonts pretend to be ISO-8859-1 fonts
 1179 when they are really ASCII fonts.  In particular the schumacher-clean
 1180 fonts have this bug in some versions of X.
 1182 To see what glyphs are included in a font, use 'xfd', like this:
 1184   xfd -fn -schumacher-clean-medium-r-normal--12-120-75-75-c-60-iso8859-1
 1186 If this shows only ASCII glyphs, the font is indeed the source of the problem.
 1188 The solution is to remove the corresponding lines from the appropriate
 1189 'fonts.alias' file, then run 'mkfontdir' in that directory, and then run
 1190 'xset fp rehash'.
 1192 ** The 'oc-unicode' package doesn't work with Emacs 21.
 1194 This package tries to define more private charsets than there are free
 1195 slots now.  The current built-in Unicode support is actually more
 1196 flexible.  (Use option 'utf-translate-cjk-mode' if you need CJK
 1197 support.)  Files encoded as emacs-mule using oc-unicode aren't
 1198 generally read correctly by Emacs 21.
 1200 * X runtime problems
 1202 ** X keyboard problems
 1204 *** You "lose characters" after typing Compose Character key.
 1206 This is because the Compose Character key is defined as the keysym
 1207 Multi_key, and Emacs (seeing that) does the proper X
 1208 character-composition processing.  If you don't want your Compose key
 1209 to do that, you can redefine it with xmodmap.
 1211 For example, here's one way to turn it into a Meta key:
 1213     xmodmap -e "keysym Multi_key = Meta_L"
 1215 If all users at your site of a particular keyboard prefer Meta to
 1216 Compose, you can make the remapping happen automatically by adding the
 1217 xmodmap command to the xdm setup script for that display.
 1219 *** Using X Window System, control-shift-leftbutton makes Emacs hang.
 1221 Use the shell command 'xset bc' to make the old X Menu package work.
 1223 *** C-SPC fails to work on Fedora GNU/Linux (or with fcitx input method).
 1225 Fedora Core 4 steals the C-SPC key by default for the 'iiimx' program
 1226 which is the input method for some languages.  It blocks Emacs users
 1227 from using the C-SPC key for 'set-mark-command'.
 1229 One solutions is to remove the '<Ctrl>space' from the 'Iiimx' file
 1230 which can be found in the '/usr/lib/X11/app-defaults' directory.
 1231 However, that requires root access.
 1233 Another is to specify 'Emacs*useXIM: false' in your X resources.
 1235 Another is to build Emacs with the '--without-xim' configure option.
 1237 The same problem happens on any other system if you are using fcitx
 1238 (Chinese input method) which by default use C-SPC for toggling.  If
 1239 you want to use fcitx with Emacs, you have two choices.  Toggle fcitx
 1240 by another key (e.g. C-\) by modifying ~/.fcitx/config, or be
 1241 accustomed to use C-@ for 'set-mark-command'.
 1243 *** M-SPC seems to be ignored as input.
 1245 See if your X server is set up to use this as a command
 1246 for character composition.
 1248 *** The S-C-t key combination doesn't get passed to Emacs on X.
 1250 This happens because some X configurations assign the Ctrl-Shift-t
 1251 combination the same meaning as the Multi_key.  The offending
 1252 definition is in the file '...lib/X11/locale/iso8859-1/Compose'; there
 1253 might be other similar combinations which are grabbed by X for similar
 1254 purposes.
 1256 We think that this can be countermanded with the 'xmodmap' utility, if
 1257 you want to be able to bind one of these key sequences within Emacs.
 1259 *** Under X, C-v and/or other keys don't work.
 1261 These may have been intercepted by your window manager.
 1262 See the WM's documentation for how to change this.
 1264 *** Clicking C-mouse-2 in the scroll bar doesn't split the window.
 1266 This currently doesn't work with scroll-bar widgets (and we don't know
 1267 a good way of implementing it with widgets).  If Emacs is configured
 1268 --without-toolkit-scroll-bars, C-mouse-2 on the scroll bar does work.
 1270 *** Inability to send an Alt-modified key, when Emacs is communicating
 1271 directly with an X server.
 1273 If you have tried to bind an Alt-modified key as a command, and it
 1274 does not work to type the command, the first thing you should check is
 1275 whether the key is getting through to Emacs.  To do this, type C-h c
 1276 followed by the Alt-modified key.  C-h c should say what kind of event
 1277 it read.  If it says it read an Alt-modified key, then make sure you
 1278 have made the key binding correctly.
 1280 If C-h c reports an event that doesn't have the Alt modifier, it may
 1281 be because your X server has no key for the Alt modifier.  The X
 1282 server that comes from MIT does not set up the Alt modifier by default.
 1284 If your keyboard has keys named Alt, you can enable them as follows:
 1286     xmodmap -e 'add mod2 = Alt_L'
 1287     xmodmap -e 'add mod2 = Alt_R'
 1289 If the keyboard has just one key named Alt, then only one of those
 1290 commands is needed.  The modifier 'mod2' is a reasonable choice if you
 1291 are using an unmodified MIT version of X.  Otherwise, choose any
 1292 modifier bit not otherwise used.
 1294 If your keyboard does not have keys named Alt, you can use some other
 1295 keys.  Use the keysym command in xmodmap to turn a function key (or
 1296 some other 'spare' key) into Alt_L or into Alt_R, and then use the
 1297 commands show above to make them modifier keys.
 1299 Note that if you have Alt keys but no Meta keys, Emacs translates Alt
 1300 into Meta.  This is because of the great importance of Meta in Emacs.
 1302 *** Emacs hangs or crashes when a large portion of text is selected or killed.
 1304 This is caused by a bug in the clipboard management applets (it has
 1305 been observed in 'klipper' and 'clipit'), which periodically request
 1306 the X clipboard contents from applications.  After a while, Emacs may
 1307 print a message:
 1309   Timed out waiting for property-notify event
 1311 A workaround is to not use 'klipper'/'clipit'.  Upgrading 'klipper' to
 1312 the one coming with KDE 3.3 or later might solve the problem; if it
 1313 doesn't, set 'select-active-regions' to 'only' or nil.
 1315 ** Window-manager and toolkit-related problems
 1317 *** Emacs built with GTK+ toolkit produces corrupted display on HiDPI screen
 1319 This can happen if you set GDK_SCALE=2 in the environment or in your
 1320 '.xinitrc' file.  (This setting is usually accompanied by
 1321 GDK_DPI_SCALE=0.5.)  Emacs can not support these settings correctly,
 1322 as it doesn't use GTK+ exclusively.  The result is that sometimes
 1323 widgets like the scroll bar are displayed incorrectly, and frames
 1324 could be displayed "cropped" to only part of the stuff that should be
 1325 displayed.
 1327 The workaround is to explicitly disable these settings when invoking
 1328 Emacs, for example (from a Posix shell prompt):
 1330   $ GDK_SCALE=1 GDK_DPI_SCALE=1 emacs
 1332 *** Emacs built with GTK+ toolkit can unexpectedly widen frames
 1334 This resizing takes place when a frame is not wide enough to accommodate
 1335 its entire menu bar.  Typically, it occurs when switching buffers or
 1336 changing a buffer's major mode and the new mode adds entries to the menu
 1337 bar.  The frame is then widened by the window manager so that the menu
 1338 bar is fully shown.  Subsequently switching to another buffer or
 1339 changing the buffer's mode will not shrink the frame back to its
 1340 previous width.  The height of the frame remains unaltered.  Apparently,
 1341 the failure is also dependent on the chosen font.
 1343 The resizing is usually accompanied by console output like
 1345 Gtk-CRITICAL **: gtk_distribute_natural_allocation: assertion 'extra_space >= 0' failed
 1347 It's not clear whether the GTK version used has any impact on the
 1348 occurrence of the failure.  So far, the failure has been observed with
 1349 GTK+ versions 3.4.2, 3.14.5 and 3.18.7.  However, another 3.4.2 build
 1350 does not exhibit the bug.
 1352 Some window managers (Xfce) apparently work around this failure by
 1353 cropping the menu bar.  With other windows managers, it's possible to
 1354 shrink the frame manually after the problem occurs, e.g. by dragging the
 1355 frame's border with the mouse.  However, some window managers have been
 1356 reported to refuse such attempts and snap back to the width needed to
 1357 show the full menu bar (wmii) or at least cause the screen to flicker
 1358 during such resizing attempts (i3, IceWM).
 1360 See also https://debbugs.gnu.org/cgi/bugreport.cgi?bug=15700,
 1361 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22000,
 1362 https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22898 and
 1363 https://lists.gnu.org/r/emacs-devel/2016-07/msg00154.html.
 1365 *** Metacity: Resizing Emacs or ALT-Tab causes X to be unresponsive.
 1367 This happens sometimes when using Metacity.  Resizing Emacs or ALT-Tab:bing
 1368 makes the system unresponsive to the mouse or the keyboard.  Killing Emacs
 1369 or shifting out from X and back again usually cures it (i.e. Ctrl-Alt-F1
 1370 and then Alt-F7).  A bug for it is here:
 1371 https://bugs.launchpad.net/ubuntu/+source/metacity/+bug/231034.
 1372 Note that a permanent fix seems to be to disable "assistive technologies".
 1374 *** Enlightenment: Frames not redrawn after switching virtual desktops
 1376 With Enlightenment version 0.25, Emacs frames may no be redrawn orderly
 1377 after switching back from another virtual desktop.  Setting the variable
 1378 'x-set-frame-visibility-more-laxly' to one of 'focus-in', 'expose' or
 1379 't' should fix this.
 1381 *** Gnome: Emacs receives input directly from the keyboard, bypassing XIM.
 1383 This seems to happen when gnome-settings-daemon version 2.12 or later
 1384 is running.  If gnome-settings-daemon is not running, Emacs receives
 1385 input through XIM without any problem.  Furthermore, this seems only
 1386 to happen in *.UTF-8 locales; zh_CN.GB2312 and zh_CN.GBK locales, for
 1387 example, work fine.  A bug report has been filed in the Gnome
 1388 bugzilla: https://bugzilla.gnome.org/show_bug.cgi?id=357032
 1390 *** Gnome: GPaste clipboard manager causes erratic behavior of 'yank'
 1392 The symptom is that 'kill-line' followed by 'yank' often (but not
 1393 always) doesn't insert the whitespace of the killed and yanked line.
 1395 The solution is to set the GPaste "trim items" option to OFF.
 1397 *** Gnome: Navigation from Nautilus to remote files.
 1399 If you navigate to a file, which belongs to a remote server, in
 1400 Nautilus via "Open With Emacs" you might not be able to save this file
 1401 once you have modified it in Emacs.  The reasons for the failure can
 1402 vary, and for some connection methods saving the file might even succeed.
 1404 If the remote connection in Nautilus uses ssh or sftp, you could
 1405 mitigate the problem by the following lines in your .emacs file:
 1407 (dir-locals-set-class-variables 'gvfs '((nil . ((create-lockfiles . nil)))))
 1408 (dir-locals-set-directory-class (format "/run/user/%d/gvfs" (user-uid)) 'gvfs)
 1410 A better approach might be to avoid navigation from Nautilus to Emacs
 1411 for such files, and instead to open the file in Emacs using Tramp
 1412 remote file name syntax.
 1414 *** KDE: When running on KDE, colors or fonts are not as specified for Emacs,
 1415 or messed up.
 1417 For example, you could see background you set for Emacs only in the
 1418 empty portions of the Emacs display, while characters have some other
 1419 background.
 1421 This happens because KDE's defaults apply its color and font
 1422 definitions even to applications that weren't compiled for KDE.  The
 1423 solution is to uncheck the "Apply fonts and colors to non-KDE apps"
 1424 option in Preferences->Look&Feel->Style (KDE 2).  In KDE 3, this option
 1425 is in the "Colors" section, rather than "Style".
 1427 Alternatively, if you do want the KDE defaults to apply to other
 1428 applications, but not to Emacs, you could modify the file 'Emacs.ad'
 1429 (should be in the '/usr/share/apps/kdisplay/app-defaults/' directory)
 1430 so that it doesn't set the default background and foreground only for
 1431 Emacs.  For example, make sure the following resources are either not
 1432 present or commented out:
 1434    Emacs.default.attributeForeground
 1435    Emacs.default.attributeBackground
 1436    Emacs*Foreground
 1437    Emacs*Background
 1439 It is also reported that a bug in the gtk-engines-qt engine can cause this if
 1440 Emacs is compiled with Gtk+.
 1441 The bug is fixed in version 0.7 or newer of gtk-engines-qt.
 1443 *** KDE / Plasma 5: Emacs exhausts memory and needs to be killed
 1445 This problem occurs when large selections contain mixed line endings
 1446 (i.e. the buffer has LF line endings, but in some parts CRLF is used).
 1447 The source of the problem is currently under investigation, older
 1448 versions of Emacs up to 24.5 just hang for a few seconds and then
 1449 return with the message "Timed out waiting for property-notify event"
 1450 as described in the previous note.  As a workaround, go to the
 1451 settings dialog for the Clipboard widget and select the option "Ignore
 1452 Selection".
 1454 Note: Plasma 5 has replaced the separate klipper process from earlier
 1455 KDE versions with functionality directly integrated into plasmashell,
 1456 so even if you've previously did not use klipper this will affect you.
 1457 Also, all configuration you might have done to klipper is not used by
 1458 the new Clipboard widget / plasmoid since it uses its own settings.
 1459 You can hide the Clipboard widget by removing its entry from the
 1460 system tray settings "Extra Items", but it's not clear if the
 1461 underlying functionality in plasmashell gets fully disabled as well.
 1462 At least a restart of plasmashell is required for the clipboard
 1463 history to be cleared.
 1465 *** CDE: Frames may cover dialogs they created when using CDE.
 1467 This can happen if you have "Allow Primary Windows On Top" enabled which
 1468 seems to be the default in the Common Desktop Environment.
 1469 To change, go in to "Desktop Controls" -> "Window Style Manager"
 1470 and uncheck "Allow Primary Windows On Top".
 1472 *** Xaw3d : When using Xaw3d scroll bars without arrows, the very first mouse
 1473 click in a scroll bar might be ignored by the scroll bar widget.  This
 1474 is probably a bug in Xaw3d; when Xaw3d is compiled with arrows, the
 1475 problem disappears.
 1477 *** Xaw: There are known binary incompatibilities between Xaw, Xaw3d, neXtaw,
 1478 XawM and the few other derivatives of Xaw.  So when you compile with
 1479 one of these, it may not work to dynamically link with another one.
 1480 For example, strange problems, such as Emacs exiting when you type
 1481 "C-x 1", were reported when Emacs compiled with Xaw3d and libXaw was
 1482 used with neXtaw at run time.
 1484 The solution is to rebuild Emacs with the toolkit version you actually
 1485 want to use, or set LD_PRELOAD to preload the same toolkit version you
 1486 built Emacs with.
 1488 *** Open Motif: Problems with file dialogs in Emacs built with Open Motif.
 1490 When Emacs 21 is built with Open Motif 2.1, it can happen that the
 1491 graphical file dialog boxes do not work properly.  The "OK", "Filter"
 1492 and "Cancel" buttons do not respond to mouse clicks.  Dragging the
 1493 file dialog window usually causes the buttons to work again.
 1495 As a workaround, you can try building Emacs using Motif or LessTif instead.
 1497 Another workaround is not to use the mouse to trigger file prompts,
 1498 but to use the keyboard.  This way, you will be prompted for a file in
 1499 the minibuffer instead of a graphical file dialog.
 1501 *** LessTif: Problems in Emacs built with LessTif.
 1503 The problems seem to depend on the version of LessTif and the Motif
 1504 emulation for which it is set up.
 1506 Only the Motif 1.2 emulation seems to be stable enough in LessTif.
 1507 LessTif 0.92-17's Motif 1.2 emulation seems to work okay on FreeBSD.
 1508 On GNU/Linux systems, lesstif-0.92.6 configured with "./configure
 1509 --enable-build-12 --enable-default-12" is reported to be the most
 1510 successful.  The binary GNU/Linux package
 1511 lesstif-devel-0.92.0-1.i386.rpm was reported to have problems with
 1512 menu placement.
 1514 On some systems, Emacs occasionally locks up, grabbing all mouse and
 1515 keyboard events.  We don't know what causes these problems; they are
 1516 not reproducible by Emacs developers.
 1518 *** Motif: The Motif version of Emacs paints the screen a solid color.
 1520 This has been observed to result from the following X resource:
 1522    Emacs*default.attributeFont:	-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*
 1524 That the resource has this effect indicates a bug in something, but we
 1525 do not know what.  If it is an Emacs bug, we hope someone can
 1526 explain what the bug is so we can fix it.  In the mean time, removing
 1527 the resource prevents the problem.
 1529 *** FVWM: Some versions of FVWM incorrectly set the 'sticky' frame parameter.
 1531 Version 2.6.4 of the FVWM can make a frame sticky (appear on all user
 1532 desktops) when setting the 'sticky' frame parameter to nil.  This may
 1533 happen without any special user interaction, for example, when Emacs
 1534 restores a saved desktop.  A fix is to install version 2.6.8 of FVWM,
 1535 see https://debbugs.gnu.org/cgi/bugreport.cgi?bug=31650.
 1537 ** General X problems
 1539 *** Redisplay using X is much slower than previous Emacs versions.
 1541 We've noticed that certain X servers draw the text much slower when
 1542 scroll bars are on the left.  We don't know why this happens.  If this
 1543 happens to you, you can work around it by putting the scroll bars
 1544 on the right (as they were in Emacs 19).
 1546 Here's how to do this:
 1548   (set-scroll-bar-mode 'right)
 1550 If you're not sure whether (or how much) this problem affects you,
 1551 try that and see how much difference it makes.  To set things back
 1552 to normal, do
 1554   (set-scroll-bar-mode 'left)
 1556 *** Error messages about undefined colors on X.
 1558 The messages might say something like this:
 1560    Unable to load color "grey95"
 1562 (typically, in the '*Messages*' buffer), or something like this:
 1564   Error while displaying tooltip: (error Undefined color lightyellow)
 1566 These problems could happen if some other X program has used up too
 1567 many colors of the X palette, leaving Emacs with insufficient system
 1568 resources to load all the colors it needs.
 1570 A solution is to exit the offending X programs before starting Emacs.
 1572 "undefined color" messages can also occur if the RgbPath entry in the
 1573 X configuration file is incorrect, or the rgb.txt file is not where
 1574 X expects to find it.
 1576 *** Improving performance with slow X connections.
 1578 There are several ways to improve this performance, any subset of which can
 1579 be carried out at the same time:
 1581 1) If you don't need X Input Methods (XIM) for entering text in some
 1582    language you use, you can improve performance on WAN links by using
 1583    the X resource useXIM to turn off use of XIM.  This does not affect
 1584    the use of Emacs's own input methods, which are part of the Leim
 1585    package.
 1587 2) If the connection is very slow, you might also want to consider
 1588    switching off scroll bars, menu bar, and tool bar.  Adding the
 1589    following forms to your .emacs file will accomplish that, but only
 1590    after the initial frame is displayed:
 1592     (scroll-bar-mode -1)
 1593     (menu-bar-mode -1)
 1594     (tool-bar-mode -1)
 1596    For still quicker startup, put these X resources in your
 1597    .Xresources or .Xdefaults file:
 1599     Emacs.verticalScrollBars: off
 1600     Emacs.menuBar: off
 1601     Emacs.toolBar: off
 1603 3) Use ssh to forward the X connection, and enable compression on this
 1604    forwarded X connection (ssh -XC remotehostname emacs ...).
 1606 4) Use lbxproxy on the remote end of the connection.  This is an interface
 1607    to the low bandwidth X extension in most modern X servers, which
 1608    improves performance dramatically, at the slight expense of correctness
 1609    of the X protocol.  lbxproxy achieves the performance gain by grouping
 1610    several X requests in one TCP packet and sending them off together,
 1611    instead of requiring a round-trip for each X request in a separate
 1612    packet.  The switches that seem to work best for emacs are:
 1613     -noatomsfile  -nowinattr  -cheaterrors -cheatevents
 1614    Note that the -nograbcmap option is known to cause problems.
 1615    For more about lbxproxy, see:
 1616    http://www.x.org/archive/X11R6.8.0/doc/lbxproxy.1.html
 1618 5) If copying and killing is slow, try to disable the interaction with the
 1619    native system's clipboard by adding these lines to your .emacs file:
 1620      (setq interprogram-cut-function nil)
 1621      (setq interprogram-paste-function nil)
 1623 *** Emacs gives the error, Couldn't find per display information.
 1625 This can result if the X server runs out of memory because Emacs uses
 1626 a large number of fonts.  On systems where this happens, C-h h is
 1627 likely to cause it.
 1629 We do not know of a way to prevent the problem.
 1631 *** Emacs does not notice when you release the mouse.
 1633 There are reports that this happened with (some) Microsoft mice and
 1634 that replacing the mouse made it stop.
 1636 *** You can't select from submenus (in the X toolkit version).
 1638 On certain systems, mouse-tracking and selection in top-level menus
 1639 works properly with the X toolkit, but neither of them works when you
 1640 bring up a submenu (such as Bookmarks or Compare or Apply Patch, in
 1641 the Files menu).
 1643 This works on most systems.  There is speculation that the failure is
 1644 due to bugs in old versions of X toolkit libraries, but no one really
 1645 knows.  If someone debugs this and finds the precise cause, perhaps a
 1646 workaround can be found.
 1648 *** An error message such as 'X protocol error: BadMatch (invalid
 1649 parameter attributes) on protocol request 93'.
 1651 This comes from having an invalid X resource, such as
 1652    emacs*Cursor:   black
 1653 (which is invalid because it specifies a color name for something
 1654 that isn't a color.)
 1656 The fix is to correct your X resources.
 1658 *** Slow startup on X11R6 with X windows.
 1660 If Emacs takes two minutes to start up on X11R6, see if your X
 1661 resources specify any Adobe fonts.  That causes the type-1 font
 1662 renderer to start up, even if the font you asked for is not a type-1
 1663 font.
 1665 One way to avoid this problem is to eliminate the type-1 fonts from
 1666 your font path, like this:
 1668         xset -fp /usr/X11R6/lib/X11/fonts/Type1/
 1670 *** Pull-down menus appear in the wrong place, in the toolkit version of Emacs.
 1672 An X resource of this form can cause the problem:
 1674    Emacs*geometry:	80x55+0+0
 1676 This resource is supposed to apply, and does apply, to the menus
 1677 individually as well as to Emacs frames.  If that is not what you
 1678 want, rewrite the resource.
 1680 To check thoroughly for such resource specifications, use 'xrdb
 1681 -query' to see what resources the X server records, and also look at
 1682 the user's ~/.Xdefaults and ~/.Xdefaults-* files.
 1684 *** Emacs running under X Window System does not handle mouse clicks.
 1685 *** 'emacs -geometry 80x20' finds a file named '80x20'.
 1687 One cause of such problems is having (setq term-file-prefix nil) in
 1688 your .emacs file.  Another cause is a bad value of EMACSLOADPATH in
 1689 the environment.
 1691 *** X doesn't work if DISPLAY uses a hostname.
 1693 People have reported kernel bugs in certain systems that cause Emacs
 1694 not to work with X if DISPLAY is set using a host name.  But
 1695 the problem does not occur if DISPLAY is set to 'unix:0.0'.  I think
 1696 the bug has to do with SIGIO or FIONREAD.
 1698 You may be able to compensate for the bug by doing (set-input-mode nil nil).
 1699 However, that has the disadvantage of turning off interrupts, so that
 1700 you are unable to quit out of a Lisp program by typing C-g.
 1702 *** Prevent double pastes in X
 1704 The problem:  a region, such as a command, is pasted twice when you copy
 1705 it with your mouse from GNU Emacs to an xterm or an RXVT shell in X.
 1706 The solution:  try the following in your X configuration file,
 1707 /etc/X11/xorg.conf  This should enable both PS/2 and USB mice for
 1708 single copies.  You do not need any other drivers or options.
 1710     Section "InputDevice"
 1711             Identifier	"Generic Mouse"
 1712             Driver	"mousedev"
 1713             Option	"Device"           "/dev/input/mice"
 1714     EndSection
 1716 *** Emacs is slow to exit in X
 1718 After you use e.g. C-x C-c to exit, it takes many seconds before the
 1719 Emacs window disappears.  If Emacs was started from a terminal, you
 1720 see the message:
 1722   Error saving to X clipboard manager.
 1723   If the problem persists, set 'x-select-enable-clipboard-manager' to nil.
 1725 As the message suggests, this problem occurs when Emacs thinks you
 1726 have a clipboard manager program running, but has trouble contacting it.
 1727 If you don't want to use a clipboard manager, you can set the
 1728 suggested variable.  Or you can make Emacs not wait so long by
 1729 reducing the value of 'x-selection-timeout', either in .emacs or with
 1730 X resources.
 1732 Sometimes this problem is due to a bug in your clipboard manager.
 1733 Updating to the latest version of the manager can help.
 1734 For example, in the Xfce 4.8 desktop environment, the clipboard
 1735 manager in versions of xfce4-settings-helper before 4.8.2 is buggy;
 1736 https://bugzilla.xfce.org/show_bug.cgi?id=7588 .
 1738 *** Warning messages when running in Ubuntu
 1740 When you start Emacs you may see something like this:
 1742 (emacs:2286): LIBDBUSMENU-GTK-CRITICAL **: watch_submenu: assertion
 1743 'GTK_IS_MENU_SHELL(menu)' failed
 1745 This happens if the Emacs binary has been renamed.  The cause is the Ubuntu
 1746 appmenu concept.  It tries to track Emacs menus and show them in the top
 1747 panel, instead of in each Emacs window.  This is not properly implemented,
 1748 so it fails for Emacs.  The order of menus is wrong, and things like copy/paste
 1749 that depend on what state Emacs is in are usually wrong (i.e. paste disabled
 1750 even if you should be able to paste, and similar).
 1752 You can get back menus on each frame by starting emacs like this:
 1753 % env UBUNTU_MENUPROXY= emacs
 1755 *** Mouse click coordinates not recognized correctly on multiple monitors.
 1757 This happens on the proprietary X server ASTEC-X when the number of
 1758 monitors is changed after the server has started.  A workaround is to
 1759 restart the X server after the monitor configuration has been changed.
 1761 * Runtime problems on character terminals
 1763 *** With X forwarding, mouse highlighting can make Emacs slow.
 1765 If you see slow updates when moving the mouse in an Emacs running on a
 1766 remote X server, try this:
 1768     (setq mouse-highlight nil)
 1770 ** The meta key does not work on xterm.
 1772 Typing M-x rings the terminal bell, and inserts a string like ";120~".
 1773 For recent xterm versions (>= 216), Emacs uses xterm's modifyOtherKeys
 1774 feature to generate strings for key combinations that are not
 1775 otherwise usable.  One circumstance in which this can cause problems
 1776 is if you have specified the X resource
 1778   xterm*VT100.Translations
 1780 to contain translations that use the meta key.  Then xterm will not
 1781 use meta in modified function-keys, which confuses Emacs.  To fix
 1782 this, you can remove the X resource or put this in your init file:
 1784   (xterm-remove-modify-other-keys)
 1786 ** The shift TAB key combination works as meta TAB on a Linux console.
 1788 This happens because on your keyboard layout, S-TAB produces the same
 1789 keycodes as typing ESC TAB individually.  The best way to solve this
 1790 is to modify your keyboard layout to produce different codes, and tell
 1791 Emacs what these new codes mean.
 1793 The current keyboard layout will probably be a .map.gz file somewhere
 1794 under /usr/share/keymaps.  Identify this file, possibly from a system
 1795 initialization file such as /etc/conf.d/keymaps.  Run gunzip on it to
 1796 decompress it, and amend the entries for keycode 15 to look something
 1797 like this:
 1799 keycode  15 = Tab
 1800         alt     keycode  15 = Meta_Tab
 1801         shift keycode 15 = F219
 1802 string F219 = "\033[4}\011"      # Shift+<tab>
 1804 After possibly saving this file under a different name, compress it
 1805 again using gzip.  Amend /etc/conf.d/keyamps, etc., if needed.
 1806 Further details can be found in the man page for loadkeys.
 1808 Then add the following line near the start of your site-start.el or
 1809 .emacs or init.el file:
 1811 (define-key input-decode-map "\e[4}\t" 'backtab)
 1813 ** Emacs spontaneously displays "I-search: " at the bottom of the screen.
 1815 This means that Control-S/Control-Q (XON/XOFF) "flow control" is being
 1816 used.  C-s/C-q flow control is bad for Emacs editors because it takes
 1817 away C-s and C-q as user commands.  Since editors do not output long
 1818 streams of text without user commands, there is no need for a
 1819 user-issuable "stop output" command in an editor; therefore, a
 1820 properly designed flow control mechanism would transmit all possible
 1821 input characters without interference.  Designing such a mechanism is
 1822 easy, for a person with at least half a brain.
 1824 There are three possible reasons why flow control could be taking place:
 1826   1) Terminal has not been told to disable flow control
 1827   2) Insufficient padding for the terminal in use
 1828   3) Some sort of terminal concentrator or line switch is responsible
 1830 First of all, many terminals have a set-up mode which controls whether
 1831 they generate XON/XOFF flow control characters.  This must be set to
 1832 "no XON/XOFF" in order for Emacs to work.  (For example, on a VT220
 1833 you may select "No XOFF" in the setup menu.)  Sometimes there is an
 1834 escape sequence that the computer can send to turn flow control off
 1835 and on.  If so, perhaps the termcap 'ti' string should turn flow
 1836 control off, and the 'te' string should turn it on.
 1838 Once the terminal has been told "no flow control", you may find it
 1839 needs more padding.  The amount of padding Emacs sends is controlled
 1840 by the termcap entry for the terminal in use, and by the output baud
 1841 rate as known by the kernel.  The shell command 'stty' will print
 1842 your output baud rate; 'stty' with suitable arguments will set it if
 1843 it is wrong.  Setting to a higher speed causes increased padding.  If
 1844 the results are wrong for the correct speed, there is probably a
 1845 problem in the termcap entry.  You must speak to a local Unix wizard
 1846 to fix this.  Perhaps you are just using the wrong terminal type.
 1848 For terminals that lack a "no flow control" mode, sometimes just
 1849 giving lots of padding will prevent actual generation of flow control
 1850 codes.  You might as well try it.
 1852 If you are really unlucky, your terminal is connected to the computer
 1853 through a concentrator which sends XON/XOFF flow control to the
 1854 computer, or it insists on sending flow control itself no matter how
 1855 much padding you give it.  Unless you can figure out how to turn flow
 1856 control off on this concentrator (again, refer to your local wizard),
 1857 you are screwed!  You should have the terminal or concentrator
 1858 replaced with a properly designed one.  In the mean time, some drastic
 1859 measures can make Emacs semi-work.
 1861 You can make Emacs ignore C-s and C-q and let the operating system
 1862 handle them.  To do this on a per-session basis, just type M-x
 1863 enable-flow-control RET.  You will see a message that C-\ and C-^ are
 1864 now translated to C-s and C-q.  (Use the same command M-x
 1865 enable-flow-control to turn *off* this special mode.  It toggles flow
 1866 control handling.)
 1868 If C-\ and C-^ are inconvenient for you (for example, if one of them
 1869 is the escape character of your terminal concentrator), you can choose
 1870 other characters by setting the variables flow-control-c-s-replacement
 1871 and flow-control-c-q-replacement.  But choose carefully, since all
 1872 other control characters are already used by emacs.
 1874 IMPORTANT: if you type C-s by accident while flow control is enabled,
 1875 Emacs output will freeze, and you will have to remember to type C-q in
 1876 order to continue.
 1878 If you work in an environment where a majority of terminals of a
 1879 certain type are flow control hobbled, you can use the function
 1880 'enable-flow-control-on' to turn on this flow control avoidance scheme
 1881 automatically.  Here is an example:
 1883 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
 1885 If this isn't quite correct (e.g. you have a mixture of flow-control hobbled
 1886 and good vt200 terminals), you can still run enable-flow-control
 1887 manually.
 1889 I have no intention of ever redesigning the Emacs command set for the
 1890 assumption that terminals use C-s/C-q flow control.  XON/XOFF flow
 1891 control technique is a bad design, and terminals that need it are bad
 1892 merchandise and should not be purchased.  Now that X is becoming
 1893 widespread, XON/XOFF seems to be on the way out.  If you can get some
 1894 use out of GNU Emacs on inferior terminals, more power to you, but I
 1895 will not make Emacs worse for properly designed systems for the sake
 1896 of inferior systems.
 1898 ** Control-S and Control-Q commands are ignored completely.
 1900 For some reason, your system is using brain-damaged C-s/C-q flow
 1901 control despite Emacs's attempts to turn it off.  Perhaps your
 1902 terminal is connected to the computer through a concentrator
 1903 that wants to use flow control.
 1905 You should first try to tell the concentrator not to use flow control.
 1906 If you succeed in this, try making the terminal work without
 1907 flow control, as described in the preceding section.
 1909 If that line of approach is not successful, map some other characters
 1910 into C-s and C-q using keyboard-translate-table.  The example above
 1911 shows how to do this with C-^ and C-\.
 1913 ** Screen is updated wrong, but only on one kind of terminal.
 1915 This could mean that the termcap entry you are using for that
 1916 terminal is wrong, or it could mean that Emacs has a bug handling
 1917 the combination of features specified for that terminal.
 1919 The first step in tracking this down is to record what characters
 1920 Emacs is sending to the terminal.  Execute the Lisp expression
 1921 (open-termscript "./emacs-script") to make Emacs write all
 1922 terminal output into the file ~/emacs-script as well; then do
 1923 what makes the screen update wrong, and look at the file
 1924 and decode the characters using the manual for the terminal.
 1925 There are several possibilities:
 1927 1) The characters sent are correct, according to the terminal manual.
 1929 In this case, there is no obvious bug in Emacs, and most likely you
 1930 need more padding, or possibly the terminal manual is wrong.
 1932 2) The characters sent are incorrect, due to an obscure aspect
 1933  of the terminal behavior not described in an obvious way by termcap.
 1935 This case is hard.  It will be necessary to think of a way for
 1936 Emacs to distinguish between terminals with this kind of behavior
 1937 and other terminals that behave subtly differently but are
 1938 classified the same by termcap; or else find an algorithm for
 1939 Emacs to use that avoids the difference.  Such changes must be
 1940 tested on many kinds of terminals.
 1942 3) The termcap entry is wrong.
 1944 See the file etc/TERMS for information on changes
 1945 that are known to be needed in commonly used termcap entries
 1946 for certain terminals.
 1948 4) The characters sent are incorrect, and clearly cannot be
 1949  right for any terminal with the termcap entry you were using.
 1951 This is unambiguously an Emacs bug, and can probably be fixed
 1952 in termcap.c, tparam.c, term.c, scroll.c, cm.c or dispnew.c.
 1954 ** Control-S and Control-Q commands are ignored completely on a net connection.
 1956 Some versions of rlogin (and possibly telnet) do not pass flow
 1957 control characters to the remote system to which they connect.
 1958 On such systems, emacs on the remote system cannot disable flow
 1959 control on the local system.  Sometimes 'rlogin -8' will avoid this problem.
 1961 One way to cure this is to disable flow control on the local host
 1962 (the one running rlogin, not the one running rlogind) using the
 1963 stty command, before starting the rlogin process.  On many systems,
 1964 "stty start u stop u" will do this.  On some systems, use
 1965 "stty -ixon" instead.
 1967 Some versions of tcsh will prevent even this from working.  One way
 1968 around this is to start another shell before starting rlogin, and
 1969 issue the stty command to disable flow control from that shell.
 1971 If none of these methods work, the best solution is to type
 1972 M-x enable-flow-control at the beginning of your emacs session, or
 1973 if you expect the problem to continue, add a line such as the
 1974 following to your .emacs (on the host running rlogind):
 1976 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
 1978 See the entry about spontaneous display of I-search (above) for more info.
 1980 ** Output from Control-V is slow.
 1982 On many bit-map terminals, scrolling operations are fairly slow.
 1983 Often the termcap entry for the type of terminal in use fails
 1984 to inform Emacs of this.  The two lines at the bottom of the screen
 1985 before a Control-V command are supposed to appear at the top after
 1986 the Control-V command.  If Emacs thinks scrolling the lines is fast,
 1987 it will scroll them to the top of the screen.
 1989 If scrolling is slow but Emacs thinks it is fast, the usual reason is
 1990 that the termcap entry for the terminal you are using does not
 1991 specify any padding time for the 'al' and 'dl' strings.  Emacs
 1992 concludes that these operations take only as much time as it takes to
 1993 send the commands at whatever line speed you are using.  You must
 1994 fix the termcap entry to specify, for the 'al' and 'dl', as much
 1995 time as the operations really take.
 1997 Currently Emacs thinks in terms of serial lines which send characters
 1998 at a fixed rate, so that any operation which takes time for the
 1999 terminal to execute must also be padded.  With bit-map terminals
 2000 operated across networks, often the network provides some sort of
 2001 flow control so that padding is never needed no matter how slow
 2002 an operation is.  You must still specify a padding time if you want
 2003 Emacs to realize that the operation takes a long time.  This will
 2004 cause padding characters to be sent unnecessarily, but they do
 2005 not really cost much.  They will be transmitted while the scrolling
 2006 is happening and then discarded quickly by the terminal.
 2008 Most bit-map terminals provide commands for inserting or deleting
 2009 multiple lines at once.  Define the 'AL' and 'DL' strings in the
 2010 termcap entry to say how to do these things, and you will have
 2011 fast output without wasted padding characters.  These strings should
 2012 each contain a single %-spec saying how to send the number of lines
 2013 to be scrolled.  These %-specs are like those in the termcap
 2014 'cm' string.
 2016 You should also define the 'IC' and 'DC' strings if your terminal
 2017 has a command to insert or delete multiple characters.  These
 2018 take the number of positions to insert or delete as an argument.
 2020 A 'cs' string to set the scrolling region will reduce the amount
 2021 of motion you see on the screen when part of the screen is scrolled.
 2023 ** You type Control-H (Backspace) expecting to delete characters.
 2025 Put 'stty dec' in your .login file and your problems will disappear
 2026 after a day or two.
 2028 The choice of Backspace for erasure was based on confusion, caused by
 2029 the fact that backspacing causes erasure (later, when you type another
 2030 character) on most display terminals.  But it is a mistake.  Deletion
 2031 of text is not the same thing as backspacing followed by failure to
 2032 overprint.  I do not wish to propagate this confusion by conforming
 2033 to it.
 2035 For this reason, I believe 'stty dec' is the right mode to use,
 2036 and I have designed Emacs to go with that.  If there were a thousand
 2037 other control characters, I would define Control-h to delete as well;
 2038 but there are not very many other control characters, and I think
 2039 that providing the most mnemonic possible Help character is more
 2040 important than adapting to people who don't use 'stty dec'.
 2042 If you are obstinate about confusing buggy overprinting with deletion,
 2043 you can redefine Backspace in your .emacs file:
 2044   (global-set-key "\b" 'delete-backward-char)
 2045 You can probably access  help-command  via f1.
 2047 ** Colors are not available on a tty or in xterm.
 2049 Emacs 21 supports colors on character terminals and terminal
 2050 emulators, but this support relies on the terminfo or termcap database
 2051 entry to specify that the display supports color.  Emacs looks at the
 2052 "Co" capability for the terminal to find out how many colors are
 2053 supported; it should be non-zero to activate the color support within
 2054 Emacs.  (Most color terminals support 8 or 16 colors.)  If your system
 2055 uses terminfo, the name of the capability equivalent to "Co" is
 2056 "colors".
 2058 In addition to the "Co" capability, Emacs needs the "op" (for
 2059 "original pair") capability, which tells how to switch the terminal
 2060 back to the default foreground and background colors.  Emacs will not
 2061 use colors if this capability is not defined.  If your terminal entry
 2062 doesn't provide such a capability, try using the ANSI standard escape
 2063 sequence \E[00m (that is, define a new termcap/terminfo entry and make
 2064 it use your current terminal's entry plus \E[00m for the "op"
 2065 capability).
 2067 Finally, the "NC" capability (terminfo name: "ncv") tells Emacs which
 2068 attributes cannot be used with colors.  Setting this capability
 2069 incorrectly might have the effect of disabling colors; try setting
 2070 this capability to '0' (zero) and see if that helps.
 2072 Emacs uses the database entry for the terminal whose name is the value
 2073 of the environment variable TERM.  With 'xterm', a common terminal
 2074 entry that supports color is 'xterm-color', so setting TERM's value to
 2075 'xterm-color' might activate the color support on an xterm-compatible
 2076 emulator.
 2078 Beginning with version 22.1, Emacs supports the --color command-line
 2079 option which may be used to force Emacs to use one of a few popular
 2080 modes for getting colors on a tty.  For example, --color=ansi8 sets up
 2081 for using the ANSI-standard escape sequences that support 8 colors.
 2083 Some modes do not use colors unless you turn on the Font-lock mode.
 2084 Some people have long ago set their '~/.emacs' files to turn on
 2085 Font-lock on X only, so they won't see colors on a tty.  The
 2086 recommended way of turning on Font-lock is by typing "M-x
 2087 global-font-lock-mode RET" or by customizing the variable
 2088 'global-font-lock-mode'.
 2090 ** Unexpected characters inserted into the buffer when you start Emacs.
 2091 See e.g. <URL:https://debbugs.gnu.org/11129>
 2093 This can happen when you start Emacs in -nw mode in an Xterm.
 2094 For example, in the *scratch* buffer, you might see something like:
 2096   0;276;0c
 2098 This is more likely to happen if you are using Emacs over a slow
 2099 connection, and begin typing before Emacs is ready to respond.
 2101 This occurs when Emacs tries to query the terminal to see what
 2102 capabilities it supports, and gets confused by the answer.
 2103 To avoid it, set xterm-extra-capabilities to a value other than
 2104 'check' (the default).  See that variable's documentation (in
 2105 term/xterm.el) for more details.
 2107 ** Incorrect or corrupted display of some Unicode characters
 2109 *** Linux console problems with double-width characters
 2111 If possible, we recommend running Emacs inside fbterm, when in a Linux
 2112 console (see the node "Emacs in a Linux console" in the Emacs FAQ).
 2113 Most Unicode characters should then be displayed correctly.
 2115 If that is not possible, the following may be useful to alleviate the
 2116 problem of displaying Unicode characters in a raw console.
 2118 The Linux console declares UTF-8 encoding, but supports only a limited
 2119 number of Unicode characters, and can cause Emacs produce corrupted or
 2120 garbled display with some unusual characters and sequences.  Emacs 28
 2121 and later by default disables 'auto-composition-mode' on this console,
 2122 for that reason, but this might not be enough.  One known problem with
 2123 this console is that zero-width and double-width characters are
 2124 displayed incorrectly (as a single-column characters), and that causes
 2125 the cursor to be out of sync with the actual display.
 2127 One way of working around this is to use the display-table feature to
 2128 display the problematic characters as some other, less problematic
 2129 ones.  Here's an example of setting up the standard display table to
 2130 show the U+01F64F PERSON WITH FOLDED HANDS character as a diamond with
 2131 a special face:
 2133   (or standard-display-table
 2134       (setq standard-display-table (make-display-table)))
 2135   (aset standard-display-table
 2136 	#x1f64f (vector (make-glyph-code #xFFFD 'escape-glyph)))
 2138 Similar setup can be done with any other problematic character.  If
 2139 the console cannot even display the U+FFFD REPLACEMENT CHARACTER, you
 2140 can use some ASCII character instead, like '?'; it will stand out due
 2141 to the 'escape-glyph' face.  The disadvantage of this method is that
 2142 all such characters will look the same on display, and the only way of
 2143 knowing what is the real codepoint in the buffer is to go to the
 2144 character and type "C-u C-x =".
 2146 *** Messed-up display on the Kitty text terminal
 2148 This terminal has its own peculiar ideas about display of unusual
 2149 characters.  For example, it hides the U+00AD SOFT HYPHEN characters
 2150 on display, which messes up Emacs cursor addressing, since Emacs
 2151 doesn't know these characters are effectively treated as zero-width
 2152 characters.
 2154 One way of working around such "hidden" characters is to tell Emacs to
 2155 display them as zero-width:
 2157   (aset glyphless-char-display #xAD 'zero-width)
 2159 Another possibility is to use display-table to display SOFT HYPHEN as
 2160 a regular ASCII dash character '-':
 2162   (or standard-display-table
 2163       (setq standard-display-table (make-display-table)))
 2164   (aset standard-display-table
 2165         #xAD (vector (make-glyph-code ?- 'escape-glyph)))
 2167 Another workaround is to set 'nobreak-char-ascii-display' to a non-nil
 2168 value, which will cause any non-ASCII space and hyphen characters to
 2169 be displayed as their ASCII counterparts, with a special face.
 2171 Kitty also differs from many other character terminals in how it
 2172 handles character compositions.  As one example, Emoji sequences that
 2173 begin with a non-Emoji character and end in U+FE0F VARIATION SELECTOR
 2174 16 should be composed into an Emoji glyph; Kitty assumes that all such
 2175 Emoji glyphs have 2-column width, whereas Emacs and many other text
 2176 terminals display them as 1-column glyphs.  Again, this causes cursor
 2177 addressing to get out of sync and eventually messes up the display.
 2179 One possible workaround for problems caused by character composition
 2180 is to turn off 'auto-composition-mode' on Kitty terminals, e.g. by
 2181 customizing the 'auto-composition-mode' variable to have as value a
 2182 string that the 'tty-type' function returns on those terminals.
 2184 *** Display artifacts on the Alacritty text terminal
 2186 This terminal is known to cause problems with Emoji sequences: when
 2187 displaying them, the Emacs text-mode frame could show gaps and other
 2188 visual artifacts.
 2190 The solution is to disable 'auto-composition-mode' on these
 2191 terminals, for example, like this:
 2193   (setq auto-composition-mode "alacritty")
 2195 This disables 'auto-composition-mode' on frames that display on
 2196 terminals of this type.
 2198 * Runtime problems specific to individual Unix variants
 2200 ** GNU/Linux
 2202 *** GNU/Linux: profiler-report outputs nothing.
 2204 A few versions of the Linux kernel have timer bugs that break CPU
 2205 profiling; see Bug#34235.  To fix the problem, upgrade to one of the
 2206 kernel versions 4.14.97, 4.19.19, or 4.20.6, or later.
 2208 *** GNU/Linux: Remote access to CVS with SSH causes file corruption.
 2210 If you access a remote CVS repository via SSH, files may be corrupted
 2211 due to bad interaction between CVS, SSH, and libc.
 2213 To fix the problem, save the following script into a file, make it
 2214 executable, and set CVS_RSH environment variable to the file name of
 2215 the script:
 2217 #!/bin/bash
 2218 exec 2> >(exec cat >&2 2>/dev/null)
 2219 exec ssh "$@"
 2221 *** GNU/Linux: Truncated svn annotate output with SSH.
 2222 https://debbugs.gnu.org/7791
 2224 The symptoms are: you are accessing a svn repository over SSH.
 2225 You use vc-annotate on a large (several thousand line) file, and the
 2226 result is truncated around the 1000 line mark.  It works fine with
 2227 other access methods (e.g. http), or from outside Emacs.
 2229 This may be a similar libc/SSH issue to the one mentioned above for CVS.
 2230 A similar workaround seems to be effective: create a script with the
 2231 same contents as the one used above for CVS_RSH, and set the SVN_SSH
 2232 environment variable to point to it.
 2234 *** GNU/Linux: After upgrading to a newer version of Emacs,
 2235 the Meta key stops working.
 2237 This was reported to happen on a GNU/Linux system distributed by
 2238 Mandrake.  The reason is that the previous version of Emacs was
 2239 modified by Mandrake to make the Alt key act as the Meta key, on a
 2240 keyboard where the Windows key is the one which produces the Meta
 2241 modifier.  A user who started using a newer version of Emacs, which
 2242 was not hacked by Mandrake, expected the Alt key to continue to act as
 2243 Meta, and was astonished when that didn't happen.
 2245 The solution is to find out what key on your keyboard produces the Meta
 2246 modifier, and use that key instead.  Try all of the keys to the left
 2247 and to the right of the space bar, together with the 'x' key, and see
 2248 which combination produces "M-x" in the echo area.  You can also use
 2249 the 'xmodmap' utility to show all the keys which produce a Meta
 2250 modifier:
 2252          xmodmap -pk | grep -Ei "meta|alt"
 2254 A more convenient way of finding out which keys produce a Meta modifier
 2255 is to use the 'xkbprint' utility, if it's available on your system:
 2257          xkbprint 0:0 /tmp/k.ps
 2259 This produces a PostScript file '/tmp/k.ps' with a picture of your
 2260 keyboard; printing that file on a PostScript printer will show what
 2261 keys can serve as Meta.
 2263 The 'xkeycaps' also shows a visual representation of the current
 2264 keyboard settings.  It also allows to modify them.
 2266 *** GNU/Linux: slow startup on Linux-based GNU systems.
 2268 People using systems based on the Linux kernel sometimes report that
 2269 startup takes 10 to 15 seconds longer than 'usual'.
 2271 This is because Emacs looks up the host name when it starts.
 2272 Normally, this takes negligible time; the extra delay is due to
 2273 improper system configuration.  This problem can occur for both
 2274 networked and non-networked machines.
 2276 Here is how to fix the configuration.  It requires being root.
 2278 **** Networked Case.
 2280 First, make sure the files '/etc/hosts' and '/etc/host.conf' both
 2281 exist.  The first line in the '/etc/hosts' file should look like this
 2282 (replace HOSTNAME with your host name):
 2284      HOSTNAME
 2286 Also make sure that the '/etc/host.conf' files contains the following
 2287 lines:
 2289     order hosts, bind
 2290     multi on
 2292 Any changes, permanent and temporary, to the host name should be
 2293 indicated in the '/etc/hosts' file, since it acts a limited local
 2294 database of addresses and names (e.g., some SLIP connections
 2295 dynamically allocate ip addresses).
 2297 **** Non-Networked Case.
 2299 The solution described in the networked case applies here as well.
 2300 However, if you never intend to network your machine, you can use a
 2301 simpler solution: create an empty '/etc/host.conf' file.  The command
 2302 'touch /etc/host.conf' suffices to create the file.  The '/etc/hosts'
 2303 file is not necessary with this approach.
 2305 *** GNU/Linux: Emacs on a tty switches the cursor to large blinking block.
 2307 This was reported to happen on some GNU/Linux systems which use
 2308 ncurses version 5.0, but could be relevant for other versions as well.
 2309 These versions of ncurses come with a 'linux' terminfo entry, where
 2310 the "cvvis" capability (termcap "vs") is defined as "\E[?25h\E[?8c"
 2311 (show cursor, change size).  This escape sequence switches on a
 2312 blinking hardware text-mode cursor whose size is a full character
 2313 cell.  This blinking cannot be stopped, since a hardware cursor
 2314 always blinks.
 2316 A work-around is to redefine the "cvvis" capability so that it
 2317 enables a *software* cursor.  The software cursor works by inverting
 2318 the colors of the character at point, so what you see is a block
 2319 cursor that doesn't blink.  For this to work, you need to redefine
 2320 the "cnorm" capability as well, so that it operates on the software
 2321 cursor instead of the hardware cursor.
 2323 To this end, run "infocmp linux > linux-term", edit the file
 2324 'linux-term' to make both the "cnorm" and "cvvis" capabilities send
 2325 the sequence "\E[?25h\E[?17;0;64c", and then run "tic linux-term" to
 2326 produce a modified terminfo entry.
 2328 Alternatively, if you want a blinking underscore as your Emacs cursor,
 2329 set the 'visible-cursor' variable to nil in your ~/.emacs:
 2330   (setq visible-cursor nil)
 2332 Still other way is to change the "cvvis" capability to send the
 2333 "\E[?25h\E[?0c" command.
 2335 ** FreeBSD
 2337 *** FreeBSD: Getting a Meta key on the console.
 2339 By default, neither Alt nor any other key acts as a Meta key on
 2340 FreeBSD, but this can be changed using kbdcontrol(1).  Dump the
 2341 current keymap to a file with the command
 2343   $ kbdcontrol -d >emacs.kbd
 2345 Edit emacs.kbd, and give the key you want to be the Meta key the
 2346 definition 'meta'.  For instance, if your keyboard has a "Windows"
 2347 key with scan code 105, change the line for scan code 105 in emacs.kbd
 2348 to look like this
 2350   105   meta   meta   meta   meta   meta   meta   meta   meta    O
 2352 to make the Windows key the Meta key.  Load the new keymap with
 2354   $ kbdcontrol -l emacs.kbd
 2356 ** HP-UX
 2358 *** HP/UX : Shell mode gives the message, "`tty`: Ambiguous".
 2360 christos@theory.tn.cornell.edu says:
 2362 The problem is that in your .cshrc you have something that tries to
 2363 execute 'tty'.  If you are not running the shell on a real tty then
 2364 tty will print "not a tty".  Csh expects one word in some places,
 2365 but tty is giving it back 3.
 2367 The solution is to add a pair of quotes around `tty` to make it a single
 2368 word:
 2370 if (`tty` == "/dev/console")
 2372 should be changed to:
 2374 if ("`tty`" == "/dev/console")
 2376 Even better, move things that set up terminal sections out of .cshrc
 2377 and into .login.
 2379 *** HP/UX: 'Pid xxx killed due to text modification or page I/O error'.
 2381 On HP/UX, you can get that error when the Emacs executable is on an NFS
 2382 file system.  HP/UX responds this way if it tries to swap in a page and
 2383 does not get a response from the server within a timeout whose default
 2384 value is just ten seconds.
 2386 If this happens to you, extend the timeout period.
 2388 *** HP/UX: The right Alt key works wrong on German HP keyboards (and perhaps
 2389 other non-English HP keyboards too).
 2391 This is because HP-UX defines the modifiers wrong in X.  Here is a
 2392 shell script to fix the problem; be sure that it is run after VUE
 2393 configures the X server.
 2395     xmodmap 2> /dev/null - << EOF
 2396     keysym Alt_L = Meta_L
 2397     keysym Alt_R = Meta_R
 2398     EOF
 2400     xmodmap - << EOF
 2401     clear mod1
 2402     keysym Mode_switch = NoSymbol
 2403     add mod1 = Meta_L
 2404     keysym Meta_R = Mode_switch
 2405     add mod2 = Mode_switch
 2406     EOF
 2408 *** HP/UX: Emacs does not recognize the AltGr key.
 2410 To fix this, set up a file ~/.dt/sessions/sessionetc with executable
 2411 rights, containing this text:
 2413 --------------------------------
 2414 xmodmap 2> /dev/null - << EOF
 2415 keysym Alt_L = Meta_L
 2416 keysym Alt_R = Meta_R
 2417 EOF
 2419 xmodmap - << EOF
 2420 clear mod1
 2421 keysym Mode_switch = NoSymbol
 2422 add mod1 = Meta_L
 2423 keysym Meta_R = Mode_switch
 2424 add mod2 = Mode_switch
 2425 EOF
 2426 --------------------------------
 2428 *** HP/UX 11.0: Emacs makes HP/UX 11.0 crash.
 2430 This is a bug in HPUX; HPUX patch PHKL_16260 is said to fix it.
 2432 ** AIX
 2434 *** AIX: Trouble using ptys.
 2436 People often install the pty devices on AIX incorrectly.
 2437 Use 'smit pty' to reinstall them properly.
 2439 *** AIXterm: Your Delete key sends a Backspace to the terminal.
 2441 The solution is to include in your .Xdefaults the lines:
 2443    *aixterm.Translations: #override <Key>BackSpace: string(0x7f)
 2444    aixterm*ttyModes: erase ^?
 2446 This makes your Backspace key send DEL (ASCII 127).
 2448 *** AIX: If linking fails because libXbsd isn't found, check if you
 2449 are compiling with the system's 'cc' and CFLAGS containing '-O5'.  If
 2450 so, you have hit a compiler bug.  Please make sure to re-configure
 2451 Emacs so that it isn't compiled with '-O5'.
 2453 *** AIX 4.3.x or 4.4: Compiling fails.
 2455 This could happen if you use /bin/c89 as your compiler, instead of
 2456 the default 'cc'.  /bin/c89 treats certain warnings, such as benign
 2457 redefinitions of macros, as errors, and fails the build.  A solution
 2458 is to use the default compiler 'cc'.
 2460 *** AIX 4: Some programs fail when run in a Shell buffer
 2461 with an error message like   No terminfo entry for "unknown".
 2463 On AIX, many terminal type definitions are not installed by default.
 2464 'unknown' is one of them.  Install the "Special Generic Terminal
 2465 Definitions" to make them defined.
 2467 ** Solaris
 2469 We list bugs in current versions here.  See also the section on legacy
 2470 systems.
 2472 *** On Solaris 10, 'make clean' and 'make check' do not work.
 2473 The Emacs build procedure uses ’find ... -path ...', which Solaris 10
 2474 'find' does not support.  You can work around the problem by
 2475 installing GNU 'find' in your PATH.  This problem should be fixed in
 2476 Emacs 29.
 2478 *** On Solaris 10 sparc, Emacs crashes during the build while saving state.
 2479 This was observed for Emacs 28.1 on Solaris 10 32-bit sparc, with
 2480 Oracle Developer Studio 12.6 (Sun C 5.15).  The failure was intermittent,
 2481 and running GNU Make a second time would typically finish the build.
 2483 *** On Solaris 10, Emacs crashes during the build process.
 2484 (This applies only with './configure --with-unexec=yes', which is rare.)
 2485 This was reported for Emacs 25.2 on i386-pc-solaris2.10 with Sun
 2486 Studio 12 (Sun C 5.9) and with Oracle Developer Studio 12.6 (Sun C
 2487 5.15), and intermittently for sparc-sun-solaris2.10 with Oracle
 2488 Developer Studio 12.5 (Sun C 5.14).  Disabling compiler optimization
 2489 seems to fix the bug, as does upgrading the Solaris 10 operating
 2490 system to Update 11.  The cause of the bug is unknown: it may be that
 2491 Emacs's archaic memory-allocation scheme is not compatible with
 2492 slightly-older versions of Solaris and/or Oracle Studio, or it may be
 2493 something else.  Since the cause is not known, possibly the bug is
 2494 still present in newer versions of Emacs, Oracle Studio, and/or
 2495 Solaris.  See Bug#26638.
 2497 *** On Solaris, C-x doesn't get through to Emacs when you use the console.
 2499 This is a Solaris feature (at least on Intel x86 cpus).  Type C-r
 2500 C-r C-t, to toggle whether C-x gets through to Emacs.
 2502 * Runtime problems specific to MS-Windows
 2504 ** Emacs on Windows 9X requires UNICOWS.DLL
 2506 If that DLL is not available, Emacs will display an error dialog
 2507 stating its absence, and refuse to run.
 2509 This is because Emacs 24.4 and later uses functions whose non-stub
 2510 implementation is only available in UNICOWS.DLL, which implements the
 2511 Microsoft Layer for Unicode on Windows 9X, or "MSLU".  This article on
 2512 MSDN:
 2514   https://web.archive.org/web/20151224032644/https://msdn.microsoft.com/en-us/goglobal/bb688166.aspx
 2516 includes a short description of MSLU and a link where it can be
 2517 downloaded.
 2519 ** Emacs refuses to start on Windows 9X because ctime64 function is missing
 2521 This is a sign that Emacs was compiled with MinGW runtime version
 2522 4.0.x or later.  These versions of runtime call in their startup code
 2523 the ctime64 function, which does not exist in MSVCRT.DLL, the C
 2524 runtime shared library, distributed with Windows 9X.
 2526 A workaround is to build Emacs with MinGW runtime 3.x (the latest
 2527 version is 3.20).
 2529 ** addpm fails to run on Windows NT4, complaining about Shell32.dll
 2531 This is likely to happen because Shell32.dll shipped with NT4 lacks
 2532 the updates required by Emacs.  Installing Internet Explorer 4 solves
 2533 the problem.  Note that it is NOT enough to install IE6, because doing
 2534 so will not install the Shell32.dll update.
 2536 ** A few seconds delay is seen at startup and for many file operations
 2538 This happens when the Net Logon service is enabled.  During Emacs
 2539 startup, this service issues many DNS requests looking up for the
 2540 Windows Domain Controller.  When Emacs accesses files on networked
 2541 drives, it automatically logs on the user into those drives, which
 2542 again causes delays when Net Logon is running.
 2544 The solution seems to be to disable Net Logon with this command typed
 2545 at the Windows shell prompt:
 2547   net stop netlogon
 2549 To start the service again, type "net start netlogon".  (You can also
 2550 stop and start the service from the Computer Management application,
 2551 accessible by right-clicking "My Computer" or "Computer", selecting
 2552 "Manage", then clicking on "Services".)
 2554 ** Emacs crashes when exiting the Emacs session
 2556 This was reported to happen when some optional DLLs, such as those
 2557 used for displaying images or the GnuTLS library or zlib compression
 2558 library, which are loaded on-demand, have a runtime dependency on the
 2559 libgcc DLL, libgcc_s_dw2-1.dll.  The reason seems to be a bug in
 2560 libgcc which rears its ugly head whenever the libgcc DLL is loaded
 2561 after Emacs has started.
 2563 One solution for this problem is to find an alternative build of the
 2564 same optional library that does not depend on the libgcc DLL.
 2566 Another possibility is to rebuild Emacs with the -shared-libgcc
 2567 switch, which will force Emacs to load libgcc_s_dw2-1.dll on startup,
 2568 ahead of any optional DLLs loaded on-demand later in the session.
 2570 ** File selection dialog opens in incorrect directories
 2572 Invoking the file selection dialog on Windows 7 or later shows a
 2573 directory that is different from what was passed to 'read-file-name'
 2574 or 'x-file-dialog' via their arguments.
 2576 This is due to a deliberate change in behavior of the file selection
 2577 dialogs introduced in Windows 7.  It is explicitly described in the
 2578 MSDN documentation of the GetOpenFileName API used by Emacs to pop up
 2579 the file selection dialog.  For the details, see
 2581   https://msdn.microsoft.com/en-us/library/windows/desktop/ms646839%28v=vs.85%29.aspx
 2583 The dialog shows the last directory in which the user selected a file
 2584 in a previous invocation of the dialog with the same initial
 2585 directory.
 2587 You can reset this "memory" of that directory by invoking the file
 2588 selection dialog with a different initial directory.
 2590 ** PATH can contain unexpanded environment variables
 2592 Old releases of TCC (version 9) and 4NT (up to version 8) do not correctly
 2593 expand App Paths entries of type REG_EXPAND_SZ.  When Emacs is run from TCC
 2594 and such an entry exists for emacs.exe, exec-path will contain the
 2595 unexpanded entry.  This has been fixed in TCC 10.  For more information,
 2596 see bug#2062.
 2598 ** Setting w32-pass-rwindow-to-system and w32-pass-lwindow-to-system to nil
 2599 does not prevent the Start menu from popping up when the left or right
 2600 "Windows" key is pressed.
 2602 This was reported to happen when XKeymacs is installed.  At least with
 2603 XKeymacs Version 3.47, deactivating XKeymacs when Emacs is active is
 2604 not enough to avoid its messing with the keyboard input.  Exiting
 2605 XKeymacs completely is reported to solve the problem.
 2607 ** Pasting from Windows clipboard into Emacs doesn't work.
 2609 This was reported to be the result of an anti-virus software blocking
 2610 the clipboard-related operations when a Web browser is open, for
 2611 security reasons.  The solution is to close the Web browser while
 2612 working in Emacs, or to add emacs.exe to the list of applications that
 2613 are allowed to use the clipboard when the Web browser is open.
 2615 ** "Pinning" Emacs to the taskbar doesn't work on Windows 10
 2617 "Doesn't work" here means that if you invoke Emacs by clicking on the
 2618 pinned icon, a separate button appears on the taskbar, instead of the
 2619 expected effect of the icon you clicked on being converted to that
 2620 button.
 2622 This is due to a bug in early versions of Windows 10, reportedly fixed
 2623 in build 1511 of Windows 10 (a.k.a. "Windows 10 SP1").  If you cannot
 2624 upgrade, read the work-around described below.
 2626 First, be sure to edit the Properties of the pinned icon to invoke
 2627 runemacs.exe, not emacs.exe.  (The latter will cause an extra cmd
 2628 window to appear when you invoke Emacs from the pinned icon.)
 2630 But the real cause of the problem is the fact that the pinned icon
 2631 (which is really a shortcut in a special directory) lacks a unique
 2632 application-defined Application User Model ID (AppUserModelID) that
 2633 identifies the current process to the taskbar.  This identifier allows
 2634 an application to group its associated processes and windows under a
 2635 single taskbar button.  Emacs on Windows specifies a unique
 2636 AppUserModelID when it starts, but Windows 10, unlike previous
 2637 versions of MS-Windows, does not propagate that ID to the pinned icon.
 2639 To work around this, use some utility, such as 'win7appid', to set the
 2640 AppUserModelID of the pinned icon to the string "Gnu.Emacs".  The
 2641 shortcut files corresponding to icons you pinned are stored by Windows
 2642 in the following subdirectory of your user's directory (by default
 2643 C:\Users\<UserName>\):
 2645  AppData\Roaming\Microsoft\Internet Explorer\Quick Launch\User Pinned\TaskBar
 2647 Look for the file 'emacs.lnk' there.
 2649 ** Windows 95 and networking.
 2651 To support server sockets, Emacs loads ws2_32.dll.  If this file is
 2652 missing, all Emacs networking features are disabled.
 2654 Old versions of Windows 95 may not have the required DLL.  To use
 2655 Emacs's networking features on Windows 95, you must install the
 2656 "Windows Socket 2" update available from MicroSoft's support Web.
 2658 ** Emacs exits with "X protocol error" when run with an X server for MS-Windows.
 2660 A certain X server for Windows had a bug which caused this.
 2661 Supposedly the newer 32-bit version of this server doesn't have the
 2662 problem.
 2664 ** Emacs crashes when opening a file with a UNC path and rails-mode is loaded.
 2666 Loading rails-mode seems to interfere with UNC path handling.  This has been
 2667 reported as a bug against both Emacs and rails-mode, so look for an updated
 2668 rails-mode that avoids this crash, or avoid using UNC paths if using
 2669 rails-mode.
 2671 ** M-x term does not work on MS-Windows.
 2673 TTY emulation on Windows is undocumented, and programs such as stty
 2674 which are used on POSIX platforms to control tty emulation do not
 2675 exist for native windows terminals.
 2677 ** Using create-fontset-from-ascii-font or the --font startup parameter
 2678 with a Chinese, Japanese or Korean font leads to display problems.
 2679 Use a Latin-only font as your default font.  If you want control over
 2680 which font is used to display Chinese, Japanese or Korean character,
 2681 use create-fontset-from-fontset-spec to define a fontset.
 2683 ** Frames are not refreshed while dialogs or menus are displayed
 2685 This means no redisplay while the File or Font dialog or a pop-up menu
 2686 is displayed.  This also means tooltips with help text for pop-up
 2687 menus are not displayed at all (except in a TTY session, where the help
 2688 text is shown in the echo area).  This is because message handling
 2689 under Windows is synchronous, so we cannot handle repaint (or any
 2690 other) messages while waiting for a system function, which popped up
 2691 the menu/dialog, to return the result of the dialog or pop-up menu
 2692 interaction.
 2694 ** Help text in tooltips does not work on old Windows versions
 2696 Windows 95 and Windows NT up to version 4.0 do not support help text
 2697 for menus.  Help text is only available in later versions of Windows.
 2699 ** Display problems with ClearType method of smoothing
 2701 When "ClearType" method is selected as the "method to smooth edges of
 2702 screen fonts" (in Display Properties, Appearance tab, under
 2703 "Effects"), there are various problems related to display of
 2704 characters:  Bold fonts can be hard to read, small portions of some
 2705 characters could appear chopped, etc.  This happens because, under
 2706 ClearType, characters are drawn outside their advertised bounding box.
 2707 Emacs 21 disabled the use of ClearType, whereas Emacs 22 allows it and
 2708 has some code to enlarge the width of the bounding box.  Apparently,
 2709 this display feature needs more changes to get it 100% right.  A
 2710 workaround is to disable ClearType.
 2712 ** Cursor is displayed as a thin vertical bar and cannot be changed
 2714 This is known to happen if the Windows Magnifier is turned on before
 2715 the Emacs session starts.  The Magnifier affects the cursor shape and
 2716 prevents any changes to it by setting the 'cursor-type' variable or
 2717 frame parameter.
 2719 The solution is to log off and on again, and then start the Emacs
 2720 session only after turning the Magnifier off.
 2722 To turn the Windows Magnifier off, click "Start->All Programs", or
 2723 "All Apps", depending on your Windows version, then select
 2724 "Accessibility" and click "Magnifier".  In the Magnifier Settings
 2725 dialog that opens, click "Exit".
 2727 ** Problems with mouse-tracking and focus management
 2729 There are problems with display if mouse-tracking is enabled and the
 2730 mouse is moved off a frame, over another frame then back over the first
 2731 frame.  A workaround is to click the left mouse button inside the frame
 2732 after moving back into it.
 2734 Some minor flickering still persists during mouse-tracking, although
 2735 not as severely as in 21.1.
 2737 An inactive cursor remains in an active window after the Windows
 2738 Manager driven switch of the focus, until a key is pressed.
 2740 ** Problems with Windows input methods
 2742 Some of the Windows input methods cause the keyboard to send
 2743 characters encoded in the appropriate coding system (e.g., ISO 8859-1
 2744 for Latin-1 characters, ISO 8859-8 for Hebrew characters, etc.).  To
 2745 make these input methods work with Emacs on Windows 9X, you might need
 2746 to set the keyboard coding system to the appropriate value after you
 2747 activate the Windows input method.  For example, if you activate the
 2748 Hebrew input method, type this:
 2750    C-x RET k hebrew-iso-8bit RET
 2752 In addition, to use these Windows input methods, you might need to set
 2753 your "Language for non-Unicode programs" (on Windows XP, this is on
 2754 the Advanced tab of Regional Settings) to the language of the input
 2755 method.
 2757 To bind keys that produce non-ASCII characters with modifiers, you
 2758 must specify raw byte codes.  For instance, if you want to bind
 2759 META-a-grave to a command, you need to specify this in your '~/.emacs':
 2761   (global-set-key [?\M-\340] ...)
 2763 The above example is for the Latin-1 environment where the byte code
 2764 of the encoded a-grave is 340 octal.  For other environments, use the
 2765 encoding appropriate to that environment.
 2767 ** Problems with the %b format specifier for format-time-string
 2769 The %b specifier for format-time-string does not produce abbreviated
 2770 month names with consistent widths for some locales on some versions
 2771 of Windows.  This is caused by a deficiency in the underlying system
 2772 library function.
 2774 ** Non-US time zones.
 2776 Many non-US time zones are implemented incorrectly.  This is due to
 2777 over-simplistic handling of daylight savings switchovers by the
 2778 Windows libraries.
 2780 ** Files larger than 4GB report wrong size in a 32-bit Windows build
 2782 Files larger than 4GB cause overflow in the size (represented as a
 2783 32-bit integer) reported by 'file-attributes'.  This affects Dired as
 2784 well, since the Windows port uses a Lisp emulation of 'ls', which relies
 2785 on 'file-attributes'.
 2787 ** Playing sound doesn't support the :data method
 2789 Sound playing is not supported with the ':data DATA' key-value pair.
 2790 You _must_ use the ':file FILE' method.
 2792 ** Typing Alt-Shift has strange effects on MS-Windows.
 2794 This combination of keys is a command to change keyboard layout.  If
 2795 you proceed to type another non-modifier key before you let go of Alt
 2796 and Shift, the Alt and Shift act as modifiers in the usual way.  A
 2797 more permanent work around is to change it to another key combination,
 2798 or disable it in the "Regional and Language Options" applet of the
 2799 Control Panel.  (The exact sequence of mouse clicks in the "Regional
 2800 and Language Options" applet needed to find the key combination that
 2801 changes the keyboard layout depends on your Windows version; for XP,
 2802 in the Languages tab, click "Details" and then "Key Settings".)
 2804 ** Interrupting Cygwin port of Bash from Emacs doesn't work.
 2806 Cygwin 1.x builds of the ported Bash cannot be interrupted from the
 2807 MS-Windows version of Emacs.  This is due to some change in the Bash
 2808 port or in the Cygwin library which apparently make Bash ignore the
 2809 keyboard interrupt event sent by Emacs to Bash.  (Older Cygwin ports
 2810 of Bash, up to b20.1, did receive SIGINT from Emacs.)
 2812 ** Accessing remote files with ange-ftp hangs the MS-Windows version of Emacs.
 2814 If the FTP client is the Cygwin port of GNU 'ftp', this appears to be
 2815 due to some bug in the Cygwin DLL or some incompatibility between it
 2816 and the implementation of asynchronous subprocesses in the Windows
 2817 port of Emacs.  Specifically, some parts of the FTP server responses
 2818 are not flushed out, apparently due to buffering issues, which
 2819 confuses ange-ftp.
 2821 The solution is to downgrade to an older version of the Cygwin DLL
 2822 (version 1.3.2 was reported to solve the problem), or use the stock
 2823 Windows FTP client, usually found in the 'C:\WINDOWS' or 'C:\WINNT'
 2824 directory.  To force ange-ftp use the stock Windows client, set the
 2825 variable 'ange-ftp-ftp-program-name' to the absolute file name of the
 2826 client's executable.  For example:
 2828  (setq ange-ftp-ftp-program-name "c:/windows/ftp.exe")
 2830 If you want to stick with the Cygwin FTP client, you can work around
 2831 this problem by putting this in your '.emacs' file:
 2833  (setq ange-ftp-ftp-program-args '("-i" "-n" "-g" "-v" "--prompt" "")
 2835 ** lpr commands don't work on MS-Windows with some cheap printers.
 2837 This problem may also strike other platforms, but the solution is
 2838 likely to be a global one, and not Emacs specific.
 2840 Many cheap inkjet, and even some cheap laser printers, do not
 2841 print plain text anymore, they will only print through graphical
 2842 printer drivers.  A workaround on MS-Windows is to use Windows's basic
 2843 built in editor to print (this is possibly the only useful purpose it
 2844 has):
 2846 (setq printer-name "")         ; notepad takes the default
 2847 (setq lpr-command "notepad")   ; notepad
 2848 (setq lpr-switches nil)        ; not needed
 2849 (setq lpr-printer-switch "/P") ; run notepad as batch printer
 2851 ** Antivirus software interacts badly with the MS-Windows version of Emacs.
 2853 The usual manifestation of these problems is that subprocesses don't
 2854 work or even wedge the entire system.  In particular, "M-x shell RET"
 2855 was reported to fail to work.  But other commands also sometimes don't
 2856 work when an antivirus package is installed.
 2858 The solution is to switch the antivirus software to a less aggressive
 2859 mode (e.g., disable the "auto-protect" feature), or even uninstall
 2860 or disable it entirely.
 2862 ** Pressing the mouse button on MS-Windows does not give a mouse-2 event.
 2864 This is usually a problem with the mouse driver.  Because most Windows
 2865 programs do not do anything useful with the middle mouse button, many
 2866 mouse drivers allow you to define the wheel press to do something
 2867 different.  Some drivers do not even have the option to generate a
 2868 middle button press.  In such cases, setting the wheel press to
 2869 "scroll" sometimes works if you press the button twice.  Trying a
 2870 generic mouse driver might help.
 2872 One particular situation where this happens is when you have
 2873 "Microsoft Intellipoint" installed, which runs the program
 2874 ipoint.exe.  The fix is reportedly to uninstall this software.
 2876 ** Scrolling the mouse wheel on MS-Windows always scrolls the top window.
 2878 This is another common problem with mouse drivers.  Instead of
 2879 generating scroll events, some mouse drivers try to fake scroll bar
 2880 movement.  But they are not intelligent enough to handle multiple
 2881 scroll bars within a frame.  Trying a generic mouse driver might help.
 2883 ** Mail sent through Microsoft Exchange in some encodings appears to be
 2884 mangled and is not seen correctly in Rmail or Gnus.  We don't know
 2885 exactly what happens, but it isn't an Emacs problem in cases we've
 2886 seen.
 2888 ** On MS-Windows, you cannot use the right-hand ALT key and the left-hand
 2889 CTRL key together to type a Control-Meta character.
 2891 This is a consequence of a misfeature beyond Emacs's control.
 2893 Under Windows, the AltGr key on international keyboards generates key
 2894 events with the modifiers Right-Alt and Left-Ctrl.  Since Emacs cannot
 2895 distinguish AltGr from an explicit Right-Alt and Left-Ctrl
 2896 combination, whenever it sees Right-Alt and Left-Ctrl it assumes that
 2897 AltGr has been pressed.  The variable 'w32-recognize-altgr' can be set
 2898 to nil to tell Emacs that AltGr is really Ctrl and Alt.
 2900 ** Under some X-servers running on MS-Windows, Emacs's display is incorrect.
 2902 The symptoms are that Emacs does not completely erase blank areas of the
 2903 screen during scrolling or some other screen operations (e.g., selective
 2904 display or when killing a region).  M-x recenter will cause the screen
 2905 to be completely redisplayed and the "extra" characters will disappear.
 2907 This is known to occur under Exceed 6, and possibly earlier versions
 2908 as well; it is reportedly solved in version and later.  The
 2909 problem lies in the X-server settings.
 2911 There are reports that you can solve the problem with Exceed by
 2912 running 'Xconfig' from within NT, choosing "X selection", then
 2913 un-checking the boxes "auto-copy X selection" and "auto-paste to X
 2914 selection".
 2916 If this does not work, please inform bug-gnu-emacs@gnu.org.  Then
 2917 please call support for your X-server and see if you can get a fix.
 2918 If you do, please send it to bug-gnu-emacs@gnu.org so we can list it here.
 2921 * Runtime problems specific to Cygwin
 2923 ** Fork failures in a build with native compilation
 2925 To prevent fork failures, shared libraries on Cygwin need to be
 2926 rebased occasionally, for the reasons explained here:
 2928   https://cygwin.com/cygwin-ug-net/highlights.html#ov-hi-process-problems
 2930 This includes the .eln files produced by an Emacs built with native
 2931 compilation.
 2933 Rebasing is handled by Cygwin's autorebase postinstall script every
 2934 time you run the Cygwin setup program (which you should do with no
 2935 Cygwin processes running).  This script knows about the .eln files
 2936 installed in the standard places (e.g.,
 2937 /usr/lib/emacs/28.1/native-lisp), but it does not know about those in
 2938 your user cache (e.g., /home/<username>/.emacs.d/eln-cache).  In order
 2939 for these to be automatically rebased, you must create a file
 2941   /var/lib/rebase/userpath.d/<username>
 2943 with one line for each directory containing .eln files.  If you are
 2944 running an installed Emacs, it should suffice to list your cache
 2945 directory.  For example, if there is an Emacs user "kbrown", then
 2946 there should be a file
 2948   /var/lib/rebase/userpath.d/kbrown
 2950 containing the single line
 2952   /home/kbrown/.emacs.d/eln-cache
 2954 If you are running an Emacs that you have built but not installed,
 2955 then you will need an additional line giving the path to the
 2956 native-lisp subdirectory of your build directory.
 2958 If more than one user will be using Emacs on your system, there should
 2959 be a file like this for each user.
 2961 Rebasing is not currently done when new .eln files are created, so
 2962 fork failures are still possible between runs of Cygwin's setup
 2963 program.  If you ever see a fork failure whose error message refers to
 2964 a .eln file, you should be able to fix it temporarily by exiting emacs
 2965 and issuing the command
 2967    find ~/.emacs.d/eln-cache -name '*.eln' | rebase -O -T -
 2969 This is called an "ephemeral" rebase.  Again, if you are running an
 2970 Emacs that has not been installed, you need to add the native-lisp
 2971 subdirectory of your build directory to this command.  Alternatively,
 2972 stop all Cygwin processes and run Cygwin's setup program to let the
 2973 autorebase postinstall script run.
 2975 It is hoped that the measures above will make native compilation
 2976 usable on 64-bit Cygwin, with only an occasional minor annoyance.  In
 2977 the 32-bit case, however, the limited address space makes frequent
 2978 fork failures extremely likely.  It is therefore strongly recommended
 2979 that you not build Emacs with native compilation on 32-bit Cygwin.
 2980 Indeed, the configure script will not allow this unless you use the
 2981 --with-cygwin32-native-compilation option.
 2983 See bug#50666 (https://debbugs.gnu.org/cgi/bugreport.cgi?bug=50666)
 2984 for further discussion.
 2987 * Runtime problems specific to macOS
 2989 ** Error message when opening Emacs on macOS
 2991 When opening Emacs, you may see an error message saying something like
 2992 this:
 2994   "Emacs" can't be opened because Apple cannot check it for malicious
 2995   software. This software needs to be updated. Contact the developer
 2996   for more information.
 2998 The reason is that Apple incorrectly catalogs Emacs as potentially
 2999 malicious software and thus shows this error message.
 3001 To avoid this alert, open Finder, go to Applications, control-click
 3002 the Emacs app icon, and then choose Open.  This adds a security
 3003 exception for Emacs and from now on you should be able to open it by
 3004 double-clicking on its icon, like any other app.
 3006 ** macOS doesn't come with libxpm, so only XPM3 is supported.
 3008 Libxpm is available for macOS as part of the XQuartz project.
 3010 ** Synthetic fonts on macOS
 3012 Synthetic bold looks thinner if the background is darker than the
 3013 foreground and font smoothing is turned on.  In such cases, you can
 3014 turn off synthetic bold for particular fonts and use overstriking
 3015 instead by customizing the variable 'face-ignored-fonts'.  For
 3016 instance, if the problem is with the Monaco font, you could put
 3017 something like the following in your init file:
 3019 (push "\\`-[^-]*-monaco-bold-" face-ignored-fonts)
 3021 ** Native Compilation on macOS
 3023 Native complitation requires the libgccjit library to be installed and
 3024 its path available to Emacs.  Errors such as:
 3026     libgccjit.so: error: error invoking gcc driver
 3027     Error: Internal native compiler error failed to compile
 3029 indicate Emacs can't find the library in running time.  One can set
 3030 the "LIBRARY_PATH" environment variable in the early initialization
 3031 file; for example:
 3033 (setenv "LIBRARY_PATH"
 3034   (string-join
 3035     '("/usr/local/opt/gcc/lib/gcc/11"
 3036       "/usr/local/opt/libgccjit/lib/gcc/11"
 3037       "/usr/local/opt/gcc/lib/gcc/11/gcc/x86_64-apple-darwin20/11.2.0") ":"))
 3039 * Build-time problems
 3041 ** Configuration
 3043 *** 'configure' warns "accepted by the compiler, rejected by the preprocessor".
 3045 This indicates a mismatch between the C compiler and preprocessor that
 3046 configure is using.  For example, on Solaris 10 trying to use
 3047 CC=/opt/developerstudio12.6/bin/cc (the Oracle Developer Studio
 3048 compiler) together with CPP=/usr/lib/cpp can result in errors of
 3049 this form.
 3051 The solution is to tell configure to use the correct C preprocessor
 3052 for your C compiler (CPP="/opt/developerstudio12.6/bin/cc -E" in the
 3053 above example).
 3055 ** Compilation
 3057 *** Link-time optimization with clang doesn't work on Fedora 20.
 3059 As of May 2014, Fedora 20 has broken LLVMgold.so plugin support in clang
 3060 (tested with clang-3.4-6.fc20) - 'clang --print-file-name=LLVMgold.so'
 3061 prints 'LLVMgold.so' instead of full path to plugin shared library, and
 3062 'clang -flto' is unable to find the plugin with the following error:
 3064 /bin/ld: error: /usr/bin/../lib/LLVMgold.so: could not load plugin library:
 3065 /usr/bin/../lib/LLVMgold.so: cannot open shared object file: No such file
 3066 or directory
 3068 The only way to avoid this is to build your own clang from source code
 3069 repositories, as described at http://clang.llvm.org/get_started.html.
 3071 *** Building Emacs over NFS fails with "Text file busy".
 3073 This was reported to happen when building Emacs on a GNU/Linux system
 3074 (Red Hat Linux 6.2) using a build directory automounted from Solaris
 3075 (SunOS 5.6) file server, but it might not be limited to that
 3076 configuration alone.  Presumably, the NFS server doesn't commit the
 3077 files' data to disk quickly enough, and the Emacs executable file is
 3078 left "busy" for several seconds after Emacs has finished dumping
 3079 itself.  This causes the subsequent commands which invoke the dumped
 3080 Emacs executable to fail with the above message.
 3082 In some of these cases, a time skew between the NFS server and the
 3083 machine where Emacs is built is detected and reported by GNU Make
 3084 (it says that some of the files have modification time in the future).
 3085 This might be a symptom of NFS-related problems.
 3087 If the NFS server runs on Solaris, apply the Solaris patch 105379-05
 3088 (Sunos 5.6: /kernel/misc/nfssrv patch).  If that doesn't work, or if
 3089 you have a different version of the OS or the NFS server, you can
 3090 force the NFS server to use 1KB blocks, which was reported to fix the
 3091 problem albeit at a price of slowing down file I/O.  You can force 1KB
 3092 blocks by specifying the "-o  rsize=1024,wsize=1024" options to the
 3093 'mount' command, or by adding ",rsize=1024,wsize=1024" to the mount
 3094 options in the appropriate system configuration file, such as
 3095 '/etc/auto.home'.
 3097 Alternatively, when Make fails due to this problem, you could wait for
 3098 a few seconds and then invoke Make again.  In one particular case,
 3099 waiting for 10 or more seconds between the two Make invocations seemed
 3100 to work around the problem.
 3102 Similar problems can happen if your machine NFS-mounts a directory
 3103 onto itself.  Suppose the Emacs sources live in '/usr/local/src' and
 3104 you are working on the host called 'marvin'.  Then an entry in the
 3105 '/etc/fstab' file like the following is asking for trouble:
 3107     marvin:/usr/local/src /usr/local/src ...options.omitted...
 3109 The solution is to remove this line from '/etc/fstab'.
 3111 *** Building a 32-bit executable on a 64-bit GNU/Linux architecture.
 3113 First ensure that the necessary 32-bit system libraries and include
 3114 files are installed.  Then use:
 3116   env CC="gcc -m32" ./configure --build=i386-linux-gnu --x-libraries=/usr/lib
 3118 (using the location of the 32-bit X libraries on your system).
 3120 *** Building on FreeBSD 11 fails at link time due to unresolved symbol
 3122 The symbol is sendmmsg@FBSD_1.4.  This is due to a faulty libgio
 3123 library on these systems.  The solution is to reconfigure Emacs while
 3124 disabling all the features that require libgio: rsvg, dbus, gconf, and
 3125 imagemagick.
 3127 *** Building Emacs 23.3 and later will fail under Cygwin 1.5.19
 3129 This is a consequence of a change to src/dired.c on 2010-07-27.  The
 3130 issue is that Cygwin 1.5.19 did not have d_ino in 'struct dirent'.
 3131 See
 3133   https://lists.gnu.org/r/emacs-devel/2010-07/msg01266.html
 3135 *** Building the native MS-Windows port fails due to unresolved externals
 3137 The linker error messages look like this:
 3139  oo-spd/i386/ctags.o:ctags.c:(.text+0x156e): undefined reference to `_imp__re_set_syntax'
 3140  collect2: ld returned 1 exit status
 3142 This happens because GCC finds an incompatible regex.h header
 3143 somewhere on the include path, before the version of regex.h supplied
 3144 with Emacs.  One such incompatible version of regex.h is part of the
 3145 GnuWin32 Regex package.
 3147 The solution is to remove the incompatible regex.h from the include
 3148 path, when compiling Emacs.  Alternatively, re-run the configure.bat
 3149 script with the "-isystem C:/GnuWin32/include" switch (adapt for your
 3150 system's place where you keep the GnuWin32 include files) -- this will
 3151 cause the compiler to search headers in the directories specified by
 3152 the Emacs Makefile _before_ it looks in the GnuWin32 include
 3153 directories.
 3155 *** Building the native MS-Windows port with Cygwin GCC can fail.
 3157 Emacs may not build using some Cygwin builds of GCC, such as Cygwin
 3158 version 1.1.8, using the default configure settings.  It appears to be
 3159 necessary to specify the -mwin32 flag when compiling, and define
 3160 __MSVCRT__, like so:
 3162   configure --with-gcc --cflags -mwin32 --cflags -D__MSVCRT__
 3164 *** Building the MS-Windows port fails with a CreateProcess failure.
 3166 Some versions of mingw32 make on some versions of Windows do not seem
 3167 to detect the shell correctly.  Try "make SHELL=cmd.exe", or if that
 3168 fails, try running make from Cygwin bash instead.
 3170 *** Building 'ctags' for MS-Windows with the MinGW port of GCC fails.
 3172 This might happen due to a bug in the MinGW header assert.h, which
 3173 defines the 'assert' macro with a trailing semi-colon.  The following
 3174 patch to assert.h should solve this:
 3176  *** include/assert.h.orig	Sun Nov  7 02:41:36 1999
 3177  --- include/assert.h	Mon Jan 29 11:49:10 2001
 3178  ***************
 3179  *** 41,47 ****
 3180    /*
 3181     * If not debugging, assert does nothing.
 3182     */
 3183  ! #define assert(x)	((void)0);
 3185    #else /* debugging enabled */
 3187  --- 41,47 ----
 3188    /*
 3189     * If not debugging, assert does nothing.
 3190     */
 3191  ! #define assert(x)	((void)0)
 3193    #else /* debugging enabled */
 3196 *** Building the MS-Windows port with Visual Studio 2005 fails.
 3198 Microsoft no longer ships the single threaded version of the C library
 3199 with their compiler, and the multithreaded static library is missing
 3200 some functions that Microsoft have deemed non-threadsafe.  The
 3201 dynamically linked C library has all the functions, but there is a
 3202 conflict between the versions of malloc in the DLL and in Emacs, which
 3203 is not resolvable due to the way Windows does dynamic linking.
 3205 We recommend the use of the MinGW port of GCC for compiling Emacs, as
 3206 not only does it not suffer these problems, but it is also Free
 3207 software like Emacs.
 3209 *** Building the MS-Windows port with Visual Studio fails compiling emacs.rc
 3211 If the build fails with the following message then the problem
 3212 described here most likely applies:
 3214 ../nt/emacs.rc(1) : error RC2176 : old DIB in icons\emacs.ico; pass it
 3215 through SDKPAINT
 3217 The Emacs icon contains a high resolution PNG icon for Vista, which is
 3218 not recognized by older versions of the resource compiler.  There are
 3219 several workarounds for this problem:
 3220 	1. Use Free MinGW tools to compile, which do not have this problem.
 3221 	2. Install the latest Windows SDK.
 3222 	3. Replace emacs.ico with an older or edited icon.
 3224 *** Building the MS-Windows port complains about unknown escape sequences.
 3226 Errors and warnings can look like this:
 3228  w32.c:1959:27: error: \x used with no following hex digits
 3229  w32.c:1959:27: warning: unknown escape sequence '\i'
 3231 This happens when paths using backslashes are passed to the compiler or
 3232 linker (via -I and possibly other compiler flags); when these paths are
 3233 included in source code, the backslashes are interpreted as escape sequences.
 3234 See https://lists.gnu.org/r/emacs-devel/2010-07/msg00995.html
 3236 The fix is to use forward slashes in all paths passed to the compiler.
 3238 ** Linking
 3240 *** Building Emacs with a system compiler fails to link because of an
 3241 undefined symbol such as __eprintf which does not appear in Emacs.
 3243 This can happen if some of the libraries linked into Emacs were built
 3244 with GCC, but Emacs itself is being linked with a compiler other than
 3245 GCC.  Object files compiled with GCC might need some helper functions
 3246 from libgcc.a, the library which comes with GCC, but the system
 3247 compiler does not instruct the linker to search libgcc.a during the
 3248 link stage.
 3250 A solution is to link with GCC, like this:
 3252         make CC=gcc
 3254 Since the .o object files already exist, this will not recompile Emacs
 3255 with GCC, but just restart by trying again to link temacs.
 3257 *** Sun with acc: Link failure when using acc on a Sun.
 3259 To use acc, you need additional options just before the libraries, such as
 3261    /usr/lang/SC2.0.1/values-Xt.o -L/usr/lang/SC2.0.1/cg87 -L/usr/lang/SC2.0.1
 3263 and you need to add -lansi just before -lc.
 3265 The precise file names depend on the compiler version, so we
 3266 cannot easily arrange to supply them.
 3268 *** 'tparam' reported as a multiply-defined symbol when linking with ncurses.
 3270 This problem results from an incompatible change in ncurses, in
 3271 version 1.9.9e approximately.  This version is unable to provide a
 3272 definition of tparm without also defining tparam.  This is also
 3273 incompatible with Terminfo; as a result, the Emacs Terminfo support
 3274 does not work with this version of ncurses.
 3276 The fix is to install a newer version of ncurses, such as version 4.2.
 3278 ** Bootstrapping
 3280 Bootstrapping (compiling the .el files) is normally only necessary
 3281 with development builds, since the .elc files are pre-compiled in releases.
 3283 *** "No rule to make target" with Ubuntu 8.04 make 3.81-3build1
 3285 Compiling the lisp files fails at random places, complaining:
 3286 "No rule to make target '/path/to/some/lisp.elc'".
 3287 The causes of this problem are not understood.  Using GNU make 3.81 compiled
 3288 from source, rather than the Ubuntu version, worked.
 3289 See <URL:https://debbugs.gnu.org/327>, <URL:https://debbugs.gnu.org/821>.
 3291 ** Dumping
 3293 *** Segfault during 'make'
 3295 If Emacs segfaults when 'make' executes one of these commands:
 3297   LC_ALL=C ./temacs -batch -l loadup bootstrap
 3298   LC_ALL=C ./temacs -batch -l loadup dump
 3300 the problem may be due to inadequate workarounds for address space
 3301 layout randomization (ASLR), an operating system feature that
 3302 randomizes the virtual address space of a process.  ASLR is commonly
 3303 enabled in Linux and NetBSD kernels, and is intended to deter exploits
 3304 of pointer-related bugs in applications.  If ASLR is enabled, the
 3305 command:
 3307    cat /proc/sys/kernel/randomize_va_space  # GNU/Linux
 3308    sysctl security.pax.aslr.global          # NetBSD
 3310 outputs a nonzero value.
 3312 These segfaults should not occur on most modern systems, because the
 3313 Emacs build procedure uses the command 'setfattr' or 'paxctl' to mark
 3314 the Emacs executable as requiring non-randomized address space, and
 3315 Emacs uses the 'personality' system call to disable address space
 3316 randomization when dumping.  However, older kernels may not support
 3317 'setfattr', 'paxctl', or 'personality', and newer Linux kernels have a
 3318 secure computing mode (seccomp) that can be configured to disable the
 3319 'personality' call.
 3321 It may be possible to work around the 'personality' problem in a newer
 3322 Linux kernel by configuring seccomp to allow the 'personality' call.
 3323 For example, if you are building Emacs under Docker, you can run the
 3324 Docker container with a security profile that allows 'personality' by
 3325 using Docker's --security-opt option with an appropriate profile; see
 3326 <https://docs.docker.com/engine/security/seccomp/>.
 3328 To work around the ASLR problem in either an older or a newer kernel,
 3329 you can temporarily disable the feature while building Emacs.  On
 3330 GNU/Linux you can do so using the following command (as root).
 3332     echo 0 > /proc/sys/kernel/randomize_va_space
 3334 You can re-enable the feature when you are done, by echoing the
 3335 original value back to the file.  NetBSD uses a different command,
 3336 e.g., 'sysctl -w security.pax.aslr.global=0'.
 3338 Alternatively, you can try using the 'setarch' command when building
 3339 temacs like this, where -R disables address space randomization:
 3341     setarch $(uname -m) -R make
 3343 ASLR is not the only problem that can break Emacs dumping.  Another
 3344 issue is that in Red Hat Linux kernels, Exec-shield is enabled by
 3345 default, and this creates a different memory layout.  Emacs should
 3346 handle this at build time, but if this fails the following
 3347 instructions may be useful.  Exec-shield is enabled on your system if
 3349     cat /proc/sys/kernel/exec-shield
 3351 prints a nonzero value.  You can temporarily disable it as follows:
 3353     echo 0 > /proc/sys/kernel/exec-shield
 3355 As with randomize_va_space, you can re-enable Exec-shield when you are
 3356 done, by echoing the original value back to the file.
 3358 *** temacs prints "Pure Lisp storage exhausted".
 3360 This means that the Lisp code loaded from the .elc and .el files during
 3361 'temacs --batch --load loadup dump' took up more space than was allocated.
 3363 This could be caused by
 3364  1) adding code to the preloaded Lisp files
 3365  2) adding more preloaded files in loadup.el
 3366  3) having a site-init.el or site-load.el which loads files.
 3367    Note that ANY site-init.el or site-load.el is nonstandard;
 3368    if you have received Emacs from some other site and it contains a
 3369    site-init.el or site-load.el file, consider deleting that file.
 3370  4) getting the wrong .el or .elc files
 3371    (not from the directory you expected).
 3372  5) deleting some .elc files that are supposed to exist.
 3373    This would cause the source files (.el files) to be
 3374    loaded instead.  They take up more room, so you lose.
 3375  6) a bug in the Emacs distribution which underestimates the space required.
 3377 If the need for more space is legitimate, change the definition
 3378 of PURESIZE in puresize.h.
 3380 But in some of the cases listed above, this problem is a consequence
 3381 of something else that is wrong.  Be sure to check and fix the real problem.
 3383 *** OpenBSD 4.0 macppc: Segfault during dumping.
 3385 The build aborts with signal 11 when the command './temacs --batch
 3386 --load loadup bootstrap' tries to load files.el.  A workaround seems
 3387 to be to reduce the level of compiler optimization used during the
 3388 build (from -O2 to -O1).  It is possible this is an OpenBSD
 3389 GCC problem specific to the macppc architecture, possibly only
 3390 occurring with older versions of GCC (e.g. 3.3.5).
 3392 *** openSUSE 10.3: Segfault in bcopy during dumping.
 3394 This is due to a bug in the bcopy implementation in openSUSE 10.3.
 3395 It is/will be fixed in an openSUSE update.
 3397 ** First execution
 3399 *** Emacs binary is not in executable format, and cannot be run.
 3401 This was reported to happen when Emacs is built in a directory mounted
 3402 via NFS, for some combinations of NFS client and NFS server.
 3403 Usually, the file 'emacs' produced in these cases is full of
 3404 binary null characters, and the 'file' utility says:
 3406     emacs: ASCII text, with no line terminators
 3408 We don't know what exactly causes this failure.  A work-around is to
 3409 build Emacs in a directory on a local disk.
 3411 *** The dumped Emacs crashes when run, trying to write pure data.
 3413 On a system where getpagesize is not a system call, it is defined
 3414 as a macro.  If the definition (in both unex*.c and malloc.c) is wrong,
 3415 it can cause problems like this.  You might be able to find the correct
 3416 value in the man page for a.out(5).
 3418 * 'make check' failures
 3420 ** emacs-module-tests fail on Ubuntu 16.04
 3422 This is due to a bug in GCC that was fixed in 2015; see
 3423 <https://lists.gnu.org/r/emacs-devel/2018-09/msg00548.html>.
 3424 You can work around the problem by using a later version of GCC or of
 3425 Ubuntu, or by configuring without modules.
 3427 * Problems on legacy systems
 3429 This section covers bugs reported on very old hardware or software.
 3430 If you are using hardware and an operating system shipped after 2000,
 3431 it is unlikely you will see any of these.
 3433 ** Solaris
 3435 *** Problem with remote X server on Suns.
 3437 On a Sun, running Emacs on one machine with the X server on another
 3438 may not work if you have used the unshared system libraries.  This
 3439 is because the unshared libraries fail to use YP for host name lookup.
 3440 As a result, the host name you specify may not be recognized.
 3442 *** Solaris 2.6: Emacs crashes with SIGBUS or SIGSEGV on Solaris after you delete a frame.
 3444 We suspect that this is a bug in the X libraries provided by
 3445 Sun.  There is a report that one of these patches fixes the bug and
 3446 makes the problem stop:
 3448 105216-01 105393-01 105518-01 105621-01 105665-01 105615-02 105216-02
 3449 105667-01 105401-08 105615-03 105621-02 105686-02 105736-01 105755-03
 3450 106033-01 105379-01 105786-01 105181-04 105379-03 105786-04 105845-01
 3451 105284-05 105669-02 105837-01 105837-02 105558-01 106125-02 105407-01
 3453 Another person using a newer system (kernel patch level Generic_105181-06)
 3454 suspects that the bug was fixed by one of these more recent patches:
 3456 106040-07  SunOS 5.6: X Input & Output Method patch
 3457 106222-01  OpenWindows 3.6: filemgr (ff.core) fixes
 3458 105284-12  Motif 1.2.7: sparc Runtime library patch
 3460 *** Solaris 7 or 8: Emacs reports a BadAtom error (from X)
 3462 This happens when Emacs was built on some other version of Solaris.
 3463 Rebuild it on Solaris 8.
 3465 *** When using M-x dbx with the SparcWorks debugger, the 'up' and 'down'
 3466 commands do not move the arrow in Emacs.
 3468 You can fix this by adding the following line to '~/.dbxinit':
 3470  dbxenv output_short_file_name off
 3472 *** On Solaris, CTRL-t is ignored by Emacs when you use
 3473 the fr.ISO-8859-15 locale (and maybe other related locales).
 3475 You can fix this by editing the file:
 3477         /usr/openwin/lib/locale/iso8859-15/Compose
 3479 Near the bottom there is a line that reads:
 3481         Ctrl<t> <quotedbl> <Y>                  : "\276"        threequarters
 3483 while it should read:
 3485         Ctrl<T> <quotedbl> <Y>                  : "\276"        threequarters
 3487 Note the lower case <t>.  Changing this line should make C-t work.
 3489 *** On Solaris, Emacs fails to set menu-bar-update-hook on startup, with error
 3490 "Error in menu-bar-update-hook: (error Point before start of properties)".
 3491 This seems to be a GCC optimization bug that occurs for GCC 4.1.2 (-g
 3492 and -g -O2) and GCC 4.2.3 (-g -O and -g -O2).  You can fix this by
 3493 compiling with GCC 4.2.3 or CC 5.7, with no optimizations.
 3495 *** Other legacy Solaris problems
 3497 **** Strange results from format %d in a few cases, on a Sun.
 3499 Sun compiler version SC3.0 has been found to miscompile part of editfns.c.
 3500 The workaround is to compile with some other compiler such as GCC.
 3502 **** On Solaris, Emacs dumps core if lisp-complete-symbol is called.
 3504 If you compile Emacs with the -fast or -xO4 option with version 3.0.2
 3505 of the Sun C compiler, Emacs dumps core when lisp-complete-symbol is
 3506 called.  The problem does not happen if you compile with GCC.
 3508 **** On Solaris, Emacs crashes if you use (display-time).
 3510 This can happen if you configure Emacs without specifying the precise
 3511 version of Solaris that you are using.
 3513 **** Solaris 2.x: GCC complains "64 bit integer types not supported".
 3515 This suggests that GCC is not installed correctly.  Most likely you
 3516 are using GCC (or earlier) on Solaris 2.6 (or later); this
 3517 does not work without patching.  To run GCC on Solaris 2.6 or
 3518 later, you must patch fixinc.svr4 and reinstall GCC from scratch as
 3519 described in the Solaris FAQ
 3520 <http://www.wins.uva.nl/pub/solaris/solaris2.html>.  A better fix is
 3521 to upgrade to GCC 2.8.1 or later.
 3523 **** Solaris 2.7: Building Emacs with WorkShop Compilers 5.0 98/12/15
 3524 C 5.0 failed, apparently with non-default CFLAGS, most probably due to
 3525 compiler bugs.  Using Sun Solaris 2.7 Sun WorkShop 6 update 1 C
 3526 release was reported to work without problems.  It worked OK on
 3527 another system with Solaris 8 using apparently the same 5.0 compiler
 3528 and the default CFLAGS.
 3530 **** Solaris 2.6 and 7: the Compose key does not work.
 3532 This is a bug in Motif in Solaris.  Supposedly it has been fixed for
 3533 the next major release of Solaris.  However, if someone with Sun
 3534 support complains to Sun about the bug, they may release a patch.
 3535 If you do this, mention Sun bug #4188711.
 3537 One workaround is to use a locale that allows non-ASCII characters.
 3538 For example, before invoking emacs, set the LC_ALL environment
 3539 variable to "en_US" (American English).  The directory /usr/lib/locale
 3540 lists the supported locales; any locale other than "C" or "POSIX"
 3541 should do.
 3543 pen@lysator.liu.se says (Feb 1998) that the Compose key does work
 3544 if you link with the MIT X11 libraries instead of the Solaris X11 libraries.
 3546 ** MS-Windows 95, 98, ME, and NT
 3548 *** MS-Windows NT/95: Problems running Perl under Emacs
 3550 'perl -de 0' just hangs when executed in an Emacs subshell.
 3551 The fault lies with Perl (indirectly with Windows NT/95).
 3553 The problem is that the Perl debugger explicitly opens a connection to
 3554 "CON", which is the DOS/NT equivalent of "/dev/tty", for interacting
 3555 with the user.
 3557 On Unix, this is okay, because Emacs (or the shell?) creates a
 3558 pseudo-tty so that /dev/tty is really the pipe Emacs is using to
 3559 communicate with the subprocess.
 3561 On NT, this fails because CON always refers to the handle for the
 3562 relevant console (approximately equivalent to a tty), and cannot be
 3563 redirected to refer to the pipe Emacs assigned to the subprocess as
 3564 stdin.
 3566 A workaround is to modify perldb.pl to use STDIN/STDOUT instead of CON.
 3568 For Perl 4:
 3570     *** PERL/LIB/PERLDB.PL.orig	Wed May 26 08:24:18 1993
 3571     --- PERL/LIB/PERLDB.PL	Mon Jul 01 15:28:16 1996
 3572     ***************
 3573     *** 68,74 ****
 3574           $rcfile=".perldb";
 3575       }
 3576       else {
 3577     !     $console = "con";
 3578           $rcfile="perldb.ini";
 3579       }
 3581     --- 68,74 ----
 3582           $rcfile=".perldb";
 3583       }
 3584       else {
 3585     !     $console = "";
 3586           $rcfile="perldb.ini";
 3587       }
 3590     For Perl 5:
 3591     *** perl/5.001/lib/perl5db.pl.orig	Sun Jun 04 21:13:40 1995
 3592     --- perl/5.001/lib/perl5db.pl	Mon Jul 01 17:00:08 1996
 3593     ***************
 3594     *** 22,28 ****
 3595           $rcfile=".perldb";
 3596       }
 3597       elsif (-e "con") {
 3598     !     $console = "con";
 3599           $rcfile="perldb.ini";
 3600       }
 3601       else {
 3602     --- 22,28 ----
 3603           $rcfile=".perldb";
 3604       }
 3605       elsif (-e "con") {
 3606     !     $console = "";
 3607           $rcfile="perldb.ini";
 3608       }
 3609       else {
 3611 *** MS-Windows 95: Alt-f6 does not get through to Emacs.
 3613 This character seems to be trapped by the kernel in Windows 95.
 3614 You can enter M-f6 by typing ESC f6.
 3616 *** MS-Windows 95/98/ME: subprocesses do not terminate properly.
 3618 This is a limitation of the Operating System, and can cause problems
 3619 when shutting down Windows.  Ensure that all subprocesses are exited
 3620 cleanly before exiting Emacs.  For more details, see the Emacs on MS
 3621 Windows FAQ (info manual "efaq-w32").
 3623 *** MS-Windows 95/98/ME: crashes when Emacs invokes non-existent programs.
 3625 When a program you are trying to run is not found on the PATH,
 3626 Windows might respond by crashing or locking up your system.  In
 3627 particular, this has been reported when trying to compile a Java
 3628 program in JDEE when javac.exe is installed, but not on the system PATH.
 3630 ** MS-DOS
 3632 *** When compiling with DJGPP on MS-Windows NT or later, "config msdos" fails.
 3634 If the error message is "VDM has been already loaded", this is because
 3635 Windows has a program called 'redir.exe' that is incompatible with a
 3636 program by the same name supplied with DJGPP, which is used by
 3637 config.bat.  To resolve this, move the DJGPP's 'bin' subdirectory to
 3638 the front of your PATH environment variable.
 3640 *** When Emacs compiled with DJGPP runs on Windows 2000 and later, it cannot
 3641 find your HOME directory.
 3643 This was reported to happen when you click on "Save for future
 3644 sessions" button in a Customize buffer.  You might see an error
 3645 message like this one:
 3647   basic-save-buffer-2: c:/FOO/BAR/~dosuser/: no such directory
 3649 (The telltale sign is the "~USER" part at the end of the directory
 3650 Emacs complains about, where USER is your username or the literal
 3651 string "dosuser", which is the default username set up by the DJGPP
 3652 startup file DJGPP.ENV.)
 3654 This happens when the functions 'user-login-name' and
 3655 'user-real-login-name' return different strings for your username as
 3656 Emacs sees it.  To correct this, make sure both USER and USERNAME
 3657 environment variables are set to the same value.  Windows 2000 and
 3658 later sets USERNAME, so if you want to keep that, make sure USER is
 3659 set to the same value.  If you don't want to set USER globally, you
 3660 can do it in the [emacs] section of your DJGPP.ENV file.
 3662 *** When Emacs compiled with DJGPP runs on Vista, it runs out of memory.
 3664 If Emacs running on Vista displays "!MEM FULL!" in the mode line, you
 3665 are hitting the memory allocation bugs in the Vista DPMI server.  See
 3666 msdos/INSTALL for how to work around these bugs (search for "Vista").
 3668 *** When compiling with DJGPP on MS-Windows 95, Make fails for some targets
 3669 like make-docfile.
 3671 This can happen if long file name support (the setting of environment
 3672 variable LFN) when Emacs distribution was unpacked and during
 3673 compilation are not the same.  See msdos/INSTALL for the explanation
 3674 of how to avoid this problem.
 3676 *** Emacs compiled with DJGPP complains at startup:
 3678   "Wrong type of argument: internal-facep, msdos-menu-active-face"
 3680 This can happen if you define an environment variable 'TERM'.  Emacs
 3681 on MSDOS uses an internal terminal emulator which is disabled if the
 3682 value of 'TERM' is anything but the string "internal".  Emacs then
 3683 works as if its terminal were a dumb glass teletype that doesn't
 3684 support faces.  To work around this, arrange for 'TERM' to be
 3685 undefined when Emacs runs.  The best way to do that is to add an
 3686 [emacs] section to the DJGPP.ENV file which defines an empty value for
 3687 'TERM'; this way, only Emacs gets the empty value, while the rest of
 3688 your system works as before.
 3690 *** MS-DOS: Emacs crashes at startup.
 3692 Some users report that Emacs 19.29 requires dpmi memory management,
 3693 and crashes on startup if the system does not have it.  We don't
 3694 know why this happens--perhaps these machines don't have enough real
 3695 memory, or perhaps something is wrong in Emacs or the compiler.
 3696 However, arranging to use dpmi support is a workaround.
 3698 You can find out if you have a dpmi host by running go32 without
 3699 arguments; it will tell you if it uses dpmi memory.  For more
 3700 information about dpmi memory, consult the djgpp FAQ.  (djgpp
 3701 is the GNU C compiler as packaged for MSDOS.)
 3703 Compiling Emacs under MSDOS is extremely sensitive for proper memory
 3704 configuration.  If you experience problems during compilation, consider
 3705 removing some or all memory resident programs (notably disk caches)
 3706 and make sure that your memory managers are properly configured.  See
 3707 the djgpp faq for configuration hints.
 3709 *** Emacs compiled with DJGPP for MS-DOS/MS-Windows cannot access files
 3710 in the directory with the special name 'dev' under the root of any
 3711 drive, e.g. 'c:/dev'.
 3713 This is an unfortunate side-effect of the support for Unix-style
 3714 device names such as /dev/null in the DJGPP runtime library.  A
 3715 work-around is to rename the problem directory to another name.
 3717 *** MS-DOS: Emacs compiled for MSDOS cannot find some Lisp files, or other
 3718 run-time support files, when long filename support is enabled.
 3720 Usually, this problem will manifest itself when Emacs exits
 3721 immediately after flashing the startup screen, because it cannot find
 3722 the Lisp files it needs to load at startup.  Redirect Emacs stdout
 3723 and stderr to a file to see the error message printed by Emacs.
 3725 Another manifestation of this problem is that Emacs is unable to load
 3726 the support for editing program sources in languages such as C and Lisp.
 3728 This can happen if the Emacs distribution was unzipped without LFN
 3729 support, thus causing long filenames to be truncated to the first 6
 3730 characters and a numeric tail that Windows 95 normally attaches to it.
 3731 You should unzip the files again with a utility that supports long
 3732 filenames (such as djtar from DJGPP or InfoZip's UnZip program
 3733 compiled with DJGPP v2).  The file msdos/INSTALL explains this issue
 3734 in more detail.
 3736 Another possible reason for such failures is that Emacs compiled for
 3737 MSDOS is used on Windows NT, where long file names are not supported
 3738 by this version of Emacs, but the distribution was unpacked by an
 3739 unzip program that preserved the long file names instead of truncating
 3740 them to DOS 8+3 limits.  To be useful on NT, the MSDOS port of Emacs
 3741 must be unzipped by a DOS utility, so that long file names are
 3742 properly truncated.
 3744 ** Apple Macintosh operating systems
 3746 *** OS X 10.9 and earlier: symlinks autocomplete as directories
 3748 Autocompleting the name of a symbolic link incorrectly appends "/".
 3749 Building and running Emacs on OS X 10.10 (or later) fixes the problem.
 3750 Older operating systems are no longer supported by Apple.
 3751 https://bugs.gnu.org/31305
 3753 ** Archaic window managers and toolkits
 3755 *** Open Look: Under Open Look, the Emacs window disappears when you type M-q.
 3757 Some versions of the Open Look window manager interpret M-q as a quit
 3758 command for whatever window you are typing at.  If you want to use
 3759 Emacs with that window manager, you should try to configure the window
 3760 manager to use some other command.   You can disable the
 3761 shortcut keys entirely by adding this line to ~/.OWdefaults:
 3763     OpenWindows.WindowMenuAccelerators: False
 3765 *** twm: A position you specified in .Xdefaults is ignored, using twm.
 3767 twm normally ignores "program-specified" positions.
 3768 You can tell it to obey them with this command in your '.twmrc' file:
 3770   UsePPosition	"on"		#allow clients to request a position
 3772 ** Bugs related to old DEC hardware
 3774 *** The Compose key on a DEC keyboard does not work as Meta key.
 3776 This shell command should fix it:
 3778   xmodmap -e 'keycode 0xb1 = Meta_L'
 3780 *** Keyboard input gets confused after a beep when using a DECserver
 3781 as a concentrator.
 3783 This problem seems to be a matter of configuring the DECserver to use
 3784 7 bit characters rather than 8 bit characters.
 3786 This file is part of GNU Emacs.
 3788 GNU Emacs is free software: you can redistribute it and/or modify
 3789 it under the terms of the GNU General Public License as published by
 3790 the Free Software Foundation, either version 3 of the License, or
 3791 (at your option) any later version.
 3793 GNU Emacs is distributed in the hope that it will be useful,
 3794 but WITHOUT ANY WARRANTY; without even the implied warranty of
 3796 GNU General Public License for more details.
 3798 You should have received a copy of the GNU General Public License
 3799 along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
 3802 Local variables:
 3803 mode: outline
 3804 paragraph-separate: "[  ]*$"
 3805 end: