2 Customizing the Lisp Environment

2.13 Reference pages

Syntax:*autoload-verbose*

The variable*autoload-verbose* controls the printing of messages that are displayed when functions or macros are loaded by the autoloading facility.

If this variable has a non-nil value, a message is printed whenever an autoloadable function or macro is loaded. The default value ist. If the value isnil, no message is printed.

Syntax:autoloadablep name

The functionautoloadablep is true if its argument is a symbol that names an autoloadable function or macro; otherwise, it is false.

This predicate is false for autoloadable functions and macros that have already been loaded into the current Lisp image.

See Also: defmacro-autoload, defun-autoload

Syntax:command-line-argument argument-number

The functioncommand-line-argument returns a string representing a command-line argument that was provided when Lisp was invoked. The command-line arguments are accessed by a position number, where
0 represents the command that invoked Lisp. The function returnsnil for positions that exceed the total number of command-line arguments specified.

The argument-number argument must be a fixnum.

;; Assume you invoked Lisp with no command-line arguments.
> (command-line-argument 0)
"lisp"

> (command-line-argument 1)
NIL

Syntax:define-autoload name filename type&key :arglist :documentation

The functiondefine-autoload provides a functional interface for autoload definitions. It evaluates all of its arguments.

The name argument is a symbol that names the function or macro that will be loaded. The filename argument is a string or a pathname that names the file containing the definition of name.

The type argument specifies the type of construct being defined, which must be either'function or'macro.

The functiondefine-autoload accepts the following keyword arguments:

• :arglist

This keyword argument specifies the argument list for name, which is accessible to the functionarglist.

• :documentation

This keyword argument specifies a documentation string for name, which is accessible to the Common Lisp functiondocumentation.

Syntax:defmacro-autoload name filename&optional arglist documentation

The macrodefmacro-autoload defines an autoloadable macro.

The name argument is a symbol that names the macro to be autoloaded; this argument is the return value ofdefmacro-autoload. The filename argument is a string or a pathname that names the file containing the definition for the macro.

The optional arglist argument specifies the macro's argument list, which is accessible to the functionarglist. The optional documentation argument is the macro's documentation string, which is accessible to the Common Lisp functiondocumentation.

These arguments are not evaluated.

See Also: defun-autoload

Syntax:defun-autoload name filename&optional arglist documentation

The macrodefun-autoload defines an autoloadable function.

The name argument is a symbol that names the function to be autoloaded; this argument is the return value ofdefun-autoload. The filename argument is a string or a pathname that names the file containing the definition for the function.

The optional arglist argument specifies the function's argument list, which is accessible to the function arglist. The optional documentation argument is the function's documentation string, which is accessible to the Common Lisp functiondocumentation.

;;; The unevaluated argument (x &rest args) becomes the argument 
;;; list for FOOD. The argument list is correctly defined when 
;;; the file is loaded.
> (defun-autoload (food "/lnz/pizza") (x &rest args)
  "This function teaches someone how to eat pizza.  If the  
   number of arguments given to FOOD exceeds 4, the pizza is 
  served with anchovies.")
FOOD

> (arglist 'food)
(X &REST ARGS)

See Also: defmacro-autoload

Syntax:disksave target-file&key :restart-function :full-gc :gc :reserved-free-segments :dynamic-free-segments :verbose

The functiondisksave saves a copy of an executing Lisp image on disk.

The target-file argument is a pathname, stream, string, or symbol that names the Lisp image file to be created; no pathname defaults are applied.

You can specify the following keyword arguments todisksave:

• :restart-function

This keyword argument specifies a function of no arguments that Lisp first calls when the resulting disk file is executed; this function is called the restart function. After calling the restart function, Lisp proceeds with the usual initialization process. Finally, Lisp enters the normal read-eval-print loop. If the restart function does not return, no initialization or top-level evaluation is performed. In this way, the saved image can be made to behave like an application program.

You should specify this keyword option when you do not need to use the Lisp top level, such as when your program has its own interaction function or is not interactive.

• :full-gc,:gc

These keyword arguments control garbage collection during the save. If:full-gc has a non-nil value, a garbage collection is performed before the image is saved. After the garbage collection, all dynamic storage is converted to static storage. Objects converted from dynamic storage to static storage are never recopied during a garbage collection; however, they are scanned for pointers to update. As a result, large systems that are loaded into Lisp and saved can have fewer garbage collections, and these garbage collections might take less time to complete.

If:gc has a non-nil value and:full-gc is unspecified ornil, a normal garbage collection is performed before the image is saved. Due to memory management constraints,disksave can force a garbage collection in addition to any requested through use of the:full-gc and:gc keyword arguments.

Note: If neither:gc nor:full-gc is specified, the saved image might contain all of the garbage that is currently in the image, and therefore the files saved on disk can be considerably larger than necessary. When you calldisksave, specifying:gc or:full-gc is recommended.

• :reserved-free-segments

This keyword argument specifies the number of segments of reserved memory that should be free in the saved image; if used, it should be set to a positive integer. Specifying a large number of segments permits you to load large amounts of code into the image or to create many foreign data structures without having to expand reserved memory and reclaim storage. However, specifying a large number of segments can increase the size of your saved image as well as the amount of memory that is required to start it up.

When ephemeral garbage collection is enabled, as it normally is when Lisp starts up, the ephemeral areas are created from the reserved area. The initial value comprises both room for creation of the ephemeral areas and room for permanent data structures.

• :dynamic-free-segments

This keyword argument specifies the number of segments of dynamic-0 space that should be free in the image; if used, it should be set to a positive integer. The total amount of dynamic space is as follows:

(amount of dynamic-0 space in use + free dynamic-0 space requested) 2

The amount is doubled because an equal amount of dynamic-1 space is allocated. If you do not specify this argument, all dynamic space that is allocated in the running image is preserved when you calldisksave.

• :verbose

If this keyword argument has a non-nil value, the progress of the saving process is reported to the terminal. Due to memory management constraints,disksave prints its messages using primitive input and output functions; thus, the messages might not appear in scripts created by the Common Lisp functiondribble.

LCL/HP and LCL/SGI take an additional keyword argument,:writable.

• :writable

If this keyword argument has a non-nil value, the portions of the Lisp image that normally would be loaded into read-only memory are loaded into writable storage when the saved image is invoked.

The default value of this argument isnil.

LCL/HP has another keyword argument,:stack-segments.

• :stack-segments

This keyword argument specifies the size in segments of the Lisp stack in the image. Specifying a large number decreases the chance of stack overflow but increases the size of the image.

It is generally a bad idea to continue from an interrupt while an image is being written to disk. If you type the interrupt character, Ctrl-c, while the image is being saved, use the:a option to abort to the top level of Lisp and invokedisksave again.

If the Window Tool Kit has been initialized and the functiondisksave is invoked, the window environment is temporarily suspended. Once thedisksave function has saved the Lisp image on disk, the windows of the running Lisp image are restored automatically to the state they were in before thedisksave function call. To restore the state of the windows when the saved image is executed, call the functioninitialize-windows or the functioned with no arguments. If you initialized the Window Tool Kit while using a specific type of X display server, you might not be able to initialize windows in the saved image under a different type of X server. You should always start a new image under the same type of X display server that you used when you saved the image. See The Window Tool Kit for more information about the Window Tool Kit.

The only foreign pointers that are preserved in a saved image are those returned by the functionforeign-variable-pointer and those created by the functionmake-foreign-pointer when the value of the:static keyword argument is non-nil. See Section 4.1.2.7 on page 97 for more information.

A segmentation violation can occur if you attempt to access constant data structures that have been compiled in the image, since they might be write-protected after the image is saved on disk. See Section 3.4.3 on page 59 for more information.

Syntax: ensure-autoloaded names

The functionensure-autoloaded determines if the specified autoloadable constructs have been loaded; it loads any constructs that have not been loaded.

The names argument is a symbol or a list of symbols.

Syntax:*enter-top-level-hook*

The variable*enter-top-level-hook* controls the behavior of Lisp when an image is started.

If the variable is bound to a compiled function or to a symbol that names a compiled function, that function is called once before Lisp enters the top level.

If the variable is not bound, Lisp searches your home directory for an initialization file to load. The file that is loaded is determined as if by the following function call:

(load (merge-pathnames "lisp-init" (user-homedir-pathname))
      :if-does-not-exist nil)

The variable*enter-top-level-hook* must be bound to a compiled function to provide an extra measure of error checking.

By default, the variable*enter-top-level-hook* is unbound.

;;; This example assumes you are working in a Lisp image named 
;;; MYLISP.  After *ENTER-TOP-LEVEL-HOOK* is bound, the image
;;; is saved on disk.  The next time MYLISP is started up, the 
;;; appropriate message appears.
> (defun ignore-lisp-init-file ()
   (format  t "Ignoring lisp init-file name~%"))
IGNORE-LISP-INIT-FILE

> (compile 'IGNORE-LISP-INIT-FILE)
IGNORE-LISP-INIT-FILE

> (setq *enter-top-level-hook* #'IGNORE-LISP-INIT-FILE)
#<Compiled-Function IGNORE-LISP-INIT-FILE 522507>

> (disksave "mylisp")
"mylisp"
> (quit)
% mylisp
;; After executing its initialization routines, Lisp responds 
;; with this message.
Ignoring lisp init-file name
> 

See Also: disksave, load

Syntax:environment-variable variable-name

The functionenvironment-variable returns the string value of a specified environment variable. The function returnsnil if the variable does not exist.

The variable-name argument must be a string.

You can use this function with the Common Lisp macrosetf to assign a value to the variable. If the variable already exists, its value is reassigned. If the variable does not exist, a new environment variable is created. If you set the value of the variable tonil, the variable is deleted.

Environment variable additions and modifications are visible only to Lisp and to programs invoked from Lisp by the functionsshell orrun-program; the programs that are invoked inherit the modifications. Environment variables that have been changed or added revert to their original values when Lisp exits.

> (environment-variable "SHELL")
"/bin/csh"

> (setf (environment-variable "SHELL") nil)
NIL

> (environment-variable "SHELL")
NIL

> (setf (environment-variable "SHELL") "/bin/sh")
"/bin/sh"

> (environment-variable "SHELL")
"/bin/sh"

See Also:run-program;shell (in The User's Guide)

Syntax:lisp-image-name

The functionlisp-image-name returns the pathname of the object file that started the current invocation of Lisp. If the object file cannot be determined, the function returnsnil.

> (lisp-image-name)
#P"/usr/local/bin/lisp"

Syntax:*prompt*

The variable*prompt* specifies the string to be used as a prompt in the top-level read-eval-print loop. Initially,*prompt* is unbound and the default prompt string (>) is used.

> (setq *prompt* "at your service! ")
NIL
at your service! 999
999
at your service! (makunbound '*prompt*)
*PROMPT*

> 999
999

Syntax:set-disksave-parameters &key :reserved-free-segments :dynamic-free-segments :verbose

The functionset-disksave-parameters sets the default values for certain keyword arguments to the functiondisksave.

The keyword arguments have the initial values listed in Table 2.2.

Initial values ofset-disksave-parameters keywords

Keyword	Platform	Initial Value
:reserved-free-segments	SGI	67
	all others	3
:dynamic-free-segments	HP	20
	SGI	28
	all others	90
:verbose	all	nil
:stack-segments (HP only)	HP	1

The values that you specify remain in effect for all subsequently saved images unless you specify different values as keyword arguments todisksave.

See Also: disksave

Syntax:working-directory

The functionworking-directory returns the current working directory as a pathname.

The Common Lisp variable*default-pathname-defaults* is set to the new working directory.

You can use the Common Lisp macrosetf withworking-directory to set the current working directory; this method of setting the working directory is preferable to explicitly setting the variable*default-pathname-defaults* because it keeps the operating system and the variable synchronized.

> (working-directory)
#P"/liquid/bin/"

> (setf (working-directory) "/u/win/")
#P"/u/win/"

> (working-directory)
#P"/u/win/"

> (setf (working-directory) "/scratch/")
#P"/scratch/"

> (working-directory)
#P"/scratch/"

> (setf (working-directory) (user-homedir-pathname))
#P"/u/win/"

> (working-directory)
#P"/u/win/"

> (pwd)
#P"/u/win/"

See Also:cd,pwd (in The User's Guide)

Generated with Harlequin WebMaker