E.6 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 or, from
eval.c. (An ordinary function would have the same general
appearance.)

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.

Let’s start with a precise explanation of the arguments to the
DEFUN macro. Here is a template for them:

DEFUN (lname, fname, sname, min, max, interactive, doc)

lname

This is the name of the Lisp symbol to define as the function name; in
the example above, it is or.

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, ‘F’ prepended to the Lisp name, with all dashes
(‘-’) in the Lisp name changed to underscores. Thus, to call
this function from C code, call For.

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 fname with ‘F’ replaced with
‘S’.

min

This is the minimum number of arguments that the function requires. The
function or allows a minimum of zero arguments.

max

This is the maximum number of arguments that the function accepts, if
there is a fixed maximum. Alternatively, it can be UNEVALLED,
indicating a special form that receives unevaluated arguments, or
MANY, indicating an unlimited number of evaluated arguments (the
equivalent of &rest). Both UNEVALLED and MANY are
macros. If max is a number, it must be more than min but
less than 8.

interactive

This is an interactive specification, a string such as might be used
as the argument of interactive in a Lisp function. In the case
of or, it is 0 (a null pointer), indicating that or
cannot be called interactively. A value of "" indicates a
function that should receive no arguments when called interactively.
If the value begins with a ‘"(’, the string is evaluated as a
Lisp form. For example:

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 ‘doc:’ identifies the comment
that follows as the documentation string. The ‘/*’ and ‘*/’
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
‘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.
‘usage:’ is required if the function has an unlimited number of
arguments.

After the call to the DEFUN macro, you must write the
argument list for the C function, including the types for the
arguments. If the primitive accepts a fixed maximum number of Lisp
arguments, there must be one C argument for each Lisp argument, and
each argument must be of type Lisp_Object. (Various macros and
functions for creating values of type Lisp_Object are declared
in the file lisp.h.) If the primitive has no upper limit on
the number of Lisp arguments, it must have exactly two C arguments:
the first is the number of Lisp arguments, and the second is the
address of a block containing their values. These have types
int and Lisp_Object * respectively. Since
Lisp_Object can hold any Lisp object of any data type, you
can determine the actual data type only at run time; so if you want
a primitive to accept only a certain type of argument, you must check
the type explicitly using a suitable predicate (see Type Predicates).

Within the function For itself, note the use of the macros
GCPRO1 and UNGCPRO. These macros are defined for the
sake of the few platforms which do not use Emacs’ default
stack-marking garbage collector. The GCPRO1 macro “protects”
a variable from garbage collection, explicitly informing the garbage
collector that that variable and all its contents must be as
accessible. GC protection is necessary in any function which can
perform Lisp evaluation by calling eval_sub or Feval as
a subroutine, either directly or indirectly.

It suffices to ensure that at least one pointer to each object is
GC-protected. 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 that
has a GCPRO). Otherwise, the local variable needs a
GCPRO.

The macro GCPRO1 protects just one local variable. If you
want to protect two variables, use GCPRO2 instead; repeating
GCPRO1 will not work. Macros GCPRO3, GCPRO4,
GCPRO5, and GCPRO6 also exist. All these macros
implicitly use local variables such as gcpro1; you must declare
these explicitly, with type struct gcpro. Thus, if you use
GCPRO2, you must declare gcpro1 and gcpro2.

UNGCPRO cancels the protection of the variables that are
protected in the current function. It is necessary to do this
explicitly.

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.
See Pure Storage.

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:

defsubr (&sname);

Here sname is the name you used as the third argument to 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
syms_of_something, and add the call to defsubr
there. If the file doesn’t have this function, or if you create a new
file, add to it a syms_of_filename (e.g.,
syms_of_myfile). Then find the spot in emacs.c where all
of these functions are called, and add a call to
syms_of_filename there.

The function syms_of_filename is also the place to define
any C variables that are to be visible as Lisp variables.
DEFVAR_LISP makes a C variable of type Lisp_Object visible
in Lisp. DEFVAR_INT makes a C variable of type int
visible in Lisp with a value that is always an integer.
DEFVAR_BOOL makes a C variable of type int visible in Lisp
with a value that is either t or nil. Note that variables
defined with DEFVAR_BOOL are automatically added to the list
byte-boolean-vars used by the byte compiler.

If you want to make a Lisp variables that is defined in C behave
like one declared with defcustom, add an appropriate entry to
cus-start.el.

If you define a file-scope C variable of type Lisp_Object,
you must protect it from garbage-collection by calling staticpro
in syms_of_filename, like this:

staticpro (&variable);

Here is another example function, with more complicated arguments.
This comes from the code in window.c, and it demonstrates the use
of macros and functions to manipulate Lisp objects.

case ON_SCROLL_BAR: /* On scroll-bar of window. */
/* Historically we are supposed to return nil in this case. */
return Qnil;

default:
abort ();
}
}

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
Ffuncall, which embodies the Lisp function funcall. Since
the Lisp function 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 Ffuncall can call the evaluator, you must
protect pointers from garbage collection around the call to
Ffuncall.

The C functions call0, call1, call2, and so on,
provide handy ways to call a Lisp function conveniently with a fixed
number of arguments. They work by calling Ffuncall.

eval.c is a very good file to look through for examples;
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 byte-opt.el that binds side-effect-free-fns and
side-effect-and-error-free-fns so that the compiler optimizer
knows about it.