This function returns the name of the file that defined symbol.
If type is nil
, then any kind of definition is acceptable.
If type is defun
, defvar
, or defface
, that
specifies function definition, variable definition, or face definition
only.
The value is normally an absolute file name. It can also be nil
,
if the definition is not associated with any file. If symbol
specifies an autoloaded function, the value can be a relative file name
without extension.
If the optional third argument native-p is non-nil
, and
Emacs was built with native compilation support (see Compilation of Lisp to Native Code), this function will try to find the .eln file
that defined symbol, instead of the .elc or .el
file. If such a .eln file is found and is not outdated, the
function will return its absolute file name; otherwise it will report
the name of either the source or the byte-compiled file.
The basis for symbol-file
is the data in the variable
load-history
.
The value of this variable is an alist that associates the names of loaded library files with the names of the functions and variables they defined, as well as the features they provided or required.
Each element in this alist describes one loaded library (including libraries that are preloaded at startup). It is a list whose CAR is the absolute file name of the library (a string). The rest of the list elements have these forms:
var
The symbol var was defined as a variable.
(defun . fun)
The function fun was defined.
(defun . fun)
, which represents defining fun as a
function.
(defface . face)
The face face was defined.
(require . feature)
The feature feature was required.
(provide . feature)
The feature feature was provided.
(cl-defmethod method specializers)
The named method was defined by using cl-defmethod
, with
specializers as its specializers.
(define-type . type)
The type type was defined.
The value of load-history
may have one element whose CAR is
nil
. This element describes definitions made with
eval-buffer
on a buffer that is not visiting a file.
The command eval-region
updates load-history
, but does so
by adding the symbols defined to the element for the file being visited,
rather than replacing that element. See Eval.
In addition to load-history
, every function keeps track of its
own history in the symbol property function-history
.
The reason why functions are treated specially in this respect is that
it is common for functions to be defined in two steps in two different
files (typically, one of them is an autoload), so in order to be
able to properly unload a file, we need to know more precisely
what that file did to the function definition.
The symbol property function-history
holds a list of the form
(file1 def2 file2 def3 ...)
, where
file1 is the last file that changed the definition and
def2 was the definition before file1, set by file2,
etc. Logically this list should end with the name of the first file
that defined this function, but to save space this last element
is usually omitted.