@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 1999, 2001, 2002, 2003,
-@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1993, 1998-1999, 2001-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/internals
@node GNU Emacs Internals, Standard Errors, Tips, Top
@menu
* Building Emacs:: How the dumped Emacs is made.
-* Pure Storage:: A kludge to make preloaded Lisp functions sharable.
+* Pure Storage:: Kludge to make preloaded Lisp functions shareable.
* Garbage Collection:: Reclaiming space for Lisp objects no longer used.
* Memory Usage:: Info about total size of Lisp objects made so far.
* Writing Emacs Primitives:: Writing C code for Emacs.
@end menu
@node Building Emacs
-@appendixsec Building Emacs
+@section Building Emacs
@cindex building Emacs
@pindex temacs
bare.
@cindex dumping Emacs
- It takes a substantial time to load the standard Lisp files. Luckily,
+ It takes some time to load the standard Lisp files. Luckily,
you don't have to do this each time you run Emacs; @file{temacs} can
dump out an executable program called @file{emacs} that has these files
preloaded. @file{emacs} starts more quickly because it does not need to
load the files. This is the Emacs executable that is normally
installed.
+@vindex preloaded-file-list
+@cindex dumped Lisp files
To create @file{emacs}, use the command @samp{temacs -batch -l loadup
dump}. The purpose of @samp{-batch} here is to prevent @file{temacs}
from trying to initialize any of its data on the terminal; this ensures
that the tables of terminal information are empty in the dumped Emacs.
The argument @samp{dump} tells @file{loadup.el} to dump a new executable
-named @file{emacs}.
+named @file{emacs}. The variable @code{preloaded-file-list} stores a
+list of the Lisp files that were dumped with the @file{emacs} executable.
- Some operating systems don't support dumping. On those systems, you
-must start Emacs with the @samp{temacs -l loadup} command each time you
-use it. This takes a substantial time, but since you need to start
-Emacs once a day at most---or once a week if you never log out---the
-extra time is not too severe a problem.
+ If you port Emacs to a new operating system, and are not able to
+implement dumping, then Emacs must load @file{loadup.el} each time it
+starts.
@cindex @file{site-load.el}
-
You can specify additional files to preload by writing a library named
-@file{site-load.el} that loads them. You may need to add a definition
+@file{site-load.el} that loads them. You may need to rebuild Emacs
+with an added definition
@example
#define SITELOAD_PURESIZE_EXTRA @var{n}
@end example
@noindent
-to make @var{n} added bytes of pure space to hold the additional files.
+to make @var{n} added bytes of pure space to hold the additional files;
+see @file{src/puresize.h}.
(Try adding increments of 20000 until it is big enough.) However, the
advantage of preloading additional files decreases as machines get
faster. On modern machines, it is usually not advisable.
installation directory for Lisp files when you install Emacs.
@item
-Specify a non-@code{nil} value for
-@code{byte-compile-dynamic-docstrings} as a local variable in each of these
-files, and load them with either @file{site-load.el} or
-@file{site-init.el}. (This method has the drawback that the
-documentation strings take up space in Emacs all the time.)
+Specify a @code{nil} value for @code{byte-compile-dynamic-docstrings}
+as a local variable in each of these files, and load them with either
+@file{site-load.el} or @file{site-init.el}. (This method has the
+drawback that the documentation strings take up space in Emacs all the
+time.)
@end itemize
It is not advisable to put anything in @file{site-load.el} or
normal features for your site, do it with @file{default.el}, so that
users can override your changes if they wish. @xref{Startup Summary}.
- In a package that can be preloaded, it is sometimes useful to
-specify a computation to be done when Emacs subsequently starts up.
-For this, use @code{eval-at-startup}:
+ In a package that can be preloaded, it is sometimes necessary (or
+useful) to delay certain evaluations until Emacs subsequently starts
+up. The vast majority of such cases relate to the values of
+customizable variables. For example, @code{tutorial-directory} is a
+variable defined in @file{startup.el}, which is preloaded. The default
+value is set based on @code{data-directory}. The variable needs to
+access the value of @code{data-directory} when Emacs starts, not when
+it is dumped, because the Emacs executable has probably been installed
+in a different location since it was dumped.
+
+@defun custom-initialize-delay symbol value
+This function delays the initialization of @var{symbol} to the next
+Emacs start. You normally use this function by specifying it as the
+@code{:initialize} property of a customizable variable. (The argument
+@var{value} is unused, and is provided only for compatiblity with the
+form Custom expects.)
+@end defun
-@defmac eval-at-startup body@dots{}
-This evaluates the @var{body} forms, either immediately if running in
-an Emacs that has already started up, or later when Emacs does start
-up. Since the value of the @var{body} forms is not necessarily
-available when the @code{eval-at-startup} form is run, that form
-always returns @code{nil}.
-@end defmac
+In the unlikely event that you need a more general functionality than
+@code{custom-initialize-delay} provides, you can use
+@code{before-init-hook} (@pxref{Startup Summary}).
@defun dump-emacs to-file from-file
@cindex unexec
@end defun
@node Pure Storage
-@appendixsec Pure Storage
+@section Pure Storage
@cindex pure storage
Emacs Lisp uses two kinds of storage for user-created Lisp objects:
@dfn{normal storage} and @dfn{pure storage}. Normal storage is where
-all the new data created during an Emacs session are kept; see the
-following section for information on normal storage. Pure storage is
-used for certain data in the preloaded standard Lisp files---data that
-should never change during actual use of Emacs.
+all the new data created during an Emacs session are kept
+(@pxref{Garbage Collection}). Pure storage is used for certain data
+in the preloaded standard Lisp files---data that should never change
+during actual use of Emacs.
Pure storage is allocated only while @file{temacs} is loading the
standard preloaded Lisp libraries. In the file @file{emacs}, it is
machine at once. Pure storage is not expandable; a fixed amount is
allocated when Emacs is compiled, and if that is not sufficient for
the preloaded libraries, @file{temacs} allocates dynamic memory for
-the part that didn't fit. If that happens, you should increase the
-compilation parameter @code{PURESIZE} in the file
-@file{src/puresize.h} and rebuild Emacs, even though the resulting
-image will work: garbage collection is disabled in this situation,
-causing a memory leak. Such an overflow normally won't happen unless you
-try to preload additional libraries or add features to the standard
-ones. Emacs will display a warning about the overflow when it
-starts.
+the part that didn't fit. The resulting image will work, but garbage
+collection (@pxref{Garbage Collection}) is disabled in this situation,
+causing a memory leak. Such an overflow normally won't happen unless
+you try to preload additional libraries or add features to the
+standard ones. Emacs will display a warning about the overflow when
+it starts. If this happens, you should increase the compilation
+parameter @code{SYSTEM_PURESIZE_EXTRA} in the file
+@file{src/puresize.h} and rebuild Emacs.
@defun purecopy object
This function makes a copy in pure storage of @var{object}, and returns
them unchanged. It signals an error if asked to copy markers.
This function is a no-op except while Emacs is being built and dumped;
-it is usually called only in the file @file{emacs/lisp/loaddefs.el}, but
-a few packages call it just in case you decide to preload them.
+it is usually called only in preloaded Lisp files.
@end defun
@defvar pure-bytes-used
function definition is copied into pure storage.
This flag is @code{t} while loading all of the basic functions for
-building Emacs initially (allowing those functions to be sharable and
+building Emacs initially (allowing those functions to be shareable and
non-collectible). Dumping Emacs as an executable always writes
@code{nil} in this variable, regardless of the value it actually has
before and after dumping.
@end defvar
@node Garbage Collection
-@appendixsec Garbage Collection
+@section Garbage Collection
@cindex garbage collection
@cindex memory allocation
itself; the latter is only allocated when the string is created.)
@end table
-If there was overflow in pure space (see the previous section),
+If there was overflow in pure space (@pxref{Pure Storage}),
@code{garbage-collect} returns @code{nil}, because a real garbage
collection can not be done in this situation.
@end deffn
@defopt garbage-collection-messages
If this variable is non-@code{nil}, Emacs displays a message at the
beginning and end of garbage collection. The default value is
-@code{nil}, meaning there are no such messages.
+@code{nil}.
@end defopt
@defvar post-gc-hook
the threshold is exhausted, but only the next time the Lisp evaluator is
called.
-The initial threshold value is 400,000. If you specify a larger
+The initial threshold value is 800,000. If you specify a larger
value, garbage collection will happen less often. This reduces the
amount of time spent garbage collecting, but increases total memory use.
You may want to do this when running a program that creates lots of
These functions and variables give information about the total amount
of memory allocation that Emacs has done, broken down by data type.
Note the difference between these and the values returned by
-@code{(garbage-collect)}; those count objects that currently exist, but
+@code{garbage-collect}; those count objects that currently exist, but
these count the number or size of all allocations, including those for
objects that have since been freed.
@end defvar
@node Writing Emacs Primitives
-@appendixsec Writing Emacs Primitives
+@section Writing Emacs Primitives
@cindex primitive function internals
@cindex writing Emacs primitives
@group
DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
doc: /* Eval args until one of them yields non-nil, then return that
-value. The remaining args are not evalled at all.
+value. The remaining args are not evalled at all.
If all args return nil, return nil.
@end group
@group
usage: (or CONDITIONS ...) */)
- (args)
- Lisp_Object args;
+ (Lisp_Object args)
@{
register Lisp_Object val = Qnil;
struct gcpro gcpro1;
@group
while (CONSP (args))
@{
- val = Feval (XCAR (args));
+ val = eval_sub (XCAR (args));
if (!NILP (val))
break;
args = XCDR (args);
called interactively. A value of @code{""} indicates a function that
should receive no arguments when called interactively. If the value
begins with a @samp{(}, the string is evaluated as a Lisp form.
+For examples of the last two forms, see @code{widen} and
+@code{narrow-to-region} in @file{editfns.c}.
@item doc
This is the documentation string. It uses C comment syntax rather
too.
@end table
- After the call to the @code{DEFUN} macro, you must write the argument
-name list that every C function must have, followed by ordinary C
-declarations for the arguments. For a function with a fixed maximum
-number of arguments, declare a C argument for each Lisp argument, and
-give them all type @code{Lisp_Object}. When a Lisp function has no
-upper limit on the number of arguments, its implementation in C actually
-receives exactly two arguments: the first is the number of Lisp
-arguments, and the second is the address of a block containing their
-values. They have types @code{int} and @w{@code{Lisp_Object *}}.
+ After the call to the @code{DEFUN} macro, you must write the
+argument list that every C function must have, including the types for
+the arguments. For a function with a fixed maximum number of
+arguments, declare a C argument for each Lisp argument, and give them
+all type @code{Lisp_Object}. When a Lisp function has no upper limit
+on the number of arguments, its implementation in C actually receives
+exactly two arguments: the first is the number of Lisp arguments, and
+the second is the address of a block containing their values. They
+have types @code{int} and @w{@code{Lisp_Object *}}.
@cindex @code{GCPRO} and @code{UNGCPRO}
@cindex protect C variables from garbage collection
``protect'' a variable from garbage collection---to inform the garbage
collector that it must look in that variable and regard its contents
as an accessible object. GC protection is necessary whenever you call
-@code{Feval} or anything that can directly or indirectly call
-@code{Feval}. At such a time, any Lisp object that this function may
-refer to again must be protected somehow.
+@code{eval_sub} (or @code{Feval}) either directly or indirectly.
+At such a time, any Lisp object that this function may refer to again
+must be protected somehow.
It suffices to ensure that at least one pointer to each object is
GC-protected; that way, the object cannot be recycled, so all pointers
to it remain valid. Thus, a particular local variable can do without
protection if it is certain that the object it points to will be
-preserved by some other pointer (such as another local variable which
-has a @code{GCPRO})@footnote{Formerly, strings were a special
-exception; in older Emacs versions, every local variable that might
-point to a string needed a @code{GCPRO}.}. Otherwise, the local
-variable needs a @code{GCPRO}.
+preserved by some other pointer (such as another local variable that
+has a @code{GCPRO}).
+@ignore
+@footnote{Formerly, strings were a special exception; in older Emacs
+versions, every local variable that might point to a string needed a
+@code{GCPRO}.}.
+@end ignore
+Otherwise, the local variable needs a @code{GCPRO}.
The macro @code{GCPRO1} protects just one local variable. If you
want to protect two variables, use @code{GCPRO2} instead; repeating
read-only (on certain operating systems) as a result of dumping Emacs.
@xref{Pure Storage}.
+@c FIXME is this still true? I don't think so...
Do not use static variables within functions---place all static
variables at top level in the file. This is necessary because Emacs on
some operating systems defines the keyword @code{static} as a null
this:
@example
-defsubr (&@var{subr-structure-name});
+defsubr (&@var{sname});
@end example
@noindent
-Here @var{subr-structure-name} is the name you used as the third
-argument to @code{DEFUN}.
+Here @var{sname} is the name you used as the third argument to @code{DEFUN}.
If you add a new primitive to a file that already has Lisp primitives
defined in it, find the function (near the end of the file) named
defined with @code{DEFVAR_BOOL} are automatically added to the list
@code{byte-boolean-vars} used by the byte compiler.
+@cindex defining customization variables in C
+ If you want to make a Lisp variables that is defined in C behave
+like one declared with @code{defcustom}, add an appropriate entry to
+@file{cus-start.el}.
+
@cindex @code{staticpro}, protection from GC
If you define a file-scope C variable of type @code{Lisp_Object},
you must protect it from garbage-collection by calling @code{staticpro}
@smallexample
@group
DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
- Scoordinates_in_window_p, 2, 2,
- "xSpecify coordinate pair: \nXExpression which evals to window: ",
- "Return non-nil if COORDINATES is in WINDOW.\n\
-COORDINATES is a cons of the form (X . Y), X and Y being distances\n\
-...
+ Scoordinates_in_window_p, 2, 2, 0,
+ doc: /* Return non-nil if COORDINATES are in WINDOW.
+ ...
@end group
@group
-If they are on the border between WINDOW and its right sibling,\n\
- `vertical-line' is returned.")
- (coordinates, window)
- register Lisp_Object coordinates, window;
+ or `right-margin' is returned. */)
+ (register Lisp_Object coordinates, Lisp_Object window)
@{
+ struct window *w;
+ struct frame *f;
int x, y;
+ Lisp_Object lx, ly;
@end group
@group
- CHECK_LIVE_WINDOW (window, 0);
- CHECK_CONS (coordinates, 1);
- x = XINT (Fcar (coordinates));
- y = XINT (Fcdr (coordinates));
+ CHECK_LIVE_WINDOW (window);
+ w = XWINDOW (window);
+ f = XFRAME (w->frame);
+ CHECK_CONS (coordinates);
+ lx = Fcar (coordinates);
+ ly = Fcdr (coordinates);
+ CHECK_NUMBER_OR_FLOAT (lx);
+ CHECK_NUMBER_OR_FLOAT (ly);
+ x = FRAME_PIXEL_X_FROM_CANON_X (f, lx) + FRAME_INTERNAL_BORDER_WIDTH(f);
+ y = FRAME_PIXEL_Y_FROM_CANON_Y (f, ly) + FRAME_INTERNAL_BORDER_WIDTH(f);
@end group
@group
- switch (coordinates_in_window (XWINDOW (window), &x, &y))
+ switch (coordinates_in_window (w, x, y))
@{
- case 0: /* NOT in window at all. */
+ case ON_NOTHING: /* NOT in window at all. */
return Qnil;
@end group
-@group
- case 1: /* In text part of window. */
- return Fcons (make_number (x), make_number (y));
-@end group
+ ...
@group
- case 2: /* In mode line of window. */
+ case ON_MODE_LINE: /* In mode line of window. */
return Qmode_line;
@end group
+ ...
+
@group
- case 3: /* On right border of window. */
- return Qvertical_line;
+ case ON_SCROLL_BAR: /* On scroll-bar of window. */
+ /* Historically we are supposed to return nil in this case. */
+ return Qnil;
@end group
@group
functions.
If you define a function which is side-effect free, update the code
-in @file{byte-opt.el} which binds @code{side-effect-free-fns} and
+in @file{byte-opt.el} that binds @code{side-effect-free-fns} and
@code{side-effect-and-error-free-fns} so that the compiler optimizer
knows about it.
@node Object Internals
-@appendixsec Object Internals
+@section Object Internals
@cindex object internals
+@c FIXME Is this still true? Does --with-wide-int affect anything?
GNU Emacs Lisp manipulates many different types of data. The actual
data are stored in a heap and the only access that programs have to it
-is through pointers. Pointers are thirty-two bits wide in most
-implementations. Depending on the operating system and type of machine
-for which you compile Emacs, twenty-nine bits are used to address the
-object, and the remaining three bits are used for the tag that
-identifies the object's type.
+is through pointers. Each pointer is 32 bits wide on 32-bit machines,
+and 64 bits wide on 64-bit machines; three of these bits are used for
+the tag that identifies the object's type, and the remainder are used
+to address the object.
Because Lisp objects are represented as tagged pointers, it is always
possible to determine the Lisp data type of any object. The C data type
@end menu
@node Buffer Internals
-@appendixsubsec Buffer Internals
+@subsection Buffer Internals
@cindex internals, of buffer
@cindex buffer internals
- Buffers contain fields not directly accessible by the Lisp programmer.
-We describe them here, naming them by the names used in the C code.
-Many are accessible indirectly in Lisp programs via Lisp primitives.
-
-Two structures are used to represent buffers in C. The
-@code{buffer_text} structure contains fields describing the text of a
-buffer; the @code{buffer} structure holds other fields. In the case
-of indirect buffers, two or more @code{buffer} structures reference
-the same @code{buffer_text} structure.
+ Two structures (see @file{buffer.h}) are used to represent buffers
+in C. The @code{buffer_text} structure contains fields describing the
+text of a buffer; the @code{buffer} structure holds other fields. In
+the case of indirect buffers, two or more @code{buffer} structures
+reference the same @code{buffer_text} structure.
-Here is a list of the @code{struct buffer_text} fields:
+Here are some of the fields in @code{struct buffer_text}:
@table @code
@item beg
-This field contains the actual address of the buffer contents.
+The address of the buffer contents.
@item gpt
-This holds the character position of the gap in the buffer.
-@xref{Buffer Gap}.
+@itemx gpt_byte
+The character and byte positions of the buffer gap. @xref{Buffer
+Gap}.
@item z
-This field contains the character position of the end of the buffer
-text.
-
-@item gpt_byte
-Contains the byte position of the gap.
-
-@item z_byte
-Holds the byte position of the end of the buffer text.
+@itemx z_byte
+The character and byte positions of the end of the buffer text.
@item gap_size
-Contains the size of buffer's gap. @xref{Buffer Gap}.
+The size of buffer's gap. @xref{Buffer Gap}.
@item modiff
-This field counts buffer-modification events for this buffer. It is
-incremented for each such event, and never otherwise changed.
-
-@item save_modiff
-Contains the previous value of @code{modiff}, as of the last time a
-buffer was visited or saved in a file.
-
-@item overlay_modiff
-Counts modifications to overlays analogous to @code{modiff}.
+@itemx save_modiff
+@itemx chars_modiff
+@itemx overlay_modiff
+These fields count the number of buffer-modification events performed
+in this buffer. @code{modiff} is incremented after each
+buffer-modification event, and is never otherwise changed;
+@code{save_modiff} contains the value of @code{modiff} the last time
+the buffer was visited or saved; @code{chars_modiff} counts only
+modifications to the characters in the buffer, ignoring all other
+kinds of changes; and @code{overlay_modiff} counts only modifications
+to the overlays.
@item beg_unchanged
-Holds the number of characters at the start of the text that are known
-to be unchanged since the last redisplay that finished.
-
-@item end_unchanged
-Holds the number of characters at the end of the text that are known to
-be unchanged since the last redisplay that finished.
+@itemx end_unchanged
+The number of characters at the start and end of the text that are
+known to be unchanged since the last complete redisplay.
@item unchanged_modified
-Contains the value of @code{modiff} at the time of the last redisplay
-that finished. If this value matches @code{modiff},
-@code{beg_unchanged} and @code{end_unchanged} contain no useful
-information.
-
-@item overlay_unchanged_modified
-Contains the value of @code{overlay_modiff} at the time of the last
-redisplay that finished. If this value matches @code{overlay_modiff},
+@itemx overlay_unchanged_modified
+The values of @code{modiff} and @code{overlay_modiff}, respectively,
+after the last complete redisplay. If their current values match
+@code{modiff} or @code{overlay_modiff}, that means
@code{beg_unchanged} and @code{end_unchanged} contain no useful
information.
markers referring to this buffer text.
@item intervals
-Contains the interval tree which records the text properties of this
-buffer.
+The interval tree which records the text properties of this buffer.
@end table
-The fields of @code{struct buffer} are:
+Some of the fields of @code{struct buffer} are:
@table @code
-@item next
-Points to the next buffer, in the chain of all buffers including killed
-buffers. This chain is used only for garbage collection, in order to
-collect killed buffers properly. Note that vectors, and most kinds of
-objects allocated as vectors, are all on one chain, but buffers are on a
-separate chain of their own.
+@item header
+A @code{struct vectorlike_header} structure where @code{header.next}
+points to the next buffer, in the chain of all buffers (including
+killed buffers). This chain is used only for garbage collection, in
+order to collect killed buffers properly. Note that vectors, and most
+kinds of objects allocated as vectors, are all on one chain, but
+buffers are on a separate chain of their own.
@item own_text
-This is a @code{struct buffer_text} structure. In an ordinary buffer,
-it holds the buffer contents. In indirect buffers, this field is not
-used.
+A @code{struct buffer_text} structure that ordinarily holds the buffer
+contents. In indirect buffers, this field is not used.
@item text
-This points to the @code{buffer_text} structure that is used for this
-buffer. In an ordinary buffer, this is the @code{own_text} field above.
-In an indirect buffer, this is the @code{own_text} field of the base
-buffer.
+A pointer to the @code{buffer_text} structure for this buffer. In an
+ordinary buffer, this is the @code{own_text} field above. In an
+indirect buffer, this is the @code{own_text} field of the base buffer.
@item pt
-Contains the character position of point in a buffer.
-
-@item pt_byte
-Contains the byte position of point in a buffer.
+@itemx pt_byte
+The character and byte positions of point in a buffer.
@item begv
-This field contains the character position of the beginning of the
-accessible range of text in the buffer.
-
-@item begv_byte
-This field contains the byte position of the beginning of the
-accessible range of text in the buffer.
+@itemx begv_byte
+The character and byte positions of the beginning of the accessible
+range of text in the buffer.
@item zv
-This field contains the character position of the end of the
-accessible range of text in the buffer.
-
-@item zv_byte
-This field contains the byte position of the end of the
-accessible range of text in the buffer.
+@itemx zv_byte
+The character and byte positions of the end of the accessible range of
+text in the buffer.
@item base_buffer
In an indirect buffer, this points to the base buffer. In an ordinary
buffer, it is null.
-@item local_var_flags
-This field contains flags indicating that certain variables are local in
-this buffer. Such variables are declared in the C code using
-@code{DEFVAR_PER_BUFFER}, and their buffer-local bindings are stored in
-fields in the buffer structure itself. (Some of these fields are
+@item local_flags
+This field contains flags indicating that certain variables are local
+in this buffer. Such variables are declared in the C code using
+@code{DEFVAR_PER_BUFFER}, and their buffer-local bindings are stored
+in fields in the buffer structure itself. (Some of these fields are
described in this table.)
@item modtime
-This field contains the modification time of the visited file. It is
-set when the file is written or read. Before writing the buffer into a
-file, this field is compared to the modification time of the file to see
-if the file has changed on disk. @xref{Buffer Modification}.
+The modification time of the visited file. It is set when the file is
+written or read. Before writing the buffer into a file, this field is
+compared to the modification time of the file to see if the file has
+changed on disk. @xref{Buffer Modification}.
@item auto_save_modified
-This field contains the time when the buffer was last auto-saved.
-
-@item auto_save_failure_time
-The time at which we detected a failure to auto-save, or -1 if we didn't
-have a failure.
+The time when the buffer was last auto-saved.
@item last_window_start
-This field contains the @code{window-start} position in the buffer as of
-the last time the buffer was displayed in a window.
+The @code{window-start} position in the buffer as of the last time the
+buffer was displayed in a window.
@item clip_changed
-This flag is set when narrowing changes in a buffer.
+This flag indicates that narrowing has changed in the buffer.
+@xref{Narrowing}.
@item prevent_redisplay_optimizations_p
-this flag indicates that redisplay optimizations should not be used
-to display this buffer.
+This flag indicates that redisplay optimizations should not be used to
+display this buffer.
-@item undo_list
-This field points to the buffer's undo list. @xref{Undo}.
+@item overlay_center
+This field holds the current overlay center position. @xref{Managing
+Overlays}.
-@item name
-The buffer name is a string that names the buffer. It is guaranteed to
-be unique. @xref{Buffer Names}.
+@item overlays_before
+@itemx overlays_after
+These fields hold, respectively, a list of overlays that end at or
+before the current overlay center, and a list of overlays that end
+after the current overlay center. @xref{Managing Overlays}.
+@code{overlays_before} is sorted in order of decreasing end position,
+and @code{overlays_after} is sorted in order of increasing beginning
+position.
-@item filename
-The name of the file visited in this buffer, or @code{nil}.
+@c FIXME? the following are now all Lisp_Object BUFFER_INTERNAL_FIELD (foo).
-@item directory
-The directory for expanding relative file names.
+@item name
+A Lisp string that names the buffer. It is guaranteed to be unique.
+@xref{Buffer Names}.
@item save_length
-Length of the file this buffer is visiting, when last read or saved.
-This and other fields concerned with saving are not kept in the
-@code{buffer_text} structure because indirect buffers are never saved.
+The length of the file this buffer is visiting, when last read or
+saved. This and other fields concerned with saving are not kept in
+the @code{buffer_text} structure because indirect buffers are never
+saved.
-@item auto_save_file_name
-File name used for auto-saving this buffer. This is not in the
-@code{buffer_text} because it's not used in indirect buffers at all.
+@item directory
+The directory for expanding relative file names. This is the value of
+the buffer-local variable @code{default-directory} (@pxref{File Name Expansion}).
+
+@item filename
+The name of the file visited in this buffer, or @code{nil}. This is
+the value of the buffer-local variable @code{buffer-file-name}
+(@pxref{Buffer File Name}).
-@item read_only
-Non-@code{nil} means this buffer is read-only.
+@item undo_list
+@itemx backed_up
+@itemx auto_save_file_name
+@itemx auto_save_file_format
+@itemx read_only
+@itemx file_format
+@itemx file_truename
+@itemx invisibility_spec
+@itemx display_count
+@itemx display_time
+These fields store the values of Lisp variables that are automatically
+buffer-local (@pxref{Buffer-Local Variables}), whose corresponding
+variable names have the additional prefix @code{buffer-} and have
+underscores replaced with dashes. For instance, @code{undo_list}
+stores the value of @code{buffer-undo-list}.
@item mark
-This field contains the mark for the buffer. The mark is a marker,
-hence it is also included on the list @code{markers}. @xref{The Mark}.
+The mark for the buffer. The mark is a marker, hence it is also
+included on the list @code{markers}. @xref{The Mark}.
@item local_var_alist
-This field contains the association list describing the buffer-local
-variable bindings of this buffer, not including the built-in
-buffer-local bindings that have special slots in the buffer object.
-(Those slots are omitted from this table.) @xref{Buffer-Local
-Variables}.
+The association list describing the buffer-local variable bindings of
+this buffer, not including the built-in buffer-local bindings that
+have special slots in the buffer object. (Those slots are omitted
+from this table.) @xref{Buffer-Local Variables}.
@item major_mode
Symbol naming the major mode of this buffer, e.g., @code{lisp-mode}.
@item mode_name
-Pretty name of major mode, e.g., @code{"Lisp"}.
-
-@item mode_line_format
-Mode line element that controls the format of the mode line. If this
-is @code{nil}, no mode line will be displayed.
-
-@item header_line_format
-This field is analogous to @code{mode_line_format} for the mode
-line displayed at the top of windows.
+Pretty name of the major mode, e.g., @code{"Lisp"}.
@item keymap
-This field holds the buffer's local keymap. @xref{Keymaps}.
-
-@item abbrev_table
-This buffer's local abbrevs.
-
-@item syntax_table
-This field contains the syntax table for the buffer. @xref{Syntax Tables}.
-
-@item category_table
-This field contains the category table for the buffer.
-
-@item case_fold_search
-The value of @code{case-fold-search} in this buffer.
-
-@item tab_width
-The value of @code{tab-width} in this buffer.
-
-@item fill_column
-The value of @code{fill-column} in this buffer.
-
-@item left_margin
-The value of @code{left-margin} in this buffer.
-
-@item auto_fill_function
-The value of @code{auto-fill-function} in this buffer.
+@itemx abbrev_table
+@itemx syntax_table
+@itemx category_table
+@itemx display_table
+These fields store the buffer's local keymap (@pxref{Keymaps}), abbrev
+table (@pxref{Abbrev Tables}), syntax table (@pxref{Syntax Tables}),
+category table (@pxref{Categories}), and display table (@pxref{Display
+Tables}).
@item downcase_table
-This field contains the conversion table for converting text to lower case.
-@xref{Case Tables}.
-
-@item upcase_table
-This field contains the conversion table for converting text to upper case.
-@xref{Case Tables}.
-
-@item case_canon_table
-This field contains the conversion table for canonicalizing text for
-case-folding search. @xref{Case Tables}.
-
-@item case_eqv_table
-This field contains the equivalence table for case-folding search.
+@itemx upcase_table
+@itemx case_canon_table
+These fields store the conversion tables for converting text to lower
+case, upper case, and for canonicalizing text for case-fold search.
@xref{Case Tables}.
-@item truncate_lines
-The value of @code{truncate-lines} in this buffer.
-
-@item ctl_arrow
-The value of @code{ctl-arrow} in this buffer.
-
-@item selective_display
-The value of @code{selective-display} in this buffer.
-
-@item selective_display_ellipsis
-The value of @code{selective-display-ellipsis} in this buffer.
-
@item minor_modes
An alist of the minor modes of this buffer.
-@item overwrite_mode
-The value of @code{overwrite_mode} in this buffer.
-
-@item abbrev_mode
-The value of @code{abbrev-mode} in this buffer.
-
-@item display_table
-This field contains the buffer's display table, or @code{nil} if it doesn't
-have one. @xref{Display Tables}.
-
-@item save_modified
-This field contains the time when the buffer was last saved, as an integer.
-@xref{Buffer Modification}.
-
-@item mark_active
-This field is non-@code{nil} if the buffer's mark is active.
-
-@item overlays_before
-This field holds a list of the overlays in this buffer that end at or
-before the current overlay center position. They are sorted in order of
-decreasing end position.
-
-@item overlays_after
-This field holds a list of the overlays in this buffer that end after
-the current overlay center position. They are sorted in order of
-increasing beginning position.
-
-@item overlay_center
-This field holds the current overlay center position. @xref{Overlays}.
-
-@item enable_multibyte_characters
-This field holds the buffer's local value of
-@code{enable-multibyte-characters}---either @code{t} or @code{nil}.
-
-@item buffer_file_coding_system
-The value of @code{buffer-file-coding-system} in this buffer.
-
-@item file_format
-The value of @code{buffer-file-format} in this buffer.
-
-@item auto_save_file_format
-The value of @code{buffer-auto-save-file-format} in this buffer.
-
@item pt_marker
-In an indirect buffer, or a buffer that is the base of an indirect
-buffer, this holds a marker that records point for this buffer when the
-buffer is not current.
-
-@item begv_marker
-In an indirect buffer, or a buffer that is the base of an indirect
-buffer, this holds a marker that records @code{begv} for this buffer
+@itemx begv_marker
+@itemx zv_marker
+These fields are only used in an indirect buffer, or in a buffer that
+is the base of an indirect buffer. Each holds a marker that records
+@code{pt}, @code{begv}, and @code{zv} respectively, for this buffer
when the buffer is not current.
-@item zv_marker
-In an indirect buffer, or a buffer that is the base of an indirect
-buffer, this holds a marker that records @code{zv} for this buffer when
-the buffer is not current.
-
-@item file_truename
-The truename of the visited file, or @code{nil}.
-
-@item invisibility_spec
-The value of @code{buffer-invisibility-spec} in this buffer.
+@item mode_line_format
+@itemx header_line_format
+@itemx case_fold_search
+@itemx tab_width
+@itemx fill_column
+@itemx left_margin
+@itemx auto_fill_function
+@itemx truncate_lines
+@itemx word_wrap
+@itemx ctl_arrow
+@itemx bidi_display_reordering
+@itemx bidi_paragraph_direction
+@itemx selective_display
+@itemx selective_display_ellipses
+@itemx overwrite_mode
+@itemx abbrev_mode
+@itemx mark_active
+@itemx enable_multibyte_characters
+@itemx buffer_file_coding_system
+@itemx cache_long_line_scans
+@itemx point_before_scroll
+@itemx left_fringe_width
+@itemx right_fringe_width
+@itemx fringes_outside_margins
+@itemx scroll_bar_width
+@itemx indicate_empty_lines
+@itemx indicate_buffer_boundaries
+@itemx fringe_indicator_alist
+@itemx fringe_cursor_alist
+@itemx scroll_up_aggressively
+@itemx scroll_down_aggressively
+@itemx cursor_type
+@itemx cursor_in_non_selected_windows
+These fields store the values of Lisp variables that are automatically
+buffer-local (@pxref{Buffer-Local Variables}), whose corresponding
+variable names have underscores replaced with dashes. For instance,
+@code{mode_line_format} stores the value of @code{mode-line-format}.
@item last_selected_window
This is the last window that was selected with this buffer in it, or @code{nil}
if that window no longer displays this buffer.
-
-@item display_count
-This field is incremented each time the buffer is displayed in a window.
-
-@item left_margin_width
-The value of @code{left-margin-width} in this buffer.
-
-@item right_margin_width
-The value of @code{right-margin-width} in this buffer.
-
-@item indicate_empty_lines
-Non-@code{nil} means indicate empty lines (lines with no text) with a
-small bitmap in the fringe, when using a window system that can do it.
-
-@item display_time
-This holds a time stamp that is updated each time this buffer is
-displayed in a window.
-
-@item scroll_up_aggressively
-The value of @code{scroll-up-aggressively} in this buffer.
-
-@item scroll_down_aggressively
-The value of @code{scroll-down-aggressively} in this buffer.
@end table
@node Window Internals
-@appendixsubsec Window Internals
+@subsection Window Internals
@cindex internals, of window
@cindex window internals
- Windows have the following accessible fields:
+ The fields of a window (for a complete list, see the definition of
+@code{struct window} in @file{window.h}) include:
@table @code
@item frame
no access to the parent windows; they operate on the windows at the
leaves of the tree, which actually display buffers.
-The following four fields also describe the window tree structure.
-
@item hchild
-In a window subdivided horizontally by child windows, the leftmost child.
-Otherwise, @code{nil}.
-
-@item vchild
-In a window subdivided vertically by child windows, the topmost child.
-Otherwise, @code{nil}.
+@itemx vchild
+These fields contain the window's leftmost child and its topmost child
+respectively. @code{hchild} is used if the window is subdivided
+horizontally by child windows, and @code{vchild} if it is subdivided
+vertically. In a live window, only one of @code{hchild}, @code{vchild},
+and @code{buffer} (q.v.) is non-@code{nil}.
@item next
-The next sibling of this window. It is @code{nil} in a window that is
-the rightmost or bottommost of a group of siblings.
-
-@item prev
-The previous sibling of this window. It is @code{nil} in a window that
-is the leftmost or topmost of a group of siblings.
-
-@item left
-This is the left-hand edge of the window, measured in columns. (The
-leftmost column on the screen is @w{column 0}.)
-
-@item top
-This is the top edge of the window, measured in lines. (The top line on
-the screen is @w{line 0}.)
-
-@item height
-The height of the window, measured in lines.
-
-@item width
-The width of the window, measured in columns. This width includes the
-scroll bar and fringes, and/or the separator line on the right of the
-window (if any).
+@itemx prev
+The next sibling and previous sibling of this window. @code{next} is
+@code{nil} if the window is the right-most or bottom-most in its group;
+@code{prev} is @code{nil} if it is the left-most or top-most in its
+group.
+
+@item left_col
+The left-hand edge of the window, measured in columns, relative to the
+leftmost column in the frame (column 0).
+
+@item top_line
+The top edge of the window, measured in lines, relative to the topmost
+line in the frame (line 0).
+
+@item total_cols
+@itemx total_lines
+The width and height of the window, measured in columns and lines
+respectively. The width includes the scroll bar and fringes, and/or
+the separator line on the right of the window (if any).
@item buffer
-The buffer that the window is displaying. This may change often during
-the life of the window.
+The buffer that the window is displaying.
@item start
-The position in the buffer that is the first character to be displayed
-in the window.
+A marker pointing to the position in the buffer that is the first
+character displayed in the window.
@item pointm
@cindex window point internals
Non-@code{nil} means current value of @code{start} was the beginning of a line
when it was chosen.
-@item too_small_ok
-Non-@code{nil} means don't delete this window for becoming ``too small.''
-
-@item height_fixed_p
-This field is temporarily set to 1 to fix the height of the selected
-window when the echo area is resized.
-
@item use_time
This is the last time that the window was selected. The function
@code{get-lru-window} uses this field.
@item vertical_scroll_bar
This window's vertical scroll bar.
-@item left_margin_width
-The width of the left margin in this window, or @code{nil} not to
-specify it (in which case the buffer's value of @code{left-margin-width}
-is used.
+@item left_margin_cols
+@itemx right_margin_cols
+The widths of the left and right margins in this window. A value of
+@code{nil} means no margin.
-@item right_margin_width
-Likewise for the right margin.
+@item left_fringe_width
+@itemx right_fringe_width
+The widths of the left and right fringes in this window. A value of
+@code{nil} or @code{t} means use the values of the frame.
-@ignore
-@item last_mark_x
-@item last_mark_y
-???Not used.
-@end ignore
+@item fringes_outside_margins
+A non-@code{nil} value means the fringes outside the display margins;
+othersize they are between the margin and the text.
@item window_end_pos
This is computed as @code{z} minus the buffer position of the last glyph
@item window_end_valid
This field is set to a non-@code{nil} value if @code{window_end_pos} is truly
-valid. This is @code{nil} if nontrivial redisplay is preempted since in that
+valid. This is @code{nil} if nontrivial redisplay is pre-empted, since in that
case the display that @code{window_end_pos} was computed for did not get
onto the screen.
-@item redisplay_end_trigger
-If redisplay in this window goes beyond this buffer position, it runs
-the @code{redisplay-end-trigger-hook}.
-
-@ignore
-@item orig_height
-@item orig_top
-??? Are temporary storage areas.
-@end ignore
-
@item cursor
A structure describing where the cursor is in this window.
A structure describing where the cursor of this window physically is.
@item phys_cursor_type
-The type of cursor that was last displayed on this window.
+@c FIXME What is this?
+@c itemx phys_cursor_ascent
+@itemx phys_cursor_height
+@itemx phys_cursor_width
+The type, height, and width of the cursor that was last displayed on
+this window.
@item phys_cursor_on_p
This field is non-zero if the cursor is physically on.
@item cursor_off_p
-Non-zero means the cursor in this window is logically on.
+Non-zero means the cursor in this window is logically off. This is
+used for blinking the cursor.
@item last_cursor_off_p
This field contains the value of @code{cursor_off_p} as of the time of
@item base_line_pos
The position in the buffer for which the line number is known, or
-@code{nil} meaning none is known.
+@code{nil} meaning none is known. If it is a buffer, don't display
+the line number as long as the window shows that buffer.
@item region_showing
If the region (or part of it) is highlighted in this window, this field
if column numbers are not being displayed.
@item current_matrix
-A glyph matrix describing the current display of this window.
-
-@item desired_matrix
-A glyph matrix describing the desired display of this window.
+@itemx desired_matrix
+Glyph matrices describing the current and desired display of this window.
@end table
@node Process Internals
-@appendixsubsec Process Internals
+@subsection Process Internals
@cindex internals, of process
@cindex process internals
- The fields of a process are:
+ The fields of a process (for a complete list, see the definition of
+@code{struct Lisp_Process} in @file{process.h}) include:
@table @code
@item name
process is running or @code{t} if the process is stopped.
@item filter
-A function used to accept output from the process instead of a buffer,
-or @code{nil}.
+If non-@code{nil}, a function used to accept output from the process
+instead of a buffer.
@item sentinel
-A function called whenever the process receives a signal, or @code{nil}.
+If non-@code{nil}, a function called whenever the state of the process
+changes.
@item buffer
The associated buffer of the process.
@item pid
An integer, the operating system's process @acronym{ID}.
+Pseudo-processes such as network or serial connections use a value of 0.
@item childp
-
-A flag, non-@code{nil} if this is really a child process.
-It is @code{nil} for a network or serial connection.
+A flag, @code{t} if this is really a child process. For a network or
+serial connection, it is a plist based on the arguments to
+@code{make-network-process} or @code{make-serial-process}.
@item mark
A marker indicating the position of the end of the last output from this
of the buffer.
@item kill_without_query
-If this is non-@code{nil}, killing Emacs while this process is still
-running does not ask for confirmation about killing the process.
+If this is non-zero, killing Emacs while this process is still running
+does not ask for confirmation about killing the process.
-@item raw_status_low
-@itemx raw_status_high
-These two fields record 16 bits each of the process status returned by
-the @code{wait} system call.
+@item raw_status
+The raw process status, as returned by the @code{wait} system call.
@item status
The process status, as @code{process-status} should return it.
@item outfd
The file descriptor for output to the process.
-@item subtty
-The file descriptor for the terminal that the subprocess is using. (On
-some systems, there is no need to record this, so the value is
-@code{nil}.)
-
@item tty_name
The name of the terminal that the subprocess is using,
or @code{nil} if it is using pipes.
@item encoding_buf
A working buffer for encoding.
-@item encoding_carryover
-Size of carryover in encoding.
-
@item inherit_coding_system_flag
Flag to set @code{coding-system} of the process buffer from the
coding system used to decode process output.
@item type
Symbol indicating the type of process: @code{real}, @code{network},
-@code{serial}
+@code{serial}.
@end table
-@ignore
- arch-tag: 4b2c33bc-d7e4-43f5-bc20-27c0db52a53e
-@end ignore
+@c FIXME Mention src/globals.h somewhere in this file?