|
6451
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the GNU Emacs Lisp Reference Manual.
|
|
|
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
|
|
|
4 @c See the file elisp.texi for copying conditions.
|
|
|
5 @setfilename ../info/internals
|
|
|
6 @node GNU Emacs Internals, Standard Errors, Tips, Top
|
|
|
7 @comment node-name, next, previous, up
|
|
|
8 @appendix GNU Emacs Internals
|
|
|
9
|
|
|
10 This chapter describes how the runnable Emacs executable is dumped with
|
|
|
11 the preloaded Lisp libraries in it, how storage is allocated, and some
|
|
|
12 internal aspects of GNU Emacs that may be of interest to C programmers.
|
|
|
13
|
|
|
14 @menu
|
|
|
15 * Building Emacs:: How to preload Lisp libraries into Emacs.
|
|
|
16 * Pure Storage:: A kludge to make preloaded Lisp functions sharable.
|
|
|
17 * Garbage Collection:: Reclaiming space for Lisp objects no longer used.
|
|
|
18 * Writing Emacs Primitives:: Writing C code for Emacs.
|
|
|
19 * Object Internals:: Data formats of buffers, windows, processes.
|
|
|
20 @end menu
|
|
|
21
|
|
|
22 @node Building Emacs, Pure Storage, GNU Emacs Internals, GNU Emacs Internals
|
|
|
23 @appendixsec Building Emacs
|
|
|
24 @cindex building Emacs
|
|
|
25 @pindex temacs
|
|
|
26
|
|
|
27 This section explains the steps involved in building the Emacs
|
|
|
28 executable. You don't have to know this material to build and install
|
|
|
29 Emacs, since the makefiles do all these things automatically. This
|
|
|
30 information is pertinent to Emacs maintenance.
|
|
|
31
|
|
|
32 Compilation of the C source files in the @file{src} directory
|
|
|
33 produces an executable file called @file{temacs}, also called a
|
|
|
34 @dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and I/O
|
|
|
35 routines, but not the editing commands.
|
|
|
36
|
|
|
37 @cindex @file{loadup.el}
|
|
|
38 The command @w{@samp{temacs -l loadup}} uses @file{temacs} to create
|
|
|
39 the real runnable Emacs executable. These arguments direct
|
|
|
40 @file{temacs} to evaluate the Lisp files specified in the file
|
|
|
41 @file{loadup.el}. These files set up the normal Emacs editing
|
|
7601
|
42 environment, resulting in an Emacs that is still impure but no longer
|
|
6451
|
43 bare.
|
|
|
44
|
|
|
45 It takes a substantial time to load the standard Lisp files. Luckily,
|
|
|
46 you don't have to do this each time you run Emacs; @file{temacs} can
|
|
7601
|
47 dump out an executable program called @file{emacs} that has these files
|
|
6451
|
48 preloaded. @file{emacs} starts more quickly because it does not need to
|
|
|
49 load the files. This is the Emacs executable that is normally
|
|
|
50 installed.
|
|
|
51
|
|
|
52 To create @file{emacs}, use the command @samp{temacs -batch -l loadup
|
|
|
53 dump}. The purpose of @samp{-batch} here is to prevent @file{temacs}
|
|
|
54 from trying to initialize any of its data on the terminal; this ensures
|
|
|
55 that the tables of terminal information are empty in the dumped Emacs.
|
|
|
56 The argument @samp{dump} tells @file{loadup.el} to dump a new executable
|
|
|
57 named @file{emacs}.
|
|
|
58
|
|
|
59 Some operating systems don't support dumping. On those systems, you
|
|
|
60 must start Emacs with the @samp{temacs -l loadup} command each time you
|
|
7086
|
61 use it. This takes a substantial time, but since you need to start
|
|
|
62 Emacs once a day at most---or once a week if you never log out---the
|
|
|
63 extra time is not too severe a problem.
|
|
6451
|
64
|
|
|
65 @cindex @file{site-load.el}
|
|
|
66 You can specify additional files to preload by writing a library named
|
|
7601
|
67 @file{site-load.el} that loads them. You may need to increase the
|
|
6451
|
68 value of @code{PURESIZE}, in @file{src/puresize.h}, to make room for the
|
|
|
69 additional files. (Try adding increments of 20000 until it is big
|
|
|
70 enough.) However, the advantage of preloading additional files
|
|
|
71 decreases as machines get faster. On modern machines, it is usually not
|
|
|
72 advisable.
|
|
|
73
|
|
|
74 @cindex @file{site-init.el}
|
|
7086
|
75 You can specify other Lisp expressions to execute just before dumping
|
|
|
76 by putting them in a library named @file{site-init.el}. However, if
|
|
|
77 they might alter the behavior that users expect from an ordinary
|
|
|
78 unmodified Emacs, it is better to put them in @file{default.el}, so that
|
|
6451
|
79 users can override them if they wish. @xref{Start-up Summary}.
|
|
|
80
|
|
7086
|
81 Before @file{loadup.el} dumps the new executable, it finds the
|
|
|
82 documentation strings for primitive and preloaded functions (and
|
|
|
83 variables) in the file where they are stored, by calling
|
|
6451
|
84 @code{Snarf-documentation} (@pxref{Accessing Documentation}). These
|
|
7086
|
85 strings were moved out of the @file{emacs} executable to make it
|
|
|
86 smaller. @xref{Documentation Basics}.
|
|
6451
|
87
|
|
|
88 @defun dump-emacs to-file from-file
|
|
|
89 @cindex unexec
|
|
|
90 This function dumps the current state of Emacs into an executable file
|
|
|
91 @var{to-file}. It takes symbols from @var{from-file} (this is normally
|
|
|
92 the executable file @file{temacs}).
|
|
|
93
|
|
|
94 If you use this function in an Emacs that was already dumped, you must
|
|
|
95 set @code{command-line-processed} to @code{nil} first for good results.
|
|
|
96 @xref{Command Line Arguments}.
|
|
|
97 @end defun
|
|
|
98
|
|
|
99 @deffn Command emacs-version
|
|
|
100 This function returns a string describing the version of Emacs that is
|
|
|
101 running. It is useful to include this string in bug reports.
|
|
|
102
|
|
|
103 @example
|
|
|
104 @group
|
|
|
105 (emacs-version)
|
|
12098
|
106 @result{} "GNU Emacs 19.29.1 (i386-debian-linux) \
|
|
|
107 of Tue Jun 6 1995 on balloon"
|
|
6451
|
108 @end group
|
|
|
109 @end example
|
|
|
110
|
|
|
111 Called interactively, the function prints the same information in the
|
|
|
112 echo area.
|
|
|
113 @end deffn
|
|
|
114
|
|
|
115 @defvar emacs-build-time
|
|
12098
|
116 The value of this variable is the time at which Emacs was built at the
|
|
6451
|
117 local site.
|
|
|
118
|
|
|
119 @example
|
|
|
120 @group
|
|
|
121 emacs-build-time
|
|
12098
|
122 @result{} "Tue Jun 6 14:55:57 1995"
|
|
6451
|
123 @end group
|
|
|
124 @end example
|
|
|
125 @end defvar
|
|
|
126
|
|
|
127 @defvar emacs-version
|
|
|
128 The value of this variable is the version of Emacs being run. It is a
|
|
12098
|
129 string such as @code{"19.29.1"}.
|
|
6451
|
130 @end defvar
|
|
|
131
|
|
7086
|
132 The following two variables did not exist before Emacs version 19.23,
|
|
|
133 which reduces their usefulness at present, but we hope they will be
|
|
|
134 convenient in the future.
|
|
|
135
|
|
|
136 @defvar emacs-major-version
|
|
7601
|
137 The major version number of Emacs, as an integer. For Emacs version
|
|
12098
|
138 19.29, the value is 19.
|
|
7086
|
139 @end defvar
|
|
|
140
|
|
|
141 @defvar emacs-minor-version
|
|
|
142 The minor version number of Emacs, as an integer. For Emacs version
|
|
12098
|
143 19.29, the value is 29.
|
|
7086
|
144 @end defvar
|
|
|
145
|
|
6451
|
146 @node Pure Storage, Garbage Collection, Building Emacs, GNU Emacs Internals
|
|
|
147 @appendixsec Pure Storage
|
|
|
148 @cindex pure storage
|
|
|
149
|
|
7086
|
150 Emacs Lisp uses two kinds of storage for user-created Lisp objects:
|
|
|
151 @dfn{normal storage} and @dfn{pure storage}. Normal storage is where
|
|
7601
|
152 all the new data created during an Emacs session is kept; see the
|
|
|
153 following section for information on normal storage. Pure storage is
|
|
|
154 used for certain data in the preloaded standard Lisp files---data that
|
|
|
155 should never change during actual use of Emacs.
|
|
6451
|
156
|
|
|
157 Pure storage is allocated only while @file{temacs} is loading the
|
|
|
158 standard preloaded Lisp libraries. In the file @file{emacs}, it is
|
|
7601
|
159 marked as read-only (on operating systems that permit this), so that
|
|
6451
|
160 the memory space can be shared by all the Emacs jobs running on the
|
|
|
161 machine at once. Pure storage is not expandable; a fixed amount is
|
|
|
162 allocated when Emacs is compiled, and if that is not sufficient for the
|
|
7086
|
163 preloaded libraries, @file{temacs} crashes. If that happens, you must
|
|
|
164 increase the compilation parameter @code{PURESIZE} in the file
|
|
6451
|
165 @file{src/puresize.h}. This normally won't happen unless you try to
|
|
|
166 preload additional libraries or add features to the standard ones.
|
|
|
167
|
|
|
168 @defun purecopy object
|
|
7086
|
169 This function makes a copy of @var{object} in pure storage and returns
|
|
6451
|
170 it. It copies strings by simply making a new string with the same
|
|
|
171 characters in pure storage. It recursively copies the contents of
|
|
7086
|
172 vectors and cons cells. It does not make copies of other objects such
|
|
|
173 as symbols, but just returns them unchanged. It signals an error if
|
|
6451
|
174 asked to copy markers.
|
|
|
175
|
|
11139
|
176 This function is a no-op except while Emacs is being built and dumped;
|
|
|
177 it is usually called only in the file @file{emacs/lisp/loaddefs.el}, but
|
|
|
178 a few packages call it just in case you decide to preload them.
|
|
6451
|
179 @end defun
|
|
|
180
|
|
|
181 @defvar pure-bytes-used
|
|
7086
|
182 The value of this variable is the number of bytes of pure storage
|
|
6451
|
183 allocated so far. Typically, in a dumped Emacs, this number is very
|
|
|
184 close to the total amount of pure storage available---if it were not,
|
|
|
185 we would preallocate less.
|
|
|
186 @end defvar
|
|
|
187
|
|
|
188 @defvar purify-flag
|
|
7086
|
189 This variable determines whether @code{defun} should make a copy of the
|
|
6451
|
190 function definition in pure storage. If it is non-@code{nil}, then the
|
|
|
191 function definition is copied into pure storage.
|
|
|
192
|
|
7086
|
193 This flag is @code{t} while loading all of the basic functions for
|
|
6451
|
194 building Emacs initially (allowing those functions to be sharable and
|
|
7086
|
195 non-collectible). Dumping Emacs as an executable always writes
|
|
|
196 @code{nil} in this variable, regardless of the value it actually has
|
|
|
197 before and after dumping.
|
|
6451
|
198
|
|
7086
|
199 You should not change this flag in a running Emacs.
|
|
6451
|
200 @end defvar
|
|
|
201
|
|
|
202 @node Garbage Collection, Writing Emacs Primitives, Pure Storage, GNU Emacs Internals
|
|
|
203 @appendixsec Garbage Collection
|
|
|
204 @cindex garbage collector
|
|
|
205
|
|
|
206 @cindex memory allocation
|
|
|
207 When a program creates a list or the user defines a new function (such
|
|
7086
|
208 as by loading a library), that data is placed in normal storage. If
|
|
|
209 normal storage runs low, then Emacs asks the operating system to
|
|
6451
|
210 allocate more memory in blocks of 1k bytes. Each block is used for one
|
|
7086
|
211 type of Lisp object, so symbols, cons cells, markers, etc., are
|
|
|
212 segregated in distinct blocks in memory. (Vectors, long strings,
|
|
|
213 buffers and certain other editing types, which are fairly large, are
|
|
|
214 allocated in individual blocks, one per object, while small strings are
|
|
|
215 packed into blocks of 8k bytes.)
|
|
6451
|
216
|
|
7086
|
217 It is quite common to use some storage for a while, then release it by
|
|
|
218 (for example) killing a buffer or deleting the last pointer to an
|
|
6451
|
219 object. Emacs provides a @dfn{garbage collector} to reclaim this
|
|
|
220 abandoned storage. (This name is traditional, but ``garbage recycler''
|
|
|
221 might be a more intuitive metaphor for this facility.)
|
|
|
222
|
|
7086
|
223 The garbage collector operates by finding and marking all Lisp objects
|
|
|
224 that are still accessible to Lisp programs. To begin with, it assumes
|
|
|
225 all the symbols, their values and associated function definitions, and
|
|
7601
|
226 any data presently on the stack, are accessible. Any objects that can
|
|
7086
|
227 be reached indirectly through other accessible objects are also
|
|
|
228 accessible.
|
|
6451
|
229
|
|
7086
|
230 When marking is finished, all objects still unmarked are garbage. No
|
|
6451
|
231 matter what the Lisp program or the user does, it is impossible to refer
|
|
7086
|
232 to them, since there is no longer a way to reach them. Their space
|
|
7601
|
233 might as well be reused, since no one will miss them. The second
|
|
|
234 (``sweep'') phase of the garbage collector arranges to reuse them.
|
|
6451
|
235
|
|
|
236 @cindex free list
|
|
7086
|
237 The sweep phase puts unused cons cells onto a @dfn{free list}
|
|
|
238 for future allocation; likewise for symbols and markers. It compacts
|
|
|
239 the accessible strings so they occupy fewer 8k blocks; then it frees the
|
|
7601
|
240 other 8k blocks. Vectors, buffers, windows, and other large objects are
|
|
7086
|
241 individually allocated and freed using @code{malloc} and @code{free}.
|
|
6451
|
242
|
|
|
243 @cindex CL note---allocate more storage
|
|
|
244 @quotation
|
|
7601
|
245 @b{Common Lisp note:} Unlike other Lisps, GNU Emacs Lisp does not
|
|
6451
|
246 call the garbage collector when the free list is empty. Instead, it
|
|
|
247 simply requests the operating system to allocate more storage, and
|
|
|
248 processing continues until @code{gc-cons-threshold} bytes have been
|
|
|
249 used.
|
|
|
250
|
|
|
251 This means that you can make sure that the garbage collector will not
|
|
|
252 run during a certain portion of a Lisp program by calling the garbage
|
|
|
253 collector explicitly just before it (provided that portion of the
|
|
|
254 program does not use so much space as to force a second garbage
|
|
|
255 collection).
|
|
|
256 @end quotation
|
|
|
257
|
|
|
258 @deffn Command garbage-collect
|
|
7086
|
259 This command runs a garbage collection, and returns information on
|
|
6451
|
260 the amount of space in use. (Garbage collection can also occur
|
|
|
261 spontaneously if you use more than @code{gc-cons-threshold} bytes of
|
|
|
262 Lisp data since the previous garbage collection.)
|
|
|
263
|
|
7086
|
264 @code{garbage-collect} returns a list containing the following
|
|
6451
|
265 information:
|
|
|
266
|
|
7086
|
267 @example
|
|
6451
|
268 @group
|
|
|
269 ((@var{used-conses} . @var{free-conses})
|
|
|
270 (@var{used-syms} . @var{free-syms})
|
|
7086
|
271 @end group
|
|
6451
|
272 (@var{used-markers} . @var{free-markers})
|
|
|
273 @var{used-string-chars}
|
|
|
274 @var{used-vector-slots}
|
|
|
275 (@var{used-floats} . @var{free-floats}))
|
|
|
276
|
|
7086
|
277 @group
|
|
6451
|
278 (garbage-collect)
|
|
|
279 @result{} ((3435 . 2332) (1688 . 0)
|
|
|
280 (57 . 417) 24510 3839 (4 . 1))
|
|
|
281 @end group
|
|
7086
|
282 @end example
|
|
6451
|
283
|
|
|
284 Here is a table explaining each element:
|
|
|
285
|
|
|
286 @table @var
|
|
|
287 @item used-conses
|
|
|
288 The number of cons cells in use.
|
|
|
289
|
|
|
290 @item free-conses
|
|
|
291 The number of cons cells for which space has been obtained from the
|
|
|
292 operating system, but that are not currently being used.
|
|
|
293
|
|
|
294 @item used-syms
|
|
|
295 The number of symbols in use.
|
|
|
296
|
|
|
297 @item free-syms
|
|
|
298 The number of symbols for which space has been obtained from the
|
|
|
299 operating system, but that are not currently being used.
|
|
|
300
|
|
|
301 @item used-markers
|
|
|
302 The number of markers in use.
|
|
|
303
|
|
|
304 @item free-markers
|
|
|
305 The number of markers for which space has been obtained from the
|
|
|
306 operating system, but that are not currently being used.
|
|
|
307
|
|
|
308 @item used-string-chars
|
|
|
309 The total size of all strings, in characters.
|
|
|
310
|
|
|
311 @item used-vector-slots
|
|
|
312 The total number of elements of existing vectors.
|
|
|
313
|
|
|
314 @item used-floats
|
|
|
315 @c Emacs 19 feature
|
|
|
316 The number of floats in use.
|
|
|
317
|
|
|
318 @item free-floats
|
|
|
319 @c Emacs 19 feature
|
|
|
320 The number of floats for which space has been obtained from the
|
|
|
321 operating system, but that are not currently being used.
|
|
|
322 @end table
|
|
|
323 @end deffn
|
|
|
324
|
|
|
325 @defopt gc-cons-threshold
|
|
7086
|
326 The value of this variable is the number of bytes of storage that must
|
|
6451
|
327 be allocated for Lisp objects after one garbage collection in order to
|
|
7086
|
328 trigger another garbage collection. A cons cell counts as eight bytes,
|
|
6451
|
329 a string as one byte per character plus a few bytes of overhead, and so
|
|
7086
|
330 on; space allocated to the contents of buffers does not count. Note
|
|
|
331 that the subsequent garbage collection does not happen immediately when
|
|
|
332 the threshold is exhausted, but only the next time the Lisp evaluator is
|
|
6451
|
333 called.
|
|
|
334
|
|
12098
|
335 The initial threshold value is 300,000. If you specify a larger
|
|
6451
|
336 value, garbage collection will happen less often. This reduces the
|
|
|
337 amount of time spent garbage collecting, but increases total memory use.
|
|
7601
|
338 You may want to do this when running a program that creates lots of
|
|
6451
|
339 Lisp data.
|
|
|
340
|
|
7086
|
341 You can make collections more frequent by specifying a smaller value,
|
|
6451
|
342 down to 10,000. A value less than 10,000 will remain in effect only
|
|
|
343 until the subsequent garbage collection, at which time
|
|
|
344 @code{garbage-collect} will set the threshold back to 10,000.
|
|
|
345 @end defopt
|
|
|
346
|
|
|
347 @c Emacs 19 feature
|
|
|
348 @defun memory-limit
|
|
|
349 This function returns the address of the last byte Emacs has allocated,
|
|
|
350 divided by 1024. We divide the value by 1024 to make sure it fits in a
|
|
|
351 Lisp integer.
|
|
|
352
|
|
|
353 You can use this to get a general idea of how your actions affect the
|
|
|
354 memory usage.
|
|
|
355 @end defun
|
|
|
356
|
|
|
357 @node Writing Emacs Primitives, Object Internals, Garbage Collection, GNU Emacs Internals
|
|
|
358 @appendixsec Writing Emacs Primitives
|
|
|
359 @cindex primitive function internals
|
|
|
360
|
|
|
361 Lisp primitives are Lisp functions implemented in C. The details of
|
|
|
362 interfacing the C function so that Lisp can call it are handled by a few
|
|
|
363 C macros. The only way to really understand how to write new C code is
|
|
|
364 to read the source, but we can explain some things here.
|
|
|
365
|
|
|
366 An example of a special form is the definition of @code{or}, from
|
|
|
367 @file{eval.c}. (An ordinary function would have the same general
|
|
|
368 appearance.)
|
|
|
369
|
|
|
370 @cindex garbage collection protection
|
|
|
371 @smallexample
|
|
|
372 @group
|
|
|
373 DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
|
|
7086
|
374 "Eval args until one of them yields non-nil, then return that value.\n\
|
|
6451
|
375 The remaining args are not evalled at all.\n\
|
|
|
376 @end group
|
|
|
377 @group
|
|
7086
|
378 If all args return nil, return nil.")
|
|
6451
|
379 (args)
|
|
|
380 Lisp_Object args;
|
|
|
381 @{
|
|
|
382 register Lisp_Object val;
|
|
|
383 Lisp_Object args_left;
|
|
|
384 struct gcpro gcpro1;
|
|
|
385 @end group
|
|
|
386
|
|
|
387 @group
|
|
7086
|
388 if (NULL (args))
|
|
6451
|
389 return Qnil;
|
|
|
390
|
|
|
391 args_left = args;
|
|
|
392 GCPRO1 (args_left);
|
|
|
393 @end group
|
|
|
394
|
|
|
395 @group
|
|
|
396 do
|
|
|
397 @{
|
|
|
398 val = Feval (Fcar (args_left));
|
|
|
399 if (!NULL (val))
|
|
|
400 break;
|
|
|
401 args_left = Fcdr (args_left);
|
|
|
402 @}
|
|
7086
|
403 while (!NULL (args_left));
|
|
6451
|
404 @end group
|
|
|
405
|
|
|
406 @group
|
|
|
407 UNGCPRO;
|
|
|
408 return val;
|
|
|
409 @}
|
|
|
410 @end group
|
|
|
411 @end smallexample
|
|
|
412
|
|
|
413 Let's start with a precise explanation of the arguments to the
|
|
7086
|
414 @code{DEFUN} macro. Here is a template for them:
|
|
6451
|
415
|
|
|
416 @example
|
|
|
417 DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc})
|
|
|
418 @end example
|
|
|
419
|
|
|
420 @table @var
|
|
|
421 @item lname
|
|
7086
|
422 This is the name of the Lisp symbol to define as the function name; in
|
|
|
423 the example above, it is @code{or}.
|
|
6451
|
424
|
|
|
425 @item fname
|
|
|
426 This is the C function name for this function. This is
|
|
|
427 the name that is used in C code for calling the function. The name is,
|
|
|
428 by convention, @samp{F} prepended to the Lisp name, with all dashes
|
|
|
429 (@samp{-}) in the Lisp name changed to underscores. Thus, to call this
|
|
|
430 function from C code, call @code{For}. Remember that the arguments must
|
|
|
431 be of type @code{Lisp_Object}; various macros and functions for creating
|
|
|
432 values of type @code{Lisp_Object} are declared in the file
|
|
|
433 @file{lisp.h}.
|
|
|
434
|
|
|
435 @item sname
|
|
|
436 This is a C variable name to use for a structure that holds the data for
|
|
|
437 the subr object that represents the function in Lisp. This structure
|
|
|
438 conveys the Lisp symbol name to the initialization routine that will
|
|
|
439 create the symbol and store the subr object as its definition. By
|
|
|
440 convention, this name is always @var{fname} with @samp{F} replaced with
|
|
|
441 @samp{S}.
|
|
|
442
|
|
|
443 @item min
|
|
7086
|
444 This is the minimum number of arguments that the function requires. The
|
|
|
445 function @code{or} allows a minimum of zero arguments.
|
|
6451
|
446
|
|
|
447 @item max
|
|
7086
|
448 This is the maximum number of arguments that the function accepts, if
|
|
|
449 there is a fixed maximum. Alternatively, it can be @code{UNEVALLED},
|
|
|
450 indicating a special form that receives unevaluated arguments, or
|
|
|
451 @code{MANY}, indicating an unlimited number of evaluated arguments (the
|
|
|
452 equivalent of @code{&rest}). Both @code{UNEVALLED} and @code{MANY} are
|
|
|
453 macros. If @var{max} is a number, it may not be less than @var{min} and
|
|
|
454 it may not be greater than seven.
|
|
6451
|
455
|
|
|
456 @item interactive
|
|
|
457 This is an interactive specification, a string such as might be used as
|
|
|
458 the argument of @code{interactive} in a Lisp function. In the case of
|
|
|
459 @code{or}, it is 0 (a null pointer), indicating that @code{or} cannot be
|
|
7086
|
460 called interactively. A value of @code{""} indicates a function that
|
|
|
461 should receive no arguments when called interactively.
|
|
6451
|
462
|
|
|
463 @item doc
|
|
|
464 This is the documentation string. It is written just like a
|
|
|
465 documentation string for a function defined in Lisp, except you must
|
|
|
466 write @samp{\n\} at the end of each line. In particular, the first line
|
|
|
467 should be a single sentence.
|
|
|
468 @end table
|
|
|
469
|
|
7086
|
470 After the call to the @code{DEFUN} macro, you must write the argument
|
|
|
471 name list that every C function must have, followed by ordinary C
|
|
|
472 declarations for the arguments. For a function with a fixed maximum
|
|
|
473 number of arguments, declare a C argument for each Lisp argument, and
|
|
7601
|
474 give them all type @code{Lisp_Object}. When a Lisp function has no
|
|
|
475 upper limit on the number of arguments, its implementation in C actually
|
|
|
476 receives exactly two arguments: the first is the number of Lisp
|
|
|
477 arguments, and the second is the address of a block containing their
|
|
|
478 values. They have types @code{int} and @w{@code{Lisp_Object *}}.
|
|
6451
|
479
|
|
|
480 Within the function @code{For} itself, note the use of the macros
|
|
|
481 @code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to ``protect''
|
|
|
482 a variable from garbage collection---to inform the garbage collector that
|
|
|
483 it must look in that variable and regard its contents as an accessible
|
|
|
484 object. This is necessary whenever you call @code{Feval} or anything
|
|
|
485 that can directly or indirectly call @code{Feval}. At such a time, any
|
|
|
486 Lisp object that you intend to refer to again must be protected somehow.
|
|
|
487 @code{UNGCPRO} cancels the protection of the variables that are
|
|
|
488 protected in the current function. It is necessary to do this explicitly.
|
|
|
489
|
|
7086
|
490 For most data types, it suffices to protect at least one pointer to
|
|
|
491 the object; as long as the object is not recycled, all pointers to it
|
|
|
492 remain valid. This is not so for strings, because the garbage collector
|
|
|
493 can move them. When the garbage collector moves a string, it relocates
|
|
|
494 all the pointers it knows about; any other pointers become invalid.
|
|
|
495 Therefore, you must protect all pointers to strings across any point
|
|
|
496 where garbage collection may be possible.
|
|
6451
|
497
|
|
7086
|
498 The macro @code{GCPRO1} protects just one local variable. If you want
|
|
|
499 to protect two, use @code{GCPRO2} instead; repeating @code{GCPRO1} will
|
|
|
500 not work. Macros @code{GCPRO3} and @code{GCPRO4} also exist.
|
|
6451
|
501
|
|
7086
|
502 These macros implicitly use local variables such as @code{gcpro1}; you
|
|
|
503 must declare these explicitly, with type @code{struct gcpro}. Thus, if
|
|
|
504 you use @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
|
|
|
505 Alas, we can't explain all the tricky details here.
|
|
6451
|
506
|
|
10487
|
507 You must not use C initializers for static or global variables unless
|
|
|
508 they are never written once Emacs is dumped. These variables with
|
|
|
509 initializers are allocated in an area of memory that becomes read-only
|
|
|
510 (on certain operating systems) as a result of dumping Emacs. @xref{Pure
|
|
|
511 Storage}.
|
|
10476
|
512
|
|
10487
|
513 Do not use static variables within functions---place all static
|
|
|
514 variables at top level in the file. This is necessary because Emacs on
|
|
|
515 some operating systems defines the keyword @code{static} as a null
|
|
|
516 macro. (This definition is used because those systems put all variables
|
|
|
517 declared static in a place that becomes read-only after dumping, whether
|
|
|
518 they have initializers or not.)
|
|
10476
|
519
|
|
7086
|
520 Defining the C function is not enough to make a Lisp primitive
|
|
|
521 available; you must also create the Lisp symbol for the primitive and
|
|
|
522 store a suitable subr object in its function cell. The code looks like
|
|
|
523 this:
|
|
6451
|
524
|
|
|
525 @example
|
|
|
526 defsubr (&@var{subr-structure-name});
|
|
|
527 @end example
|
|
|
528
|
|
|
529 @noindent
|
|
7086
|
530 Here @var{subr-structure-name} is the name you used as the third
|
|
|
531 argument to @code{DEFUN}.
|
|
6451
|
532
|
|
7086
|
533 If you add a new primitive to a file that already has Lisp primitives
|
|
|
534 defined in it, find the function (near the end of the file) named
|
|
|
535 @code{syms_of_@var{something}}, and add the call to @code{defsubr}
|
|
|
536 there. If the file doesn't have this function, or if you create a new
|
|
|
537 file, add to it a @code{syms_of_@var{filename}} (e.g.,
|
|
|
538 @code{syms_of_myfile}). Then find the spot in @file{emacs.c} where all
|
|
|
539 of these functions are called, and add a call to
|
|
|
540 @code{syms_of_@var{filename}} there.
|
|
6451
|
541
|
|
7601
|
542 The function @code{syms_of_@var{filename}} is also the place to define
|
|
|
543 any C variables that are to be visible as Lisp variables.
|
|
7086
|
544 @code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible
|
|
|
545 in Lisp. @code{DEFVAR_INT} makes a C variable of type @code{int}
|
|
|
546 visible in Lisp with a value that is always an integer.
|
|
|
547 @code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp
|
|
|
548 with a value that is either @code{t} or @code{nil}.
|
|
6451
|
549
|
|
7086
|
550 Here is another example function, with more complicated arguments.
|
|
|
551 This comes from the code for the X Window System, and it demonstrates
|
|
|
552 the use of macros and functions to manipulate Lisp objects.
|
|
6451
|
553
|
|
|
554 @smallexample
|
|
|
555 @group
|
|
|
556 DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
|
|
|
557 Scoordinates_in_window_p, 2, 2,
|
|
|
558 "xSpecify coordinate pair: \nXExpression which evals to window: ",
|
|
|
559 "Return non-nil if POSITIONS is in WINDOW.\n\
|
|
|
560 \(POSITIONS is a list, (SCREEN-X SCREEN-Y)\)\n\
|
|
|
561 @end group
|
|
|
562 @group
|
|
|
563 Returned value is list of positions expressed\n\
|
|
|
564 relative to window upper left corner.")
|
|
|
565 (coordinate, window)
|
|
|
566 register Lisp_Object coordinate, window;
|
|
|
567 @{
|
|
|
568 register Lisp_Object xcoord, ycoord;
|
|
|
569 @end group
|
|
|
570
|
|
|
571 @group
|
|
|
572 if (!CONSP (coordinate)) wrong_type_argument (Qlistp, coordinate);
|
|
|
573 CHECK_WINDOW (window, 2);
|
|
|
574 xcoord = Fcar (coordinate);
|
|
|
575 ycoord = Fcar (Fcdr (coordinate));
|
|
|
576 CHECK_NUMBER (xcoord, 0);
|
|
|
577 CHECK_NUMBER (ycoord, 1);
|
|
|
578 @end group
|
|
|
579 @group
|
|
|
580 if ((XINT (xcoord) < XINT (XWINDOW (window)->left))
|
|
|
581 || (XINT (xcoord) >= (XINT (XWINDOW (window)->left)
|
|
|
582 + XINT (XWINDOW (window)->width))))
|
|
7086
|
583 return Qnil;
|
|
6451
|
584 XFASTINT (xcoord) -= XFASTINT (XWINDOW (window)->left);
|
|
|
585 @end group
|
|
|
586 @group
|
|
|
587 if (XINT (ycoord) == (screen_height - 1))
|
|
|
588 return Qnil;
|
|
|
589 @end group
|
|
|
590 @group
|
|
|
591 if ((XINT (ycoord) < XINT (XWINDOW (window)->top))
|
|
|
592 || (XINT (ycoord) >= (XINT (XWINDOW (window)->top)
|
|
|
593 + XINT (XWINDOW (window)->height)) - 1))
|
|
7086
|
594 return Qnil;
|
|
6451
|
595 @end group
|
|
|
596 @group
|
|
|
597 XFASTINT (ycoord) -= XFASTINT (XWINDOW (window)->top);
|
|
|
598 return (Fcons (xcoord, Fcons (ycoord, Qnil)));
|
|
|
599 @}
|
|
|
600 @end group
|
|
|
601 @end smallexample
|
|
|
602
|
|
7086
|
603 Note that C code cannot call functions by name unless they are defined
|
|
|
604 in C. The way to call a function written in Lisp is to use
|
|
|
605 @code{Ffuncall}, which embodies the Lisp function @code{funcall}. Since
|
|
|
606 the Lisp function @code{funcall} accepts an unlimited number of
|
|
|
607 arguments, in C it takes two: the number of Lisp-level arguments, and a
|
|
|
608 one-dimensional array containing their values. The first Lisp-level
|
|
|
609 argument is the Lisp function to call, and the rest are the arguments to
|
|
|
610 pass to it. Since @code{Ffuncall} can call the evaluator, you must
|
|
|
611 protect pointers from garbage collection around the call to
|
|
|
612 @code{Ffuncall}.
|
|
|
613
|
|
|
614 The C functions @code{call0}, @code{call1}, @code{call2}, and so on,
|
|
|
615 provide handy ways to call a Lisp function conveniently with a fixed
|
|
|
616 number of arguments. They work by calling @code{Ffuncall}.
|
|
6451
|
617
|
|
|
618 @file{eval.c} is a very good file to look through for examples;
|
|
|
619 @file{lisp.h} contains the definitions for some important macros and
|
|
|
620 functions.
|
|
|
621
|
|
|
622 @node Object Internals, , Writing Emacs Primitives, GNU Emacs Internals
|
|
|
623 @appendixsec Object Internals
|
|
|
624 @cindex object internals
|
|
|
625
|
|
|
626 GNU Emacs Lisp manipulates many different types of data. The actual
|
|
|
627 data are stored in a heap and the only access that programs have to it is
|
|
|
628 through pointers. Pointers are thirty-two bits wide in most
|
|
|
629 implementations. Depending on the operating system and type of machine
|
|
|
630 for which you compile Emacs, twenty-four to twenty-six bits are used to
|
|
|
631 address the object, and the remaining six to eight bits are used for a
|
|
|
632 tag that identifies the object's type.
|
|
|
633
|
|
7086
|
634 Because Lisp objects are represented as tagged pointers, it is always
|
|
|
635 possible to determine the Lisp data type of any object. The C data type
|
|
|
636 @code{Lisp_Object} can hold any Lisp object of any data type. Ordinary
|
|
|
637 variables have type @code{Lisp_Object}, which means they can hold any
|
|
|
638 type of Lisp value; you can determine the actual data type only at run
|
|
|
639 time. The same is true for function arguments; if you want a function
|
|
|
640 to accept only a certain type of argument, you must check the type
|
|
|
641 explicitly using a suitable predicate (@pxref{Type Predicates}).
|
|
6451
|
642 @cindex type checking internals
|
|
|
643
|
|
|
644 @menu
|
|
|
645 * Buffer Internals:: Components of a buffer structure.
|
|
|
646 * Window Internals:: Components of a window structure.
|
|
|
647 * Process Internals:: Components of a process structure.
|
|
|
648 @end menu
|
|
|
649
|
|
|
650 @node Buffer Internals, Window Internals, Object Internals, Object Internals
|
|
|
651 @appendixsubsec Buffer Internals
|
|
|
652 @cindex internals, of buffer
|
|
|
653 @cindex buffer internals
|
|
|
654
|
|
|
655 Buffers contain fields not directly accessible by the Lisp programmer.
|
|
|
656 We describe them here, naming them by the names used in the C code.
|
|
|
657 Many are accessible indirectly in Lisp programs via Lisp primitives.
|
|
|
658
|
|
|
659 @table @code
|
|
|
660 @item name
|
|
7601
|
661 The buffer name is a string that names the buffer. It is guaranteed to
|
|
6451
|
662 be unique. @xref{Buffer Names}.
|
|
|
663
|
|
|
664 @item save_modified
|
|
|
665 This field contains the time when the buffer was last saved, as an integer.
|
|
|
666 @xref{Buffer Modification}.
|
|
|
667
|
|
|
668 @item modtime
|
|
|
669 This field contains the modification time of the visited file. It is
|
|
|
670 set when the file is written or read. Every time the buffer is written
|
|
|
671 to the file, this field is compared to the modification time of the
|
|
|
672 file. @xref{Buffer Modification}.
|
|
|
673
|
|
|
674 @item auto_save_modified
|
|
|
675 This field contains the time when the buffer was last auto-saved.
|
|
|
676
|
|
|
677 @item last_window_start
|
|
|
678 This field contains the @code{window-start} position in the buffer as of
|
|
|
679 the last time the buffer was displayed in a window.
|
|
|
680
|
|
7086
|
681 @item undo_list
|
|
|
682 This field points to the buffer's undo list. @xref{Undo}.
|
|
6451
|
683
|
|
|
684 @item syntax_table_v
|
|
|
685 This field contains the syntax table for the buffer. @xref{Syntax Tables}.
|
|
|
686
|
|
|
687 @item downcase_table
|
|
|
688 This field contains the conversion table for converting text to lower case.
|
|
|
689 @xref{Case Table}.
|
|
|
690
|
|
|
691 @item upcase_table
|
|
|
692 This field contains the conversion table for converting text to upper case.
|
|
|
693 @xref{Case Table}.
|
|
|
694
|
|
|
695 @item case_canon_table
|
|
|
696 This field contains the conversion table for canonicalizing text for
|
|
|
697 case-folding search. @xref{Case Table}.
|
|
|
698
|
|
|
699 @item case_eqv_table
|
|
|
700 This field contains the equivalence table for case-folding search.
|
|
|
701 @xref{Case Table}.
|
|
|
702
|
|
|
703 @item display_table
|
|
|
704 This field contains the buffer's display table, or @code{nil} if it doesn't
|
|
|
705 have one. @xref{Display Tables}.
|
|
|
706
|
|
|
707 @item markers
|
|
7086
|
708 This field contains the chain of all markers that currently point into
|
|
|
709 the buffer. Deletion of text in the buffer, and motion of the buffer's
|
|
|
710 gap, must check each of these markers and perhaps update it.
|
|
|
711 @xref{Markers}.
|
|
6451
|
712
|
|
|
713 @item backed_up
|
|
7601
|
714 This field is a flag that tells whether a backup file has been made
|
|
6451
|
715 for the visited file of this buffer.
|
|
|
716
|
|
|
717 @item mark
|
|
|
718 This field contains the mark for the buffer. The mark is a marker,
|
|
|
719 hence it is also included on the list @code{markers}. @xref{The Mark}.
|
|
|
720
|
|
7086
|
721 @item mark_active
|
|
|
722 This field is non-@code{nil} if the buffer's mark is active.
|
|
|
723
|
|
6451
|
724 @item local_var_alist
|
|
7086
|
725 This field contains the association list describing the variables local
|
|
|
726 in this buffer, and their values, with the exception of local variables
|
|
|
727 that have special slots in the buffer object. (Those slots are omitted
|
|
|
728 from this table.) @xref{Buffer-Local Variables}.
|
|
|
729
|
|
12098
|
730 @item base_buffer
|
|
|
731 This field holds the buffer's base buffer (if it is an indirect buffer),
|
|
|
732 or @code{nil}.
|
|
|
733
|
|
7086
|
734 @item keymap
|
|
|
735 This field holds the buffer's local keymap. @xref{Keymaps}.
|
|
6451
|
736
|
|
7086
|
737 @item overlay_center
|
|
|
738 This field holds the current overlay center position. @xref{Overlays}.
|
|
|
739
|
|
|
740 @item overlays_before
|
|
|
741 This field holds a list of the overlays in this buffer that end at or
|
|
|
742 before the current overlay center position. They are sorted in order of
|
|
|
743 decreasing end position.
|
|
|
744
|
|
|
745 @item overlays_after
|
|
|
746 This field holds a list of the overlays in this buffer that end after
|
|
|
747 the current overlay center position. They are sorted in order of
|
|
|
748 increasing beginning position.
|
|
6451
|
749 @end table
|
|
|
750
|
|
|
751 @node Window Internals, Process Internals, Buffer Internals, Object Internals
|
|
|
752 @appendixsubsec Window Internals
|
|
|
753 @cindex internals, of window
|
|
|
754 @cindex window internals
|
|
|
755
|
|
|
756 Windows have the following accessible fields:
|
|
|
757
|
|
|
758 @table @code
|
|
|
759 @item frame
|
|
7086
|
760 The frame that this window is on.
|
|
6451
|
761
|
|
|
762 @item mini_p
|
|
7086
|
763 Non-@code{nil} if this window is a minibuffer window.
|
|
6451
|
764
|
|
|
765 @item buffer
|
|
7601
|
766 The buffer that the window is displaying. This may change often during
|
|
6451
|
767 the life of the window.
|
|
|
768
|
|
|
769 @item dedicated
|
|
7086
|
770 Non-@code{nil} if this window is dedicated to its buffer.
|
|
6451
|
771
|
|
|
772 @item pointm
|
|
|
773 @cindex window point internals
|
|
7086
|
774 This is the value of point in the current buffer when this window is
|
|
6451
|
775 selected; when it is not selected, it retains its previous value.
|
|
|
776
|
|
7086
|
777 @item start
|
|
7601
|
778 The position in the buffer that is the first character to be displayed
|
|
7086
|
779 in the window.
|
|
|
780
|
|
|
781 @item force_start
|
|
|
782 If this flag is non-@code{nil}, it says that the window has been
|
|
|
783 scrolled explicitly by the Lisp program. This affects what the next
|
|
|
784 redisplay does if point is off the screen: instead of scrolling the
|
|
|
785 window to show the text around point, it moves point to a location that
|
|
|
786 is on the screen.
|
|
|
787
|
|
|
788 @item last_modified
|
|
|
789 The @code{modified} field of the window's buffer, as of the last time
|
|
|
790 a redisplay completed in this window.
|
|
|
791
|
|
|
792 @item last_point
|
|
|
793 The buffer's value of point, as of the last time
|
|
|
794 a redisplay completed in this window.
|
|
|
795
|
|
6451
|
796 @item left
|
|
7086
|
797 This is the left-hand edge of the window, measured in columns. (The
|
|
6451
|
798 leftmost column on the screen is @w{column 0}.)
|
|
|
799
|
|
|
800 @item top
|
|
7086
|
801 This is the top edge of the window, measured in lines. (The top line on
|
|
6451
|
802 the screen is @w{line 0}.)
|
|
|
803
|
|
7086
|
804 @item height
|
|
|
805 The height of the window, measured in lines.
|
|
|
806
|
|
|
807 @item width
|
|
|
808 The width of the window, measured in columns.
|
|
|
809
|
|
6451
|
810 @item next
|
|
7086
|
811 This is the window that is the next in the chain of siblings. It is
|
|
|
812 @code{nil} in a window that is the rightmost or bottommost of a group of
|
|
|
813 siblings.
|
|
6451
|
814
|
|
|
815 @item prev
|
|
7086
|
816 This is the window that is the previous in the chain of siblings. It is
|
|
|
817 @code{nil} in a window that is the leftmost or topmost of a group of
|
|
|
818 siblings.
|
|
6451
|
819
|
|
7086
|
820 @item parent
|
|
|
821 Internally, Emacs arranges windows in a tree; each group of siblings has
|
|
|
822 a parent window whose area includes all the siblings. This field points
|
|
|
823 to a window's parent.
|
|
|
824
|
|
|
825 Parent windows do not display buffers, and play little role in display
|
|
|
826 except to shape their child windows. Emacs Lisp programs usually have
|
|
|
827 no access to the parent windows; they operate on the windows at the
|
|
7601
|
828 leaves of the tree, which actually display buffers.
|
|
6451
|
829
|
|
|
830 @item hscroll
|
|
7086
|
831 This is the number of columns that the display in the window is scrolled
|
|
6451
|
832 horizontally to the left. Normally, this is 0.
|
|
|
833
|
|
|
834 @item use_time
|
|
7086
|
835 This is the last time that the window was selected. The function
|
|
6451
|
836 @code{get-lru-window} uses this field.
|
|
|
837
|
|
|
838 @item display_table
|
|
7086
|
839 The window's display table, or @code{nil} if none is specified for it.
|
|
|
840
|
|
|
841 @item update_mode_line
|
|
|
842 Non-@code{nil} means this window's mode line needs to be updated.
|
|
|
843
|
|
|
844 @item base_line_number
|
|
|
845 The line number of a certain position in the buffer, or @code{nil}.
|
|
|
846 This is used for displaying the line number of point in the mode line.
|
|
|
847
|
|
|
848 @item base_line_pos
|
|
|
849 The position in the buffer for which the line number is known, or
|
|
|
850 @code{nil} meaning none is known.
|
|
|
851
|
|
|
852 @item region_showing
|
|
|
853 If the region (or part of it) is highlighted in this window, this field
|
|
|
854 holds the mark position that made one end of that region. Otherwise,
|
|
|
855 this field is @code{nil}.
|
|
6451
|
856 @end table
|
|
|
857
|
|
|
858 @node Process Internals, , Window Internals, Object Internals
|
|
|
859 @appendixsubsec Process Internals
|
|
|
860 @cindex internals, of process
|
|
|
861 @cindex process internals
|
|
|
862
|
|
|
863 The fields of a process are:
|
|
|
864
|
|
|
865 @table @code
|
|
|
866 @item name
|
|
|
867 A string, the name of the process.
|
|
|
868
|
|
|
869 @item command
|
|
|
870 A list containing the command arguments that were used to start this
|
|
|
871 process.
|
|
|
872
|
|
|
873 @item filter
|
|
|
874 A function used to accept output from the process instead of a buffer,
|
|
|
875 or @code{nil}.
|
|
|
876
|
|
|
877 @item sentinel
|
|
|
878 A function called whenever the process receives a signal, or @code{nil}.
|
|
|
879
|
|
|
880 @item buffer
|
|
|
881 The associated buffer of the process.
|
|
|
882
|
|
|
883 @item pid
|
|
|
884 An integer, the Unix process @sc{id}.
|
|
|
885
|
|
|
886 @item childp
|
|
|
887 A flag, non-@code{nil} if this is really a child process.
|
|
|
888 It is @code{nil} for a network connection.
|
|
|
889
|
|
|
890 @item mark
|
|
7601
|
891 A marker indicating the position of the end of the last output from this
|
|
|
892 process inserted into the buffer. This is often but not always the end
|
|
|
893 of the buffer.
|
|
6451
|
894
|
|
|
895 @item kill_without_query
|
|
7086
|
896 If this is non-@code{nil}, killing Emacs while this process is still
|
|
|
897 running does not ask for confirmation about killing the process.
|
|
|
898
|
|
|
899 @item raw_status_low
|
|
|
900 @itemx raw_status_high
|
|
|
901 These two fields record 16 bits each of the process status returned by
|
|
|
902 the @code{wait} system call.
|
|
|
903
|
|
|
904 @item status
|
|
|
905 The process status, as @code{process-status} should return it.
|
|
|
906
|
|
|
907 @item tick
|
|
|
908 @itemx update_tick
|
|
|
909 If these two fields are not equal, a change in the status of the process
|
|
|
910 needs to be reported, either by running the sentinel or by inserting a
|
|
|
911 message in the process buffer.
|
|
|
912
|
|
|
913 @item pty_flag
|
|
|
914 Non-@code{nil} if communication with the subprocess uses a @sc{pty};
|
|
|
915 @code{nil} if it uses a pipe.
|
|
|
916
|
|
|
917 @item infd
|
|
|
918 The file descriptor for input from the process.
|
|
|
919
|
|
|
920 @item outfd
|
|
|
921 The file descriptor for output to the process.
|
|
|
922
|
|
|
923 @item subtty
|
|
|
924 The file descriptor for the terminal that the subprocess is using. (On
|
|
|
925 some systems, there is no need to record this, so the value is
|
|
|
926 @code{nil}.)
|
|
12098
|
927
|
|
|
928 @item tty_name
|
|
|
929 The name of the terminal that the subprocess is using,
|
|
|
930 or @code{nil} if it is using pipes.
|
|
6451
|
931 @end table
|
