@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 1999
-@c Free Software Foundation, Inc.
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/internals
@node GNU Emacs Internals, Standard Errors, Tips, Top
internal aspects of GNU Emacs that may be of interest to C programmers.
@menu
-* Building Emacs:: How to the dumped Emacs is made.
+* Building Emacs:: How the dumped Emacs is made.
* Pure Storage:: A kludge to make preloaded Lisp functions sharable.
* Garbage Collection:: Reclaiming space for Lisp objects no longer used.
* Memory Usage:: Info about total size of Lisp objects made so far.
After @file{loadup.el} reads @file{site-load.el}, it finds the
documentation strings for primitive and preloaded functions (and
-variables) in the file @file{etc/DOC} where they are stored, by calling
-@code{Snarf-documentation} (@pxref{Accessing Documentation}).
+variables) in the file @file{etc/DOC} where they are stored, by
+calling @code{Snarf-documentation} (@pxref{Definition of
+Snarf-documentation,, Accessing Documentation}).
@cindex @file{site-init.el}
You can specify other Lisp expressions to execute just before dumping
@defun purecopy object
This function makes a copy in pure storage of @var{object}, and returns
it. It copies a string by simply making a new string with the same
-characters in pure storage. It recursively copies the contents of
-vectors and cons cells. It does not make copies of other objects such
-as symbols, but just returns them unchanged. It signals an error if
-asked to copy markers.
+characters, but without text properties, in pure storage. It
+recursively copies the contents of vectors and cons cells. It does
+not make copies of other objects such as symbols, but just 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
@code{nil}, meaning there are no such messages.
@end defopt
+@defvar post-gc-hook
+This is a normal hook that is run at the end of garbage collection.
+Garbage collection is inhibited while the hook functions run, so be
+careful writing them.
+@end defvar
+
@defopt gc-cons-threshold
The value of this variable is the number of bytes of storage that must
be allocated for Lisp objects after one garbage collection in order to
@code{garbage-collect} will set the threshold back to 10,000.
@end defopt
- The value return by @code{garbage-collect} describes the amount of
+ The value returned by @code{garbage-collect} describes the amount of
memory used by Lisp data, broken down by data type. By contrast, the
function @code{memory-limit} provides information on the total amount of
memory Emacs is currently using.
memory usage.
@end defun
+@defun memory-use-counts
+This returns a list of numbers that count the number of objects
+created in this Emacs session. Each of these counters increments for
+a certain kind of object. See the documentation string for details.
+@end defun
+
+@defvar gcs-done
+This variable contains the total number of garbage collections
+done so far in this Emacs session.
+@end defvar
+
+@defvar gc-elapsed
+This variable contains the total number of seconds of elapsed time
+during garbage collection so far in this Emacs session, as a floating
+point number.
+@end defvar
+
@node Memory Usage
@section Memory Usage
@smallexample
@group
DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
- "Eval args until one of them yields non-nil; return that value.\n\
-The remaining args are not evalled at all.\n\
+ 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
-If all args return nil, return nil.")
+usage: (or CONDITIONS ...) */)
(args)
Lisp_Object args;
@{
- register Lisp_Object val;
- Lisp_Object args_left;
+ register Lisp_Object val = Qnil;
struct gcpro gcpro1;
@end group
@group
- if (NILP (args))
- return Qnil;
-
- args_left = args;
- GCPRO1 (args_left);
+ GCPRO1 (args);
@end group
@group
- do
+ while (CONSP (args))
@{
- val = Feval (Fcar (args_left));
+ val = Feval (XCAR (args));
if (!NILP (val))
- break;
- args_left = Fcdr (args_left);
+ break;
+ args = XCDR (args);
@}
- while (!NILP (args_left));
@end group
@group
@code{MANY}, indicating an unlimited number of evaluated arguments (the
equivalent of @code{&rest}). Both @code{UNEVALLED} and @code{MANY} are
macros. If @var{max} is a number, it may not be less than @var{min} and
-it may not be greater than seven.
+it may not be greater than eight.
@item interactive
This is an interactive specification, a string such as might be used as
should receive no arguments when called interactively.
@item doc
-This is the documentation string. It is written just like a
-documentation string for a function defined in Lisp, except you must
-write @samp{\n\} at the end of each line. In particular, the first line
-should be a single sentence.
+This is the documentation string. It uses C comment syntax rather
+than C string syntax because comment syntax requires nothing special
+to include multiple lines. The @samp{doc:} identifies the comment
+that follows as the documentation string. The @samp{/*} and @samp{*/}
+delimiters that begin and end the comment are not part of the
+documentation string.
+
+If the last line of the documentation string begins with the keyword
+@samp{usage:}, the rest of the line is treated as the argument list
+for documentation purposes. This way, you can use different argument
+names in the documentation string from the ones used in the C code.
+@samp{usage:} is required if the function has an unlimited number of
+arguments.
+
+All the usual rules for documentation strings in Lisp code
+(@pxref{Documentation Tips}) apply to C code documentation strings
+too.
@end table
After the call to the @code{DEFUN} macro, you must write the argument
@code{UNGCPRO} cancels the protection of the variables that are
protected in the current function. It is necessary to do this explicitly.
- For most data types, it suffices to protect at least one pointer to
-the object; as long as the object is not recycled, all pointers to it
-remain valid. This is not so for strings, because the garbage collector
-can move them. When the garbage collector moves a string, it relocates
-all the pointers it knows about; any other pointers become invalid.
-Therefore, you must protect all pointers to strings across any point
-where garbage collection may be possible.
-
- 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} and @code{GCPRO4} 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 @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
+ 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.)
+
+ 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
+@code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
Alas, we can't explain all the tricky details here.
+ 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
+arguments. This C vector may be part of a Lisp vector, but it need
+not be. The responsibility for using @code{GCPRO} to protect the Lisp
+arguments from GC if necessary rests with the caller in this case,
+since the caller allocated or found the storage for them.
+
You must not use C initializers for static or global variables unless
the variables are never written once Emacs is dumped. These variables
with initializers are allocated in an area of memory that becomes
of these functions are called, and add a call to
@code{syms_of_@var{filename}} there.
+@anchor{Defining Lisp variables in C}
@vindex byte-boolean-vars
The function @code{syms_of_@var{filename}} is also the place to define
any C variables that are to be visible as Lisp variables.
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\
+ "Return non-nil if COORDINATES is in WINDOW.\n\
COORDINATES is a cons of the form (X . Y), X and Y being distances\n\
...
@end group
@file{lisp.h} contains the definitions for some important macros and
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
-@code{side-effect-and-error-free-fns} to include it. This will help the
-optimizer.
+ 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
+@code{side-effect-and-error-free-fns} so that the compiler optimizer
+knows about it.
@node Object Internals
@appendixsec Object Internals
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-eight bits are used to address the
-object, and the remaining four bits are used for a GC mark bit and the
-tag that identifies the object's type.
+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.
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
@item gpt
This holds the character position of the gap in the buffer.
+@xref{Buffer Gap}.
@item z
This field contains the character position of the end of the buffer
Holds the byte position of the end of the buffer text.
@item gap_size
-Contains the size of buffer's gap.
+Contains the size of buffer's gap. @xref{Buffer Gap}.
@item modiff
This field counts buffer-modification events for this buffer. It is
@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}.
-
+
@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.
-
+
@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},
@code{beg_unchanged} and @code{end_unchanged} contain no useful
information.
-
+
@item markers
The markers that refer to this buffer. This is actually a single
marker, and successive elements in its marker @code{chain} are the other
Contains the byte position of point in a buffer.
@item begv
-This field contains the character position of the beginning of the
+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
+This field contains the byte position 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
+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
+This field contains the byte position of the end of the
accessible range of text in the buffer.
@item base_buffer
This flag is set when narrowing changes in a buffer.
@item prevent_redisplay_optimizations_p
-this flag indicates that redisplay optimizations should not be used
+this flag indicates that redisplay optimizations should not be used
to display this buffer.
@item undo_list
@item filename
The name of the file visited in this buffer, or @code{nil}.
-
+
@item directory
The directory for expanding relative file names.
@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
+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 read_only
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 analoguous to @code{mode_line_format} for the mode
line displayed at the top of windows.
@item keymap
@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
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
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
@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
is on the screen.
@item frozen_window_start_p
-This field is set temporarily to 1 to indicate to redisplay that
+This field is set temporarily to 1 to indicate to redisplay that
@code{start} of this window should not be changed, even if point
gets invisible.
@item redisplay_end_trigger
If redisplay in this window goes beyond this buffer position, it runs
-run the @code{redisplay-end-trigger-hook}.
+the @code{redisplay-end-trigger-hook}.
@ignore
@item orig_height
The associated buffer of the process.
@item pid
-An integer, the Unix process @sc{id}.
+An integer, the operating system's process @acronym{ID}.
@item childp
A flag, non-@code{nil} if this is really a child process.
message in the process buffer.
@item pty_flag
-Non-@code{nil} if communication with the subprocess uses a @sc{pty};
+Non-@code{nil} if communication with the subprocess uses a @acronym{PTY};
@code{nil} if it uses a pipe.
@item infd
Coding-system for encoding the output to this process.
@item encoding_buf
-A working buffer for enecoding.
+A working buffer for encoding.
@item encoding_carryover
Size of carryover in encoding.
Flag to set @code{coding-system} of the process buffer from the
coding system used to decode process output.
@end table
+
+@ignore
+ arch-tag: 4b2c33bc-d7e4-43f5-bc20-27c0db52a53e
+@end ignore