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