Function: defvar

defvar is a special form defined in eval.c.

Signature

(defvar SYMBOL &optional INITVALUE DOCSTRING)

Documentation

Define SYMBOL as a variable, and return SYMBOL.

You are not required to define a variable in order to use it, but defining it lets you supply an initial value and documentation, which can be referred to by the Emacs help facilities and other programming tools. The defvar form also declares the variable as "special", so that it is always dynamically bound even if lexical-binding is t.

If SYMBOL's value is void and the optional argument INITVALUE is provided, INITVALUE is evaluated and the result used to set SYMBOL's value. If SYMBOL is buffer-local, its default value is what is set; buffer-local values are not affected. If INITVALUE is missing, SYMBOL's value is not set.

If SYMBOL is let-bound, then this form does not affect the local let binding but the toplevel default binding instead, like
`set-toplevel-default-binding`.
(defcustom behaves similarly in this respect.)

The optional argument DOCSTRING is a documentation string for the variable.

To define a user option, use defcustom instead of defvar.

To define a buffer-local variable, use defvar-local.

View in manual

Probably introduced at or before Emacs version 1.5.

Source Code

// Defined in /usr/src/emacs/src/eval.c
{
  Lisp_Object sym, tail;

  sym = XCAR (args);
  tail = XCDR (args);

  CHECK_SYMBOL (sym);

  if (!NILP (tail))
    {
      if (!NILP (XCDR (tail)) && !NILP (XCDR (XCDR (tail))))
	error ("Too many arguments");
      Lisp_Object exp = XCAR (tail);
      tail = XCDR (tail);
      return defvar (sym, exp, CAR (tail), true);
    }
  else if (!NILP (Vinternal_interpreter_environment)
	   && (SYMBOLP (sym) && !XSYMBOL (sym)->u.s.declared_special))
    /* A simple (defvar foo) with lexical scoping does "nothing" except
       declare that var to be dynamically scoped *locally* (i.e. within
       the current file or let-block).  */
    Vinternal_interpreter_environment
      = Fcons (sym, Vinternal_interpreter_environment);
  else
    {
      /* Simple (defvar <var>) should not count as a definition at all.
	 It could get in the way of other definitions, and unloading this
	 package could try to make the variable unbound.  */
    }

  return sym;
}