The simplest way to use a variable is globally. This means that the variable has just one value at a time, and this value is in effect (at least for the moment) throughout the Lisp system. The value remains in effect until you specify a new one. When a new value replaces the old one, no trace of the old value remains in the variable. You specify a value for a symbol with setq. For example,

(setq x '(a b))

gives the variable x the value (a b). Note that setq is a special form (Special Forms); it does not evaluate its first argument, the name of the variable, but it does evaluate the second argument, the new value. Once the variable has a value, you can refer to it by using the symbol itself as an expression. Thus,

x => (a b)

assuming the setq form shown above has already been executed. If you do set the same variable again, the new value replaces the old one:

x
     => (a b)
(setq x 4)
     => 4
x
     => 4

In Emacs Lisp, certain symbols normally evaluate to themselves. These include nil and t, as well as any symbol whose name starts with : (these are called keywords). These symbols cannot be rebound, nor can their values be changed. Any attempt to set or bind nil or t signals a setting-constant error. The same is true for a keyword (a symbol whose name starts with :), if it is interned in the standard obarray, except that setting such a symbol to itself is not an error.

nil ≡ 'nil
     => nil
(setq nil 500)
error--> Attempt to set constant symbol: nil

keywordp

function returns t if object is a symbol whose name starts with :, interned in the standard obarray, and returns nil otherwise.

These constants are fundamentally different from the constants defined using the defconst special form (Defining Variables). A defconst form serves to inform human readers that you do not intend to change the value of a variable, but Emacs does not raise an error if you actually change it. A small number of additional symbols are made read-only for various practical reasons. These include enable-multibyte-characters, most-positive-fixnum, most-negative-fixnum, and a few others. Any attempt to set or bind these also signals a setting-constant error.

Global variables have values that last until explicitly superseded with new values. Sometimes it is useful to give a variable a local value—a value that takes effect only within a certain part of a Lisp program. When a variable has a local value, we say that it is locally bound to that value, and that it is a local variable. For example, when a function is called, its argument variables receive local values, which are the actual arguments supplied to the function call; these local bindings take effect within the body of the function. To take another example, the let special form explicitly establishes local bindings for specific variables, which take effect only within the body of the let form. We also speak of the global binding, which is where (conceptually) the global value is kept. Establishing a local binding saves away the variable's previous value (or lack of one). We say that the previous value is shadowed. Both global and local values may be shadowed. If a local binding is in effect, using setq on the local variable stores the specified value in the local binding. When that local binding is no longer in effect, the previously shadowed value (or lack of one) comes back. A variable can have more than one local binding at a time (e.g., if there are nested let forms that bind the variable). The current binding is the local binding that is actually in effect. It determines the value returned by evaluating the variable symbol, and it is the binding acted on by setq. For most purposes, you can think of the current binding as the innermost local binding, or the global binding if there is no local binding. To be more precise, a rule called the scoping rule determines where in a program a local binding takes effect. The default scoping rule in Emacs Lisp is called dynamic scoping, which simply states that the current binding at any given point in the execution of a program is the most recently-created binding for that variable that still exists. For details about dynamic scoping, and an alternative scoping rule called lexical scoping, Variable Scoping. Lately Emacs is moving towards using lexical binding in more and more places, with the goal of eventually making lexical binding the default. In particular, all Emacs Lisp source files and the *scratch* buffer use lexical scoping. The special forms let and let* exist to create local bindings:

let

This special form sets up local bindings for a certain set of variables, as specified by bindings, and then evaluates all of the forms in textual order. Its return value is the value of the last form in forms. The local bindings set up by let will be in effect only within the body of forms. Each of the bindings is either (i) a symbol, in which case that symbol is locally bound to nil; or (ii) a list of the form (SYMBOL VALUE-FORM), in which case symbol is locally bound to the result of evaluating value-form. If value-form is omitted, nil is used. All of the value-form/s in /bindings are evaluated in the order they appear and before binding any of the symbols to them. Here is an example of this: z is bound to the old value of y, which is 2, not the new value of y, which is 1.

(setq y 2)
     => 2

(let ((y 1)
      (z y))
  (list y z))
     => (1 2)

On the other hand, the order of bindings is unspecified: in the following example, either 1 or 2 might be printed.

(let ((x 1)
      (x 2))
  (print x))

Therefore, avoid binding a variable more than once in a single let form.

let*

This special form is like let, but it binds each variable right after computing its local value, before computing the local value for the next variable. Therefore, an expression in bindings can refer to the preceding symbols bound in this let* form. Compare the following example with the example above for let.

(setq y 2)
     => 2

(let* ((y 1)
       (z y))    ; Use the just-established value of y.
  (list y z))
     => (1 1)

Basically, the let* binding of x and y in the previous example is equivalent to using nested let bindings:

(let ((y 1))
  (let ((z y))
    (list y z)))

letrec

This special form is like let*, but all the variables are bound before any of the local values are computed. The values are then assigned to the locally bound variables. This is only useful when lexical binding is in effect, and you want to create closures that refer to bindings that would otherwise not yet be in effect when using let*. For instance, here's a closure that removes itself from a hook after being run once:

(letrec ((hookfun (lambda ()
                    (message "Run once")
                    (remove-hook 'post-command-hook hookfun))))
  (add-hook 'post-command-hook hookfun))

dlet

This special form is like let, but it binds all variables dynamically. This is rarely useful—you usually want to bind normal variables lexically, and special variables (i.e., variables that are defined with defvar) dynamically, and this is what let does. dlet can be useful when interfacing with old code that assumes that certain variables are dynamically bound (Dynamic Binding), but it's impractical to defvar these variables. dlet will temporarily make the bound variables special, execute the forms, and then make the variables non-special again.

named-let

This special form is a looping construct inspired from the Scheme language. It is similar to let: It binds the variables in bindings, and then evaluates body. However, named-let also binds name to a local function whose formal arguments are the variables in bindings and whose body is body. This allows body to call itself recursively by calling name, where the arguments passed to name are used as the new values of the bound variables in the recursive invocation. Example of a loop summing a list of numbers:

(named-let sum ((numbers '(1 2 3 4))
                (running-sum 0))
  (if numbers
      (sum (cdr numbers) (+ running-sum (car numbers)))
    running-sum))
=> 10

Recursive calls to name that occur in tail positions in body are guaranteed to be optimized as tail calls, which means that they will not consume any additional stack space no matter how deeply the recursion runs. Such recursive calls will effectively jump to the top of the loop with new values for the variables. A function call is in the tail position if it's the very last thing done so that the value returned by the call is the value of body itself, as is the case in the recursive call to sum above. named-let can only be used when lexical-binding is enabled. Lexical Binding. Here is a complete list of the other facilities that create local bindings:

• Function calls (Functions).
• Macro calls (Macros).
• condition-case (Errors).

Variables can also have buffer-local bindings (Buffer-Local Variables); a few variables have terminal-local bindings (Multiple Terminals). These kinds of bindings work somewhat like ordinary local bindings, but they are localized depending on where you are in Emacs.

We say that a variable is void if its symbol has an unassigned value cell (Symbol Components). Under Emacs Lisp's default dynamic scoping rule (Variable Scoping), the value cell stores the variable's current (local or global) value. Note that an unassigned value cell is not the same as having nil in the value cell. The symbol nil is a Lisp object and can be the value of a variable, just as any other object can be; but it is still a value. If a variable is void, trying to evaluate the variable signals a void-variable error, instead of returning a value. Under the optional lexical scoping rule, the value cell only holds the variable's global value—the value outside of any lexical binding construct. When a variable is lexically bound, the local value is determined by the lexical environment; hence, variables can have local values even if their symbols' value cells are unassigned.

makunbound

This function empties out the value cell of symbol, making the variable void. It returns symbol. If symbol has a dynamic local binding, makunbound voids the current binding, and this voidness lasts only as long as the local binding is in effect. Afterwards, the previously shadowed local or global binding is reexposed; then the variable will no longer be void, unless the reexposed binding is void too. Here are some examples (assuming dynamic binding is in effect):

(setq x 1)               ; Put a value in the global binding.
     => 1
(let ((x 2))             ; Locally bind it.
  (makunbound 'x)        ; Void the local binding.
  x)
error--> Symbol's value as variable is void: x
x                        ; The global binding is unchanged.
     => 1

(let ((x 2))             ; Locally bind it.
  (let ((x 3))           ; And again.
    (makunbound 'x)      ; Void the innermost-local binding.
    x))                  ; And refer: it's void.
error--> Symbol's value as variable is void: x

(let ((x 2))
  (let ((x 3))
    (makunbound 'x))     ; Void inner binding
  x)                     ; Now outer let binding is visible.
     => 2

boundp

This function returns t if variable (a symbol) is not void, and nil if it is void. Here are some examples (assuming dynamic binding is in effect):

(boundp 'abracadabra)          ; Starts out void.
     => nil
(let ((abracadabra 5))         ; Locally bind it.
  (boundp 'abracadabra))
     => t
(boundp 'abracadabra)          ; Still globally void.
     => nil
(setq abracadabra 5)           ; Make it globally nonvoid.
     => 5
(boundp 'abracadabra)
     => t

A variable definition is a construct that announces your intention to use a symbol as a global variable. It uses the special forms defvar or defconst, which are documented below. A variable definition serves three purposes. First, it informs people who read the code that the symbol is intended to be used a certain way (as a variable). Second, it informs the Lisp system of this, optionally supplying an initial value and a documentation string. Third, it provides information to programming tools such as etags, allowing them to find where the variable was defined. The difference between defconst and defvar is mainly a matter of intent, serving to inform human readers of whether the value should ever change. Emacs Lisp does not actually prevent you from changing the value of a variable defined with defconst. One notable difference between the two forms is that defconst unconditionally initializes the variable, whereas defvar initializes it only if it is originally void. To define a customizable variable, you should use defcustom (which calls defvar as a subroutine). Variable Definitions.

defvar

This special form defines symbol as a variable and optionally initializes and documents it. Note that it doesn't evaluate symbol; the symbol to be defined should appear explicitly in the defvar form. defvar also marks symbol as special, meaning that its bindings should always be dynamic (Variable Scoping). If value is specified, and symbol is void (i.e., it has no dynamically bound value; Void Variables), then defvar evaluates value, and initializes symbol by setting it to the result of the evaluation. But if symbol is not void, defvar does not evaluate value, and leaves symbol's value unchanged. If value is omitted, defvar doesn't change the value of symbol in any case. Note that specifying a value, even nil, marks the variable as special permanently. Whereas if value is omitted, then defvar marks the variable special only locally (i.e. within the current lexical scope, or within the current file, if defvar is at the top-level). This can be useful for suppressing byte compilation warnings, see Compiler Errors. If symbol has a buffer-local binding in the current buffer, and value is specified, defvar modifies the default value of symbol, which is buffer-independent, rather than the buffer-local binding. It sets the default value if the default value is void. Buffer-Local Variables. If symbol is already let bound (e.g., if the defvar form occurs in a let form), then defvar sets the toplevel default value of symbol, like set-default-toplevel-value. The let binding remains in effect until its binding construct exits. Variable Scoping. When you evaluate a top-level defvar form with C-M-x (eval-defun) or with C-x C-e (eval-last-sexp) in Emacs Lisp mode, a special feature of these two commands arranges to set the variable unconditionally, without testing whether its value is void. If the doc-string argument is supplied, it specifies the documentation string for the variable (stored in the symbol's variable-documentation property). Documentation. 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 defvar form returns symbol, but it is normally used at top level in a file where its value does not matter. For a more elaborate example of using defvar without a value, see Local defvar example.

defconst

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. The defconst form, like defvar, marks the variable as special, meaning that it should always be dynamically bound (Variable Scoping). In addition, it marks the variable as risky (File Local Variables). 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's 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

When you define a variable whose value is a function, or a list of functions, use a name that ends in -function or -functions, respectively. There are several other variable name conventions; here is a complete list:

...-hook

The variable is a normal hook (Hooks).

...-function

The value is a function.

...-functions

The value is a list of functions.

...-form

The value is a form (an expression).

...-forms

The value is a list of forms (expressions).

...-predicate

The value is a predicate—a function of one argument that returns non-nil for success and nil for failure.

...-flag

The value is significant only as to whether it is nil or not. Since such variables often end up acquiring more values over time, this convention is not strongly recommended.

...-program

The value is a program name.

...-command

The value is a whole shell command.

...-switches

The value specifies options for a command.

PREFIX--...

The variable is intended for internal use and is defined in the file PREFIX.el. (Emacs code contributed before 2018 may follow other conventions, which are being phased out.)

...-internal

The variable is intended for internal use and is defined in C code. (Emacs code contributed before 2018 may follow other conventions, which are being phased out.)

When you define a variable, always consider whether you should mark it as safe or risky; see File Local Variables. When defining and initializing a variable that holds a complicated value (such as a syntax table for a major mode), it's best to put the entire computation of the value into the defvar, like this:

(defvar my-major-mode-syntax-table
  (let ((table (make-syntax-table)))
    (modify-syntax-entry ?# "<" table)
    ...
    table)
  DOCSTRING)

This method has several benefits. First, if the user quits while loading the file, the variable is either still uninitialized or initialized properly, never in-between. If it is still uninitialized, reloading the file will initialize it properly. Second, reloading the file once the variable is initialized will not alter it; that is important if the user has changed its value. Third, evaluating the defvar form with C-M-x will reinitialize the variable completely.

The usual way to reference a variable is to write the symbol which names it. Symbol Forms. Occasionally, you may want to reference a variable which is only determined at run time. In that case, you cannot specify the variable name in the text of the program. You can use the symbol-value function to extract the value.

symbol-value

This function returns the value stored in symbol's value cell. This is where the variable's current (dynamic) value is stored. If the variable has no local binding, this is simply its global value. If the variable is void, a void-variable error is signaled. If the variable is lexically bound, the value reported by symbol-value is not necessarily the same as the variable's lexical value, which is determined by the lexical environment rather than the symbol's value cell. Variable Scoping.

(setq abracadabra 5)
     => 5
(setq foo 9)
     => 9

;; Here the symbol abracadabra
;;   is the symbol whose value is examined.
(let ((abracadabra 'foo))
  (symbol-value 'abracadabra))
     => foo

;; Here
;;   which is foo
;;   is the symbol whose value is examined.
(let ((abracadabra 'foo))
  (symbol-value abracadabra))
     => 9

(symbol-value 'abracadabra)
     => 5

The usual way to change the value of a variable is with the special form setq. When you need to compute the choice of variable at run time, use the function set.

setq

This special form is the most common method of changing a variable's value. Each symbol is given a new value, which is the result of evaluating the corresponding form. The current binding of the symbol is changed. setq does not evaluate symbol; it sets the symbol that you write. We say that this argument is automatically quoted. The q in setq stands for "quoted". The value of the setq form is the value of the last form.

(setq x (1+ 2))
     => 3
x                   ; x now has a global value.
     => 3
(let ((x 5))
  (setq x 6)        ; The local binding of x is set.
  x)
     => 6
x                   ; The global value is unchanged.
     => 3

Note that the first form is evaluated, then the first symbol is set, then the second form is evaluated, then the second symbol is set, and so on:

(setq x 10          ; Notice that x is set before
      y (1+ x))     ;   the value of y is computed.
     => 11

set

This function puts value in the value cell of symbol. Since it is a function rather than a special form, the expression written for symbol is evaluated to obtain the symbol to set. The return value is value. When dynamic variable binding is in effect (the default), set has the same effect as setq, apart from the fact that set evaluates its symbol argument whereas setq does not. But when a variable is lexically bound, set affects its dynamic value, whereas setq affects its current (lexical) value. Variable Scoping.

(set one 1)
error--> Symbol's value as variable is void: one
(set 'one 1)
     => 1
(set 'two 'one)
     => one
(set two 2)         ; two evaluates to symbol one.
     => 2
one                 ; So it is one that was set.
     => 2
(let ((one 1))      ; This binding of one is set
  (set 'one 3)      ;   not the global value.
  one)
     => 3
one
     => 2

If symbol is not actually a symbol, a wrong-type-argument error is signaled.

(set '(x y) 'z)
error--> Wrong type argument: symbolp, (x y)

setopt

This is like setq (see above), but meant for user options. This macro uses the Customize machinery to set the variable(s) (Variable Definitions). In particular, setopt will run the setter function associated with the variable. For instance, if you have:

(defcustom my-var 1
  "My var."
  :type 'number
  :set (lambda (var val)
         (set-default var val)
         (message "We set %s to %s" var val)))

then the following, in addition to setting my-var to 2, will also issue a message:

(setopt my-var 2)

setopt also checks whether the value is valid for the user option. For instance, using setopt to set a user option defined with a number type to a string will signal an error. Unlike defcustom and related customization commands, such as customize-variable, setopt is meant for non-interactive use, in particular in the user init file. For that reason, it doesn't record the standard, saved, and user-set values, and doesn't mark the variable as candidate for saving in the custom file. The setopt macro can be used on regular, non-user option variables, but is much less efficient than setq. The main use case for this macro is setting user options in the user's init file.

It is sometimes useful to take some action when a variable changes its value. The variable watchpoint facility provides the means to do so. Some possible uses for this feature include keeping display in sync with variable settings, and invoking the debugger to track down unexpected changes to variables (Variable Debugging). The following functions may be used to manipulate and query the watch functions for a variable.

add-variable-watcher

This function arranges for watch-function to be called whenever symbol is modified. Modifications through aliases (Variable Aliases) will have the same effect. watch-function will be called, just before changing the value of symbol, with 4 arguments: symbol, newval, operation, and where. symbol is the variable being changed. newval is the value it will be changed to. (The old value is available to watch-function as the value of symbol, since it was not yet changed to newval.) operation is a symbol representing the kind of change, one of: set, let, unlet, makunbound, or defvaralias. where is a buffer if the buffer-local value of the variable is being changed, nil otherwise.

remove-variable-watcher

This function removes watch-function from symbol's list of watchers.

get-variable-watchers

This function returns the list of symbol's active watcher functions.

There are a couple of ways in which a variable could be modified (or at least appear to be modified) without triggering a watchpoint. Since watchpoints are attached to symbols, modification to the objects contained within variables (e.g., by a list modification function Modifying Lists) is not caught by this mechanism. Additionally, C code can modify the value of variables directly, bypassing the watchpoint mechanism. A minor limitation of this feature, again because it targets symbols, is that only variables of dynamic scope may be watched. This poses little difficulty, since modifications to lexical variables can be discovered easily by inspecting the code within the scope of the variable (unlike dynamic variables, which can be modified by any code at all, Variable Scoping).

When you create a local binding for a variable, that binding takes effect only within a limited portion of the program (Local Variables). This section describes exactly what this means. Each local binding has a certain scope and extent. Scope refers to where in the textual source code the binding can be accessed. Extent refers to when, as the program is executing, the binding exists. For historical reasons, there are two dialects of Emacs Lisp, selected via the lexical-binding buffer-local variable. In the modern Emacs Lisp dialect, local bindings are lexical by default. A lexical binding has lexical scope, meaning that any reference to the variable must be located textually within the binding construct(With some exceptions; for instance). It also has indefinite extent, meaning that under some circumstances the binding can live on even after the binding construct has finished executing, by means of objects called closures. Lexical scoping is also commonly called static scoping. Local bindings can also be dynamic, which they always are in the old Emacs Lisp dialect and optionally in the modern dialect. A dynamic binding has dynamic scope, meaning that any part of the program can potentially access the variable binding. It also has dynamic extent, meaning that the binding lasts only while the binding construct (such as the body of a let form) is being executed. The old dynamic-only Emacs Lisp dialect is still the default in code loaded or evaluated from Lisp files that lack a dialect declaration. Eventually the modern dialect will be made the default. All Lisp files should declare the dialect used to ensure that they keep working correctly in the future. The following subsections describe lexical binding and dynamic binding in greater detail, and how to enable lexical binding in Emacs Lisp programs.

(let ((x 1))    ; x is lexically bound.
  (+ x 3))
     => 4

(defun getx ()
  x)            ; x is used free in this function.

(let ((x 1))    ; x is lexically bound.
  (getx))
error--> Symbol's value as variable is void: x

(defvar my-ticker nil)   ; We will use this dynamically bound
                         ; variable to store a closure.

(let ((x 0))             ; x is lexically bound.
  (setq my-ticker (lambda ()
                    (setq x (1+ x)))))
    => #f(lambda () [(x 0)]
          (setq x (1+ x)))

(funcall my-ticker)
    => 1

(funcall my-ticker)
    => 2

(funcall my-ticker)
    => 3

x                        ; Note that x has no global value.
error--> Symbol's value as variable is void: x

(defvar x -99)  ; x receives an initial value of −99.

(defun getx ()
  x)            ; x is used free in this function.

(let ((x 1))    ; x is dynamically bound.
  (getx))
     => 1

;; After the let form finishes
;; previous value

(getx)
     => -99

(defvar x -99)      ; x receives an initial value of −99.

(defun addx ()
  (setq x (1+ x)))  ; Add 1 to x and return its new value.

(let ((x 1))
  (addx)
  (addx))
     => 3           ; The two addx calls add to x twice.

;; After the let form finishes
;; previous value

(addx)
     => -98

(let (_)
  (defvar x)      ; Let-bindings of x will be dynamic within this let.
  (let ((x -99))  ; This is a dynamic binding of x.
    (defun get-dynamic-x ()
      x)))

(let ((x 'lexical)) ; This is a lexical binding of x.
  (defun get-lexical-x ()
    x))

(let (_)
  (defvar x)
  (let ((x 'dynamic))
    (list (get-lexical-x)
          (get-dynamic-x))))
    => (lexical dynamic)

;;; ...  -*- lexical-binding: t -*-

;;; ...  -*- lexical-binding: nil -*-

$ rm *.elc                                # force recompilation
$ EMACS_GENERATE_DYNVARS=1 make           # generate .dynvars
$ cat *.dynvars > ~/my-dynvars            # combine .dynvars
$ rm *.elc                                # force recompilation
$ EMACS_DYNVARS_FILE=~/my-dynvars make    # perform checks

Global and local variable bindings are found in most programming languages in one form or another. Emacs, however, also supports additional, unusual kinds of variable binding, such as buffer-local bindings, which apply only in one buffer. Having different values for a variable in different buffers is an important customization method. (Variables can also have bindings that are local to each terminal. Multiple Terminals.)

(setq foo 'g)
(set-buffer "a")
(make-local-variable 'foo)
(setq foo 'a)
(let ((foo 'temp))
  ;; foo => 'temp  ; let binding in buffer ‘a’
  (set-buffer "b")
  ;; foo => 'g     ; the global value since foo is not local in ‘b’
  BODY...)
foo => 'g        ; exiting restored the local value in buffer ‘a’
                 ; but we don't see that in buffer ‘b’
(set-buffer "a") ; verify the local value was restored
foo => 'a

;; In buffer ‘b1’:
(setq foo 5)                ; Affects all buffers.
     => 5
(make-local-variable 'foo)  ; Now it is local in ‘b1’.
     => foo
foo                         ; That did not change
     => 5                   ;   the value.
(setq foo 6)                ; Change the value
     => 6                   ;   in ‘b1’.
foo
     => 6

;; In buffer ‘b2’
(with-current-buffer "b2"
  foo)
     => 5

(setq-local var1 "value1"
            var2 "value2")

(make-local-variable 'foobar)
(makunbound 'foobar)
(make-local-variable 'bind-me)
(setq bind-me 69)
(setq lcl (buffer-local-variables))
    ;; First
=> ((mark-active . nil)
    (buffer-undo-list . nil)
    (mode-name . "Fundamental")
    ...
    ;; Next
    ;; This one is buffer-local and void:
    foobar
    ;; This one is buffer-local and nonvoid:
    (bind-me . 69))

;; In buffer ‘foo’:
(make-local-variable 'buffer-local)
     => buffer-local
(setq buffer-local 'value-in-foo)
     => value-in-foo
(setq-default buffer-local 'new-default)
     => new-default
buffer-local
     => value-in-foo
(default-value 'buffer-local)
     => new-default

;; In (the new) buffer ‘bar’:
buffer-local
     => new-default
(default-value 'buffer-local)
     => new-default
(setq buffer-local 'another-default)
     => another-default
(default-value 'buffer-local)
     => another-default

;; Back in buffer ‘foo’:
buffer-local
     => value-in-foo
(default-value 'buffer-local)
     => another-default

(set-default (car '(a b c)) 23)
     => 23
(default-value 'a)
     => 23

(defvar variable 'global-value)
    => variable
(let ((variable 'let-binding))
  (default-value 'variable))
    => let-binding
(let ((variable 'let-binding))
  (default-toplevel-value 'variable))
    => global-value

A file can specify local variable values; Emacs uses these to create buffer-local bindings for those variables in the buffer visiting that file. Local Variables in Files, for basic information about file-local variables. This section describes the functions and variables that affect how file-local variables are processed. If a file-local variable could specify an arbitrary function or Lisp expression that would be called later, visiting a file could take over your Emacs. Emacs protects against this by automatically setting only those file-local variables whose specified values are known to be safe. Other file-local variables are set only if the user agrees. For additional safety, read-circle is temporarily bound to nil when Emacs reads file-local variables (Input Functions). This prevents the Lisp reader from recognizing circular and shared Lisp structures (Circular Objects).

enable-local-variables

This variable controls whether to process file-local variables. The possible values are:

t (the default)

Set the safe variables, and query (once) about any unsafe variables.

:safe

Set only the safe variables and do not query.

:all

Set all the variables and do not query.

nil

Don't set any variables.

anything else

Query (once) about all the variables.

inhibit-local-variables-regexps

This is a list of regular expressions. If a file has a name matching an element of this list, then it is not scanned for any form of file-local variable. For examples of why you might want to use this, Auto Major Mode.

permanently-enabled-local-variables

Some local variable settings will, by default, be heeded even if enable-local-variables is nil. By default, this is only the case for the lexical-binding local variable setting, but this can be controlled by using this variable, which is a list of symbols.

safe-local-variable-directories

This is a list of directories where local variables are always enabled. Directory-local variables loaded from these directories, such as the variables in .dir-locals.el, will be enabled even if they are risky. The directories in this list must be fully-expanded absolute file names. They may also be remote directories if the variable enable-remote-dir-locals is set non-nil.

hack-local-variables

This function parses, and binds or evaluates as appropriate, any local variables specified by the contents of the current buffer. The variable enable-local-variables has its effect here. However, this function does not look for the mode: local variable in the -*- line. set-auto-mode does that, also taking enable-local-variables into account (Auto Major Mode). This function also puts into effect directory-local variables as specified in .dir-locals.el. If the buffer is not visiting any file, then the directory-local variables that apply are those which would be applicable to files in the default-directory (Directory Local Variables). This function works by walking the alists stored in file-local-variables-alist and dir-local-variables-alist and applying each local variable in turn. It calls before-hack-local-variables-hook and hack-local-variables-hook before and after applying the variables, respectively. It only calls the before-hook if file-local-variables-alist is non-nil; it always calls the other hook. This function ignores a mode element if it specifies the same major mode as the buffer already has. If the optional argument handle-mode is t, then all this function does is return a symbol specifying the major mode, if the -*- line or the local variables list specifies one, and nil otherwise. It does not set the mode or any other file-local variable. If handle-mode has any value other than nil or t, any settings of mode in the -*- line or the local variables list are ignored, and the other settings are applied. If handle-mode is nil, all the file local variables are set.

file-local-variables-alist

This buffer-local variable holds the alist of file-local variable settings. Each element of the alist is of the form (VAR . VALUE), where var is a symbol of the local variable and value is its value. When Emacs visits a file, it first collects all the file-local variables into this alist, and then the hack-local-variables function applies them one by one.

before-hack-local-variables-hook

Emacs calls this hook immediately before applying file-local variables stored in file-local-variables-alist.

hack-local-variables-hook

Emacs calls this hook immediately after it finishes applying file-local variables stored in file-local-variables-alist.

You can specify safe values for a variable with a safe-local-variable property. The property has to be a function of one argument; any value is safe if the function returns non-nil given that value. Many commonly-encountered file variables have safe-local-variable properties; these include fill-column, fill-prefix, and indent-tabs-mode. For boolean-valued variables that are safe, use booleanp as the property value. If you want to define safe-local-variable properties for variables defined in C source code, add the names and the properties of those variables to the list in the "Safe local variables" section of files.el. When defining a user option using defcustom, you can set its safe-local-variable property by adding the arguments :safe FUNCTION to defcustom (Variable Definitions). However, a safety predicate defined using :safe will only be known once the package that contains the defcustom is loaded, which is often too late. As an alternative, you can use the autoload cookie (Autoload) to assign the option its safety predicate, like this:

;;;###autoload (put 'VAR 'safe-local-variable 'PRED)

The safe value definitions specified with autoload are copied into the package's autoloads file (loaddefs.el for most packages bundled with Emacs), and are known to Emacs since the beginning of a session.

safe-local-variable-values

This variable provides another way to mark some variable values as safe. It is a list of cons cells (VAR . VAL), where var is a variable name and val is a value which is safe for that variable. When Emacs asks the user whether or not to obey a set of file-local variable specifications, the user can choose to mark them as safe. Doing so adds those variable/value pairs to safe-local-variable-values, and saves it to the user's custom file.

ignored-local-variable-values

If there are some values of particular local variables that you always want to ignore completely, you can use this variable. Its value has the same form as safe-local-variable-values; a file-local variable setting to the value that appears in the list will always be ignored when processing the local variables specified by the file. As with that variable, when Emacs queries the user about whether to obey file-local variables, the user can choose to ignore their particular values permanently, and that will alter this variable and save it to the user's custom file. Variable-value pairs that appear in this variable take precedence over the same pairs in safe-local-variable-values.

safe-local-variable-p

This function returns non-nil if it is safe to give sym the value val, based on the above criteria.

Some variables are considered risky. If a variable is risky, it is never entered automatically into safe-local-variable-values; Emacs always queries before setting a risky variable, unless the user explicitly allows a value by customizing safe-local-variable-values directly. Any variable whose name has a non-nil risky-local-variable property is considered risky. When you define a user option using defcustom, you can set its risky-local-variable property by adding the arguments :risky VALUE to defcustom (Variable Definitions). In addition, any variable whose name ends in any of -command, -frame-alist, -function, -functions, -hook, -hooks, -form, -forms, -map, -map-alist, -mode-alist, -program, or -predicate is automatically considered risky. The variables font-lock-keywords, font-lock-keywords followed by a digit, and font-lock-syntactic-keywords are also considered risky.

risky-local-variable-p

This function returns non-nil if sym is a risky variable, based on the above criteria.

ignored-local-variables

This variable holds a list of variables that should not be given local values by files. Any value specified for one of these variables is completely ignored.

The Eval: "variable" is also a potential loophole, so Emacs normally asks for confirmation before handling it.

enable-local-eval

This variable controls processing of Eval: in -*- lines or local variables lists in files being visited. A value of t means process them unconditionally; nil means ignore them; anything else means ask the user what to do for each file. The default value is maybe.

safe-local-eval-forms

This variable holds a list of expressions that are safe to evaluate when found in the Eval: "variable" in a file local variables list.

If the expression is a function call and the function has a safe-local-eval-function property, the property value determines whether the expression is safe to evaluate. The property value can be a predicate to call to test the expression, a list of such predicates (it's safe if any predicate succeeds), or t (always safe provided the arguments are constant). Text properties are also potential loopholes, since their values could include functions to call. So Emacs discards all text properties from string values specified for file-local variables.

A directory can specify local variable values common to all files in that directory; Emacs uses these to create buffer-local bindings for those variables in buffers visiting any file in that directory. This is useful when the files in the directory belong to some project and therefore share the same local variables. There are two different methods for specifying directory local variables: by putting them in a special file, or by defining a project class for that directory.

Constant dir-locals-file

This constant is the name of the file where Emacs expects to find the directory-local variables. The name of the file is .dir-locals.el=(The MS-DOS version of Emacs uses =_dir-locals.el instead). A file by that name in a directory causes Emacs to apply its settings to any file in that directory or any of its subdirectories (optionally, you can exclude subdirectories; see below). If some of the subdirectories have their own .dir-locals.el files, Emacs uses the settings from the deepest file it finds starting from the file's directory and moving up the directory tree. This constant is also used to derive the name of a second dir-locals file .dir-locals-2.el. If this second dir-locals file is present in the same directory as .dir-locals.el, then it will be loaded in addition to .dir-locals.el. This is useful when .dir-locals.el is under version control in a shared repository and cannot be used for personal customizations. The file specifies local variables as a specially formatted list; see Per-directory Local Variables, for more details.

hack-dir-local-variables

This function reads the .dir-locals.el file and stores the directory-local variables in file-local-variables-alist that is local to the buffer visiting any file in the directory, without applying them. It also stores the directory-local settings in dir-locals-class-alist, where it defines a special class for the directory in which .dir-locals.el file was found. This function works by calling dir-locals-set-class-variables and dir-locals-set-directory-class, described below.

hack-dir-local-variables-non-file-buffer

This function looks for directory-local variables, and immediately applies them in the current buffer. It is intended to be called in the mode commands for non-file buffers, such as Dired buffers, to let them obey directory-local variable settings. For non-file buffers, Emacs looks for directory-local variables in default-directory and its parent directories.

dir-locals-set-class-variables

This function defines a set of variable settings for the named class, which is a symbol. You can later assign the class to one or more directories, and Emacs will apply those variable settings to all files in those directories. The list in variables can be of one of the two forms: (MAJOR-MODE . ALIST) or (DIRECTORY . LIST). With the first form, if the file's buffer turns on a mode that is derived from major-mode, then all the variables in the associated alist are applied; alist should be of the form (NAME . VALUE). A special value nil for major-mode means the settings are applicable to any mode. In alist, you can use a special name: subdirs. If the associated value is nil, the alist is only applied to files in the relevant directory, not to those in any subdirectories. With the second form of variables, if directory is the initial substring of the file's directory, then list is applied recursively by following the above rules; list should be of one of the two forms accepted by this function in variables.

dir-locals-set-directory-class

This function assigns class to all the files in directory and its subdirectories. Thereafter, all the variable settings specified for class will be applied to any visited file in directory and its children. class must have been already defined by dir-locals-set-class-variables. Emacs uses this function internally when it loads directory variables from a .dir-locals.el file. In that case, the optional argument mtime holds the file modification time (as returned by file-attributes). Emacs uses this time to check stored local variables are still valid. If you are assigning a class directly, not via a file, this argument should be nil.

dir-locals-class-alist

This alist holds the class symbols and the associated variable settings. It is updated by dir-locals-set-class-variables.

dir-locals-directory-cache

This alist holds directory names, their assigned class names, and modification times of the associated directory local variables file (if there is one). The function dir-locals-set-directory-class updates this list.

dir-local-variables-alist

This buffer-local variable holds the alist of directory-local variable settings. Each element of the alist is of the form (VAR . VALUE), where var is a symbol of the local variable and value is its value (this is the same structure as that of file-local-variables-alist, File Local Variables). When Emacs visits a file, it collects all the directory-local variables into this alist, and then the hack-local-variables function applies them one by one (again, File Local Variables).

hack-dir-local-get-variables-functions

This special hook holds the functions that gather the directory-local variables to use for a given buffer. By default it contains just the function that obeys the other settings described in the present section. But it can be used to add support for more sources of directory-local variables, such as those used by other text editors. The functions on this hook are called with no argument, in the buffer to which we intend to apply the directory-local variables, after the buffer's major mode function has been run, so they can use sources of information such as major-mode or buffer-file-name to find the variables that should be applied. It should return either a cons cell of the form (DIRECTORY . ALIST) or a list of such cons-cells. A nil return value means that it found no directory-local variables. directory should be a string: the name of the directory to which the variables apply. alist is a list of variables together with their values that apply to the current buffer, where every element is of the form (VARNAME . VALUE). The various alist returned by these functions will be combined, and in case of conflicts, the settings coming from deeper directories will take precedence over those coming from higher directories in the directory hierarchy. Finally, since this hook is run every time we visit a file it is important to try and keep those functions efficient, which will usually require some kind of caching.

enable-dir-local-variables

If nil, directory-local variables are ignored. This variable may be useful for modes that want to ignore directory-locals while still respecting file-local variables (File Local Variables).

Connection-local variables provide a general mechanism for different variable settings in buffers with a remote connection (Remote Files). They are bound and set depending on the remote connection a buffer is dedicated to.

(connection-local-set-profile-variables
  'remote-bash
  '((shell-file-name . "/bin/bash")
    (shell-command-switch . "-c")
    (shell-interactive-switch . "-i")
    (shell-login-switch . "-l")))

(connection-local-set-profile-variables
  'remote-ksh
  '((shell-file-name . "/bin/ksh")
    (shell-command-switch . "-c")
    (shell-interactive-switch . "-i")
    (shell-login-switch . "-l")))

(connection-local-set-profile-variables
  'remote-null-device
  '((null-device . "/dev/null")))

(connection-local-set-profile-variables
  'remote-bash
  (append
   (connection-local-get-profile-variables 'remote-bash)
   '((shell-command-dont-erase-buffer . t))))

(connection-local-set-profiles
  '(:application tramp :protocol "ssh" :machine "localhost")
  'remote-bash 'remote-null-device)

(connection-local-set-profiles
  '(:application tramp :protocol "sudo"
    :user "root" :machine "localhost")
  'remote-ksh 'remote-null-device)

(connection-local-set-profiles
  '(:application tramp :protocol "ssh" :machine "localhost")
  'remote-bash)

(connection-local-set-profiles
  '(:application tramp :protocol "sudo"
    :user "root" :machine "localhost")
  'remote-ksh)

(connection-local-set-profiles
  nil 'remote-null-device)

(hack-connection-local-variables
  '(:application tramp :protocol "ssh" :machine "localhost"))

connection-local-variables-alist
     => ((null-device . "/dev/null")
        (shell-login-switch . "-l")
        (shell-interactive-switch . "-i")
        (shell-command-switch . "-c")
        (shell-file-name . "/bin/bash"))

(connection-local-set-profile-variables
  'my-remote-perl
  '((perl-command-name . "/usr/local/bin/perl5")
    (perl-command-switch . "-e %s")))

(connection-local-set-profiles
  '(:application my-app :protocol "ssh" :machine "remotehost")
  'my-remote-perl)

(let ((default-directory "/ssh:remotehost:/working/dir/"))
  (with-connection-local-application-variables 'my-app
    do something useful))

(defvar my-app-variable nil)

(connection-local-set-profile-variables
 'my-app-connection-default-profile
 '((my-app-variable . nil)))

(connection-local-set-profiles
 '(:application my-app)
 'my-app-connection-default-profile)

(defun my-app-get-variable ()
  (with-connection-local-application-variables 'my-app
    (or my-app-variable
        (setq-connection-local my-app-variable
                               do something useful))))

It is sometimes useful to make two variables synonyms, so that both variables always have the same value, and changing either one also changes the other. Whenever you change the name of a variable—either because you realize its old name was not well chosen, or because its meaning has partly changed—it can be useful to keep the old name as an alias of the new one for compatibility. You can do this with defvaralias.

defvaralias

This function defines the symbol new-alias as a variable alias for symbol base-variable. This means that retrieving the value of new-alias returns the value of base-variable, and changing the value of new-alias changes the value of base-variable. The two aliased variable names always share the same value and the same bindings. If the docstring argument is non-nil, it specifies the documentation for new-alias; otherwise, the alias gets the same documentation as base-variable has, if any, unless base-variable is itself an alias, in which case new-alias gets the documentation of the variable at the end of the chain of aliases. This function returns base-variable. If the resulting variable definition chain would be circular, then Emacs will signal a cyclic-variable-indirection error.

Variable aliases are convenient for replacing an old name for a variable with a new name. make-obsolete-variable declares that the old name is obsolete and therefore that it may be removed at some stage in the future.

make-obsolete-variable

This function makes the byte compiler warn that the variable obsolete-name is obsolete. If current-name is a symbol, it is the variable's new name; then the warning message says to use current-name instead of obsolete-name. If current-name is a string, this is the message and there is no replacement variable. when should be a string indicating when the variable was first made obsolete (usually a version number string). The optional argument access-type, if non-nil, should specify the kind of access that will trigger obsolescence warnings; it can be either get or set.

You can make two variables synonyms and declare one obsolete at the same time using the macro define-obsolete-variable-alias.

define-obsolete-variable-alias

This macro marks the variable obsolete-name as obsolete and also makes it an alias for the variable current-name. It is equivalent to the following:

(defvaralias OBSOLETE-NAME CURRENT-NAME DOCSTRING)
(make-obsolete-variable OBSOLETE-NAME CURRENT-NAME WHEN)

This macro evaluates all its parameters, and both obsolete-name and current-name should be symbols, so a typical usage would look like:

(define-obsolete-variable-alias 'foo-thing 'bar-thing "27.1")

indirect-variable

This function returns the variable at the end of the chain of aliases of variable. If variable is not a symbol, or if variable is not defined as an alias, the function returns variable.

(defvaralias 'foo 'bar)
(indirect-variable 'foo)
     => bar
(indirect-variable 'bar)
     => bar
(setq bar 2)
bar
     => 2
foo
     => 2
(setq foo 0)
bar
     => 0
foo
     => 0

Ordinary Lisp variables can be assigned any value that is a valid Lisp object. However, certain Lisp variables are not defined in Lisp, but in C. Most of these variables are defined in the C code using DEFVAR_LISP. Like variables defined in Lisp, these can take on any value. However, some variables are defined using DEFVAR_INT or DEFVAR_BOOL. Writing Emacs Primitives, in particular the description of functions of the type syms_of_FILENAME, for a brief discussion of the C implementation. Variables of type DEFVAR_BOOL can only take on the values nil or t. Attempting to assign them any other value will set them to t:

(let ((display-hourglass 5))
  display-hourglass)
     => t

byte-boolean-vars

This variable holds a list of all variables of type DEFVAR_BOOL.

Variables of type DEFVAR_INT can take on only integer values. Attempting to assign them any other value will result in an error:

(setq undo-limit 1000.0)
error--> Wrong type argument: integerp, 1000.0

A generalized variable or place form is one of the many places in Lisp memory where values can be stored using the setf macro (Setting Generalized Variables). The simplest place form is a regular Lisp variable. But the CARs and CDRs of lists, elements of arrays, properties of symbols, and many other locations are also places where Lisp values get stored. Generalized variables are analogous to lvalues in the C language, where x = a[i] gets an element from an array and a[i] = x stores an element using the same notation. Just as certain forms like a[i] can be lvalues in C, there is a set of forms that can be generalized variables in Lisp.

(setf (NAME ARGS...) VALUE)

(SETTER ARGS... VALUE)

(let ((temp VALUE))
  (SETTER ARGS... temp)
  temp)

(gv-define-setter caar (val x) `(setcar (car ,x) ,val))

(gv-define-expander substring
  (lambda (do place from &optional to)
    (gv-letplace (getter setter) place
      (macroexp-let2* (from to)
        (funcall do `(substring ,getter ,from ,to)
                 (lambda (v)
                   (macroexp-let2* (v)
                     `(progn
                        ,(funcall setter `(cl--set-substring
                                           ,getter ,from ,to ,v))
                        ,v))))))))

(defmacro incf (place &optional n)
  (gv-letplace (getter setter) place
    (macroexp-let2* ((v (or n 1)))
      (funcall setter `(+ ,v ,getter)))))

When you set a variable to a value and then close Emacs and restart it, that value won't be automatically restored. Users usually set normal variables in their startup files, or use Customize (Customization) to set user options permanently, and various packages have various files where they store the data (e.g., Gnus stores this in .newsrc.eld and the URL library stores cookies in ~/.emacs.d/url/cookies). For things in between these two extremes (i.e., configuration which goes in the startup file, and massive application state that goes into separate files), Emacs provides a facility to replicate data between sessions called multisession variables. (This facility may not be available on all systems.) To give you an idea of how these are meant to be used, here's a small example:

(define-multisession-variable foo 0)
(defun my-adder (num)
  (interactive "nAdd number: ")
  (setf (multisession-value foo)
        (+ (multisession-value foo) num))
  (message "The new number is: %s" (multisession-value foo)))

This defines the variable foo and binds it to a special multisession object which is initialized with the value 0 (if the variable doesn't already exist from a previous session). The my-adder command queries the user for a number, adds this to the old (possibly saved value), and then saves the new value. This facility isn't meant to be used for huge data structures, but should be performant for most values.

define-multisession-variable

This macro defines name as a multisession variable, and gives it the initial-value if this variable hasn't been assigned a value earlier. doc is the doc string, and several keyword arguments can be used in args:

:package PACKAGE-SYMBOL

This keyword says that a multisession variable belongs to the package specified by package-symbol. The combination of package-symbol and name has to be unique. If package-symbol isn't given, this will default to the first "segment" of the name symbol's name, which is the part of its name up to and excluding the first -. For instance, if name is foo and package-symbol isn't given, package-symbol will default to foo.

:synchronized BOOL

Multisession variables can be synchronized if bool is non-nil. This means that if there're two concurrent Emacs instances running, and the other Emacs changes the multisession variable foo, the current Emacs instance will retrieve that modified data when accessing the value. If synchronized is nil or missing, this won't happen, and the values in all Emacs sessions using the variable will be independent of each other.

:storage STORAGE

Use the specified storage method. This can be either sqlite (in Emacs compiled with SQLite support) or files. If not given, this defaults to the value of the multisession-storage variable, described below.

multisession-value

This function returns the current value of variable. If this variable hasn't been accessed before in this Emacs session, or if it's changed externally, it will be read in from external storage. If not, the current value in this session is returned as is. It is an error to call this function for a variable that is not a multisession variable. Values retrieved via multisession-value may or may not be eq to each other, but they will always be equal. This is a generalized variable (Generalized Variables), so the way to update such a variable is to say, for instance:

(setf (multisession-value foo-bar) 'zot)

Only Emacs Lisp values that have a readable print syntax (Printed Representation) can be saved this way. If the multisession variable is synchronized, setting it may update the value first. For instance:

(cl-incf (multisession-value foo-bar))

This first checks whether the value has changed in a different Emacs instance, retrieves that value, and then adds 1 to that value and stores it. But note that this is done without locking, so if many instances are updating the value at the same time, it's unpredictable which instance "wins".

multisession-delete

This function deletes object and its value from its persistent storage.

make-multisession

You can also make persistent values that aren't tied to a specific variable, but are tied to an explicit package and key.

(setq foo (make-multisession :package "mail"
                             :key "friends"))
(setf (multisession-value foo) 'everybody)

This supports the same keywords as define-multisession-variable, but also supports a :initial-value keyword, which specifies the default value.

multisession-storage

This variable controls how the multisession variables are stored. It value defaults to files, which means that the values are stored in a one-file-per-variable structure inside the directory specified by multisession-directory. If this value is sqlite instead, the values are stored in an SQLite database; this is only available if Emacs was built with SQLite support.

multisession-directory

The multisession variables are stored under this directory, which defaults to multisession/ subdirectory of the user-emacs-directory, which is typically ~/.emacs.d/multisession/.

Command list-multisession-values

This command pops up a buffer listing all the multisession variables, and enters a special mode multisession-edit-mode which allows you to delete them and edit their values.