11.15 Interrogate-Symbols

interrogate-symbols is designed to find why symbols are left in the image even though they should not be. Since keeping information in the image would itself keep symbols, the facility has as little functionality as possible. The result is a non-intuitive interface, and you should be ready for this. You are encouraged to try other methods first. In particular, you might consider contacting Lisp Support first.

To use interrogate-symbols pass :interrogate-symbols t to deliver. This loads the interrogate symbol facility. and causes the delivered image to check for the command line argument -interrogate-symbols on startup. If this command line argument appears, the image first does symbol interrogation, and then proceeds to run the application as normal.

Symbol interrogation starts by building an internal table of reverse pointers, during which the image prints some messages about its progress. When it finishes, it prompts:

Enter Symbol >

The input is read one line at a time. Each line is interpreted as a single string, where SYMBOLNAME and PACKAGENAME contain no colons and the line does not begin with a plus sign unless specified. The string can take one of five formats. If the string is of the format:

SYMBOLNAME
then it is a symbol name. The string is used as the argument to find-symbol (in the current package).

Note the string is used as-is, so it must not contain escape characters or leading or trailing spaces, and must be in the right case. For example, the symbol that is printed:
```
SETF::\"USER\"\ \"WHATEVER\"
```
must be entered:
```
SETF::"USER" "WHATEVER"  
```
[ omitting the escape characters #\\ ] and to find the symbol CAR, you must enter CAR, and not car. #\: characters after the first one (or the first pair) are taken as part of the symbol.

If the symbol is found, the image prints a list, when the first element is the symbol, the second element is a list of interesting symbols that point to that symbol (possibly through uninteresting symbols), and the third element is a list of symbols that point to the symbol directly. A symbol B points to symbol B directly when there is a chain of pointers from A to B which does not go via another symbol.

An interesting symbol is a symbol in another package, or a symbol from the same package which is pointed to by a symbol from another package. The idea is that the interesting symbols are the symbols that are most likely to be worth further investigation.

Both the second and the third element may be the symbol :many rather than a list, if there are more the sys::*maximum-interrogate-return* (default value 30) of them.
PACKAGENAME:SYMBOLNAME or
PACKAGENAME::SYMBOLNAME
then it is a package name followed by a symbol name. The characters up to the first colon are used to search for the package. The characters after the last colon comprise a symbol name. Like in 1. above, both the package name and the symbol name must exactly match the actual package and symbol name. The output is the same as in 1.
+SYMBOLNAME or
+PACKAGENAME:SYMBOLNAME or
+PACKAGENAME::SYMBOLNAME
then the package and/or symbol is determined from the rest of the string as in 1. or 2. However, instead of looking for symbols that point to it, the image builds a tree of reversed pointers starting from the symbol, going to depth sys::*check-symbol-depth*. In the tree, the car is an object and the cdr is a list of pointers to it. Each pointer may be a single object (if it has reached the depth limit, or found an object that is already in the tree), or a recursive tree. The tree may be quite extensive.
PACKAGENAME:
than the line specifies a package name. If the string does not start with a #\+, the image prints each symbol from other packages that point (as defined in 1.) to symbols in the package, followed by a list of the symbols in the package that it points to. To construct this list it has to check the reverse pointers from all the symbols in the package, which may take a long time if the package contains many symbols.

This option is especially useful in conjunction with the :smash-packages-symbols keyword to deliver, to find why a package that should have gone remains in the image.
+PACKAGENAME:
then the rest of the string is treated as a package name as in 4., but the image prints the same information that 1. prints, but for each symbol in the package.