changeset 84003:e9ba15158cdc

Move to ../doc/lispref

--- a/lispref/internals.texi	Thu Sep 06 04:11:53 2007 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,1522 +0,0 @@
-@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  Free Software Foundation, Inc.
-@c See the file elisp.texi for copying conditions.
-@setfilename ../info/internals
-@node GNU Emacs Internals, Standard Errors, Tips, Top
-@comment  node-name,  next,  previous,  up
-@appendix GNU Emacs Internals
-
-This chapter describes how the runnable Emacs executable is dumped with
-the preloaded Lisp libraries in it, how storage is allocated, and some
-internal aspects of GNU Emacs that may be of interest to C programmers.
-
-@menu
-* 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.
-* Writing Emacs Primitives::   Writing C code for Emacs.
-* Object Internals::    Data formats of buffers, windows, processes.
-@end menu
-
-@node Building Emacs
-@appendixsec Building Emacs
-@cindex building Emacs
-@pindex temacs
-
-  This section explains the steps involved in building the Emacs
-executable.  You don't have to know this material to build and install
-Emacs, since the makefiles do all these things automatically.  This
-information is pertinent to Emacs maintenance.
-
-   Compilation of the C source files in the @file{src} directory
-produces an executable file called @file{temacs}, also called a
-@dfn{bare impure Emacs}.  It contains the Emacs Lisp interpreter and I/O
-routines, but not the editing commands.
-
-@cindex @file{loadup.el}
-  The command @w{@samp{temacs -l loadup}} uses @file{temacs} to create
-the real runnable Emacs executable.  These arguments direct
-@file{temacs} to evaluate the Lisp files specified in the file
-@file{loadup.el}.  These files set up the normal Emacs editing
-environment, resulting in an Emacs that is still impure but no longer
-bare.
-
-@cindex dumping Emacs
-  It takes a substantial 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.
-
-  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}.
-
-  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.
-
-@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
-
-@example
-#define SITELOAD_PURESIZE_EXTRA @var{n}
-@end example
-
-@noindent
-to make @var{n} added bytes of pure space to hold the additional files.
-(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.
-
-  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{Definition of
-Snarf-documentation,, Accessing Documentation}).
-
-@cindex @file{site-init.el}
-@cindex preloading additional functions and variables
-  You can specify other Lisp expressions to execute just before dumping
-by putting them in a library named @file{site-init.el}.  This file is
-executed after the documentation strings are found.
-
-  If you want to preload function or variable definitions, there are
-three ways you can do this and make their documentation strings
-accessible when you subsequently run Emacs:
-
-@itemize @bullet
-@item
-Arrange to scan these files when producing the @file{etc/DOC} file,
-and load them with @file{site-load.el}.
-
-@item
-Load the files with @file{site-init.el}, then copy the files into the
-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.)
-@end itemize
-
-  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}.
-
-  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}:
-
-@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
-
-@defun dump-emacs to-file from-file
-@cindex unexec
-This function dumps the current state of Emacs into an executable file
-@var{to-file}.  It takes symbols from @var{from-file} (this is normally
-the executable file @file{temacs}).
-
-If you want to use this function in an Emacs that was already dumped,
-you must run Emacs with @samp{-batch}.
-@end defun
-
-@node Pure Storage
-@appendixsec 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.
-
-  Pure storage is allocated only while @file{temacs} is loading the
-standard preloaded Lisp libraries.  In the file @file{emacs}, it is
-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} 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
-it.  It copies a string by simply making a new string with the same
-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
-a few packages call it just in case you decide to preload them.
-@end defun
-
-@defvar pure-bytes-used
-The value of this variable is the number of bytes of pure storage
-allocated so far.  Typically, in a dumped Emacs, this number is very
-close to the total amount of pure storage available---if it were not,
-we would preallocate less.
-@end defvar
-
-@defvar purify-flag
-This variable determines whether @code{defun} should make a copy of the
-function definition in pure storage.  If it is non-@code{nil}, then the
-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
-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.
-
-You should not change this flag in a running Emacs.
-@end defvar
-
-@node Garbage Collection
-@appendixsec Garbage Collection
-@cindex garbage collection
-
-@cindex memory allocation
-  When a program creates a list or the user defines a new function (such
-as by loading a library), that data is placed in normal storage.  If
-normal storage runs low, then Emacs asks the operating system to
-allocate more memory in blocks of 1k bytes.  Each block is used for one
-type of Lisp object, so symbols, cons cells, markers, etc., are
-segregated in distinct blocks in memory.  (Vectors, long strings,
-buffers and certain other editing types, which are fairly large, are
-allocated in individual blocks, one per object, while small strings are
-packed into blocks of 8k bytes.)
-
-  It is quite common to use some storage for a while, then release it by
-(for example) killing a buffer or deleting the last pointer to an
-object.  Emacs provides a @dfn{garbage collector} to reclaim this
-abandoned storage.  (This name is traditional, but ``garbage recycler''
-might be a more intuitive metaphor for this facility.)
-
-  The garbage collector operates by finding and marking all Lisp objects
-that are still accessible to Lisp programs.  To begin with, it assumes
-all the symbols, their values and associated function definitions, and
-any data presently on the stack, are accessible.  Any objects that can
-be reached indirectly through other accessible objects are also
-accessible.
-
-  When marking is finished, all objects still unmarked are garbage.  No
-matter what the Lisp program or the user does, it is impossible to refer
-to them, since there is no longer a way to reach them.  Their space
-might as well be reused, since no one will miss them.  The second
-(``sweep'') phase of the garbage collector arranges to reuse them.
-
-@c ??? Maybe add something describing weak hash tables here?
-
-@cindex free list
-  The sweep phase puts unused cons cells onto a @dfn{free list}
-for future allocation; likewise for symbols and markers.  It compacts
-the accessible strings so they occupy fewer 8k blocks; then it frees the
-other 8k blocks.  Vectors, buffers, windows, and other large objects are
-individually allocated and freed using @code{malloc} and @code{free}.
-
-@cindex CL note---allocate more storage
-@quotation
-@b{Common Lisp note:} Unlike other Lisps, GNU Emacs Lisp does not
-call the garbage collector when the free list is empty.  Instead, it
-simply requests the operating system to allocate more storage, and
-processing continues until @code{gc-cons-threshold} bytes have been
-used.
-
-This means that you can make sure that the garbage collector will not
-run during a certain portion of a Lisp program by calling the garbage
-collector explicitly just before it (provided that portion of the
-program does not use so much space as to force a second garbage
-collection).
-@end quotation
-
-@deffn Command garbage-collect
-This command runs a garbage collection, and returns information on
-the amount of space in use.  (Garbage collection can also occur
-spontaneously if you use more than @code{gc-cons-threshold} bytes of
-Lisp data since the previous garbage collection.)
-
-@code{garbage-collect} returns a list containing the following
-information:
-
-@example
-@group
-((@var{used-conses} . @var{free-conses})
- (@var{used-syms} . @var{free-syms})
-@end group
- (@var{used-miscs} . @var{free-miscs})
- @var{used-string-chars}
- @var{used-vector-slots}
- (@var{used-floats} . @var{free-floats})
- (@var{used-intervals} . @var{free-intervals})
- (@var{used-strings} . @var{free-strings}))
-@end example
-
-Here is an example:
-
-@example
-@group
-(garbage-collect)
-     @result{} ((106886 . 13184) (9769 . 0)
-                (7731 . 4651) 347543 121628
-                (31 . 94) (1273 . 168)
-                (25474 . 3569))
-@end group
-@end example
-
-Here is a table explaining each element:
-
-@table @var
-@item used-conses
-The number of cons cells in use.
-
-@item free-conses
-The number of cons cells for which space has been obtained from the
-operating system, but that are not currently being used.
-
-@item used-syms
-The number of symbols in use.
-
-@item free-syms
-The number of symbols for which space has been obtained from the
-operating system, but that are not currently being used.
-
-@item used-miscs
-The number of miscellaneous objects in use.  These include markers and
-overlays, plus certain objects not visible to users.
-
-@item free-miscs
-The number of miscellaneous objects for which space has been obtained
-from the operating system, but that are not currently being used.
-
-@item used-string-chars
-The total size of all strings, in characters.
-
-@item used-vector-slots
-The total number of elements of existing vectors.
-
-@item used-floats
-@c Emacs 19 feature
-The number of floats in use.
-
-@item free-floats
-@c Emacs 19 feature
-The number of floats for which space has been obtained from the
-operating system, but that are not currently being used.
-
-@item used-intervals
-The number of intervals in use.  Intervals are an internal
-data structure used for representing text properties.
-
-@item free-intervals
-The number of intervals for which space has been obtained
-from the operating system, but that are not currently being used.
-
-@item used-strings
-The number of strings in use.
-
-@item free-strings
-The number of string headers for which the space was obtained from the
-operating system, but which are currently not in use.  (A string
-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
-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.
-@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
-trigger another garbage collection.  A cons cell counts as eight bytes,
-a string as one byte per character plus a few bytes of overhead, and so
-on; space allocated to the contents of buffers does not count.  Note
-that the subsequent garbage collection does not happen immediately when
-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
-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
-Lisp data.
-
-You can make collections more frequent by specifying a smaller value,
-down to 10,000.  A value less than 10,000 will remain in effect only
-until the subsequent garbage collection, at which time
-@code{garbage-collect} will set the threshold back to 10,000.
-@end defopt
-
-@defopt gc-cons-percentage
-The value of this variable specifies the amount of consing before a
-garbage collection occurs, as a fraction of the current heap size.
-This criterion and @code{gc-cons-threshold} apply in parallel, and
-garbage collection occurs only when both criteria are satisfied.
-
-As the heap size increases, the time to perform a garbage collection
-increases.  Thus, it can be desirable to do them less frequently in
-proportion.
-@end defopt
-
-  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.
-
-@c Emacs 19 feature
-@defun memory-limit
-This function returns the address of the last byte Emacs has allocated,
-divided by 1024.  We divide the value by 1024 to make sure it fits in a
-Lisp integer.
-
-You can use this to get a general idea of how your actions affect the
-memory usage.
-@end defun
-
-@defvar memory-full
-This variable is @code{t} if Emacs is close to out of memory for Lisp
-objects, and @code{nil} otherwise.
-@end defvar
-
-@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
-@cindex memory usage
-
-  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
-these count the number or size of all allocations, including those for
-objects that have since been freed.
-
-@defvar cons-cells-consed
-The total number of cons cells that have been allocated so far
-in this Emacs session.
-@end defvar
-
-@defvar floats-consed
-The total number of floats that have been allocated so far
-in this Emacs session.
-@end defvar
-
-@defvar vector-cells-consed
-The total number of vector cells that have been allocated so far
-in this Emacs session.
-@end defvar
-
-@defvar symbols-consed
-The total number of symbols that have been allocated so far
-in this Emacs session.
-@end defvar
-
-@defvar string-chars-consed
-The total number of string characters that have been allocated so far
-in this Emacs session.
-@end defvar
-
-@defvar misc-objects-consed
-The total number of miscellaneous objects that have been allocated so
-far in this Emacs session.  These include markers and overlays, plus
-certain objects not visible to users.
-@end defvar
-
-@defvar intervals-consed
-The total number of intervals that have been allocated so far
-in this Emacs session.
-@end defvar
-
-@defvar strings-consed
-The total number of strings that have been allocated so far in this
-Emacs session.
-@end defvar
-
-@node Writing Emacs Primitives
-@appendixsec Writing Emacs Primitives
-@cindex primitive function internals
-@cindex writing Emacs primitives
-
-  Lisp primitives are Lisp functions implemented in C.  The details of
-interfacing the C function so that Lisp can call it are handled by a few
-C macros.  The only way to really understand how to write new C code is
-to read the source, but we can explain some things here.
-
-  An example of a special form is the definition of @code{or}, from
-@file{eval.c}.  (An ordinary function would have the same general
-appearance.)
-
-@cindex garbage collection protection
-@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.
-If all args return nil, return nil.
-@end group
-@group
-usage: (or CONDITIONS ...)  */)
-  (args)
-     Lisp_Object args;
-@{
-  register Lisp_Object val = Qnil;
-  struct gcpro gcpro1;
-@end group
-
-@group
-  GCPRO1 (args);
-@end group
-
-@group
-  while (CONSP (args))
-    @{
-      val = Feval (XCAR (args));
-      if (!NILP (val))
-        break;
-      args = XCDR (args);
-    @}
-@end group
-
-@group
-  UNGCPRO;
-  return val;
-@}
-@end group
-@end smallexample
-
-@cindex @code{DEFUN}, C macro to define Lisp primitives
-  Let's start with a precise explanation of the arguments to the
-@code{DEFUN} macro.  Here is a template for them:
-
-@example
-DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc})
-@end example
-
-@table @var
-@item lname
-This is the name of the Lisp symbol to define as the function name; in
-the example above, it is @code{or}.
-
-@item fname
-This is the C function name for this function.  This is
-the name that is used in C code for calling the function.  The name is,
-by convention, @samp{F} prepended to the Lisp name, with all dashes
-(@samp{-}) in the Lisp name changed to underscores.  Thus, to call this
-function from C code, call @code{For}.  Remember that the arguments must
-be of type @code{Lisp_Object}; various macros and functions for creating
-values of type @code{Lisp_Object} are declared in the file
-@file{lisp.h}.
-
-@item sname
-This is a C variable name to use for a structure that holds the data for
-the subr object that represents the function in Lisp.  This structure
-conveys the Lisp symbol name to the initialization routine that will
-create the symbol and store the subr object as its definition.  By
-convention, this name is always @var{fname} with @samp{F} replaced with
-@samp{S}.
-
-@item min
-This is the minimum number of arguments that the function requires.  The
-function @code{or} allows a minimum of zero arguments.
-
-@item max
-This is the maximum number of arguments that the function accepts, if
-there is a fixed maximum.  Alternatively, it can be @code{UNEVALLED},
-indicating a special form that receives unevaluated arguments, or
-@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 eight.
-
-@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.
-
-@item doc
-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
-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 *}}.
-
-@cindex @code{GCPRO} and @code{UNGCPRO}
-@cindex protect C variables from garbage collection
-  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.  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; 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 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
-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
-read-only (on certain operating systems) as a result of dumping Emacs.
-@xref{Pure Storage}.
-
-  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
-macro.  (This definition is used because those systems put all variables
-declared static in a place that becomes read-only after dumping, whether
-they have initializers or not.)
-
-@cindex @code{defsubr}, Lisp symbol for a primitive
-  Defining the C function is not enough to make a Lisp primitive
-available; you must also create the Lisp symbol for the primitive and
-store a suitable subr object in its function cell.  The code looks like
-this:
-
-@example
-defsubr (&@var{subr-structure-name});
-@end example
-
-@noindent
-Here @var{subr-structure-name} 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
-@code{syms_of_@var{something}}, and add the call to @code{defsubr}
-there.  If the file doesn't have this function, or if you create a new
-file, add to it a @code{syms_of_@var{filename}} (e.g.,
-@code{syms_of_myfile}).  Then find the spot in @file{emacs.c} where all
-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
-@cindex defining Lisp variables in C
-@cindex @code{DEFVAR_INT}, @code{DEFVAR_LISP}, @code{DEFVAR_BOOL}
-  The function @code{syms_of_@var{filename}} is also the place to define
-any C variables that are to be visible as Lisp variables.
-@code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible
-in Lisp.  @code{DEFVAR_INT} makes a C variable of type @code{int}
-visible in Lisp with a value that is always an integer.
-@code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp
-with a value that is either @code{t} or @code{nil}.  Note that variables
-defined with @code{DEFVAR_BOOL} are automatically added to the list
-@code{byte-boolean-vars} used by the byte compiler.
-
-@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}
-in @code{syms_of_@var{filename}}, like this:
-
-@example
-staticpro (&@var{variable});
-@end example
-
-  Here is another example function, with more complicated arguments.
-This comes from the code in @file{window.c}, and it demonstrates the use
-of macros and functions to manipulate Lisp objects.
-
-@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\
-...
-@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;
-@{
-  int x, y;
-@end group
-
-@group
-  CHECK_LIVE_WINDOW (window, 0);
-  CHECK_CONS (coordinates, 1);
-  x = XINT (Fcar (coordinates));
-  y = XINT (Fcdr (coordinates));
-@end group
-
-@group
-  switch (coordinates_in_window (XWINDOW (window), &x, &y))
-    @{
-    case 0:			/* 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. */
-      return Qmode_line;
-@end group
-
-@group
-    case 3:			/* On right border of window.  */
-      return Qvertical_line;
-@end group
-
-@group
-    default:
-      abort ();
-    @}
-@}
-@end group
-@end smallexample
-
-  Note that C code cannot call functions by name unless they are defined
-in C.  The way to call a function written in Lisp is to use
-@code{Ffuncall}, which embodies the Lisp function @code{funcall}.  Since
-the Lisp function @code{funcall} accepts an unlimited number of
-arguments, in C it takes two: the number of Lisp-level arguments, and a
-one-dimensional array containing their values.  The first Lisp-level
-argument is the Lisp function to call, and the rest are the arguments to
-pass to it.  Since @code{Ffuncall} can call the evaluator, you must
-protect pointers from garbage collection around the call to
-@code{Ffuncall}.
-
-  The C functions @code{call0}, @code{call1}, @code{call2}, and so on,
-provide handy ways to call a Lisp function conveniently with a fixed
-number of arguments.  They work by calling @code{Ffuncall}.
-
-  @file{eval.c} is a very good file to look through for examples;
-@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} so that the compiler optimizer
-knows about it.
-
-@node Object Internals
-@appendixsec Object Internals
-@cindex object internals
-
-  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.
-
-  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
-@code{Lisp_Object} can hold any Lisp object of any data type.  Ordinary
-variables have type @code{Lisp_Object}, which means they can hold any
-type of Lisp value; you can determine the actual data type only at run
-time.  The same is true for function arguments; if you want a function
-to accept only a certain type of argument, you must check the type
-explicitly using a suitable predicate (@pxref{Type Predicates}).
-@cindex type checking internals
-
-@menu
-* Buffer Internals::    Components of a buffer structure.
-* Window Internals::    Components of a window structure.
-* Process Internals::   Components of a process structure.
-@end menu
-
-@node Buffer Internals
-@appendixsubsec 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.
-
-Here is a list of the @code{struct buffer_text} fields:
-
-@table @code
-@item beg
-This field contains the actual address of the buffer contents.
-
-@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
-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.
-
-@item gap_size
-Contains 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}.
-
-@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
-markers referring to this buffer text.
-
-@item intervals
-Contains the interval tree which records the text properties of this
-buffer.
-@end table
-
-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 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.
-
-@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.
-
-@item pt
-Contains the character position of point in a buffer.
-
-@item pt_byte
-Contains the byte position 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.
-
-@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.
-
-@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
-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}.
-
-@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.
-
-@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.
-
-@item clip_changed
-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
-to display this buffer.
-
-@item undo_list
-This field points to the buffer's undo list.  @xref{Undo}.
-
-@item name
-The buffer name is a string that names the buffer.  It is guaranteed to
-be unique.  @xref{Buffer Names}.
-
-@item filename
-The name of the file visited in this buffer, or @code{nil}.
-
-@item directory
-The directory for expanding relative file 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.
-
-@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 read_only
-Non-@code{nil} means this buffer is read-only.
-
-@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}.
-
-@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}.
-
-@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.
-
-@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.
-
-@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.
-@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
-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 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
-@cindex internals, of window
-@cindex window internals
-
-  Windows have the following accessible fields:
-
-@table @code
-@item frame
-The frame that this window is on.
-
-@item mini_p
-Non-@code{nil} if this window is a minibuffer window.
-
-@item parent
-Internally, Emacs arranges windows in a tree; each group of siblings has
-a parent window whose area includes all the siblings.  This field points
-to a window's parent.
-
-Parent windows do not display buffers, and play little role in display
-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.
-
-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}.
-
-@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).
-
-@item buffer
-The buffer that the window is displaying.  This may change often during
-the life of the window.
-
-@item start
-The position in the buffer that is the first character to be displayed
-in the window.
-
-@item pointm
-@cindex window point internals
-This is the value of point in the current buffer when this window is
-selected; when it is not selected, it retains its previous value.
-
-@item force_start
-If this flag is non-@code{nil}, it says that the window has been
-scrolled explicitly by the Lisp program.  This affects what the next
-redisplay does if point is off the screen: instead of scrolling the
-window to show the text around point, it moves point to a location that
-is on the screen.
-
-@item frozen_window_start_p
-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 start_at_line_beg
-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 sequence_number
-A unique number assigned to this window when it was created.
-
-@item last_modified
-The @code{modiff} field of the window's buffer, as of the last time
-a redisplay completed in this window.
-
-@item last_overlay_modified
-The @code{overlay_modiff} field of the window's buffer, as of the last
-time a redisplay completed in this window.
-
-@item last_point
-The buffer's value of point, as of the last time a redisplay completed
-in this window.
-
-@item last_had_star
-A non-@code{nil} value means the window's buffer was ``modified'' when the
-window was last updated.
-
-@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 right_margin_width
-Likewise for the right margin.
-
-@ignore
-@item last_mark_x
-@item last_mark_y
-???Not used.
-@end ignore
-
-@item window_end_pos
-This is computed as @code{z} minus the buffer position of the last glyph
-in the current matrix of the window.  The value is only valid if
-@code{window_end_valid} is not @code{nil}.
-
-@item window_end_bytepos
-The byte position corresponding to @code{window_end_pos}.
-
-@item window_end_vpos
-The window-relative vertical position of the line containing
-@code{window_end_pos}.
-
-@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
-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.
-
-@item last_cursor
-The value of @code{cursor} as of the last redisplay that finished.
-
-@item phys_cursor
-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.
-
-@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.
-
-@item last_cursor_off_p
-This field contains the value of @code{cursor_off_p} as of the time of
-the last redisplay.
-
-@item must_be_updated_p
-This is set to 1 during redisplay when this window must be updated.
-
-@item hscroll
-This is the number of columns that the display in the window is scrolled
-horizontally to the left.  Normally, this is 0.
-
-@item vscroll
-Vertical scroll amount, in pixels.  Normally, this is 0.
-
-@item dedicated
-Non-@code{nil} if this window is dedicated to its buffer.
-
-@item display_table
-The window's display table, or @code{nil} if none is specified for it.
-
-@item update_mode_line
-Non-@code{nil} means this window's mode line needs to be updated.
-
-@item base_line_number
-The line number of a certain position in the buffer, or @code{nil}.
-This is used for displaying the line number of point in the mode line.
-
-@item base_line_pos
-The position in the buffer for which the line number is known, or
-@code{nil} meaning none is known.
-
-@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.
-
-@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.
-@end table
-
-@node Process Internals
-@appendixsubsec Process Internals
-@cindex internals, of process
-@cindex process internals
-
-  The fields of a process are:
-
-@table @code
-@item name
-A string, the name of the process.
-
-@item command
-A list containing the command arguments that were used to start this
-process.
-
-@item filter
-A function used to accept output from the process instead of a buffer,
-or @code{nil}.
-
-@item sentinel
-A function called whenever the process receives a signal, or @code{nil}.
-
-@item buffer
-The associated buffer of the process.
-
-@item pid
-An integer, the operating system's process @acronym{ID}.
-
-@item childp
-A flag, non-@code{nil} if this is really a child process.
-It is @code{nil} for a network connection.
-
-@item mark
-A marker indicating the position of the end of the last output from this
-process inserted into the buffer.  This is often but not always the end
-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.
-
-@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 status
-The process status, as @code{process-status} should return it.
-
-@item tick
-@itemx update_tick
-If these two fields are not equal, a change in the status of the process
-needs to be reported, either by running the sentinel or by inserting a
-message in the process buffer.
-
-@item pty_flag
-Non-@code{nil} if communication with the subprocess uses a @acronym{PTY};
-@code{nil} if it uses a pipe.
-
-@item infd
-The file descriptor for input from the process.
-
-@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 decode_coding_system
-Coding-system for decoding the input from this process.
-
-@item decoding_buf
-A working buffer for decoding.
-
-@item decoding_carryover
-Size of carryover in decoding.
-
-@item encode_coding_system
-Coding-system for encoding the output to this process.
-
-@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.
-@end table
-
-@ignore
-   arch-tag: 4b2c33bc-d7e4-43f5-bc20-27c0db52a53e
-@end ignore