2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1998 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
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.
15 * Building Emacs:: How to the dumped Emacs is made.
16 * Pure Storage:: A kludge to make preloaded Lisp functions sharable.
17 * Garbage Collection:: Reclaiming space for Lisp objects no longer used.
18 * Memory Usage:: Info about total size of Lisp objects made so far.
19 * Writing Emacs Primitives:: Writing C code for Emacs.
20 * Object Internals:: Data formats of buffers, windows, processes.
24 @appendixsec Building Emacs
25 @cindex building Emacs
28 This section explains the steps involved in building the Emacs
29 executable. You don't have to know this material to build and install
30 Emacs, since the makefiles do all these things automatically. This
31 information is pertinent to Emacs maintenance.
33 Compilation of the C source files in the @file{src} directory
34 produces an executable file called @file{temacs}, also called a
35 @dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and I/O
36 routines, but not the editing commands.
38 @cindex @file{loadup.el}
39 The command @w{@samp{temacs -l loadup}} uses @file{temacs} to create
40 the real runnable Emacs executable. These arguments direct
41 @file{temacs} to evaluate the Lisp files specified in the file
42 @file{loadup.el}. These files set up the normal Emacs editing
43 environment, resulting in an Emacs that is still impure but no longer
46 It takes a substantial time to load the standard Lisp files. Luckily,
47 you don't have to do this each time you run Emacs; @file{temacs} can
48 dump out an executable program called @file{emacs} that has these files
49 preloaded. @file{emacs} starts more quickly because it does not need to
50 load the files. This is the Emacs executable that is normally
53 To create @file{emacs}, use the command @samp{temacs -batch -l loadup
54 dump}. The purpose of @samp{-batch} here is to prevent @file{temacs}
55 from trying to initialize any of its data on the terminal; this ensures
56 that the tables of terminal information are empty in the dumped Emacs.
57 The argument @samp{dump} tells @file{loadup.el} to dump a new executable
60 Some operating systems don't support dumping. On those systems, you
61 must start Emacs with the @samp{temacs -l loadup} command each time you
62 use it. This takes a substantial time, but since you need to start
63 Emacs once a day at most---or once a week if you never log out---the
64 extra time is not too severe a problem.
66 @cindex @file{site-load.el}
67 You can specify additional files to preload by writing a library named
68 @file{site-load.el} that loads them. You may need to increase the value
69 of @code{PURESIZE}, in @file{src/puresize.h}, to make room for the
70 additional data. (Try adding increments of 20000 until it is big
71 enough.) However, the advantage of preloading additional files
72 decreases as machines get faster. On modern machines, it is usually not
75 After @file{loadup.el} reads @file{site-load.el}, it finds the
76 documentation strings for primitive and preloaded functions (and
77 variables) in the file @file{etc/DOC} where they are stored, by calling
78 @code{Snarf-documentation} (@pxref{Accessing Documentation}).
80 @cindex @file{site-init.el}
81 You can specify other Lisp expressions to execute just before dumping
82 by putting them in a library named @file{site-init.el}. This file is
83 executed after the documentation strings are found.
85 If you want to preload function or variable definitions, there are
86 three ways you can do this and make their documentation strings
87 accessible when you subsequently run Emacs:
91 Arrange to scan these files when producing the @file{etc/DOC} file,
92 and load them with @file{site-load.el}.
95 Load the files with @file{site-init.el}, then copy the files into the
96 installation directory for Lisp files when you install Emacs.
99 Specify a non-@code{nil} value for
100 @code{byte-compile-dynamic-docstrings} as a local variable in each these
101 files, and load them with either @file{site-load.el} or
102 @file{site-init.el}. (This method has the drawback that the
103 documentation strings take up space in Emacs all the time.)
106 It is not advisable to put anything in @file{site-load.el} or
107 @file{site-init.el} that would alter any of the features that users
108 expect in an ordinary unmodified Emacs. If you feel you must override
109 normal features for your site, do it with @file{default.el}, so that
110 users can override your changes if they wish. @xref{Start-up Summary}.
112 @defun dump-emacs to-file from-file
114 This function dumps the current state of Emacs into an executable file
115 @var{to-file}. It takes symbols from @var{from-file} (this is normally
116 the executable file @file{temacs}).
118 If you want to use this function in an Emacs that was already dumped,
119 you must run Emacs with @samp{-batch}.
123 @appendixsec Pure Storage
126 Emacs Lisp uses two kinds of storage for user-created Lisp objects:
127 @dfn{normal storage} and @dfn{pure storage}. Normal storage is where
128 all the new data created during an Emacs session is kept; see the
129 following section for information on normal storage. Pure storage is
130 used for certain data in the preloaded standard Lisp files---data that
131 should never change during actual use of Emacs.
133 Pure storage is allocated only while @file{temacs} is loading the
134 standard preloaded Lisp libraries. In the file @file{emacs}, it is
135 marked as read-only (on operating systems that permit this), so that
136 the memory space can be shared by all the Emacs jobs running on the
137 machine at once. Pure storage is not expandable; a fixed amount is
138 allocated when Emacs is compiled, and if that is not sufficient for the
139 preloaded libraries, @file{temacs} crashes. If that happens, you must
140 increase the compilation parameter @code{PURESIZE} in the file
141 @file{src/puresize.h}. This normally won't happen unless you try to
142 preload additional libraries or add features to the standard ones.
144 @defun purecopy object
145 This function makes a copy of @var{object} in pure storage and returns
146 it. It copies strings by simply making a new string with the same
147 characters in pure storage. It recursively copies the contents of
148 vectors and cons cells. It does not make copies of other objects such
149 as symbols, but just returns them unchanged. It signals an error if
150 asked to copy markers.
152 This function is a no-op except while Emacs is being built and dumped;
153 it is usually called only in the file @file{emacs/lisp/loaddefs.el}, but
154 a few packages call it just in case you decide to preload them.
157 @defvar pure-bytes-used
158 The value of this variable is the number of bytes of pure storage
159 allocated so far. Typically, in a dumped Emacs, this number is very
160 close to the total amount of pure storage available---if it were not,
161 we would preallocate less.
165 This variable determines whether @code{defun} should make a copy of the
166 function definition in pure storage. If it is non-@code{nil}, then the
167 function definition is copied into pure storage.
169 This flag is @code{t} while loading all of the basic functions for
170 building Emacs initially (allowing those functions to be sharable and
171 non-collectible). Dumping Emacs as an executable always writes
172 @code{nil} in this variable, regardless of the value it actually has
173 before and after dumping.
175 You should not change this flag in a running Emacs.
178 @node Garbage Collection
179 @appendixsec Garbage Collection
180 @cindex garbage collector
182 @cindex memory allocation
183 When a program creates a list or the user defines a new function (such
184 as by loading a library), that data is placed in normal storage. If
185 normal storage runs low, then Emacs asks the operating system to
186 allocate more memory in blocks of 1k bytes. Each block is used for one
187 type of Lisp object, so symbols, cons cells, markers, etc., are
188 segregated in distinct blocks in memory. (Vectors, long strings,
189 buffers and certain other editing types, which are fairly large, are
190 allocated in individual blocks, one per object, while small strings are
191 packed into blocks of 8k bytes.)
193 It is quite common to use some storage for a while, then release it by
194 (for example) killing a buffer or deleting the last pointer to an
195 object. Emacs provides a @dfn{garbage collector} to reclaim this
196 abandoned storage. (This name is traditional, but ``garbage recycler''
197 might be a more intuitive metaphor for this facility.)
199 The garbage collector operates by finding and marking all Lisp objects
200 that are still accessible to Lisp programs. To begin with, it assumes
201 all the symbols, their values and associated function definitions, and
202 any data presently on the stack, are accessible. Any objects that can
203 be reached indirectly through other accessible objects are also
206 When marking is finished, all objects still unmarked are garbage. No
207 matter what the Lisp program or the user does, it is impossible to refer
208 to them, since there is no longer a way to reach them. Their space
209 might as well be reused, since no one will miss them. The second
210 (``sweep'') phase of the garbage collector arranges to reuse them.
213 The sweep phase puts unused cons cells onto a @dfn{free list}
214 for future allocation; likewise for symbols and markers. It compacts
215 the accessible strings so they occupy fewer 8k blocks; then it frees the
216 other 8k blocks. Vectors, buffers, windows, and other large objects are
217 individually allocated and freed using @code{malloc} and @code{free}.
219 @cindex CL note---allocate more storage
221 @b{Common Lisp note:} Unlike other Lisps, GNU Emacs Lisp does not
222 call the garbage collector when the free list is empty. Instead, it
223 simply requests the operating system to allocate more storage, and
224 processing continues until @code{gc-cons-threshold} bytes have been
227 This means that you can make sure that the garbage collector will not
228 run during a certain portion of a Lisp program by calling the garbage
229 collector explicitly just before it (provided that portion of the
230 program does not use so much space as to force a second garbage
234 @deffn Command garbage-collect
235 This command runs a garbage collection, and returns information on
236 the amount of space in use. (Garbage collection can also occur
237 spontaneously if you use more than @code{gc-cons-threshold} bytes of
238 Lisp data since the previous garbage collection.)
240 @code{garbage-collect} returns a list containing the following
245 ((@var{used-conses} . @var{free-conses})
246 (@var{used-syms} . @var{free-syms})
248 (@var{used-miscs} . @var{free-miscs})
249 @var{used-string-chars}
250 @var{used-vector-slots}
251 (@var{used-floats} . @var{free-floats})
252 (@var{used-intervals} . @var{free-intervals}))
260 @result{} ((106886 . 13184) (9769 . 0)
261 (7731 . 4651) 347543 121628
262 (31 . 94) (1273 . 168))
266 Here is a table explaining each element:
270 The number of cons cells in use.
273 The number of cons cells for which space has been obtained from the
274 operating system, but that are not currently being used.
277 The number of symbols in use.
280 The number of symbols for which space has been obtained from the
281 operating system, but that are not currently being used.
284 The number of miscellaneous objects in use. These include markers and
285 overlays, plus certain objects not visible to users.
288 The number of miscellaneous objects for which space has been obtained
289 from the operating system, but that are not currently being used.
291 @item used-string-chars
292 The total size of all strings, in characters.
294 @item used-vector-slots
295 The total number of elements of existing vectors.
299 The number of floats in use.
303 The number of floats for which space has been obtained from the
304 operating system, but that are not currently being used.
307 The number of intervals in use. Intervals are an internal
308 data structure used for representing text properties.
311 The number of intervals for which space has been obtained
312 from the operating system, but that are not currently being used.
316 @defopt garbage-collection-messages
317 If this variable is non-@code{nil}, Emacs displays a message at the
318 beginning and end of garbage collection. The default value is
319 @code{nil}, meaning there are no such messages.
322 @defopt gc-cons-threshold
323 The value of this variable is the number of bytes of storage that must
324 be allocated for Lisp objects after one garbage collection in order to
325 trigger another garbage collection. A cons cell counts as eight bytes,
326 a string as one byte per character plus a few bytes of overhead, and so
327 on; space allocated to the contents of buffers does not count. Note
328 that the subsequent garbage collection does not happen immediately when
329 the threshold is exhausted, but only the next time the Lisp evaluator is
332 The initial threshold value is 400,000. If you specify a larger
333 value, garbage collection will happen less often. This reduces the
334 amount of time spent garbage collecting, but increases total memory use.
335 You may want to do this when running a program that creates lots of
338 You can make collections more frequent by specifying a smaller value,
339 down to 10,000. A value less than 10,000 will remain in effect only
340 until the subsequent garbage collection, at which time
341 @code{garbage-collect} will set the threshold back to 10,000.
344 The value return by @code{garbage-collect} describes the amount of
345 memory used by Lisp data, broken down by data type. By contrast, the
346 function @code{memory-limit} provides information on the total amount of
347 memory Emacs is currently using.
351 This function returns the address of the last byte Emacs has allocated,
352 divided by 1024. We divide the value by 1024 to make sure it fits in a
355 You can use this to get a general idea of how your actions affect the
360 @section Memory Usage
362 These functions and variables give information about the total amount
363 of memory allocation that Emacs has done, broken down by data type.
364 Note the difference between these and the values returned by
365 @code{(garbage-collect)}; those count objects that currently exist, but
366 these count the number or size of all allocations, including those for
367 objects that have since been freed.
369 @defvar cons-cells-consed
370 The total number of cons cells that have been allocated so far
371 in this Emacs session.
374 @defvar floats-consed
375 The total number of floats that have been allocated so far
376 in this Emacs session.
379 @defvar vector-cells-consed
380 The total number of vector cells that have been allocated so far
381 in this Emacs session.
384 @defvar symbols-consed
385 The total number of symbols that have been allocated so far
386 in this Emacs session.
389 @defvar string-chars-consed
390 The total number of string characters that have been allocated so far
391 in this Emacs session.
394 @defvar misc-objects-consed
395 The total number of miscellaneous objects that have been allocated so
396 far in this Emacs session. These include markers and overlays, plus
397 certain objects not visible to users.
400 @defvar intervals-consed
401 The total number of intervals that have been allocated so far
402 in this Emacs session.
405 @node Writing Emacs Primitives
406 @appendixsec Writing Emacs Primitives
407 @cindex primitive function internals
409 Lisp primitives are Lisp functions implemented in C. The details of
410 interfacing the C function so that Lisp can call it are handled by a few
411 C macros. The only way to really understand how to write new C code is
412 to read the source, but we can explain some things here.
414 An example of a special form is the definition of @code{or}, from
415 @file{eval.c}. (An ordinary function would have the same general
418 @cindex garbage collection protection
421 DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
422 "Eval args until one of them yields non-nil; return that value.\n\
423 The remaining args are not evalled at all.\n\
426 If all args return nil, return nil.")
430 register Lisp_Object val;
431 Lisp_Object args_left;
446 val = Feval (Fcar (args_left));
449 args_left = Fcdr (args_left);
451 while (!NULL (args_left));
461 Let's start with a precise explanation of the arguments to the
462 @code{DEFUN} macro. Here is a template for them:
465 DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc})
470 This is the name of the Lisp symbol to define as the function name; in
471 the example above, it is @code{or}.
474 This is the C function name for this function. This is
475 the name that is used in C code for calling the function. The name is,
476 by convention, @samp{F} prepended to the Lisp name, with all dashes
477 (@samp{-}) in the Lisp name changed to underscores. Thus, to call this
478 function from C code, call @code{For}. Remember that the arguments must
479 be of type @code{Lisp_Object}; various macros and functions for creating
480 values of type @code{Lisp_Object} are declared in the file
484 This is a C variable name to use for a structure that holds the data for
485 the subr object that represents the function in Lisp. This structure
486 conveys the Lisp symbol name to the initialization routine that will
487 create the symbol and store the subr object as its definition. By
488 convention, this name is always @var{fname} with @samp{F} replaced with
492 This is the minimum number of arguments that the function requires. The
493 function @code{or} allows a minimum of zero arguments.
496 This is the maximum number of arguments that the function accepts, if
497 there is a fixed maximum. Alternatively, it can be @code{UNEVALLED},
498 indicating a special form that receives unevaluated arguments, or
499 @code{MANY}, indicating an unlimited number of evaluated arguments (the
500 equivalent of @code{&rest}). Both @code{UNEVALLED} and @code{MANY} are
501 macros. If @var{max} is a number, it may not be less than @var{min} and
502 it may not be greater than seven.
505 This is an interactive specification, a string such as might be used as
506 the argument of @code{interactive} in a Lisp function. In the case of
507 @code{or}, it is 0 (a null pointer), indicating that @code{or} cannot be
508 called interactively. A value of @code{""} indicates a function that
509 should receive no arguments when called interactively.
512 This is the documentation string. It is written just like a
513 documentation string for a function defined in Lisp, except you must
514 write @samp{\n\} at the end of each line. In particular, the first line
515 should be a single sentence.
518 After the call to the @code{DEFUN} macro, you must write the argument
519 name list that every C function must have, followed by ordinary C
520 declarations for the arguments. For a function with a fixed maximum
521 number of arguments, declare a C argument for each Lisp argument, and
522 give them all type @code{Lisp_Object}. When a Lisp function has no
523 upper limit on the number of arguments, its implementation in C actually
524 receives exactly two arguments: the first is the number of Lisp
525 arguments, and the second is the address of a block containing their
526 values. They have types @code{int} and @w{@code{Lisp_Object *}}.
528 Within the function @code{For} itself, note the use of the macros
529 @code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to ``protect''
530 a variable from garbage collection---to inform the garbage collector that
531 it must look in that variable and regard its contents as an accessible
532 object. This is necessary whenever you call @code{Feval} or anything
533 that can directly or indirectly call @code{Feval}. At such a time, any
534 Lisp object that you intend to refer to again must be protected somehow.
535 @code{UNGCPRO} cancels the protection of the variables that are
536 protected in the current function. It is necessary to do this explicitly.
538 For most data types, it suffices to protect at least one pointer to
539 the object; as long as the object is not recycled, all pointers to it
540 remain valid. This is not so for strings, because the garbage collector
541 can move them. When the garbage collector moves a string, it relocates
542 all the pointers it knows about; any other pointers become invalid.
543 Therefore, you must protect all pointers to strings across any point
544 where garbage collection may be possible.
546 The macro @code{GCPRO1} protects just one local variable. If you want
547 to protect two, use @code{GCPRO2} instead; repeating @code{GCPRO1} will
548 not work. Macros @code{GCPRO3} and @code{GCPRO4} also exist.
550 These macros implicitly use local variables such as @code{gcpro1}; you
551 must declare these explicitly, with type @code{struct gcpro}. Thus, if
552 you use @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
553 Alas, we can't explain all the tricky details here.
555 You must not use C initializers for static or global variables unless
556 they are never written once Emacs is dumped. These variables with
557 initializers are allocated in an area of memory that becomes read-only
558 (on certain operating systems) as a result of dumping Emacs. @xref{Pure
561 Do not use static variables within functions---place all static
562 variables at top level in the file. This is necessary because Emacs on
563 some operating systems defines the keyword @code{static} as a null
564 macro. (This definition is used because those systems put all variables
565 declared static in a place that becomes read-only after dumping, whether
566 they have initializers or not.)
568 Defining the C function is not enough to make a Lisp primitive
569 available; you must also create the Lisp symbol for the primitive and
570 store a suitable subr object in its function cell. The code looks like
574 defsubr (&@var{subr-structure-name});
578 Here @var{subr-structure-name} is the name you used as the third
579 argument to @code{DEFUN}.
581 If you add a new primitive to a file that already has Lisp primitives
582 defined in it, find the function (near the end of the file) named
583 @code{syms_of_@var{something}}, and add the call to @code{defsubr}
584 there. If the file doesn't have this function, or if you create a new
585 file, add to it a @code{syms_of_@var{filename}} (e.g.,
586 @code{syms_of_myfile}). Then find the spot in @file{emacs.c} where all
587 of these functions are called, and add a call to
588 @code{syms_of_@var{filename}} there.
590 The function @code{syms_of_@var{filename}} is also the place to define
591 any C variables that are to be visible as Lisp variables.
592 @code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible
593 in Lisp. @code{DEFVAR_INT} makes a C variable of type @code{int}
594 visible in Lisp with a value that is always an integer.
595 @code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp
596 with a value that is either @code{t} or @code{nil}.
598 If you define a file-scope C variable of type @code{Lisp_Object},
599 you must protect it for garbage-collection by calling @code{staticpro}
600 in @code{syms_of_@var{filename}}, like this:
603 staticpro (&@var{variable});
606 Here is another example function, with more complicated arguments.
607 This comes from the code in @file{window.c}, and it demonstrates the use
608 of macros and functions to manipulate Lisp objects.
612 DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
613 Scoordinates_in_window_p, 2, 2,
614 "xSpecify coordinate pair: \nXExpression which evals to window: ",
615 "Return non-nil if COORDINATES is in WINDOW.\n\
616 COORDINATES is a cons of the form (X . Y), X and Y being distances\n\
620 If they are on the border between WINDOW and its right sibling,\n\
621 `vertical-line' is returned.")
622 (coordinates, window)
623 register Lisp_Object coordinates, window;
629 CHECK_LIVE_WINDOW (window, 0);
630 CHECK_CONS (coordinates, 1);
631 x = XINT (Fcar (coordinates));
632 y = XINT (Fcdr (coordinates));
636 switch (coordinates_in_window (XWINDOW (window), &x, &y))
638 case 0: /* NOT in window at all. */
643 case 1: /* In text part of window. */
644 return Fcons (make_number (x), make_number (y));
648 case 2: /* In mode line of window. */
653 case 3: /* On right border of window. */
654 return Qvertical_line;
665 Note that C code cannot call functions by name unless they are defined
666 in C. The way to call a function written in Lisp is to use
667 @code{Ffuncall}, which embodies the Lisp function @code{funcall}. Since
668 the Lisp function @code{funcall} accepts an unlimited number of
669 arguments, in C it takes two: the number of Lisp-level arguments, and a
670 one-dimensional array containing their values. The first Lisp-level
671 argument is the Lisp function to call, and the rest are the arguments to
672 pass to it. Since @code{Ffuncall} can call the evaluator, you must
673 protect pointers from garbage collection around the call to
676 The C functions @code{call0}, @code{call1}, @code{call2}, and so on,
677 provide handy ways to call a Lisp function conveniently with a fixed
678 number of arguments. They work by calling @code{Ffuncall}.
680 @file{eval.c} is a very good file to look through for examples;
681 @file{lisp.h} contains the definitions for some important macros and
684 @node Object Internals
685 @appendixsec Object Internals
686 @cindex object internals
688 GNU Emacs Lisp manipulates many different types of data. The actual
689 data are stored in a heap and the only access that programs have to it
690 is through pointers. Pointers are thirty-two bits wide in most
691 implementations. Depending on the operating system and type of machine
692 for which you compile Emacs, twenty-eight bits are used to address the
693 object, and the remaining four bits are used for a GC mark bit and the
694 tag that identifies the object's type.
696 Because Lisp objects are represented as tagged pointers, it is always
697 possible to determine the Lisp data type of any object. The C data type
698 @code{Lisp_Object} can hold any Lisp object of any data type. Ordinary
699 variables have type @code{Lisp_Object}, which means they can hold any
700 type of Lisp value; you can determine the actual data type only at run
701 time. The same is true for function arguments; if you want a function
702 to accept only a certain type of argument, you must check the type
703 explicitly using a suitable predicate (@pxref{Type Predicates}).
704 @cindex type checking internals
707 * Buffer Internals:: Components of a buffer structure.
708 * Window Internals:: Components of a window structure.
709 * Process Internals:: Components of a process structure.
712 @node Buffer Internals
713 @appendixsubsec Buffer Internals
714 @cindex internals, of buffer
715 @cindex buffer internals
717 Buffers contain fields not directly accessible by the Lisp programmer.
718 We describe them here, naming them by the names used in the C code.
719 Many are accessible indirectly in Lisp programs via Lisp primitives.
723 The buffer name is a string that names the buffer. It is guaranteed to
724 be unique. @xref{Buffer Names}.
727 This field contains the time when the buffer was last saved, as an integer.
728 @xref{Buffer Modification}.
731 This field contains the modification time of the visited file. It is
732 set when the file is written or read. Every time the buffer is written
733 to the file, this field is compared to the modification time of the
734 file. @xref{Buffer Modification}.
736 @item auto_save_modified
737 This field contains the time when the buffer was last auto-saved.
739 @item last_window_start
740 This field contains the @code{window-start} position in the buffer as of
741 the last time the buffer was displayed in a window.
744 This field points to the buffer's undo list. @xref{Undo}.
747 This field contains the syntax table for the buffer. @xref{Syntax Tables}.
750 This field contains the conversion table for converting text to lower case.
754 This field contains the conversion table for converting text to upper case.
757 @item case_canon_table
758 This field contains the conversion table for canonicalizing text for
759 case-folding search. @xref{Case Tables}.
762 This field contains the equivalence table for case-folding search.
766 This field contains the buffer's display table, or @code{nil} if it doesn't
767 have one. @xref{Display Tables}.
770 This field contains the chain of all markers that currently point into
771 the buffer. Deletion of text in the buffer, and motion of the buffer's
772 gap, must check each of these markers and perhaps update it.
776 This field is a flag that tells whether a backup file has been made
777 for the visited file of this buffer.
780 This field contains the mark for the buffer. The mark is a marker,
781 hence it is also included on the list @code{markers}. @xref{The Mark}.
784 This field is non-@code{nil} if the buffer's mark is active.
786 @item local_var_alist
787 This field contains the association list describing the buffer-local
788 variable bindings of this buffer, not including the built-in
789 buffer-local bindings that have special slots in the buffer object.
790 (Those slots are omitted from this table.) @xref{Buffer-Local
794 This field holds the buffer's base buffer (if it is an indirect buffer),
798 This field holds the buffer's local keymap. @xref{Keymaps}.
801 This field holds the current overlay center position. @xref{Overlays}.
803 @item overlays_before
804 This field holds a list of the overlays in this buffer that end at or
805 before the current overlay center position. They are sorted in order of
806 decreasing end position.
809 This field holds a list of the overlays in this buffer that end after
810 the current overlay center position. They are sorted in order of
811 increasing beginning position.
813 @item enable_multibyte_characters
814 This field holds the buffer's local value of
815 @code{enable-multibyte-characters}---either @code{t} or @code{nil}.
818 @node Window Internals
819 @appendixsubsec Window Internals
820 @cindex internals, of window
821 @cindex window internals
823 Windows have the following accessible fields:
827 The frame that this window is on.
830 Non-@code{nil} if this window is a minibuffer window.
833 The buffer that the window is displaying. This may change often during
834 the life of the window.
837 Non-@code{nil} if this window is dedicated to its buffer.
840 @cindex window point internals
841 This is the value of point in the current buffer when this window is
842 selected; when it is not selected, it retains its previous value.
845 The position in the buffer that is the first character to be displayed
849 If this flag is non-@code{nil}, it says that the window has been
850 scrolled explicitly by the Lisp program. This affects what the next
851 redisplay does if point is off the screen: instead of scrolling the
852 window to show the text around point, it moves point to a location that
856 The @code{modified} field of the window's buffer, as of the last time
857 a redisplay completed in this window.
860 The buffer's value of point, as of the last time
861 a redisplay completed in this window.
864 This is the left-hand edge of the window, measured in columns. (The
865 leftmost column on the screen is @w{column 0}.)
868 This is the top edge of the window, measured in lines. (The top line on
869 the screen is @w{line 0}.)
872 The height of the window, measured in lines.
875 The width of the window, measured in columns.
878 This is the window that is the next in the chain of siblings. It is
879 @code{nil} in a window that is the rightmost or bottommost of a group of
883 This is the window that is the previous in the chain of siblings. It is
884 @code{nil} in a window that is the leftmost or topmost of a group of
888 Internally, Emacs arranges windows in a tree; each group of siblings has
889 a parent window whose area includes all the siblings. This field points
890 to a window's parent.
892 Parent windows do not display buffers, and play little role in display
893 except to shape their child windows. Emacs Lisp programs usually have
894 no access to the parent windows; they operate on the windows at the
895 leaves of the tree, which actually display buffers.
898 This is the number of columns that the display in the window is scrolled
899 horizontally to the left. Normally, this is 0.
902 This is the last time that the window was selected. The function
903 @code{get-lru-window} uses this field.
906 The window's display table, or @code{nil} if none is specified for it.
908 @item update_mode_line
909 Non-@code{nil} means this window's mode line needs to be updated.
911 @item base_line_number
912 The line number of a certain position in the buffer, or @code{nil}.
913 This is used for displaying the line number of point in the mode line.
916 The position in the buffer for which the line number is known, or
917 @code{nil} meaning none is known.
920 If the region (or part of it) is highlighted in this window, this field
921 holds the mark position that made one end of that region. Otherwise,
922 this field is @code{nil}.
925 @node Process Internals
926 @appendixsubsec Process Internals
927 @cindex internals, of process
928 @cindex process internals
930 The fields of a process are:
934 A string, the name of the process.
937 A list containing the command arguments that were used to start this
941 A function used to accept output from the process instead of a buffer,
945 A function called whenever the process receives a signal, or @code{nil}.
948 The associated buffer of the process.
951 An integer, the Unix process @sc{id}.
954 A flag, non-@code{nil} if this is really a child process.
955 It is @code{nil} for a network connection.
958 A marker indicating the position of the end of the last output from this
959 process inserted into the buffer. This is often but not always the end
962 @item kill_without_query
963 If this is non-@code{nil}, killing Emacs while this process is still
964 running does not ask for confirmation about killing the process.
967 @itemx raw_status_high
968 These two fields record 16 bits each of the process status returned by
969 the @code{wait} system call.
972 The process status, as @code{process-status} should return it.
976 If these two fields are not equal, a change in the status of the process
977 needs to be reported, either by running the sentinel or by inserting a
978 message in the process buffer.
981 Non-@code{nil} if communication with the subprocess uses a @sc{pty};
982 @code{nil} if it uses a pipe.
985 The file descriptor for input from the process.
988 The file descriptor for output to the process.
991 The file descriptor for the terminal that the subprocess is using. (On
992 some systems, there is no need to record this, so the value is
996 The name of the terminal that the subprocess is using,
997 or @code{nil} if it is using pipes.