Mercurial > emacs
comparison lispref/internals.texi @ 7086:075343a6b32b
*** empty log message ***
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Sun, 24 Apr 1994 21:47:17 +0000 |
parents | 8240c0b1d695 |
children | c5927c75b2b5 |
comparison
equal
deleted
inserted
replaced
7085:5e56975be72a | 7086:075343a6b32b |
---|---|
56 The argument @samp{dump} tells @file{loadup.el} to dump a new executable | 56 The argument @samp{dump} tells @file{loadup.el} to dump a new executable |
57 named @file{emacs}. | 57 named @file{emacs}. |
58 | 58 |
59 Some operating systems don't support dumping. On those systems, you | 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 | 60 must start Emacs with the @samp{temacs -l loadup} command each time you |
61 use it. This takes a long time, but since you need to start Emacs once | 61 use it. This takes a substantial time, but since you need to start |
62 a day at most---or once a week if you never log out---the extra time is | 62 Emacs once a day at most---or once a week if you never log out---the |
63 not too severe a problem. | 63 extra time is not too severe a problem. |
64 | 64 |
65 @cindex @file{site-load.el} | 65 @cindex @file{site-load.el} |
66 You can specify additional files to preload by writing a library named | 66 You can specify additional files to preload by writing a library named |
67 @file{site-load.el} which loads them. You may need to increase the | 67 @file{site-load.el} which loads them. You may need to increase the |
68 value of @code{PURESIZE}, in @file{src/puresize.h}, to make room for the | 68 value of @code{PURESIZE}, in @file{src/puresize.h}, to make room for the |
70 enough.) However, the advantage of preloading additional files | 70 enough.) However, the advantage of preloading additional files |
71 decreases as machines get faster. On modern machines, it is usually not | 71 decreases as machines get faster. On modern machines, it is usually not |
72 advisable. | 72 advisable. |
73 | 73 |
74 @cindex @file{site-init.el} | 74 @cindex @file{site-init.el} |
75 You can specify other things to be done in Lisp just before dumping by | 75 You can specify other Lisp expressions to execute just before dumping |
76 putting them in a library named @file{site-init.el}. However, if these | 76 by putting them in a library named @file{site-init.el}. However, if |
77 things might alter the behavior that users expect from an ordinary | 77 they might alter the behavior that users expect from an ordinary |
78 unmodified Emacs, it is better to do them in @file{default.el}, so that | 78 unmodified Emacs, it is better to put them in @file{default.el}, so that |
79 users can override them if they wish. @xref{Start-up Summary}. | 79 users can override them if they wish. @xref{Start-up Summary}. |
80 | 80 |
81 Before @file{emacs} is dumped, the documentation strings for primitive | 81 Before @file{loadup.el} dumps the new executable, it finds the |
82 and preloaded functions (and variables) need to be found in the file | 82 documentation strings for primitive and preloaded functions (and |
83 where they are stored. This is done by calling | 83 variables) in the file where they are stored, by calling |
84 @code{Snarf-documentation} (@pxref{Accessing Documentation}). These | 84 @code{Snarf-documentation} (@pxref{Accessing Documentation}). These |
85 strings were moved out of @file{emacs} to make it smaller. | 85 strings were moved out of the @file{emacs} executable to make it |
86 @xref{Documentation Basics}. | 86 smaller. @xref{Documentation Basics}. |
87 | 87 |
88 @defun dump-emacs to-file from-file | 88 @defun dump-emacs to-file from-file |
89 @cindex unexec | 89 @cindex unexec |
90 This function dumps the current state of Emacs into an executable file | 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 | 91 @var{to-file}. It takes symbols from @var{from-file} (this is normally |
127 @defvar emacs-version | 127 @defvar emacs-version |
128 The value of this variable is the version of Emacs being run. It is a | 128 The value of this variable is the version of Emacs being run. It is a |
129 string such as @code{"19.22.1"}. | 129 string such as @code{"19.22.1"}. |
130 @end defvar | 130 @end defvar |
131 | 131 |
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 | |
137 The major version number of Emacs, as an integer. | |
138 @end defvar | |
139 | |
140 @defvar emacs-minor-version | |
141 The minor version number of Emacs, as an integer. For Emacs version | |
142 19.23, the value is 23. | |
143 @end defvar | |
144 | |
132 @node Pure Storage, Garbage Collection, Building Emacs, GNU Emacs Internals | 145 @node Pure Storage, Garbage Collection, Building Emacs, GNU Emacs Internals |
133 @appendixsec Pure Storage | 146 @appendixsec Pure Storage |
134 @cindex pure storage | 147 @cindex pure storage |
135 | 148 |
136 There are two types of storage in GNU Emacs Lisp for user-created Lisp | 149 Emacs Lisp uses two kinds of storage for user-created Lisp objects: |
137 objects: @dfn{normal storage} and @dfn{pure storage}. Normal storage is | 150 @dfn{normal storage} and @dfn{pure storage}. Normal storage is where |
138 where all the new data which is created during an Emacs session is kept; | 151 all the new data which is created during an Emacs session is kept; see |
139 see the following section for information on normal storage. Pure | 152 the following section for information on normal storage. Pure storage |
140 storage is used for certain data in the preloaded standard Lisp files: | 153 is used for certain data in the preloaded standard Lisp files---data |
141 data that should never change during actual use of Emacs. | 154 that should never change during actual use of Emacs. |
142 | 155 |
143 Pure storage is allocated only while @file{temacs} is loading the | 156 Pure storage is allocated only while @file{temacs} is loading the |
144 standard preloaded Lisp libraries. In the file @file{emacs}, it is | 157 standard preloaded Lisp libraries. In the file @file{emacs}, it is |
145 marked as read-only (on operating systems which permit this), so that | 158 marked as read-only (on operating systems which permit this), so that |
146 the memory space can be shared by all the Emacs jobs running on the | 159 the memory space can be shared by all the Emacs jobs running on the |
147 machine at once. Pure storage is not expandable; a fixed amount is | 160 machine at once. Pure storage is not expandable; a fixed amount is |
148 allocated when Emacs is compiled, and if that is not sufficient for the | 161 allocated when Emacs is compiled, and if that is not sufficient for the |
149 preloaded libraries, @file{temacs} crashes. If that happens, you will | 162 preloaded libraries, @file{temacs} crashes. If that happens, you must |
150 have to increase the compilation parameter @code{PURESIZE} in the file | 163 increase the compilation parameter @code{PURESIZE} in the file |
151 @file{src/puresize.h}. This normally won't happen unless you try to | 164 @file{src/puresize.h}. This normally won't happen unless you try to |
152 preload additional libraries or add features to the standard ones. | 165 preload additional libraries or add features to the standard ones. |
153 | 166 |
154 @defun purecopy object | 167 @defun purecopy object |
155 This function makes a copy of @var{object} in pure storage and returns | 168 This function makes a copy of @var{object} in pure storage and returns |
156 it. It copies strings by simply making a new string with the same | 169 it. It copies strings by simply making a new string with the same |
157 characters in pure storage. It recursively copies the contents of | 170 characters in pure storage. It recursively copies the contents of |
158 vectors and cons cells. It does not make copies of symbols, or any | 171 vectors and cons cells. It does not make copies of other objects such |
159 other objects, but just returns them unchanged. It signals an error if | 172 as symbols, but just returns them unchanged. It signals an error if |
160 asked to copy markers. | 173 asked to copy markers. |
161 | 174 |
162 This function is used only while Emacs is being built and dumped; it is | 175 This function is used only while Emacs is being built and dumped; it is |
163 called only in the file @file{emacs/lisp/loaddefs.el}. | 176 called only in the file @file{emacs/lisp/loaddefs.el}. |
164 @end defun | 177 @end defun |
165 | 178 |
166 @defvar pure-bytes-used | 179 @defvar pure-bytes-used |
167 The value of this variable is the number of bytes of pure storage | 180 The value of this variable is the number of bytes of pure storage |
168 allocated so far. Typically, in a dumped Emacs, this number is very | 181 allocated so far. Typically, in a dumped Emacs, this number is very |
169 close to the total amount of pure storage available---if it were not, | 182 close to the total amount of pure storage available---if it were not, |
170 we would preallocate less. | 183 we would preallocate less. |
171 @end defvar | 184 @end defvar |
172 | 185 |
173 @defvar purify-flag | 186 @defvar purify-flag |
174 This variable determines whether @code{defun} should make a copy of the | 187 This variable determines whether @code{defun} should make a copy of the |
175 function definition in pure storage. If it is non-@code{nil}, then the | 188 function definition in pure storage. If it is non-@code{nil}, then the |
176 function definition is copied into pure storage. | 189 function definition is copied into pure storage. |
177 | 190 |
178 This flag is @code{t} while loading all of the basic functions for | 191 This flag is @code{t} while loading all of the basic functions for |
179 building Emacs initially (allowing those functions to be sharable and | 192 building Emacs initially (allowing those functions to be sharable and |
180 non-collectible). It is set to @code{nil} when Emacs is saved out | 193 non-collectible). Dumping Emacs as an executable always writes |
181 as @file{emacs}. The flag is set and reset in the C sources. | 194 @code{nil} in this variable, regardless of the value it actually has |
182 | 195 before and after dumping. |
183 You should not change this flag in a running Emacs. | 196 |
197 You should not change this flag in a running Emacs. | |
184 @end defvar | 198 @end defvar |
185 | 199 |
186 @node Garbage Collection, Writing Emacs Primitives, Pure Storage, GNU Emacs Internals | 200 @node Garbage Collection, Writing Emacs Primitives, Pure Storage, GNU Emacs Internals |
187 @appendixsec Garbage Collection | 201 @appendixsec Garbage Collection |
188 @cindex garbage collector | 202 @cindex garbage collector |
189 | 203 |
190 @cindex memory allocation | 204 @cindex memory allocation |
191 When a program creates a list or the user defines a new function (such | 205 When a program creates a list or the user defines a new function (such |
192 as by loading a library), then that data is placed in normal storage. | 206 as by loading a library), that data is placed in normal storage. If |
193 If normal storage runs low, then Emacs asks the operating system to | 207 normal storage runs low, then Emacs asks the operating system to |
194 allocate more memory in blocks of 1k bytes. Each block is used for one | 208 allocate more memory in blocks of 1k bytes. Each block is used for one |
195 type of Lisp object, so symbols, cons cells, markers, etc.@: are | 209 type of Lisp object, so symbols, cons cells, markers, etc., are |
196 segregated in distinct blocks in memory. (Vectors, buffers and certain | 210 segregated in distinct blocks in memory. (Vectors, long strings, |
197 other editing types, which are fairly large, are allocated in individual | 211 buffers and certain other editing types, which are fairly large, are |
198 blocks, one per object, while strings are packed into blocks of 8k | 212 allocated in individual blocks, one per object, while small strings are |
199 bytes.) | 213 packed into blocks of 8k bytes.) |
200 | 214 |
201 It is quite common to use some storage for a while, then release it | 215 It is quite common to use some storage for a while, then release it by |
202 by, for example, killing a buffer or deleting the last pointer to an | 216 (for example) killing a buffer or deleting the last pointer to an |
203 object. Emacs provides a @dfn{garbage collector} to reclaim this | 217 object. Emacs provides a @dfn{garbage collector} to reclaim this |
204 abandoned storage. (This name is traditional, but ``garbage recycler'' | 218 abandoned storage. (This name is traditional, but ``garbage recycler'' |
205 might be a more intuitive metaphor for this facility.) | 219 might be a more intuitive metaphor for this facility.) |
206 | 220 |
207 The garbage collector operates by scanning all the objects that have | 221 The garbage collector operates by finding and marking all Lisp objects |
208 been allocated and marking those that are still accessible to Lisp | 222 that are still accessible to Lisp programs. To begin with, it assumes |
209 programs. To begin with, all the symbols, their values and associated | 223 all the symbols, their values and associated function definitions, and |
210 function definitions, and any data presently on the stack, are | 224 any data presently on the stack, are accessible. Any objects which can |
211 accessible. Any objects which can be reached indirectly through other | 225 be reached indirectly through other accessible objects are also |
212 accessible objects are also accessible. | 226 accessible. |
213 | 227 |
214 When this is finished, all inaccessible objects are garbage. No | 228 When marking is finished, all objects still unmarked are garbage. No |
215 matter what the Lisp program or the user does, it is impossible to refer | 229 matter what the Lisp program or the user does, it is impossible to refer |
216 to them, since there is no longer a way to reach them. Their | 230 to them, since there is no longer a way to reach them. Their space |
217 space might as well be reused, since no one will notice. That is what | 231 might as well be reused, since no one will miss them. The second, |
218 the garbage collector arranges to do. | 232 ``sweep'' phase of the garbage collector arranges to reuse them. |
219 | 233 |
220 @cindex free list | 234 @cindex free list |
221 Unused cons cells are chained together onto a @dfn{free list} for | 235 The sweep phase puts unused cons cells onto a @dfn{free list} |
222 future allocation; likewise for symbols and markers. The accessible | 236 for future allocation; likewise for symbols and markers. It compacts |
223 strings are compacted so they are contiguous in memory; then the rest of | 237 the accessible strings so they occupy fewer 8k blocks; then it frees the |
224 the space formerly occupied by strings is made available to the string | 238 other 8k blocks. Vectors, buffers, windows and other large objects are |
225 creation functions. Vectors, buffers, windows and other large objects | 239 individually allocated and freed using @code{malloc} and @code{free}. |
226 are individually allocated and freed using @code{malloc}. | |
227 | 240 |
228 @cindex CL note---allocate more storage | 241 @cindex CL note---allocate more storage |
229 @quotation | 242 @quotation |
230 @b{Common Lisp note:} unlike other Lisps, GNU Emacs Lisp does not | 243 @b{Common Lisp note:} unlike other Lisps, GNU Emacs Lisp does not |
231 call the garbage collector when the free list is empty. Instead, it | 244 call the garbage collector when the free list is empty. Instead, it |
239 program does not use so much space as to force a second garbage | 252 program does not use so much space as to force a second garbage |
240 collection). | 253 collection). |
241 @end quotation | 254 @end quotation |
242 | 255 |
243 @deffn Command garbage-collect | 256 @deffn Command garbage-collect |
244 This command runs a garbage collection, and returns information on | 257 This command runs a garbage collection, and returns information on |
245 the amount of space in use. (Garbage collection can also occur | 258 the amount of space in use. (Garbage collection can also occur |
246 spontaneously if you use more than @code{gc-cons-threshold} bytes of | 259 spontaneously if you use more than @code{gc-cons-threshold} bytes of |
247 Lisp data since the previous garbage collection.) | 260 Lisp data since the previous garbage collection.) |
248 | 261 |
249 @code{garbage-collect} returns a list containing the following | 262 @code{garbage-collect} returns a list containing the following |
250 information: | 263 information: |
251 | 264 |
252 @smallexample | 265 @example |
253 @group | 266 @group |
254 ((@var{used-conses} . @var{free-conses}) | 267 ((@var{used-conses} . @var{free-conses}) |
255 (@var{used-syms} . @var{free-syms}) | 268 (@var{used-syms} . @var{free-syms}) |
269 @end group | |
256 (@var{used-markers} . @var{free-markers}) | 270 (@var{used-markers} . @var{free-markers}) |
257 @var{used-string-chars} | 271 @var{used-string-chars} |
258 @var{used-vector-slots} | 272 @var{used-vector-slots} |
259 (@var{used-floats} . @var{free-floats})) | 273 (@var{used-floats} . @var{free-floats})) |
260 | 274 |
275 @group | |
261 (garbage-collect) | 276 (garbage-collect) |
262 @result{} ((3435 . 2332) (1688 . 0) | 277 @result{} ((3435 . 2332) (1688 . 0) |
263 (57 . 417) 24510 3839 (4 . 1)) | 278 (57 . 417) 24510 3839 (4 . 1)) |
264 @end group | 279 @end group |
265 @end smallexample | 280 @end example |
266 | 281 |
267 Here is a table explaining each element: | 282 Here is a table explaining each element: |
268 | 283 |
269 @table @var | 284 @table @var |
270 @item used-conses | 285 @item used-conses |
304 operating system, but that are not currently being used. | 319 operating system, but that are not currently being used. |
305 @end table | 320 @end table |
306 @end deffn | 321 @end deffn |
307 | 322 |
308 @defopt gc-cons-threshold | 323 @defopt gc-cons-threshold |
309 The value of this variable is the number of bytes of storage that must | 324 The value of this variable is the number of bytes of storage that must |
310 be allocated for Lisp objects after one garbage collection in order to | 325 be allocated for Lisp objects after one garbage collection in order to |
311 request another garbage collection. A cons cell counts as eight bytes, | 326 trigger another garbage collection. A cons cell counts as eight bytes, |
312 a string as one byte per character plus a few bytes of overhead, and so | 327 a string as one byte per character plus a few bytes of overhead, and so |
313 on. (Space allocated to the contents of buffers does not count.) Note | 328 on; space allocated to the contents of buffers does not count. Note |
314 that the new garbage collection does not happen immediately when the | 329 that the subsequent garbage collection does not happen immediately when |
315 threshold is exhausted, but only the next time the Lisp evaluator is | 330 the threshold is exhausted, but only the next time the Lisp evaluator is |
316 called. | 331 called. |
317 | 332 |
318 The initial threshold value is 100,000. If you specify a larger | 333 The initial threshold value is 100,000. If you specify a larger |
319 value, garbage collection will happen less often. This reduces the | 334 value, garbage collection will happen less often. This reduces the |
320 amount of time spent garbage collecting, but increases total memory use. | 335 amount of time spent garbage collecting, but increases total memory use. |
321 You may want to do this when running a program which creates lots of | 336 You may want to do this when running a program which creates lots of |
322 Lisp data. | 337 Lisp data. |
323 | 338 |
324 You can make collections more frequent by specifying a smaller value, | 339 You can make collections more frequent by specifying a smaller value, |
325 down to 10,000. A value less than 10,000 will remain in effect only | 340 down to 10,000. A value less than 10,000 will remain in effect only |
326 until the subsequent garbage collection, at which time | 341 until the subsequent garbage collection, at which time |
327 @code{garbage-collect} will set the threshold back to 10,000. | 342 @code{garbage-collect} will set the threshold back to 10,000. |
328 @end defopt | 343 @end defopt |
329 | 344 |
352 | 367 |
353 @cindex garbage collection protection | 368 @cindex garbage collection protection |
354 @smallexample | 369 @smallexample |
355 @group | 370 @group |
356 DEFUN ("or", For, Sor, 0, UNEVALLED, 0, | 371 DEFUN ("or", For, Sor, 0, UNEVALLED, 0, |
357 "Eval args until one of them yields non-NIL, then return that value.\n\ | 372 "Eval args until one of them yields non-nil, then return that value.\n\ |
358 The remaining args are not evalled at all.\n\ | 373 The remaining args are not evalled at all.\n\ |
359 @end group | 374 @end group |
360 @group | 375 @group |
361 If all args return NIL, return NIL.") | 376 If all args return nil, return nil.") |
362 (args) | 377 (args) |
363 Lisp_Object args; | 378 Lisp_Object args; |
364 @{ | 379 @{ |
365 register Lisp_Object val; | 380 register Lisp_Object val; |
366 Lisp_Object args_left; | 381 Lisp_Object args_left; |
367 struct gcpro gcpro1; | 382 struct gcpro gcpro1; |
368 @end group | 383 @end group |
369 | 384 |
370 @group | 385 @group |
371 if (NULL(args)) | 386 if (NULL (args)) |
372 return Qnil; | 387 return Qnil; |
373 | 388 |
374 args_left = args; | 389 args_left = args; |
375 GCPRO1 (args_left); | 390 GCPRO1 (args_left); |
376 @end group | 391 @end group |
381 val = Feval (Fcar (args_left)); | 396 val = Feval (Fcar (args_left)); |
382 if (!NULL (val)) | 397 if (!NULL (val)) |
383 break; | 398 break; |
384 args_left = Fcdr (args_left); | 399 args_left = Fcdr (args_left); |
385 @} | 400 @} |
386 while (!NULL(args_left)); | 401 while (!NULL (args_left)); |
387 @end group | 402 @end group |
388 | 403 |
389 @group | 404 @group |
390 UNGCPRO; | 405 UNGCPRO; |
391 return val; | 406 return val; |
392 @} | 407 @} |
393 @end group | 408 @end group |
394 @end smallexample | 409 @end smallexample |
395 | 410 |
396 Let's start with a precise explanation of the arguments to the | 411 Let's start with a precise explanation of the arguments to the |
397 @code{DEFUN} macro. Here are the general names for them: | 412 @code{DEFUN} macro. Here is a template for them: |
398 | 413 |
399 @example | 414 @example |
400 DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc}) | 415 DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc}) |
401 @end example | 416 @end example |
402 | 417 |
403 @table @var | 418 @table @var |
404 @item lname | 419 @item lname |
405 This is the name of the Lisp symbol to define with this | 420 This is the name of the Lisp symbol to define as the function name; in |
406 function; in the example above, it is @code{or}. | 421 the example above, it is @code{or}. |
407 | 422 |
408 @item fname | 423 @item fname |
409 This is the C function name for this function. This is | 424 This is the C function name for this function. This is |
410 the name that is used in C code for calling the function. The name is, | 425 the name that is used in C code for calling the function. The name is, |
411 by convention, @samp{F} prepended to the Lisp name, with all dashes | 426 by convention, @samp{F} prepended to the Lisp name, with all dashes |
422 create the symbol and store the subr object as its definition. By | 437 create the symbol and store the subr object as its definition. By |
423 convention, this name is always @var{fname} with @samp{F} replaced with | 438 convention, this name is always @var{fname} with @samp{F} replaced with |
424 @samp{S}. | 439 @samp{S}. |
425 | 440 |
426 @item min | 441 @item min |
427 This is the minimum number of arguments that the function requires. For | 442 This is the minimum number of arguments that the function requires. The |
428 @code{or}, no arguments are required. | 443 function @code{or} allows a minimum of zero arguments. |
429 | 444 |
430 @item max | 445 @item max |
431 This is the maximum number of arguments that the function accepts. | 446 This is the maximum number of arguments that the function accepts, if |
432 Alternatively, it can be @code{UNEVALLED}, indicating a special form | 447 there is a fixed maximum. Alternatively, it can be @code{UNEVALLED}, |
433 that receives unevaluated arguments. A function with the equivalent of | 448 indicating a special form that receives unevaluated arguments, or |
434 an @code{&rest} argument would have @code{MANY} in this position. Both | 449 @code{MANY}, indicating an unlimited number of evaluated arguments (the |
435 @code{UNEVALLED} and @code{MANY} are macros. This argument must be one | 450 equivalent of @code{&rest}). Both @code{UNEVALLED} and @code{MANY} are |
436 of these macros or a number at least as large as @var{min}. It may not | 451 macros. If @var{max} is a number, it may not be less than @var{min} and |
437 be greater than six. | 452 it may not be greater than seven. |
438 | 453 |
439 @item interactive | 454 @item interactive |
440 This is an interactive specification, a string such as might be used as | 455 This is an interactive specification, a string such as might be used as |
441 the argument of @code{interactive} in a Lisp function. In the case of | 456 the argument of @code{interactive} in a Lisp function. In the case of |
442 @code{or}, it is 0 (a null pointer), indicating that @code{or} cannot be | 457 @code{or}, it is 0 (a null pointer), indicating that @code{or} cannot be |
443 called interactively. A value of @code{""} indicates an interactive | 458 called interactively. A value of @code{""} indicates a function that |
444 function taking no arguments. | 459 should receive no arguments when called interactively. |
445 | 460 |
446 @item doc | 461 @item doc |
447 This is the documentation string. It is written just like a | 462 This is the documentation string. It is written just like a |
448 documentation string for a function defined in Lisp, except you must | 463 documentation string for a function defined in Lisp, except you must |
449 write @samp{\n\} at the end of each line. In particular, the first line | 464 write @samp{\n\} at the end of each line. In particular, the first line |
450 should be a single sentence. | 465 should be a single sentence. |
451 @end table | 466 @end table |
452 | 467 |
453 After the call to the @code{DEFUN} macro, you must write the list | 468 After the call to the @code{DEFUN} macro, you must write the argument |
454 of argument names that every C function must have, followed by | 469 name list that every C function must have, followed by ordinary C |
455 ordinary C declarations for them. Normally, all the arguments must | 470 declarations for the arguments. For a function with a fixed maximum |
456 be declared as @code{Lisp_Object}. If the function has no upper limit | 471 number of arguments, declare a C argument for each Lisp argument, and |
457 on the number of arguments in Lisp, then in C it receives two arguments: | 472 give them all type @code{Lisp_Object}. If the function has no upper |
458 the number of Lisp arguments, and the address of a block containing their | 473 limit on the number of arguments in Lisp, then in C it receives two |
459 values. These have types @code{int} and @w{@code{Lisp_Object *}}. | 474 arguments: the first is the number of Lisp arguments, and the second is |
475 the address of a block containing their values. They have types | |
476 @code{int} and @w{@code{Lisp_Object *}}. | |
460 | 477 |
461 Within the function @code{For} itself, note the use of the macros | 478 Within the function @code{For} itself, note the use of the macros |
462 @code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to ``protect'' | 479 @code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to ``protect'' |
463 a variable from garbage collection---to inform the garbage collector that | 480 a variable from garbage collection---to inform the garbage collector that |
464 it must look in that variable and regard its contents as an accessible | 481 it must look in that variable and regard its contents as an accessible |
466 that can directly or indirectly call @code{Feval}. At such a time, any | 483 that can directly or indirectly call @code{Feval}. At such a time, any |
467 Lisp object that you intend to refer to again must be protected somehow. | 484 Lisp object that you intend to refer to again must be protected somehow. |
468 @code{UNGCPRO} cancels the protection of the variables that are | 485 @code{UNGCPRO} cancels the protection of the variables that are |
469 protected in the current function. It is necessary to do this explicitly. | 486 protected in the current function. It is necessary to do this explicitly. |
470 | 487 |
471 For most data types, it suffices to know that one pointer to the | 488 For most data types, it suffices to protect at least one pointer to |
472 object is protected; as long as the object is not recycled, all pointers | 489 the object; as long as the object is not recycled, all pointers to it |
473 to it remain valid. This is not so for strings, because the garbage | 490 remain valid. This is not so for strings, because the garbage collector |
474 collector can move them. When a string is moved, any pointers to it | 491 can move them. When the garbage collector moves a string, it relocates |
475 that the garbage collector does not know about will not be properly | 492 all the pointers it knows about; any other pointers become invalid. |
476 relocated. Therefore, all pointers to strings must be protected across | 493 Therefore, you must protect all pointers to strings across any point |
477 any point where garbage collection may be possible. | 494 where garbage collection may be possible. |
478 | 495 |
479 The macro @code{GCPRO1} protects just one local variable. If you | 496 The macro @code{GCPRO1} protects just one local variable. If you want |
480 want to protect two, use @code{GCPRO2} instead; repeating @code{GCPRO1} | 497 to protect two, use @code{GCPRO2} instead; repeating @code{GCPRO1} will |
481 will not work. There are also @code{GCPRO3} and @code{GCPRO4}. | 498 not work. Macros @code{GCPRO3} and @code{GCPRO4} also exist. |
482 | 499 |
483 In addition to using these macros, you must declare the local | 500 These macros implicitly use local variables such as @code{gcpro1}; you |
484 variables such as @code{gcpro1} which they implicitly use. If you | 501 must declare these explicitly, with type @code{struct gcpro}. Thus, if |
485 protect two variables, with @code{GCPRO2}, you must declare | 502 you use @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}. |
486 @code{gcpro1} and @code{gcpro2}, as it uses them both. Alas, we can't | 503 Alas, we can't explain all the tricky details here. |
487 explain all the tricky details here. | 504 |
488 | 505 Defining the C function is not enough to make a Lisp primitive |
489 Defining the C function is not enough; you must also create the | 506 available; you must also create the Lisp symbol for the primitive and |
490 Lisp symbol for the primitive and store a suitable subr object | 507 store a suitable subr object in its function cell. The code looks like |
491 in its function cell. This is done by adding code to an initialization | 508 this: |
492 routine. The code looks like this: | |
493 | 509 |
494 @example | 510 @example |
495 defsubr (&@var{subr-structure-name}); | 511 defsubr (&@var{subr-structure-name}); |
496 @end example | 512 @end example |
497 | 513 |
498 @noindent | 514 @noindent |
499 @var{subr-structure-name} is the name you used as the third argument to | 515 Here @var{subr-structure-name} is the name you used as the third |
500 @code{DEFUN}. | 516 argument to @code{DEFUN}. |
501 | 517 |
502 If you are adding a primitive to a file that already has Lisp | 518 If you add a new primitive to a file that already has Lisp primitives |
503 primitives defined in it, find the function (near the end of the file) | 519 defined in it, find the function (near the end of the file) named |
504 named @code{syms_of_@var{something}}, and add that function call to it. | 520 @code{syms_of_@var{something}}, and add the call to @code{defsubr} |
505 If the file doesn't have this function, or if you create a new file, add | 521 there. If the file doesn't have this function, or if you create a new |
506 to it a @code{syms_of_@var{filename}} (e.g., @code{syms_of_myfile}). | 522 file, add to it a @code{syms_of_@var{filename}} (e.g., |
507 Then find the spot in @file{emacs.c} where all of these functions are | 523 @code{syms_of_myfile}). Then find the spot in @file{emacs.c} where all |
508 called, and add a call to @code{syms_of_@var{filename}} there. | 524 of these functions are called, and add a call to |
525 @code{syms_of_@var{filename}} there. | |
509 | 526 |
510 This function @code{syms_of_@var{filename}} is also the place to | 527 This function @code{syms_of_@var{filename}} is also the place to |
511 define any C variables which are to be visible as Lisp variables. | 528 define any C variables which are to be visible as Lisp variables. |
512 @code{DEFVAR_LISP} is used to make a C variable of type | 529 @code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible |
513 @code{Lisp_Object} visible in Lisp. @code{DEFVAR_INT} is used to make a | 530 in Lisp. @code{DEFVAR_INT} makes a C variable of type @code{int} |
514 C variable of type @code{int} visible in Lisp with a value that is an | 531 visible in Lisp with a value that is always an integer. |
515 integer. | 532 @code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp |
516 | 533 with a value that is either @code{t} or @code{nil}. |
517 Here is another function, with more complicated arguments. This comes | 534 |
518 from the code for the X Window System, and it demonstrates the use of | 535 Here is another example function, with more complicated arguments. |
519 macros and functions to manipulate Lisp objects. | 536 This comes from the code for the X Window System, and it demonstrates |
537 the use of macros and functions to manipulate Lisp objects. | |
520 | 538 |
521 @smallexample | 539 @smallexample |
522 @group | 540 @group |
523 DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p, | 541 DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p, |
524 Scoordinates_in_window_p, 2, 2, | 542 Scoordinates_in_window_p, 2, 2, |
545 @end group | 563 @end group |
546 @group | 564 @group |
547 if ((XINT (xcoord) < XINT (XWINDOW (window)->left)) | 565 if ((XINT (xcoord) < XINT (XWINDOW (window)->left)) |
548 || (XINT (xcoord) >= (XINT (XWINDOW (window)->left) | 566 || (XINT (xcoord) >= (XINT (XWINDOW (window)->left) |
549 + XINT (XWINDOW (window)->width)))) | 567 + XINT (XWINDOW (window)->width)))) |
550 @{ | 568 return Qnil; |
551 return Qnil; | |
552 @} | |
553 XFASTINT (xcoord) -= XFASTINT (XWINDOW (window)->left); | 569 XFASTINT (xcoord) -= XFASTINT (XWINDOW (window)->left); |
554 @end group | 570 @end group |
555 @group | 571 @group |
556 if (XINT (ycoord) == (screen_height - 1)) | 572 if (XINT (ycoord) == (screen_height - 1)) |
557 return Qnil; | 573 return Qnil; |
558 @end group | 574 @end group |
559 @group | 575 @group |
560 if ((XINT (ycoord) < XINT (XWINDOW (window)->top)) | 576 if ((XINT (ycoord) < XINT (XWINDOW (window)->top)) |
561 || (XINT (ycoord) >= (XINT (XWINDOW (window)->top) | 577 || (XINT (ycoord) >= (XINT (XWINDOW (window)->top) |
562 + XINT (XWINDOW (window)->height)) - 1)) | 578 + XINT (XWINDOW (window)->height)) - 1)) |
563 @{ | 579 return Qnil; |
564 return Qnil; | |
565 @} | |
566 @end group | 580 @end group |
567 @group | 581 @group |
568 XFASTINT (ycoord) -= XFASTINT (XWINDOW (window)->top); | 582 XFASTINT (ycoord) -= XFASTINT (XWINDOW (window)->top); |
569 return (Fcons (xcoord, Fcons (ycoord, Qnil))); | 583 return (Fcons (xcoord, Fcons (ycoord, Qnil))); |
570 @} | 584 @} |
571 @end group | 585 @end group |
572 @end smallexample | 586 @end smallexample |
573 | 587 |
574 Note that you cannot directly call functions defined in Lisp as, for | 588 Note that C code cannot call functions by name unless they are defined |
575 example, the primitive function @code{Fcons} is called above. You must | 589 in C. The way to call a function written in Lisp is to use |
576 create the appropriate Lisp form, protect everything from garbage | 590 @code{Ffuncall}, which embodies the Lisp function @code{funcall}. Since |
577 collection, and @code{Feval} the form, as was done in @code{For} above. | 591 the Lisp function @code{funcall} accepts an unlimited number of |
592 arguments, in C it takes two: the number of Lisp-level arguments, and a | |
593 one-dimensional array containing their values. The first Lisp-level | |
594 argument is the Lisp function to call, and the rest are the arguments to | |
595 pass to it. Since @code{Ffuncall} can call the evaluator, you must | |
596 protect pointers from garbage collection around the call to | |
597 @code{Ffuncall}. | |
598 | |
599 The C functions @code{call0}, @code{call1}, @code{call2}, and so on, | |
600 provide handy ways to call a Lisp function conveniently with a fixed | |
601 number of arguments. They work by calling @code{Ffuncall}. | |
578 | 602 |
579 @file{eval.c} is a very good file to look through for examples; | 603 @file{eval.c} is a very good file to look through for examples; |
580 @file{lisp.h} contains the definitions for some important macros and | 604 @file{lisp.h} contains the definitions for some important macros and |
581 functions. | 605 functions. |
582 | 606 |
590 implementations. Depending on the operating system and type of machine | 614 implementations. Depending on the operating system and type of machine |
591 for which you compile Emacs, twenty-four to twenty-six bits are used to | 615 for which you compile Emacs, twenty-four to twenty-six bits are used to |
592 address the object, and the remaining six to eight bits are used for a | 616 address the object, and the remaining six to eight bits are used for a |
593 tag that identifies the object's type. | 617 tag that identifies the object's type. |
594 | 618 |
595 Because all access to data is through tagged pointers, it is always | 619 Because Lisp objects are represented as tagged pointers, it is always |
596 possible to determine the type of any object. This allows variables to | 620 possible to determine the Lisp data type of any object. The C data type |
597 be untyped, and the values assigned to them to be changed without regard | 621 @code{Lisp_Object} can hold any Lisp object of any data type. Ordinary |
598 to type. Function arguments also can be of any type; if you want a | 622 variables have type @code{Lisp_Object}, which means they can hold any |
599 function to accept only a certain type of argument, you must check the | 623 type of Lisp value; you can determine the actual data type only at run |
600 type explicitly using a suitable predicate (@pxref{Type Predicates}). | 624 time. The same is true for function arguments; if you want a function |
625 to accept only a certain type of argument, you must check the type | |
626 explicitly using a suitable predicate (@pxref{Type Predicates}). | |
601 @cindex type checking internals | 627 @cindex type checking internals |
602 | 628 |
603 @menu | 629 @menu |
604 * Buffer Internals:: Components of a buffer structure. | 630 * Buffer Internals:: Components of a buffer structure. |
605 * Window Internals:: Components of a window structure. | 631 * Window Internals:: Components of a window structure. |
635 | 661 |
636 @item last_window_start | 662 @item last_window_start |
637 This field contains the @code{window-start} position in the buffer as of | 663 This field contains the @code{window-start} position in the buffer as of |
638 the last time the buffer was displayed in a window. | 664 the last time the buffer was displayed in a window. |
639 | 665 |
640 @item undodata | 666 @item undo_list |
641 This field points to the buffer's undo stack. @xref{Undo}. | 667 This field points to the buffer's undo list. @xref{Undo}. |
642 | 668 |
643 @item syntax_table_v | 669 @item syntax_table_v |
644 This field contains the syntax table for the buffer. @xref{Syntax Tables}. | 670 This field contains the syntax table for the buffer. @xref{Syntax Tables}. |
645 | 671 |
646 @item downcase_table | 672 @item downcase_table |
662 @item display_table | 688 @item display_table |
663 This field contains the buffer's display table, or @code{nil} if it doesn't | 689 This field contains the buffer's display table, or @code{nil} if it doesn't |
664 have one. @xref{Display Tables}. | 690 have one. @xref{Display Tables}. |
665 | 691 |
666 @item markers | 692 @item markers |
667 This field contains the chain of all markers that point into the | 693 This field contains the chain of all markers that currently point into |
668 buffer. At each deletion or motion of the buffer gap, all of these | 694 the buffer. Deletion of text in the buffer, and motion of the buffer's |
669 markers must be checked and perhaps updated. @xref{Markers}. | 695 gap, must check each of these markers and perhaps update it. |
696 @xref{Markers}. | |
670 | 697 |
671 @item backed_up | 698 @item backed_up |
672 This field is a flag which tells whether a backup file has been made | 699 This field is a flag which tells whether a backup file has been made |
673 for the visited file of this buffer. | 700 for the visited file of this buffer. |
674 | 701 |
675 @item mark | 702 @item mark |
676 This field contains the mark for the buffer. The mark is a marker, | 703 This field contains the mark for the buffer. The mark is a marker, |
677 hence it is also included on the list @code{markers}. @xref{The Mark}. | 704 hence it is also included on the list @code{markers}. @xref{The Mark}. |
678 | 705 |
706 @item mark_active | |
707 This field is non-@code{nil} if the buffer's mark is active. | |
708 | |
679 @item local_var_alist | 709 @item local_var_alist |
680 This field contains the association list containing all of the variables | 710 This field contains the association list describing the variables local |
681 local in this buffer, and their values. The function | 711 in this buffer, and their values, with the exception of local variables |
682 @code{buffer-local-variables} returns a copy of this list. | 712 that have special slots in the buffer object. (Those slots are omitted |
683 @xref{Buffer-Local Variables}. | 713 from this table.) @xref{Buffer-Local Variables}. |
684 | 714 |
685 @item mode_line_format | 715 @item keymap |
686 This field contains a Lisp object which controls how to display the mode | 716 This field holds the buffer's local keymap. @xref{Keymaps}. |
687 line for this buffer. @xref{Mode Line Format}. | 717 |
718 @item overlay_center | |
719 This field holds the current overlay center position. @xref{Overlays}. | |
720 | |
721 @item overlays_before | |
722 This field holds a list of the overlays in this buffer that end at or | |
723 before the current overlay center position. They are sorted in order of | |
724 decreasing end position. | |
725 | |
726 @item overlays_after | |
727 This field holds a list of the overlays in this buffer that end after | |
728 the current overlay center position. They are sorted in order of | |
729 increasing beginning position. | |
688 @end table | 730 @end table |
689 | 731 |
690 @node Window Internals, Process Internals, Buffer Internals, Object Internals | 732 @node Window Internals, Process Internals, Buffer Internals, Object Internals |
691 @appendixsubsec Window Internals | 733 @appendixsubsec Window Internals |
692 @cindex internals, of window | 734 @cindex internals, of window |
694 | 736 |
695 Windows have the following accessible fields: | 737 Windows have the following accessible fields: |
696 | 738 |
697 @table @code | 739 @table @code |
698 @item frame | 740 @item frame |
699 The frame that this window is on. | 741 The frame that this window is on. |
700 | 742 |
701 @item mini_p | 743 @item mini_p |
702 Non-@code{nil} if this window is a minibuffer window. | 744 Non-@code{nil} if this window is a minibuffer window. |
703 | |
704 @item height | |
705 The height of the window, measured in lines. | |
706 | |
707 @item width | |
708 The width of the window, measured in columns. | |
709 | 745 |
710 @item buffer | 746 @item buffer |
711 The buffer which the window is displaying. This may change often during | 747 The buffer which the window is displaying. This may change often during |
712 the life of the window. | 748 the life of the window. |
713 | 749 |
714 @item dedicated | 750 @item dedicated |
715 Non-@code{nil} if this window is dedicated to its buffer. | 751 Non-@code{nil} if this window is dedicated to its buffer. |
716 | |
717 @item start | |
718 The position in the buffer which is the first character to be displayed | |
719 in the window. | |
720 | 752 |
721 @item pointm | 753 @item pointm |
722 @cindex window point internals | 754 @cindex window point internals |
723 This is the value of point in the current buffer when this window is | 755 This is the value of point in the current buffer when this window is |
724 selected; when it is not selected, it retains its previous value. | 756 selected; when it is not selected, it retains its previous value. |
725 | 757 |
758 @item start | |
759 he position in the buffer which is the first character to be displayed | |
760 in the window. | |
761 | |
762 @item force_start | |
763 If this flag is non-@code{nil}, it says that the window has been | |
764 scrolled explicitly by the Lisp program. This affects what the next | |
765 redisplay does if point is off the screen: instead of scrolling the | |
766 window to show the text around point, it moves point to a location that | |
767 is on the screen. | |
768 | |
769 @item last_modified | |
770 The @code{modified} field of the window's buffer, as of the last time | |
771 a redisplay completed in this window. | |
772 | |
773 @item last_point | |
774 The buffer's value of point, as of the last time | |
775 a redisplay completed in this window. | |
776 | |
726 @item left | 777 @item left |
727 This is the left-hand edge of the window, measured in columns. (The | 778 This is the left-hand edge of the window, measured in columns. (The |
728 leftmost column on the screen is @w{column 0}.) | 779 leftmost column on the screen is @w{column 0}.) |
729 | 780 |
730 @item top | 781 @item top |
731 This is the top edge of the window, measured in lines. (The top line on | 782 This is the top edge of the window, measured in lines. (The top line on |
732 the screen is @w{line 0}.) | 783 the screen is @w{line 0}.) |
733 | 784 |
785 @item height | |
786 The height of the window, measured in lines. | |
787 | |
788 @item width | |
789 The width of the window, measured in columns. | |
790 | |
734 @item next | 791 @item next |
735 This is the window that is the next in the chain of siblings. | 792 This is the window that is the next in the chain of siblings. It is |
793 @code{nil} in a window that is the rightmost or bottommost of a group of | |
794 siblings. | |
736 | 795 |
737 @item prev | 796 @item prev |
738 This is the window that is the previous in the chain of siblings. | 797 This is the window that is the previous in the chain of siblings. It is |
739 | 798 @code{nil} in a window that is the leftmost or topmost of a group of |
740 @item force_start | 799 siblings. |
741 This is a flag which, if non-@code{nil}, says that the window has been | 800 |
742 scrolled explicitly by the Lisp program. At the next redisplay, if | 801 @item parent |
743 point is off the screen, instead of scrolling the window to show the | 802 Internally, Emacs arranges windows in a tree; each group of siblings has |
744 text around point, point will be moved to a location that is on the | 803 a parent window whose area includes all the siblings. This field points |
745 screen. | 804 to a window's parent. |
805 | |
806 Parent windows do not display buffers, and play little role in display | |
807 except to shape their child windows. Emacs Lisp programs usually have | |
808 no access to the parent windows; they operate on the windows at the | |
809 leaves of the tree, that actually display buffers. | |
746 | 810 |
747 @item hscroll | 811 @item hscroll |
748 This is the number of columns that the display in the window is scrolled | 812 This is the number of columns that the display in the window is scrolled |
749 horizontally to the left. Normally, this is 0. | 813 horizontally to the left. Normally, this is 0. |
750 | 814 |
751 @item use_time | 815 @item use_time |
752 This is the last time that the window was selected. The function | 816 This is the last time that the window was selected. The function |
753 @code{get-lru-window} uses this field. | 817 @code{get-lru-window} uses this field. |
754 | 818 |
755 @item display_table | 819 @item display_table |
756 The window's display table, or @code{nil} if none is specified for it. | 820 The window's display table, or @code{nil} if none is specified for it. |
821 | |
822 @item update_mode_line | |
823 Non-@code{nil} means this window's mode line needs to be updated. | |
824 | |
825 @item base_line_number | |
826 The line number of a certain position in the buffer, or @code{nil}. | |
827 This is used for displaying the line number of point in the mode line. | |
828 | |
829 @item base_line_pos | |
830 The position in the buffer for which the line number is known, or | |
831 @code{nil} meaning none is known. | |
832 | |
833 @item region_showing | |
834 If the region (or part of it) is highlighted in this window, this field | |
835 holds the mark position that made one end of that region. Otherwise, | |
836 this field is @code{nil}. | |
757 @end table | 837 @end table |
758 | 838 |
759 @node Process Internals, , Window Internals, Object Internals | 839 @node Process Internals, , Window Internals, Object Internals |
760 @appendixsubsec Process Internals | 840 @appendixsubsec Process Internals |
761 @cindex internals, of process | 841 @cindex internals, of process |
786 | 866 |
787 @item childp | 867 @item childp |
788 A flag, non-@code{nil} if this is really a child process. | 868 A flag, non-@code{nil} if this is really a child process. |
789 It is @code{nil} for a network connection. | 869 It is @code{nil} for a network connection. |
790 | 870 |
791 @item flags | |
792 A symbol indicating the state of the process. Possible values include | |
793 @code{run}, @code{stop}, @code{closed}, etc. | |
794 | |
795 @item reason | |
796 An integer, the Unix signal number that the process received that | |
797 caused the process to terminate or stop. If the process has exited, | |
798 then this is the exit code it specified. | |
799 | |
800 @item mark | 871 @item mark |
801 A marker indicating the position of end of last output from this process | 872 A marker indicating the position of end of last output from this process |
802 inserted into the buffer. This is usually the end of the buffer. | 873 inserted into the buffer. This is usually the end of the buffer. |
803 | 874 |
804 @item kill_without_query | 875 @item kill_without_query |
805 A flag, non-@code{nil} meaning this process should not cause | 876 If this is non-@code{nil}, killing Emacs while this process is still |
806 confirmation to be needed if Emacs is killed. | 877 running does not ask for confirmation about killing the process. |
878 | |
879 @item raw_status_low | |
880 @itemx raw_status_high | |
881 These two fields record 16 bits each of the process status returned by | |
882 the @code{wait} system call. | |
883 | |
884 @item status | |
885 The process status, as @code{process-status} should return it. | |
886 | |
887 @item tick | |
888 @itemx update_tick | |
889 If these two fields are not equal, a change in the status of the process | |
890 needs to be reported, either by running the sentinel or by inserting a | |
891 message in the process buffer. | |
892 | |
893 @item pty_flag | |
894 Non-@code{nil} if communication with the subprocess uses a @sc{pty}; | |
895 @code{nil} if it uses a pipe. | |
896 | |
897 @item infd | |
898 The file descriptor for input from the process. | |
899 | |
900 @item outfd | |
901 The file descriptor for output to the process. | |
902 | |
903 @item subtty | |
904 The file descriptor for the terminal that the subprocess is using. (On | |
905 some systems, there is no need to record this, so the value is | |
906 @code{nil}.) | |
807 @end table | 907 @end table |