Next: , Previous: Future Local Variables, Up: Variables

11.13 File Local Variables

A file can specify local variable values; Emacs uses these to create buffer-local bindings for those variables in the buffer visiting that file. See Local Variables in Files, for basic information about file local variables. This section describes the functions and variables that affect processing of file local variables.

— User Option: 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.

— Function: hack-local-variables &optional mode-only

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 (see Auto Major Mode).

If the optional argument mode-only is non-nil, then all this function does is return t if the `-*-' line or the local variables list specifies a mode and nil otherwise. It does not set the mode nor any other file local variable.

If a file local variable could specify a function that would be called later, or an expression that would be executed later, simply visiting a file could take over your Emacs. Emacs takes several measures to prevent this.

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 standardly have safe-local-variable properties, including fill-column, fill-prefix, and indent-tabs-mode. For boolean-valued variables that are safe, use booleanp as the property value. Lambda expressions should be quoted so that describe-variable can display the predicate.

— User Option: 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.

— Function: safe-local-variable-p sym val

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. A 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 considered risky. The variables `font-lock-keywords', `font-lock-keywords' followed by a digit, and `font-lock-syntactic-keywords' are also considered risky. Finally, any variable whose name has a non-nil risky-local-variable property is considered risky.

— Function: risky-local-variable-p sym

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

If a variable is risky, it will not be entered automatically into safe-local-variable-values as described above. Therefore, Emacs will always query before setting a risky variable, unless the user explicitly allows the setting by customizing safe-local-variable-values directly.

— Variable: 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.

— User Option: 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.

— User Option: 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.