X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/f46305c86cd247b2396e73ce8bb064f69373834d..8208d2bf95f924ed810dc06e84fc4c7d5ac004a5:/doc/lispref/internals.texi diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 06375c1e18..3a5bd4aea7 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -1,6 +1,6 @@ @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 @@ -15,6 +15,7 @@ internal aspects of GNU Emacs that may be of interest to C programmers. * 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. @@ -111,11 +112,18 @@ drawback that the documentation strings take up space in Emacs all the 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 @@ -512,8 +520,8 @@ done so far in this Emacs session. @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 @@ -568,6 +576,19 @@ The total number of strings that have been allocated so far in this 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{} 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 @@ -912,7 +933,7 @@ following basic data types: integer, symbol, string, cons cell, float, 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 @@ -940,7 +961,7 @@ Array, a fixed-size set of Lisp objects which may be accessed by an index. 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. @@ -1261,6 +1282,8 @@ except to shape their child windows. Emacs Lisp programs usually have 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 @@ -1432,11 +1455,6 @@ The position in the buffer for which the line number is known, or @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. @@ -1464,12 +1482,10 @@ process. For a network or serial process, it is @code{nil} if the 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. @@ -1606,7 +1622,7 @@ although @code{off_t} is always signed, @code{time_t} need not be. @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 @@ -1614,20 +1630,22 @@ Prefer @code{intmax_t} for representing values that might be any 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?