GNU Emacs Lisp Reference Manual
For Emacs Version 22.1
Revision 2.9, April 2007
by Bil Lewis, Dan LaLiberte, Richard Stallman
and the GNU Manual Group
This is edition 2.9 of the GNU Emacs Lisp Reference Manual,
corresponding to Emacs version 22.1.
Copyright
c
 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002, 2003,
2004, 2005, 2006, 2007 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU Free Documentation License, Version 1.2 or any later
version published by the Free Software Foundation; with the Invariant Sections
being “GNU General Public License,” with the Front-Cover texts being “A
GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled “GNU Free Documentation License.”
(a) The FSF’s Back-Cover Text is: “You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free Software
Foundation raise funds for GNU development.”
Published by the Free Software Foundation
51 Franklin St, Fifth Floor
Boston, MA 02110-1301
USA
ISBN 1-882114-74-4
Cover art by Etienne Suvasa.
i
Short Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 Lisp Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3 Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

34 Searching and Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
35 Syntax Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
ii
36 Abbrevs and Abbrev Expansion. . . . . . . . . . . . . . . . . . . . . . . . 699
37 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
38 Emacs Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
39 Operating System Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
A Emacs 21 Antinews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838
B GNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . . 843
C GNU General Public License . . . . . . . . . . . . . . . . . . . . . . . . . . 850
D Tips and Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856
E GNU Emacs Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
F Standard Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891
G Buffer-Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895
H Standard Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899
I Standard Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908
iii
Table of Contents
1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Lisp History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3 Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3.1 Some Terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3.2 nil and t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3.3 Evaluation Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3.4 Printing Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3.5 Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3.6 Buffer Text Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3.7 Format of Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.3.11 Bool-Vector Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
iv
2.3.12 Hash Table Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.3.13 Function Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.3.14 Macro Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.3.15 Primitive Function Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.3.16 Byte-Code Function Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.3.17 Autoload Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.4 Editing Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.4.1 Buffer Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.4.2 Marker Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.4.3 Window Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.4.4 Frame Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.4.5 Window Configuration Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.4.6 Frame Configuration Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.4.7 Process Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.4.8 Stream Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.4.9 Keymap Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.4.10 Overlay Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.5 Read Syntax for Circular Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.6 Type Predicates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.7 Equality Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3 Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.1 Integer Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.2 Floating Point Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.3 Type Predicates for Numbers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.4 Comparison of Numbers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.5 Numeric Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.6 Arithmetic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.7 Rounding Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

6.3 Functions that Operate on Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
6.4 Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
6.5 Functions for Vectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
6.6 Char-Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.7 Bool-vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7 Hash Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
7.1 Creating Hash Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
7.2 Hash Table Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
7.3 Defining Hash Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
7.4 Other Hash Table Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
8 Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
8.1 Symbol Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
8.2 Defining Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
8.3 Creating and Interning Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
8.4 Property Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
8.4.1 Property Lists and Association Lists. . . . . . . . . . . . . . . . . . . . . 107
8.4.2 Property List Functions for Symbols . . . . . . . . . . . . . . . . . . . . . 108
8.4.3 Property Lists Outside Symbols . . . . . . . . . . . . . . . . . . . . . . . . . 108
vi
9 Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
9.1 Kinds of Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.1.1 Self-Evaluating Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.1.2 Symbol Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.1.3 Classification of List Forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
9.1.4 Symbol Function Indirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
9.1.5 Evaluation of Function Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
9.1.6 Lisp Macro Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
9.1.7 Special Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
9.1.8 Autoloading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.2 Quoting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

11.10.1 Introduction to Buffer-Local Variables. . . . . . . . . . . . . . . . . 148
11.10.2 Creating and Deleting Buffer-Local Bindings . . . . . . . . . . 149
11.10.3 The Default Value of a Buffer-Local Variable . . . . . . . . . . 152
11.11 Frame-Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
vii
11.12 Possible Future Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
11.13 File Local Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
11.14 Variable Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
11.15 Variables with Restricted Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
12 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
12.1 What Is a Function? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
12.2 Lambda Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
12.2.1 Components of a Lambda Expression . . . . . . . . . . . . . . . . . . . 162
12.2.2 A Simple Lambda-Expression Example . . . . . . . . . . . . . . . . . 162
12.2.3 Other Features of Argument Lists . . . . . . . . . . . . . . . . . . . . . . 163
12.2.4 Documentation Strings of Functions . . . . . . . . . . . . . . . . . . . . 164
12.3 Naming a Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
12.4 Defining Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
12.5 Calling Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
12.6 Mapping Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
12.7 Anonymous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
12.8 Accessing Function Cell Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
12.9 Declaring Functions Obsolete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
12.10 Inline Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
12.11 Determining whether a Function is Safe to Call . . . . . . . . . . . . 174
12.12 Other Topics Related to Functions . . . . . . . . . . . . . . . . . . . . . . . . . 174
13 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
13.1 A Simple Example of a Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
13.2 Expansion of a Macro Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
13.3 Macros and Byte Compilation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

15.10 Hooks for Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
16 Byte Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
16.1 Performance of Byte-Compiled Code . . . . . . . . . . . . . . . . . . . . . . . . 214
16.2 The Compilation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
16.3 Documentation Strings and Compilation . . . . . . . . . . . . . . . . . . . . 217
16.4 Dynamic Loading of Individual Functions . . . . . . . . . . . . . . . . . . . 218
16.5 Evaluation During Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
16.6 Compiler Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
16.7 Byte-Code Function Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
16.8 Disassembled Byte-Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
17 Advising Emacs Lisp Functions. . . . . . . . . . . . 226
17.1 A Simple Advice Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
17.2 Defining Advice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
17.3 Around-Advice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
17.4 Computed Advice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
17.5 Activation of Advice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
17.6 Enabling and Disabling Advice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
17.7 Preactivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
17.8 Argument Access in Advice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
17.9 Advising Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
17.10 The Combined Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
18 Debugging Lisp Programs . . . . . . . . . . . . . . . . . . 237
18.1 The Lisp Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
18.1.1 Entering the Debugger on an Error . . . . . . . . . . . . . . . . . . . . . 237
18.1.2 Debugging Infinite Loops. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
18.1.3 Entering the Debugger on a Function Call . . . . . . . . . . . . . . 239
18.1.4 Explicit Entry to the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . 240
18.1.5 Using the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
18.1.6 Debugger Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
18.1.7 Invoking the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

18.3.1 Excess Open Parentheses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
18.3.2 Excess Close Parentheses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
18.4 Test Coverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
18.5 Debugging Problems in Compilation . . . . . . . . . . . . . . . . . . . . . . . . 267
19 Reading and Printing Lisp Objects. . . . . . . . 268
19.1 Introduction to Reading and Printing . . . . . . . . . . . . . . . . . . . . . . . 268
19.2 Input Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
19.3 Input Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
19.4 Output Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
19.5 Output Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
19.6 Variables Affecting Output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
20 Minibuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
20.1 Introduction to Minibuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
20.2 Reading Text Strings with the Minibuffer . . . . . . . . . . . . . . . . . . . 279
20.3 Reading Lisp Objects with the Minibuffer . . . . . . . . . . . . . . . . . . . 281
20.4 Minibuffer History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
20.5 Initial Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
20.6 Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
20.6.1 Basic Completion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
20.6.2 Completion and the Minibuffer . . . . . . . . . . . . . . . . . . . . . . . . . 288
20.6.3 Minibuffer Commands that Do Completion . . . . . . . . . . . . . 289
x
20.6.4 High-Level Completion Functions . . . . . . . . . . . . . . . . . . . . . . 291
20.6.5 Reading File Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
20.6.6 Programmed Completion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
20.7 Yes-or-No Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
20.8 Asking Multiple Y-or-N Questions . . . . . . . . . . . . . . . . . . . . . . . . . . 298
20.9 Reading a Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
20.10 Minibuffer Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
20.11 Minibuffer Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

21.7.3 Modifying and Translating Input Events. . . . . . . . . . . . . . . . 333
21.7.4 Invoking the Input Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
21.7.5 Quoted Character Input. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
21.7.6 Miscellaneous Event Input Features . . . . . . . . . . . . . . . . . . . . 335
21.8 Special Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
21.9 Waiting for Elapsed Time or Input . . . . . . . . . . . . . . . . . . . . . . . . . . 337
21.10 Quitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
21.11 Prefix Command Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
21.12 Recursive Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
xi
21.13 Disabling Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
21.14 Command History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
21.15 Keyboard Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
22 Keymaps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
22.1 Key Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
22.2 Keymap Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
22.3 Format of Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
22.4 Creating Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
22.5 Inheritance and Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
22.6 Prefix Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
22.7 Active Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
22.8 Searching the Active Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
22.9 Controlling the Active Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
22.10 Key Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
22.11 Functions for Key Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
22.12 Changing Key Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
22.13 Remapping Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
22.14 Keymaps for Translating Sequences of Events . . . . . . . . . . . . . . 365
22.15 Commands for Binding Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
22.16 Scanning Keymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

23.4.2 The Data Structure of the Mode Line . . . . . . . . . . . . . . . . . . 402
23.4.3 The Top Level of Mode Line Control . . . . . . . . . . . . . . . . . . . 404
23.4.4 Variables Used in the Mode Line . . . . . . . . . . . . . . . . . . . . . . . 405
23.4.5 %-Constructs in the Mode Line . . . . . . . . . . . . . . . . . . . . . . . . . 407
23.4.6 Properties in the Mode Line. . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
23.4.7 Window Header Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
23.4.8 Emulating Mode-Line Formatting . . . . . . . . . . . . . . . . . . . . . . 410
23.5 Imenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
23.6 Font Lock Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
23.6.1 Font Lock Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
23.6.2 Search-based Fontification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
23.6.3 Customizing Search-Based Fontification . . . . . . . . . . . . . . . . 417
23.6.4 Other Font Lock Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
23.6.5 Levels of Font Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
23.6.6 Precalculated Fontification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
23.6.7 Faces for Font Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
23.6.8 Syntactic Font Lock. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
23.6.9 Setting Syntax Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
23.6.10 Multiline Font Lock Constructs . . . . . . . . . . . . . . . . . . . . . . . 422
23.6.10.1 Font Lock Multiline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
23.6.10.2 Region to Fontify after a Buffer Change . . . . . . . . . . 423
23.7 Desktop Save Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
24 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
24.1 Documentation Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
24.2 Access to Documentation Strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
24.3 Substituting Key Bindings in Documentation . . . . . . . . . . . . . . . . 428
24.4 Describing Characters for Help Messages . . . . . . . . . . . . . . . . . . . . 429
24.5 Help Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
25 Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
25.1 Visiting Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

26.1.3 Making and Deleting Numbered Backup Files . . . . . . . . . . 474
26.1.4 Naming Backup Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
26.2 Auto-Saving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
26.3 Reverting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
27 Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
27.1 Buffer Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
27.2 The Current Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
27.3 Buffer Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
27.4 Buffer File Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
27.5 Buffer Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
27.6 Buffer Modification Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
27.7 Read-Only Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
27.8 The Buffer List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
27.9 Creating Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
27.10 Killing Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
27.11 Indirect Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
27.12 The Buffer Gap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
28 Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
28.1 Basic Concepts of Emacs Windows . . . . . . . . . . . . . . . . . . . . . . . . . . 497
28.2 Splitting Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
28.3 Deleting Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
28.4 Selecting Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
28.5 Cyclic Ordering of Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
28.6 Buffers and Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
28.7 Displaying Buffers in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
28.8 Choosing a Window for Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
28.9 Windows and Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
28.10 The Window Start Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
xiv
28.11 Textual Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515

29.9 Input Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
29.10 Visibility of Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
29.11 Raising and Lowering Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
29.12 Frame Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
29.13 Mouse Tracking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
29.14 Mouse Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
29.15 Pop-Up Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
29.16 Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
29.17 Pointer Shape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
29.18 Window System Selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
29.19 Drag and Drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
29.20 Color Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
29.21 Text Terminal Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
29.22 X Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555
29.23 Display Feature Testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555
xv
30 Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
30.1 Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
30.2 Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
30.2.1 Motion by Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
30.2.2 Motion by Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
30.2.3 Motion to an End of the Buffer. . . . . . . . . . . . . . . . . . . . . . . . . 561
30.2.4 Motion by Text Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
30.2.5 Motion by Screen Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
30.2.6 Moving over Balanced Expressions . . . . . . . . . . . . . . . . . . . . . 566
30.2.7 Skipping Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
30.3 Excursions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
30.4 Narrowing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
31 Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572
31.1 Overview of Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572

32.17 Indentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
xvi
32.17.1 Indentation Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
32.17.2 Indentation Controlled by Major Mode . . . . . . . . . . . . . . . . 610
32.17.3 Indenting an Entire Region . . . . . . . . . . . . . . . . . . . . . . . . . . . 611
32.17.4 Indentation Relative to Previous Lines . . . . . . . . . . . . . . . . 612
32.17.5 Adjustable “Tab Stops” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613
32.17.6 Indentation-Based Motion Commands . . . . . . . . . . . . . . . . . 613
32.18 Case Changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613
32.19 Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
32.19.1 Examining Text Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
32.19.2 Changing Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616
32.19.3 Text Property Search Functions . . . . . . . . . . . . . . . . . . . . . . . 618
32.19.4 Properties with Special Meanings . . . . . . . . . . . . . . . . . . . . . 620
32.19.5 Formatted Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
32.19.6 Stickiness of Text Properties . . . . . . . . . . . . . . . . . . . . . . . . . . 625
32.19.7 Saving Text Properties in Files . . . . . . . . . . . . . . . . . . . . . . . . 626
32.19.8 Lazy Computation of Text Properties . . . . . . . . . . . . . . . . . 627
32.19.9 Defining Clickable Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
32.19.10 Links and Mouse-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
32.19.11 Defining and Using Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630
32.19.12 Why Text Properties are not Intervals . . . . . . . . . . . . . . . 632
32.20 Substituting for a Character Code . . . . . . . . . . . . . . . . . . . . . . . . . 633
32.21 Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
32.22 Transposition of Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
32.23 Base 64 Encoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
32.24 MD5 Checksum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
32.25 Atomic Change Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
32.26 Change Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
33 Non-ASCII Characters. . . . . . . . . . . . . . . . . . . . . . 640

34.3.2 Complex Regexp Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
34.3.3 Regular Expression Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 672
34.4 Regular Expression Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
34.5 POSIX Regular Expression Searching . . . . . . . . . . . . . . . . . . . . . . . 676
34.6 The Match Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
34.6.1 Replacing the Text that Matched. . . . . . . . . . . . . . . . . . . . . . . 676
34.6.2 Simple Match Data Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
34.6.3 Accessing the Entire Match Data . . . . . . . . . . . . . . . . . . . . . . . 679
34.6.4 Saving and Restoring the Match Data . . . . . . . . . . . . . . . . . . 680
34.7 Search and Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
34.8 Standard Regular Expressions Used in Editing . . . . . . . . . . . . . . 683
35 Syntax Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
35.1 Syntax Table Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
35.2 Syntax Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
35.2.1 Table of Syntax Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685
35.2.2 Syntax Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687
35.3 Syntax Table Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
35.4 Syntax Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
35.5 Motion and Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
35.6 Parsing Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
35.6.1 Motion Commands Based on Parsing . . . . . . . . . . . . . . . . . . . 692
35.6.2 Finding the Parse State for a Position . . . . . . . . . . . . . . . . . . 692
35.6.3 Parser State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
35.6.4 Low-Level Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
35.6.5 Parameters to Control Parsing . . . . . . . . . . . . . . . . . . . . . . . . . 695
35.7 Some Standard Syntax Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
35.8 Syntax Table Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
35.9 Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696
36 Abbrevs and Abbrev Expansion . . . . . . . . . . . 699
36.1 Setting Up Abbrev Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699

37.17 Misc Network Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
37.18 Packing and Unpacking Byte Arrays . . . . . . . . . . . . . . . . . . . . . . . 732
37.18.1 Describing Data Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
37.18.2 Functions to Unpack and Pack Bytes . . . . . . . . . . . . . . . . . . 734
37.18.3 Examples of Byte Unpacking and Packing . . . . . . . . . . . . . 735
38 Emacs Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
38.1 Refreshing the Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
38.2 Forcing Redisplay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
38.3 Truncation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
38.4 The Echo Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
38.4.1 Displaying Messages in the Echo Area . . . . . . . . . . . . . . . . . . 741
38.4.2 Reporting Operation Progress . . . . . . . . . . . . . . . . . . . . . . . . . . 743
38.4.3 Logging Messages in ‘*Messages*’. . . . . . . . . . . . . . . . . . . . . . 744
38.4.4 Echo Area Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
38.5 Reporting Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
38.5.1 Warning Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
38.5.2 Warning Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
38.5.3 Warning Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748
38.6 Invisible Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748
38.7 Selective Display. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
38.8 Temporary Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
38.9 Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
38.9.1 Managing Overlays. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
xix
38.9.2 Overlay Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
38.9.3 Searching for Overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
38.10 Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
38.11 Line Height. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
38.12 Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
38.12.1 Defining Faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763

38.16.9 Image Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
38.17 Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
38.17.1 Button Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
38.17.2 Button Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798
38.17.3 Making Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798
38.17.4 Manipulating Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
38.17.5 Button Buffer Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
38.18 Abstract Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
38.18.1 Abstract Display Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 801
38.18.2 Abstract Display Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803
38.19 Blinking Parentheses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805
38.20 Usual Display Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
xx
38.21 Display Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
38.21.1 Display Table Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
38.21.2 Active Display Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
38.21.3 Glyphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
38.22 Beeping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
38.23 Window Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
39 Operating System Interface . . . . . . . . . . . . . . . . 812
39.1 Starting Up Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
39.1.1 Summary: Sequence of Actions at Startup . . . . . . . . . . . . . . 812
39.1.2 The Init File, ‘.emacs’ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
39.1.3 Terminal-Specific Initialization . . . . . . . . . . . . . . . . . . . . . . . . . 814
39.1.4 Command-Line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815
39.2 Getting Out of Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
39.2.1 Killing Emacs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
39.2.2 Suspending Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
39.3 Operating System Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819
39.4 User Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822

D.5 Tips for Avoiding Compiler Warnings. . . . . . . . . . . . . . . . . . . . . . . . 862
D.6 Tips for Documentation Strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862
D.7 Tips on Writing Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
D.8 Conventional Headers for Emacs Libraries . . . . . . . . . . . . . . . . . . . 867
Appendix E GNU Emacs Internals . . . . . . . . . . 870
E.1 Building Emacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
E.2 Pure Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871
E.3 Garbage Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
E.4 Memory Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875
E.5 Writing Emacs Primitives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 876
E.6 Object Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880
E.6.1 Buffer Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880
E.6.2 Window Internals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
E.6.3 Process Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889
Appendix F Standard Errors . . . . . . . . . . . . . . . . . 891
Appendix G Buffer-Local Variables . . . . . . . . . . 895
Appendix H Standard Keymaps . . . . . . . . . . . . . . 899
Appendix I Standard Hooks . . . . . . . . . . . . . . . . . 903
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908
Chapter 1: Introduction 1
1 Introduction
Most of the GNU Emacs text editor is written in the programming language called Emacs
Lisp. You can write new code in Emacs Lisp and install it as an extension to the editor.
However, Emacs Lisp is more than a mere “extension language”; it is a full computer
programming language in its own right. You can use it as you would any other programming
language.
Because Emacs Lisp is designed for use in an editor, it has special features for scanning
and parsing text as well as features for handling files, buffers, displays, subprocesses, and
so on. Emacs Lisp is closely integrated with the editing facilities; thus, editing commands
are functions that can also conveniently be called from Lisp programs, and parameters for

Months, and sometimes years, go by between updates. So please attach no significance to
the lack of a reply—your mail will be acted on in due time. If you want to contact the
Emacs maintainers more quickly, send mail to [email protected].
Chapter 1: Introduction 2
1.2 Lisp History
Lisp (LISt Processing language) was first developed in the late 1950s at the Massachusetts
Institute of Technology for research in artificial intelligence. The great power of the Lisp
language makes it ideal for other purposes as well, such as writing editing commands.
Dozens of Lisp implementations have been built over the years, each with its own id-
iosyncrasies. Many of them were inspired by Maclisp, which was written in the 1960s at
MIT’s Project MAC. Eventually the implementors of the descendants of Maclisp came to-
gether and developed a standard for Lisp systems, called Common Lisp. In the meantime,
Gerry Sussman and Guy Steele at MIT developed a simplified but very powerful dialect of
Lisp, called Scheme.
GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common Lisp. If you
know Common Lisp, you will notice many similarities. However, many features of Common
Lisp have been omitted or simplified in order to reduce the memory requirements of GNU
Emacs. Sometimes the simplifications are so drastic that a Common Lisp user might be
very confused. We will occasionally point out how GNU Emacs Lisp differs from Common
Lisp. If you don’t know Common Lisp, don’t worry about it; this manual is self-contained.
A certain amount of Common Lisp emulation is available via the ‘cl’ library. See Info
file ‘cl’, node ‘Top’.
Emacs Lisp is not at all influenced by Scheme; but the GNU project has an imple-
mentation of Scheme, called Guile. We use Guile in all new GNU software that calls for
extensibility.
1.3 Conventions
This section explains the notational conventions that are used in this manual. You may
want to skip this section and refer back to it later.
1.3.1 Some Terms
Throughout this manual, the phrases “the Lisp reader” and “the Lisp printer” refer to those