gnu emacs lisp bytecode reference manual .diff (90 ... if we look at the relative ratio of c++to

GNU Emacs Lisp Bytecode Reference

ManualCollated and edited by Rocky Bernstein with contibutions from Pipcet, Chris Wellons,Stefan Monnier, Hallvard Breien Furuseth, and the Emacs community.

1

i

Short Contents

1 Introduction to Emacs Lisp Byte Code and LAP . . . . . . . . . . . . 12 Emacs Lisp Bytecode Environment . . . . . . . . . . . . . . . . . . . . . . . 6

3 Emacs Lisp Bytecode Instructions . . . . . . . . . . . . . . . . . . . . . . . 304 Instruction Changes Between Emacs Releases . . . . . . . . . . . . . 1535 Opcode Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1616 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Instruction Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Bytecode Function Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

ii

Table of Contents

1 Introduction to Emacs Lisp ByteCode and LAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 Why is Emacs Lisp Bytecode Important and How isEmacs as a Program Different? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2 Emacs Lisp Bytecode and LAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Example showing use of byte-compile-lapcode . . . . . . . . . . . . . . . . . . 3

1.3 Emacs Lisp Virtual Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 Wither Bytecode - Its Future . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Emacs Lisp Bytecode Environment . . . . . . . . . . . . 62.1 Emacs Lisp Bytecode Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.1.1 Function Parameter (lambda) List . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.2 Bytecode Unibyte String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.1.3 Constants Vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.1.4 Maximum Stack Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.1.5 Docstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.1.6 Interactive Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Examples showing the interactive specification . . . . . . . . . . . . . . . . . 12

2.2 Emacs Lisp Bytecode Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.3 Emacs Lisp Bytecode Interpreter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.4 Emacs Lisp Bytecode Bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.5 Emacs Lisp Bytecode Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.6 Functions and Commands for working with LAP and Bytecode . . 18

2.6.1 aref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.6.2 batch-byte-compile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.6.3 batch-byte-recompile-directory . . . . . . . . . . . . . . . . . . . . . . . 192.6.4 byte-code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.6.5 byte-compile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.6.6 byte-compile-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.6.7 byte-compile-sexp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.6.8 byte-recalc-examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.6.9 byte-recompile-directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.6.10 byte-recompile-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.6.11 compile-defun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.6.12 disassemble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.6.13 disassemble-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.6.14 disassemble-full . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.6.15 display-call-tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.6.16 functionp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.6.17 make-byte-code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.6.18 symbol-function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

2.7 Bytecode Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

iii

2.7.1 Constant Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.7.2 Unreachable Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.7.3 Strength Reduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

2.8 Bytecode Disassembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

3 Emacs Lisp Bytecode Instructions . . . . . . . . . . . . 303.1 Instruction-Description Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

3.1.1 Instruction Jargon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303.1.2 Instruction Description Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

3.2 Argument-Packing Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33stack-ref (17) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33varref (815) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34varset (1623) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35varbind (2431) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36call (3239) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37unbind (4047) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

3.3 Constants-Vector Retrieval Instructions . . . . . . . . . . . . . . . . . . . . . . . . 39constant (192255) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39constant2 (129) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

3.4 Exception-Handling Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41pophandler (48) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41pushconditioncase (49) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42pushcatch (50) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

3.5 Control-Flow Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44goto (130) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44goto-if-nil (131) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45goto-if-not-nil (132) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46goto-if-nil-else-pop (133) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47goto-if-not-nil-else-pop (134) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48return (135) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49switch (183) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

3.6 Function-Call Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513.6.1 Lisp Function Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

symbolp (57) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51consp (58) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52stringp (59) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53listp (60) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54eq (61) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55memq (62) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56not (63) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57symbol-value (74) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58symbol-function (75) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59set (76) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60fset (77) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61get (78) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .