— Special Form: defvar symbol [value [doc-string]]

This special form defines symbol as a variable and can also initialize and document it. The definition informs a person reading your code that symbol is used as a variable that might be set or changed. Note that symbol is not evaluated; the symbol to be defined must appear explicitly in the defvar.

If symbol is void and value is specified, defvar evaluates it and sets symbol to the result. But if symbol already has a value (i.e., it is not void), value is not even evaluated, and symbol's value remains unchanged. If value is omitted, the value of symbol is not changed in any case.

If symbol has a buffer-local binding in the current buffer, defvar operates on the default value, which is buffer-independent, not the current (buffer-local) binding. It sets the default value if the default value is void. See Buffer-Local Variables.

When you evaluate a top-level defvar form with C-M-x in Emacs Lisp mode (eval-defun), a special feature of eval-defun arranges to set the variable unconditionally, without testing whether its value is void.

If the doc-string argument appears, it specifies the documentation for the variable. (This opportunity to specify documentation is one of the main benefits of defining the variable.) The documentation is stored in the symbol's variable-documentation property. The Emacs help functions (see Documentation) look for this property.

If the documentation string begins with the character ‘*’, Emacs allows users to set it interactively using the set-variable command. However, you should nearly always use defcustom instead of defvar to define such variables, so that users can use M-x customize and related commands to set them. In that case, it is not necessary to begin the documentation string with ‘*’. See Customization.

Here are some examples. This form defines foo but does not initialize it:

          (defvar foo)
               ⇒ foo

This example initializes the value of bar to 23, and gives it a documentation string:

          (defvar bar 23
            "The normal weight of a bar.")
               ⇒ bar

The following form changes the documentation string for bar, making it a user option, but does not change the value, since bar already has a value. (The addition (1+ nil) would get an error if it were evaluated, but since it is not evaluated, there is no error.)

          (defvar bar (1+ nil)
            "*The normal weight of a bar.")
               ⇒ bar
          bar
               ⇒ 23

Here is an equivalent expression for the defvar special form:

          (defvar symbol value doc-string)
          ==
          (progn
            (if (not (boundp 'symbol))
                (setq symbol value))
            (if 'doc-string
              (put 'symbol 'variable-documentation 'doc-string))
            'symbol)

The defvar form returns symbol, but it is normally used at top level in a file where its value does not matter.

— Special Form: defconst symbol value [doc-string]

This special form defines symbol as a value and initializes it. It informs a person reading your code that symbol has a standard global value, established here, that should not be changed by the user or by other programs. Note that symbol is not evaluated; the symbol to be defined must appear explicitly in the defconst.

defconst always evaluates value, and sets the value of symbol to the result. If symbol does have a buffer-local binding in the current buffer, defconst sets the default value, not the buffer-local value. (But you should not be making buffer-local bindings for a symbol that is defined with defconst.)

An example of the use of defconst is Emacs' definition of float-pi—the mathematical constant pi, which ought not to be changed by anyone (attempts by the Indiana State Legislature notwithstanding). As the second form illustrates, however, defconst is only advisory.

          (defconst float-pi 3.141592653589793 "The value of Pi.")
               ⇒ float-pi
          (setq float-pi 3)
               ⇒ float-pi
          float-pi
               ⇒ 3

— Function: user-variable-p variable

This function returns t if variable is a user option—a variable intended to be set by the user for customization—and nil otherwise. (Variables other than user options exist for the internal purposes of Lisp programs, and users need not know about them.)

User option variables are distinguished from other variables either though being declared using defcustom¹ or by the first character of their variable-documentation property. If the property exists and is a string, and its first character is ‘*’, then the variable is a user option. Aliases of user options are also user options.