@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 1999, 2002, 2003, 2004,
-@c 2005 Free Software Foundation, Inc.
+@c 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/internals
@node GNU Emacs Internals, Standard Errors, Tips, Top
marked as read-only (on operating systems that permit this), so that
the memory space can be shared by all the Emacs jobs running on the
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} crashes. If that happens, you must
-increase the compilation parameter @code{PURESIZE} in the file
-@file{src/puresize.h}. This normally won't happen unless you try to
-preload additional libraries or add features to the standard ones.
+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.
@defun purecopy object
This function makes a copy in pure storage of @var{object}, and returns
object consists of a header and the storage for the string text
itself; the latter is only allocated when the string is created.)
@end table
+
+If there was overflow in pure space (see the previous section),
+@code{garbage-collect} returns @code{nil}, because a real garbage
+collection can not be done in this situation.
@end deffn
@defopt garbage-collection-messages
@smallexample
@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.
+ doc: /* Eval args until one of them yields non-nil, then return that
+value. The remaining args are not evalled at all.
If all args return nil, return nil.
@end group
@group
values. They have types @code{int} and @w{@code{Lisp_Object *}}.
Within the function @code{For} itself, note the use of the macros
-@code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to ``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. This 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 you intend to refer to again must be protected somehow.
-@code{UNGCPRO} cancels the protection of the variables that are
-protected in the current function. It is necessary to do this explicitly.
+@code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to
+``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.
It suffices to ensure that at least one pointer to each object is
-GC-protected; as long as the object is not recycled, all pointers to
-it remain valid. So if you are sure that a local variable points to
-an object that will be preserved by some other pointer, that local
-variable does not need a @code{GCPRO}. (Formerly, strings were an
-exception to this rule; in older Emacs versions, every pointer to a
-string needed to be marked by GC.)
+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}.
The macro @code{GCPRO1} protects just one local variable. If you
-want to protect two, use @code{GCPRO2} instead; repeating
-@code{GCPRO1} will not work. Macros, @code{GCPRO3}, @code{GCPRO4},
-@code{GCPRO5}, and @code{GCPRO6} also exist. These macros implicitly
-use local variables such as @code{gcpro1}; you must declare these
-explicitly, with type @code{struct gcpro}. Thus, if you use
+want to protect two variables, use @code{GCPRO2} instead; repeating
+@code{GCPRO1} will not work. Macros @code{GCPRO3}, @code{GCPRO4},
+@code{GCPRO5}, and @code{GCPRO6} also exist. All these macros
+implicitly use local variables such as @code{gcpro1}; you must declare
+these explicitly, with type @code{struct gcpro}. Thus, if you use
@code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
Alas, we can't explain all the tricky details here.
+ @code{UNGCPRO} cancels the protection of the variables that are
+protected in the current function. It is necessary to do this
+explicitly.
+
Built-in functions that take a variable number of arguments actually
accept two arguments at the C level: the number of Lisp arguments, and
a @code{Lisp_Object *} pointer to a C vector containing those Lisp
is @code{nil}, no mode line will be displayed.
@item header_line_format
-This field is analoguous to @code{mode_line_format} for the mode
+This field is analogous to @code{mode_line_format} for the mode
line displayed at the top of windows.
@item keymap
when it was chosen.
@item too_small_ok
-Non-@code{nil} means don't delete this window for becoming ``too small''.
+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