The first time this function is called, it writes out and dereferences all heap-allocated code vectors except those being executed when this function is called (perhaps by some other stack group/process as well). The code vectors are written to the file specified by file. This file cannot exist when this function is called for the first time (the system will create it). A heap-allocated code vector is one that is not stored in text space when the Lisp image is built. The function objects associated with the code vectors are destructively modified to become stub functions (with a pointer to file). The code vectors that are written to file are orphaned and thus will be garbage collected by the next global gc --a global gc is required to collect them because most code vectors are in oldspace.
In subsequent calls, the file argument is ignored. The file specified in the first call is used. All heap-allocated code vectors except those actually in use are flushed with each call. In the second and subsequent calls, newly created code vectors are appended to those already flushed.
If in the first call to sys:flush-codevectors file is unspecified or nil, the system creates an anonymous filename that is not visible in the filesystem (ls will not find it, because it is unlinked after it is created, so it is removed automatically when Lisp exits). If you use an anonymous file, dumplisp will not work (since the file where the code vectors are will not be available when the dumped image is restarted).
The verbose argument, if true, will cause this function to print information about the actions it takes. The default for verbose is nil. Note that you can specify the file argument as nil if you wish to specify verbose as t and have the system choose an anonymous filename.
This function is primarily designed to clear the system before a training run to determine necessary code vectors for a specific application. However, periodically calling this function during ordinary Lisp operation may prevent the image from growing unnecessarily and may improve locality of reference. Please note that we say may in the last sentence.