(Writing Emacs Primitives): Strings are

no longer special for GCPROs.  Mention GCPRO5, GCPRO6.
Explain GCPRO convention for varargs function args.

1 files changed, 22 insertions, 15 deletions

diff --git a/lispref/internals.texi b/lispref/internals.texi
index a6ddd02afe5..a96eacf39d2 100644
--- a/lispref/internals.texi
+++ b/lispref/internals.texi
@@ -572,23 +572,30 @@ 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.
 
-  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 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 protecting the Lisp arguments from GC
+rests with the caller in this case.
+
   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