16.3 Symbol Values

The value field of a symbol normally contains a Lisp object. However, a symbol can be unbound, meaning that it logically has no value. This is internally indicated by storing a special Lisp object, called the unbound marker and stored in the global variable Qunbound. The unbound marker is of a special Lisp object type called symbol-value-magic. It is impossible for the Lisp programmer to directly create or access any object of this type.

You must not let any “symbol-value-magic” object escape to the Lisp level. Printing any of these objects will cause the message ‘INTERNAL EMACS BUG’ to appear as part of the print representation. (You may see this normally when you call debug_print() from the debugger on a Lisp object.) If you let one of these objects escape to the Lisp level, you will violate a number of assumptions contained in the C code and make the unbound marker not function right.

When a symbol is created, its value field (and function field) are set to Qunbound. The Lisp programmer can restore these conditions later using makunbound or fmakunbound, and can query to see whether the value of function fields are bound (i.e. have a value other than Qunbound) using boundp and fboundp. The fields are set to a normal Lisp object using set (or setq) and fset.

Other symbol-value-magic objects are used as special markers to indicate variables that have non-normal properties. This includes any variables that are tied into C variables (setting the variable magically sets some global variable in the C code, and likewise for retrieving the variable’s value), variables that magically tie into slots in the current buffer, variables that are buffer-local, etc. The symbol-value-magic object is stored in the value cell in place of a normal object, and the code to retrieve a symbol’s value (i.e. symbol-value) knows how to do special things with them. This means that you should not just fetch the value cell directly if you want a symbol’s value.

The exact workings of this are rather complex and involved and are well-documented in comments in buffer.c, symbols.c, and lisp.h.