@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1993, 1998-1999, 2001-2013 Free Software
+@c Copyright (C) 1990-1993, 1998-1999, 2001-2014 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node GNU Emacs Internals
* 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.
+* C Dialect:: What C variant Emacs is written in.
* Writing Emacs Primitives:: Writing C code for Emacs.
* Object Internals:: Data formats of buffers, windows, processes.
* C Integer Types:: How C integer types are used inside Emacs.
time.)
@end itemize
+@cindex change @code{load-path} at configure time
+@cindex @option{--enable-locallisppath} option to @command{configure}
It is not advisable to put anything in @file{site-load.el} or
@file{site-init.el} that would alter any of the features that users
expect in an ordinary unmodified Emacs. If you feel you must override
normal features for your site, do it with @file{default.el}, so that
users can override your changes if they wish. @xref{Startup Summary}.
+Note that if either @file{site-load.el} or @file{site-init.el} changes
+@code{load-path}, the changes will be lost after dumping.
+@xref{Library Search}. To make a permanent change to
+@code{load-path}, use the @option{--enable-locallisppath} option
+of @command{configure}.
In a package that can be preloaded, it is sometimes necessary (or
useful) to delay certain evaluations until Emacs subsequently starts
@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.
+during garbage collection so far in this Emacs session, as a
+floating-point number.
@end defvar
@node Memory Usage
Emacs session.
@end defvar
+@node C Dialect
+@section C Dialect
+@cindex C programming language
+
+The C part of Emacs is portable to C99 or later: C11-specific features such
+as @samp{<stdalign.h>} and @samp{_Noreturn} are not used without a check,
+typically at configuration time, and the Emacs build procedure
+provides a substitute implementation if necessary. Some C11 features,
+such as anonymous structures and unions, are too difficult to emulate,
+so they are avoided entirely.
+
+At some point in the future the base C dialect will no doubt change to C11.
+
@node Writing Emacs Primitives
@section Writing Emacs Primitives
@cindex primitive function internals
macros. If @var{max} is a number, it must be more than @var{min} but
less than 8.
+@cindex interactive specification in primitives
@item interactive
-This is an interactive specification, a string such as might be used as
-the argument of @code{interactive} in a Lisp function. In the case of
-@code{or}, it is 0 (a null pointer), indicating that @code{or} cannot be
-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}.
+This is an interactive specification, a string such as might be used
+as the argument of @code{interactive} in a Lisp function. In the case
+of @code{or}, it is 0 (a null pointer), indicating that @code{or}
+cannot be 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 example:
+
+@example
+@group
+DEFUN ("foo", Ffoo, Sfoo, 0, UNEVALLED,
+ "(list (read-char-by-name \"Insert character: \")\
+ (prefix-numeric-value current-prefix-arg)\
+ t))",
+ doc: /* @dots{} /*)
+@end group
+@end example
@item doc
This is the documentation string. It uses C comment syntax rather
vectorlike or miscellaneous object. Each of these data types has the
corresponding tag value. All tags are enumerated by @code{enum Lisp_Type}
and placed into a 3-bit bitfield of the @code{Lisp_Object}. The rest of the
-bits is the value itself. Integer values are immediate, i.e., directly
+bits is the value itself. Integers are immediate, i.e., directly
represented by those @dfn{value bits}, and all other objects are represented
by the C pointers to a corresponding object allocated from the heap. Width
of the @code{Lisp_Object} is platform- and configuration-dependent: usually
Symbol, the unique-named entity commonly used as an identifier.
@item struct Lisp_Float
-Floating point value.
+Floating-point value.
@item union Lisp_Misc
Miscellaneous kinds of objects which don't fit into any of the above.
no access to the parent windows; they operate on the windows at the
leaves of the tree, which actually display buffers.
+@c FIXME: These two slots and the `buffer' slot below were replaced
+@c with a single slot `contents' on 2013-03-28. --xfq
@item hchild
@itemx vchild
These fields contain the window's leftmost child and its topmost child
@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
-holds the mark position that made one end of that region. Otherwise,
-this field is @code{nil}.
-
@item column_number_displayed
The column number currently displayed in this window's mode line, or @code{nil}
if column numbers are not being displayed.
process is running or @code{t} if the process is stopped.
@item filter
-If non-@code{nil}, a function used to accept output from the process
-instead of a buffer.
+A function used to accept output from the process.
@item sentinel
-If non-@code{nil}, a function called whenever the state of the process
-changes.
+A function called whenever the state of the process changes.
@item buffer
The associated buffer of the process.
@item
Prefer the Emacs-defined type @code{printmax_t} for representing
-values that might be any signed integer value that can be printed,
+values that might be any signed integer that can be printed,
using a @code{printf}-family function.
@item
signed integer value.
@item
-In bitfields, prefer @code{unsigned int} or @code{signed int} to
-@code{int}, as @code{int} is less portable: it might be signed, and
-might not be. Single-bit bit fields are invariably @code{unsigned
-int} so that their values are 0 and 1.
-
-@item
-In C, Emacs commonly uses @code{bool}, 1, and 0 for boolean values.
-Using @code{bool} for booleans can make programs easier to read and a
-bit faster than using @code{int}. Although it is also OK to use
-@code{int}, this older style is gradually being phased out. When
+Prefer @code{bool}, @code{false} and @code{true} for booleans.
+Using @code{bool} can make programs easier to read and a bit faster than
+using @code{int}. Although it is also OK to use @code{int}, @code{0}
+and @code{1}, this older style is gradually being phased out. When
using @code{bool}, respect the limitations of the replacement
implementation of @code{bool}, as documented in the source file
@file{lib/stdbool.in.h}, so that Emacs remains portable to pre-C99
-platforms.
+platforms. In particular, boolean bitfields should be of type
+@code{bool_bf}, not @code{bool}, so that they work correctly even when
+compiling Objective C with standard GCC.
+
+@item
+In bitfields, prefer @code{unsigned int} or @code{signed int} to
+@code{int}, as @code{int} is less portable: it might be signed, and
+might not be. Single-bit bit fields should be @code{unsigned int} or
+@code{bool_bf} so that their values are 0 or 1.
@end itemize
@c FIXME Mention src/globals.h somewhere in this file?
HCoop / bpt / emacs.git / blobdiff