augment-environment

Function, system package

Arguments: environment &key variable symbol-macro constant function macro declare special-operator block tag compiler-macro flavor-iv reuse locative

This function returns a new environment object created by augmenting environment with the information provided by the keyword aguments.

The keyword argument corresponding to namespaces (variable, symbol-macro, constant, function, macro, special-operator, block, tag, and flavor-iv), locative information can be supplied for each name added. (See variable-information, function-information, tag-information, and block-information for information on appropriate locative values for different objects.) Locative information can be provided for each name by having instead of a list of names for one of the arguments listed above, an alist with the car of each element being the name and the cdr being the locative information.

The keyword arguments are:

• variable: the value should be a list of symbols that will be visible as bound variables in the new environment. Declarations already in the environment or added by the declare keyword argument provide information about these variables (whether they are lexical, or special, for example).

• symbol-macro: the value should be a list of symbol-macro definitions of the form (*name* *definition*) (similar to specifications to symbol-macrolet). Thus the new environment will have a symbol-macro binding for each name and macroexpand will be able to expand them correctly. A type declaration for a name added to the declare argument wraps a the form mentioning the type about the definition.

• constant: the value should be a list of symbols that will be visible as constants in the new environment.

• function: the value should be a list of function names that will be visible as local functions in the new environment.

• macro: the value should be a list of macro definitions of the form (*name* *definition*) (similar to specifications to macrolet). Each definition must be a function of two arguments (a form and an environment). The new environment will have a local macro binding for each name corresponding to the macro expander function.

• declare: the value should be a list of special operator names that will be visible in the environment. The environment must be a global-environment; either the null lexical environment or a compile-file environment shadowing the global environment (in this case the reuse argument should be specified as true).

• special-operator: the value should be a list of special operator names that will be visible in the new environment.

• block: the value should be a list of block names that will be visible in the new environment.

• tag: the value should be a list of tag names that will be visible in the new environment.

• compiler-macro: the value should be a list of compiler-macro names that will be visible in the environment. The environment must be a global-environment; either the null lexical environment or a compile-file environment shadowing the global environment (in this case the reuse argument should be specified as true).

• flavor-iv: the value should be a list of flavor instance variable names that will be visible in the new environment.

• reuse: when reuse is nil (the default) a new environment object is consed, i.e. the environment object returned is not eq to the one given. When reuse is non-nil, then the old environment object is returned, and any additions to the environment are added at the same level, as if they had been all added in the same call to augment-environment which created this environment object.

• locative: if only one name is being added by this call to augment-environment, then the locative information for that single name can be provided as the value of this argument, thereby saving the consing necessary to place the locative with the name itself.

block-information

Function, system package

Arguments: name &optional env

This function returns information about the block named by name in the environment env. env may an environment object or nil, indicating the null lexical environment.

Three values are returned: :block, a locative, and declaration list. The car of the locative is a catch tag (usually a unique cons cell) and the cdr of the locative is nil as long as the block is within scope. As part of the cleanup when the block is exiting, the cdr of the block's locative is set to 'invalid, which marks the block as being no longer in scope.

See environments.html for more information on environments.

ce-get

Function, system package

Arguments: obj ind &optional env

Returns the ind property of obj. obj may be any object, but it is generally intended that it either be a symbol or a cons. The environment is specified either by the presence of the env argument, the value of *compile-file-environment*, or the value of *evaluation-environment*.
Each is tried in succession, and if the object and indicated property is found, the value is returned, otherwise the process is continued until the property is found or the environments are exhausted, at which point the object is consulted in a global way. If no ind property exists for obj, nil is returned. There is no default value; a return value of nil indicates that the property does not exist.

See environments.html for more information on environments.

ce-putprop

Function, system package

Arguments: obj value ind &optional env

Returns value, after storing it as the ind property of obj. obj may be any object, but it is generally intended that it either be a symbol or a cons. The environment is specified either by the presence of the env argument, or the value of *compile-file-environment*, or the value of *evaluation-environment*, but only if it contains an :evaluation. If either environment is non-nil, then it must be an environment created by sys::make-compile-file-environment. The property is stored into the environment using #'eq as the test for symbols, and #'equal for any other object. If the specified environment is nil, then the property is stored in the global environment.

If the value is nil, the property is effectively removed, as if by remprop, remhash, etc.

See environments.html for more information on environments.

command-line-argument

Function, system package

Arguments: n &key application

This function and its relatives, command-line-arguments and command-line-argument-count, provide information about the command line that invoked Allegro CL. Their precise behavior depends on the value of the application keyword argument.

The command line includes the following, in the order specified:

1. The executable name. This may include directory information (i.e. /usr/local/acl/mlisp) or may not (just mlisp).

2. Command-line arguments prefixed by a +. these are used on Windows only.

3. command-line arguments prefixed by a - and, when appropriate, the values of those arguments.

4. the special marker -- (a double dash).

5. any arguments whatsoever that follow the double-dash.

See Command line arguments in startup.html for a list of command-line arguments accepted by Allegro CL.

When the value of the :application keyword argument is true

The application arguments are the executable name (number 1 in the list above) and the ones which follow the double dash (number 5 in the list above). Consider that those arguments are collected as strings in a list called the list-of-application-arguments. When application is true (it defaults to t), the command-line argument information functions behave as follows:

• command-line-argument with argument n returns the (0 based) nth element of the list-of-application-arguments. It is an error to specify a value for n equal to or greater than the length of list-of-application-arguments.

• command-line-arguments returns the list list-of-application-arguments.

• command-line-argument-count returns the length of the list list-of-application-arguments.

Examples when :application is true

;;  Lisp was started on UNIX with the command line
;;  (we assume the mlisp executable is in a directory
;;  included in the PATH environment variable):
% mlisp -qq -- init 5 safe

(sys:command-line-argument-count :application t)
  RETURNS 4
(sys:command-line-argument-count)  ;; :application defaults to T
  RETURNS 4
(sys:command-line-arguments)
  RETURNS ("mlisp" "init" "5" "safe")
;;  or perhaps (/usr/local/acl70/mlisp init 5 safe)
;;  assuming mlisp is in /usr/local/acl70/: the directory
;;  may or may not be included.
(sys:command-line-argument 0)
  RETURNS "mlisp"  ;; or perhaps "/usr/local/acl70/mlisp"
(sys:command-line-argument 1)
  RETURNS "init"
(sys:command-line-argument 2)
  RETURNS "5"
(sys:command-line-argument 3)
  RETURNS "safe"
(sys:command-line-argument 4)
  ERROR    ;;  the first argument to sys:command-line-argument
           ;;  must be less than the number of arguments
           ;;  as returned by sys:command-line-argument-count

;;  Lisp was started on WINDOWS with the command line
% mlisp.exe +co -qq -- init 5 safe
;;  The values returned by the command-line argument functions are the
;;  same as on UNIX (except "mlisp.exe" or 
;;  "C:\\Program Files\\acl70\\mlisp.exe" replaces "mlisp" or 
;;  "/usr/local/acl70/mlisp".

When the value of the :application keyword argument is nil

All arguments except those beginning with + are considered command-line arguments by these functions when application is nil. That includes the executable name (number 1 in the list above), the - arguments and their values (number 3 in the list above), the double dash (number 4 in the queue above), and arguments which follow the double dash (number 5 in the list above). Consider that those arguments are collected as strings in a list called the list-of-arguments. When application is nil, the command-line argument information functions behave as follows:

• command-line-argument with argument n returns the (0 based) nth element of the list-of-arguments. It is an error to specify a value for n equal to or greater than the length of list-of-arguments. Note the + arguments are ignored and will not be returned for any value of n. The double dash, if present, is considered and will be returned for some value of n.

• command-line-arguments returns the list list-of-arguments. Note the + arguments are ignored and thus not included, while the double dash, if present, is included.

• command-line-argument-count returns the length of the list list-of-arguments. Note the + arguments are ignored and thus not counted, while the double dash is counted as an argument.

Examples when :application is nil

;;  Lisp was started on UNIX with the command line
;;  (we assume the mlisp executable is in a directory
;;  included in the PATH environment variable):
% mlisp -qq -- init 5 safe

(sys:command-line-argument-count :application nil)
  RETURNS 6
(sys:command-line-arguments :application nil)
  RETURNS ("mlisp" "-qq" "--" "init" "5" "safe")
;;  or perhaps (/usr/local/acl70/mlisp -qq -- init 5 safe)
;;  assuming mlisp is in /usr/local/acl70/: the directory
;;  may or may not be included.
(sys:command-line-argument 0)
  RETURNS "mlisp"  ;; or perhaps "/usr/local/acl70/mlisp"
(sys:command-line-argument 1)
  RETURNS "-qq"
(sys:command-line-argument 2)
  RETURNS "--"
(sys:command-line-argument 3)
  RETURNS "init"
(sys:command-line-argument 4)
  RETURNS "5"
(sys:command-line-argument 5)
  RETURNS "safe"
(sys:command-line-argument 6)

  ERROR    ;;  the first argument to sys:command-line-argument
           ;;  must be less than the number of arguments
           ;;  as returned by sys:command-line-argument-count

;;  Lisp was started on WINDOWS with the command line
% mlisp.exe +co -qq -- init 5 safe
;;  The values returned by the command-line argument functions are the
;;  same as on UNIX (except "mlisp.exe" or 
;;  "C:\\Program Files\\acl70\\mlisp.exe" replaces "mlisp" or 
;;  "/usr/local/acl70/mlisp". The command-line argument functions
;;  always ignore the + arguments.

Anomolies when :application is true

If the Allegro CL image was created with dumplisp (or build-lisp-image or generate-application) with the ignore-command-line-arguments argument true (the default is nil), then arguments are not processed by Allegro CL when it starts up and all arguments (regardless of whether a -- appears on the command line) are handled by these functions and the value of the application keyword argument has no effect.

Anomolies when :application is nil

The system may tack on arguments in addition to those you specified. In particular, when using the Emacs-Lisp interface, the arguments -e (start-emacs-lisp-interface t) may be added (to start in connection between Lisp and Emacs). Do not be surprised is you see these additional arguments. The system never adds arguments after a -- (double dash).

The path of the executable

Note that the zeroth argument is the name of the executable as entered in the command line, with or without path information. That is, the 0th argument may be, say, "mlisp" (without path information) or may be, say, "/usr/local/acl70/mlisp" (with path information). If path information is not provided and you need it, evaluating

(translate-logical-pathname (concatenate 'string "sys:"
(sys:command-line-argument 0)))

will typically work. (But that form signals an error when path information is provided.)

Uses of command-line arguments

You may use this information as you see fit. One possible use, for example, is to have some function defined and run (perhaps in the initialization file .clinit.cl) which takes some action (such as loading specific files) based on the values of the arguments. Recall again that + arguments are ignored and so their presence or absence cannot be used to affect behavior once Lisp has started.

command-line-argument-count

Function, system package

Arguments: &key application

This function and its relatives, command-line-arguments and command-line-argument, provide information about the command line that invoked Allegro CL. Their precise behavior depends on the value of the application keyword argument.

The command line includes the following, in the order specified:

1. The executable name. This may include directory information (i.e. /usr/local/acl/mlisp) or may not (just mlisp).

2. Command-line arguments prefixed by a +. these are used on Windows only.

3. command-line arguments prefixed by a - and, when appropriate, the values of those arguments.

4. the special marker -- (a double dash).

5. any arguments whatsoever that follow the double-dash.

See Command line arguments in startup.html for a list of command-line arguments accepted by Allegro CL.

When the value of the :application keyword argument is true

The application arguments are the executable name (number 1 in the list above) and the ones which follow the double dash (number 5 in the list above). Consider that those arguments are collected as strings in a list called the list-of-application-arguments. When application is true (it defaults to t), the command-line argument information functions behave as follows:

• command-line-argument with argument n returns the (0 based) nth element of the list-of-application-arguments. It is an error to specify a value for n equal to or greater than the length of list-of-application-arguments.

• command-line-arguments returns the list list-of-application-arguments.

• command-line-argument-count returns the length of the list list-of-application-arguments.

Examples when :application is true

;;  Lisp was started on UNIX with the command line
;;  (we assume the mlisp executable is in a directory
;;  included in the PATH environment variable):
% mlisp -qq -- init 5 safe

(sys:command-line-argument-count :application t)
  RETURNS 4
(sys:command-line-argument-count)  ;; :application defaults to T
  RETURNS 4
(sys:command-line-arguments)
  RETURNS ("mlisp" "init" "5" "safe")
;;  or perhaps (/usr/local/acl70/mlisp init 5 safe)
;;  assuming mlisp is in /usr/local/acl70/: the directory
;;  may or may not be included.
(sys:command-line-argument 0)
  RETURNS "mlisp"  ;; or perhaps "/usr/local/acl70/mlisp"
(sys:command-line-argument 1)
  RETURNS "init"
(sys:command-line-argument 2)
  RETURNS "5"
(sys:command-line-argument 3)
  RETURNS "safe"
(sys:command-line-argument 4)
  ERROR    ;;  the first argument to sys:command-line-argument
           ;;  must be less than the number of arguments
           ;;  as returned by sys:command-line-argument-count

;;  Lisp was started on WINDOWS with the command line
% mlisp.exe +co -qq -- init 5 safe
;;  The values returned by the command-line argument functions are the
;;  same as on UNIX (except "mlisp.exe" or 
;;  "C:\\Program Files\\acl70\\mlisp.exe" replaces "mlisp" or 
;;  "/usr/local/acl70/mlisp".

When the value of the :application keyword argument is nil

All arguments except those beginning with + are considered command-line arguments by these functions when application is nil. That includes the executable name (number 1 in the list above), the - arguments and their values (number 3 in the list above), the double dash (number 4 in the queue above), and arguments which follow the double dash (number 5 in the list above). Consider that those arguments are collected as strings in a list called the list-of-arguments. When application is nil, the command-line argument information functions behave as follows:

• command-line-argument with argument n returns the (0 based) nth element of the list-of-arguments. It is an error to specify a value for n equal to or greater than the length of list-of-arguments. Note the + arguments are ignored and will not be returned for any value of n. The double dash, if present, is considered and will be returned for some value of n.

• command-line-arguments returns the list list-of-arguments. Note the + arguments are ignored and thus not included, while the double dash, if present, is included.

• command-line-argument-count returns the length of the list list-of-arguments. Note the + arguments are ignored and thus not counted, while the double dash is counted as an argument.

Examples when :application is nil

;;  Lisp was started on UNIX with the command line
;;  (we assume the mlisp executable is in a directory
;;  included in the PATH environment variable):
% mlisp -qq -- init 5 safe

(sys:command-line-argument-count :application nil)
  RETURNS 6
(sys:command-line-arguments :application nil)
  RETURNS ("mlisp" -qq -- "init" "5" "safe")
;;  or perhaps (/usr/local/acl70/mlisp -qq -- init 5 safe)
;;  assuming mlisp is in /usr/local/acl70/: the directory
;;  may or may not be included.
(sys:command-line-argument 0)
  RETURNS "mlisp"  ;; or perhaps "/usr/local/acl70/mlisp"
(sys:command-line-argument 1)
  RETURNS "-qq"
(sys:command-line-argument 2)
  RETURNS "--"
(sys:command-line-argument 3)
  RETURNS "init"
(sys:command-line-argument 4)
  RETURNS "5"
(sys:command-line-argument 5)
  RETURNS "safe"
(sys:command-line-argument 6)

  ERROR    ;;  the first argument to sys:command-line-argument
           ;;  must be less than the number of arguments
           ;;  as returned by sys:command-line-argument-count

;;  Lisp was started on WINDOWS with the command line
% mlisp.exe +co -qq -- init 5 safe
;;  The values returned by the command-line argument functions are the
;;  same as on UNIX (except "mlisp.exe" or 
;;  "C:\\Program Files\\acl70\\mlisp.exe" replaces "mlisp" or 
;;  "/usr/local/acl70/mlisp". The command-line argument functions
;;  always ignore the + arguments.

Anomolies when :application is true

If the Allegro CL image was created with dumplisp (or build-lisp-image or generate-application) with the ignore-command-line-arguments argument true (the default is nil), then arguments are not processed by Allegro CL when it starts up and all arguments (regardless of whether a -- appears on the command line) are handled by these functions and the value of the application keyword argument has no effect.

Anomolies when :application is nil

The system may tack on arguments in addition to those you specified. In particular, when using the Emacs-Lisp interface, the arguments -e (start-emacs-lisp-interface t) may be added (to start in connection between Lisp and Emacs). Do not be surprised is you see these additional arguments. The system never adds arguments after a -- (double dash).

The path of the executable

Note that the zeroth argument is the name of the executable as entered in the command line, with or without path information. That is, the 0th argument may be, say, "mlisp" (without path information) or may be, say, "/usr/local/acl70/mlisp" (with path information). If path information is not provided and you need it, evaluating

(translate-logical-pathname (concatenate 'string "sys:"
(sys:command-line-argument 0)))

will typically work. (But that form signals an error when path information is provided.)

Uses of command-line arguments

You may use this information as you see fit. One possible use, for example, is to have some function defined and run (perhaps in the initialization file .clinit.cl) which takes some action (such as loading specific files) based on the values of the arguments. Recall again that + arguments are ignored and so their presence or absence cannot be used to affect behavior once Lisp has started.

command-line-arguments

Function, system package

Arguments: &key application

This function and its relatives, command-line-argument and command-line-argument-count, provide information about the command line that invoked Allegro CL. Their precise behavior depends on the value of the application keyword argument.

The command line includes the following, in the order specified:

1. The executable name. This may include directory information (i.e. /usr/local/acl/mlisp) or may not (just mlisp).

2. Command-line arguments prefixed by a +. these are used on Windows only.

3. command-line arguments prefixed by a - and, when appropriate, the values of those arguments.

4. the special marker -- (a double dash).

5. any arguments whatsoever that follow the double-dash.

See Command line arguments in startup.html for a list of command-line arguments accepted by Allegro CL.

When the value of the :application keyword argument is true

The application arguments are the executable name (number 1 in the list above) and the ones which follow the double dash (number 5 in the list above). Consider that those arguments are collected as strings in a list called the list-of-application-arguments. When application is true (it defaults to t), the command-line argument information functions behave as follows:

• command-line-argument with argument n returns the (0 based) nth element of the list-of-application-arguments. It is an error to specify a value for n equal to or greater than the length of list-of-application-arguments.

• command-line-arguments returns the list list-of-application-arguments.

• command-line-argument-count returns the length of the list list-of-application-arguments.

Examples when :application is true

;;  Lisp was started on UNIX with the command line
;;  (we assume the mlisp executable is in a directory
;;  included in the PATH environment variable):
% mlisp -qq -- init 5 safe

(sys:command-line-argument-count :application t)
  RETURNS 4
(sys:command-line-argument-count)  ;; :application defaults to T
  RETURNS 4
(sys:command-line-arguments)
  RETURNS ("mlisp" "init" "5" "safe")
;;  or perhaps (/usr/local/acl70/mlisp init 5 safe)
;;  assuming mlisp is in /usr/local/acl70/: the directory
;;  may or may not be included.
(sys:command-line-argument 0)
  RETURNS "mlisp"  ;; or perhaps "/usr/local/acl70/mlisp"
(sys:command-line-argument 1)
  RETURNS "init"
(sys:command-line-argument 2)
  RETURNS "5"
(sys:command-line-argument 3)
  RETURNS "safe"
(sys:command-line-argument 4)
  ERROR    ;;  the first argument to sys:command-line-argument
           ;;  must be less than the number of arguments
           ;;  as returned by sys:command-line-argument-count

;;  Lisp was started on WINDOWS with the command line
% mlisp.exe +co -qq -- init 5 safe
;;  The values returned by the command-line argument functions are the
;;  same as on UNIX (except "mlisp.exe" or 
;;  "C:\\Program Files\\acl70\\mlisp.exe" replaces "mlisp" or 
;;  "/usr/local/acl70/mlisp".

When the value of the :application keyword argument is nil

All arguments except those beginning with + are considered command-line arguments by these functions when application is nil. That includes the executable name (number 1 in the list above), the - arguments and their values (number 3 in the list above), the double dash (number 4 in the queue above), and arguments which follow the double dash (number 5 in the list above). Consider that those arguments are collected as strings in a list called the list-of-arguments. When application is nil, the command-line argument information functions behave as follows:

• command-line-argument with argument n returns the (0 based) nth element of the list-of-arguments. It is an error to specify a value for n equal to or greater than the length of list-of-arguments. Note the + arguments are ignored and will not be returned for any value of n. The double dash, if present, is considered and will be returned for some value of n.

• command-line-arguments returns the list list-of-arguments. Note the + arguments are ignored and thus not included, while the double dash, if present, is included.

• command-line-argument-count returns the length of the list list-of-arguments. Note the + arguments are ignored and thus not counted, while the double dash is counted as an argument.

Examples when :application is nil

;;  Lisp was started on UNIX with the command line
;;  (we assume the mlisp executable is in a directory
;;  included in the PATH environment variable):
% mlisp -qq -- init 5 safe

(sys:command-line-argument-count :application nil)
  RETURNS 6
(sys:command-line-arguments :application nil)
  RETURNS ("mlisp" "-qq" "--" "init" "5" "safe")
;;  or perhaps (/usr/local/acl70/mlisp -qq -- init 5 safe)
;;  assuming mlisp is in /usr/local/acl70/: the directory
;;  may or may not be included.
(sys:command-line-argument 0)
  RETURNS "mlisp"  ;; or perhaps "/usr/local/acl70/mlisp"
(sys:command-line-argument 1)
  RETURNS "-qq"
(sys:command-line-argument 2)
  RETURNS "--"
(sys:command-line-argument 3)
  RETURNS "init"
(sys:command-line-argument 4)
  RETURNS "5"
(sys:command-line-argument 5)
  RETURNS "safe"
(sys:command-line-argument 6)

  ERROR    ;;  the first argument to sys:command-line-argument
           ;;  must be less than the number of arguments
           ;;  as returned by sys:command-line-argument-count

;;  Lisp was started on WINDOWS with the command line
% mlisp.exe +co -qq -- init 5 safe
;;  The values returned by the command-line argument functions are the
;;  same as on UNIX (except "mlisp.exe" or 
;;  "C:\\Program Files\\acl70\\mlisp.exe" replaces "mlisp" or 
;;  "/usr/local/acl70/mlisp". The command-line argument functions
;;  always ignore the + arguments.

Anomolies when :application is true

If the Allegro CL image was created with dumplisp (or build-lisp-image or generate-application) with the ignore-command-line-arguments argument true (the default is nil), then arguments are not processed by Allegro CL when it starts up and all arguments (regardless of whether a `--' appears on the command line) are handled by these functions and the value of the application keyword argument has no effect.

Anomolies when :application is nil

The system may tack on arguments in addition to those you specified. In particular, when using the Emacs-Lisp interface, the arguments -e (start-emacs-lisp-interface t) may be added (to start in connection between Lisp and Emacs). Do not be surprised is you see these additional arguments. The system never adds arguments after a -- (double dash).

The path of the executable

Note that the zeroth argument is the name of the executable as entered in the command line, with or without path information. That is, the 0th argument may be, say, "mlisp" (without path information) or may be, say, "/usr/local/acl70/mlisp" (with path information). If path information is not provided and you need it, evaluating

(translate-logical-pathname (concatenate 'string "sys:"
(sys:command-line-argument 0)))

will typically work. (But that form signals an error when path information is provided.)

Uses of command-line arguments

You may use this information as you see fit. One possible use, for example, is to have some function defined and run (perhaps in the initialization file .clinit.cl) which takes some action (such as loading specific files) based on the values of the arguments. Recall again that + arguments are ignored and so their presence or absence cannot be used to affect behavior once Lisp has started.

This function and its relatives, command-line-argument and command-line-argument-count, provide information about the command line that invoked Allegro CL. Their behavior depends on the value of the application keyword argument. If the value of that argument is true (the default is t), only the executable name and arguments appearing after the first occurrence of --, if there is one, in the command line are considered. If the value of application is nil, all arguments except those beginning with +, but including the --, if there is one, are included.

As said above, + arguments, which are Windows specific and affect how the executable starts up on Windows, are discarded and not included in the information returned by this or any of the command-line argument functions.

See with-command-line-arguments, which is a macro that can be used to process command-line arguments. See Command line arguments in startup.html for a list of command-line arguments accepted by Allegro CL.

command-line-argument returns the nth item on the command line. The item numbering is zero-based. If the value of the application keyword argument is true (the default), only the image name and the arguments after (and not including) the first occurrence of -- in the command line are counted. If the value of application is nil, all arguments including the -- are included. The executable name is argument 0. The argument is returned as a string.

command-line-arguments returns a list of strings indicating the arguments appearing on the command line used to start Allegro CL. If the value of the application keyword argument is true (the default), only the image name and the arguments appearing after the first occurrence of -- are included. If the value of application is nil, all arguments including the --, if there is one, are included.

command-line-argument-count returns the number of arguments on the Allegro CL command line. If the value of the application keyword argument is true (the default), only the image name and the arguments appearing after the first occurrence of --, if there is one, are counted. If the value of application is nil, all arguments, including the --, if there is one, are counted.

If the Allegro CL image was created with dumplisp (or build-lisp-image or generate-application) with the ignore-command-line-arguments argument true (the default is nil), then no argument is processed by Allegro CL when it starts up and all arguments (regardless of whether a -- appears on the command line) are handled by these functions and the value of the application keyword argument has no effect.

The purpose of these functions is to allow you to customize the running of Lisp when the image is invoked. As a simple example, suppose you invoke Lisp (the example is on Windows) as follows:

mlisp.exe -qq -- foo -batch bar 

Here, mlisp.exe is the name of the Allegro CL executable. No -I argument is specified (but one is inserted by the system) so the image is mlisp.dxl in the same directory as mlisp.exe. Note first that Lisp will not run in batch mode since the -batch appears after --. However, no initialization file will be read since the -qq argument appears before the --.

Here is what the various command line functions return given that command line:

(sys:command-line-arguments :application nil)
[returns] ("C:\\Program Files\\acl70\\mlisp.exe" "-I" 
"C:\\Program Files\\acl70\\mlisp.dxl"
"-qq" "--"
"foo" "-batch" "bar")
(sys:command-line-argument 0) 
[returns] "C:\\Program Files\\acl70\\mlisp.exe"
(sys:command-line-argument 1)
[returns] "foo"
(sys:command-line-argument 3 :application nil)
[returns] "-qq"
(sys:command-line-arguments)
[returns] ("C:\\Program Files\\acl70\\mlisp.exe" 
"foo" "-batch" "bar")
(sys:command-line-argument-count) 
[returns] 4
(sys:command-line-argument-count :application nil) 
[returns] 8

Note that the zeroth argument is the name of the executable as entered in the command line, with or without (in the example, with) path information. If the path information is not provided and you need it, evaluating

(translate-logical-pathname (concatenate 'string "sys:"
(sys:command-line-argument 0)))

will typically work.

You may use this information as you see fit. One possible use, for example, is to have some function defined and run (perhaps in the initialization file .clinit.cl) which takes some action (such as loading specific files) based on the values of the arguments.

constant-value

Function, system package

Arguments: form &optional environment

Returns form if form does not represent a constant a la constantp (with identical arguments), otherwise returns the value that form should constantly represent. Macroexpansions are performed. If environment is given, all lookups are done per the given environment, otherwise constant-ness is determined by the global environment(s).

See environments.html for more information on environments.

copy-file

Function, system package

Arguments: from to &key link overwrite preserve-symbolic-links preserve-time remove-destination force verbose

The :osi module (see Operating System Interface Functionality in os-interface.html) has additional functionality relating to file handling. See particularly OSI file handling functionality in that document. The symbol sys:copy-file is exported from the new excl.osi package (as well as from the system package).

Copies from to to. If overwrite is non-nil, to will be overwritten if it exists.

If remove-destination is specified true, to is removed (if it exists) before the copy is attempted. (You might want to specify this if you have write permission for the directory but not for the file.) If force is specified true, if an error occurs opening to for overwriting, to is removed and the operation is retried. :force true essentially means overwrite if you can, remove if you must (when to exists). force and overwrite are effectively ignored when remove-destination is specified true.

It is an error to specify an existing file as the value of to unless at least one of the overwrite, remove-destination, or force keyword arguments is specified true.

The link argument only has meaning on UNIX platforms (symbolic and hard links are not supported on Windows) so it is ignored on Windows. On UNIX, it can have the following values:

• t: if link is t, then perform the copy by creating a hard link if the source and destination are on the same filesystem and by creating a symbolic link if they are on different filesystems.

• :hard: if link is :hard, then perform the copy by creating a hard link.

• nil (the default): if link is nil, then just copy the file.

In earlier releases, the link argument was called link-ok. link-ok is still accepted and its value is made the value of link (it is an error to supply values for both link and link-ok). Use of link-ok is deprecated.

If preserve-symbolic-links is true, copy a symbolic link by making a symbolic link, otherwise copy normally--link is ignored if from is a symbolic link. Because symbolic links are not supported on Windows, this argument has meaning on UNIX only. preserve-symbolic-links defaults to nil.

If preserve-time is true, then the time on to is set to be the same as from. preserve-time defaults to t.

Either of both from and to can be streams (in which case irrelevant keyword arguments are ignored). This allows for copying bytes from one stream to another or a stream to or from a file.

If the verbose argument is specified true, infomation will be printed about the copying operation.

In earlier releases, copy-file accepted an element-type keyword argument to specify the element type of the streams opened to the file to be copied and the new file. That argument was not in fact useful and has been removed. A warning is signaled if it is specified.

See Filesystem manipulation functions in os-interface.html for information on file and directory information and manipulation functions in Allegro CL.

declaration-information

Function, system package

Arguments: symbol &optional env

This function returns information about declarations named by symbol in the environment specified by env. The null lexical environment is used when env is unspecified or nil.

declaration-information only returns declarations that are not usually associated with a variable or function namespace. If the name or value of a variable or function has been given a declaration, then that declaration will not be retrieved by declaration-information, it will instead be retrieved by the appropriate variable-information or function-information call, and will be returned as an element of the third value returned.

When symbol is optimize, declaration-information returns a list whose elements are of the form (quality value) -- i.e. (space 2) or (speed 3) -- where the quality is one of the optimization qualities space, size, speed, compilation-speed, and debug, and the value is 0, 1, 2, or 3. This list is the single value returned. This list must not be modified.

When symbol is declaration, declaration-information returns a list whose elements are declaration names that have been proclaimed valid through the use of declaration proclamations. This list is the single value returned. This list must not be modified.

define-declaration

Macro, system package

Arguments: namespec lambda-list prop kind &optional def

This macro defines a handler for the declaration named by namespec. augment-environment uses the information provided by this macro when processing declarations.

The arguments are:

• namespec is either a single name, or else it is a list which allows classes of declarations (an example of this is the inline and notinline declaration, which, when returned from a function-information call is either the value (inline inline) or (inline notinline). This classification allows proper shadowing of declarations as they are propagated into inward contours, so that for example a free inline declaration will shadow any other notinline declaration by virtue of its presence as the first declaration of the inline class to be found.

• lambda-list is a simple lambda list. The only lambda-list keywords recognized are &optional and &rest. The "arguments" for the declaration specifier are implied by the whole lambda list, which is useful for recasting the declaration by either extracting one or more individual declarations from the declaration specifier, or putting multiple declarations together.

• prop allows a symbol to be defined (it should not be a keyword, nor should it be exported or accessible from the user package) to use as a property indicator. This is for global declarations which will either be attached to the environment, or in the case of the null environment it will serve as a property indicator for the name globally. The value nil can be given for this argument, in which case declarations in the global environment are ignored, and augment-environment to a global environment silently ignores that declaration.

• kind is one of :variable, :function, :both, or :declare. It determines how the declaration is treated, and the first value returned from the parsing function defined by define-declaration.

• If def is given it can be either a symbol or a lambda expression of two arguments, receiving the declaration and the current environment. If def is a symbol it is taken to be the name of an already-defined function which is of the same two arguments. If def is not provided or is nil, a function is created with default actions, which assumes the declaration is to be of the form (decl name1 name2 ... nameN). If the body is specified, it must return two values, according to the definition in CLtL-2 p 213 (with the two exceptions that kind might be :both, which follows the same rules for both :variable and :function, and also if the kind is :declare, the list returned is a list of (list key value) instead of the cons that is specified there, to ease the consistency of the implementation).

See environments.html for more information on environments.

defpatch

Macro, system package

Arguments: *id version desc &key compile-feature withdrawn (defpatch-version 1) (post-loadable t)

This macro is used for its side-effects, to define the file it appears in as a patch file. Also, whether the contents of the file are actually loaded can be controlled based on the conditions and features existing within the version of Lisp compiling the patch or the version into which the patch is loaded.

At any given time during execution, those patches currently loaded are tracked and can be listed by the dribble-bug function. A useful related function is print-system-state, which takes an optional stream argument defaulting to standard-output and prints the dribble-bug information to that stream.

Whether or not the patch file contents were actually loaded, the defpatch information is recorded in the image that attempted to load it, including information, if applicable, as to why the load was not completed. See the description of load-patches for information on why a load might be aborted and what errors might occur during the loading of a patch file.

Patch files are named as follows, as described in in The Allegro CL patch naming scheme in delivery.html):

p[m][p][n].[v]

So the first letter is p, followed by

• [m], one character denoting the version of Allegro CL, followed by

• [p], one character denoting the product, followed by

• [n], three characters denoting the patch sequence number, followed by a period (.), followed by

• [v], three characters denoting the patch version.

sys:defpatch required arguments:

sys:defpatch keyword arguments:

More information on compile-feature keyword argument. This argument is designed to facilitate producing patches for different platforms. For example, suppose a patch is only applicable to :dlfcn versions of Allegro CL (those that load .so foreign files rather than .sl or .dll foreign files -- Sparc/Solaris 2 e.g.) Specifying :dlfcn as the value of compile-feature will cause compilation to proceed when compiled by a :dlfcn Allegro CL but to abort when compiled by a non-:dlfcn version. Aborting is what you want in that case, since the patch is not needed for those versions. The aborting of compilation will signal a condition which looks for a sys::abort-patch-compiling restart. If that restart is not present, an error is signaled (and the programmer must intervene to do something). More typically, compilation of patch files are done in a form like the following:

(dolist (x patch-files)  (restart-case
  (compile-file x)  (sys::abort-patch-compiling
  (patch) ;; Actions of your choice, e.g
  printing a message like:  (format
  t "Aborted patch file ~s, featurep returned nil" x))))

Compilation of the remaining patch files will continue and all relevant patch files will be present when the dolist form completes.

Patches for applications are described in Patching your application after delivery. Patches for Allegro CL products are described in Patches and updates in index.html.

ensure-portable-walking-environment

Function, system package

Arguments: environment

This function returns an environment suitable for portable code walkers to use entirely within the ANSI Specification of Common Lisp.

Normally a :compiler environment will expand compiler-macros (though a :compilation environment will not do so, as per spec). The compiler does macroexpansions with a :compiler environment, so that the macroexpansion process can be a part of the compilation process, and so that compiler-savvy compiler-macros and macros can gain insights into the compiler's inner workings. Code walkers are themselves macros or compiler-macros at their top level (since it is only these two entities that can get access to environments), so these macros/compiler-macros must each make the decision as to whether they will handle a walk portably or non-portably. A non-portable walk will include possible compiler-macro expansions and stops at special forms (see the documentation for the Allegro CL implementation of macroexpand and macroexpand-1 in cl:macroexpand and cl:macroexpand-1 in implementation.html). But if the walker wants to operate portably, without expansion of compiler-macros and with macroexpansion of special forms, then this function must be called and the result used as the environment for the walk.

This function will always return an environment. If the environment argument is nil, then a new, empty :interpreter environment will be returned. If the environment argument is a :compiler environment, then it will be augmented once with no new information, and the result will be changed to a :compilation environment and returned. All other environment arguments wil be returned unchanged.

See environments.html for more information on environments.

flush-codevectors

Function, system package

Arguments: &optional file verbose

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.

funcall-after-idle-timeout

Function, system package

Arguments: seconds function &rest args

This function should not be used in an SMP Lisp, as idle time is ill-defined in such images.

This function causes function to be applied to args if the system is ever completely idle for seconds. The action is taken only once. The returned value is a function of zero args that will cancel the idle hook.

function-information

Function, system package

Arguments: fspec &optional env all-declarations special-operators

This function returns information about the operator named by fspec when it is found in the functional position in the environment env. env may be an environment object or nil, indicating the null lexical environment. all-declarations is a boolean which requests a building of all declarations out of previous declarations of the same name, including the global environment. This switch is added so that the interpreter, which almost never looks at declarations, doesn't need to cons as much for no good reason. special-operaor is a boolean which controls whether :special-operator is returned for the first value when fspec names both a macro and a special-operator in certain cases (see below for more information). The default is nil, and :macro is returned in that case.

Four values are returned.

The first value returned is one of the following values, providing information about the type of definition or binding of fspec:

• nil: there is no binding or definition of fspec.

• :function: fspec refers to a function.

• :macro: fspec refers to a macro.

• :compiler-macro: fspec has a compiler macro associated with it. (If the symbol names both a macro and a compiler macro, see below for details.)

• :special-operator: fspec refers to a special operator. (If fspec refers to both a macro and a special operator, see below for details.)

The second returned value is a locative cons (a cons whose car and/or cdr may be used as a mutable value). This locative cons is used to provide the local binding of the value (for :evaluation environments) or local compiler structure information (for the compiler/compilation environments). To reduce consing at critical points in the environments implementation, there are a few exceptions where the second value is not a cons representing a locative:

• When the first return value from function-information is :special-operator, then the second value is nil, because the value of a special operator is opaque to the programmer (companion-macros are mandated by the spec in order for a non-compiler to "see" into special-operators, and so a functional value does not make sense).

• When the first return value from function-information is either :function or :macro, and the definition is in fact dynamic and thus accessible via fdefinition or macro-function, respectively, then the second returned value is nil, unless the third argument to function-information is non-nil, indicating that consing definitions and declarations is ok.

The third returned value is an alist containing information declarations that apply to the bindings of symbol. The keys are symbols that name declaration specifiers (such as dynamic-extent, inline, ftype, etc.) and the value (that is, the cadr of the alist component) is the associated value.

The fourth returned value is a boolean indicating whether definition is local or global: the value is true if the binding is local, nil if not. (In CLtL-2, this local/global boolean is the second returned value.)

If one considers a namespace to be a one-to-one mapping of a name to a binding, then the function namespace is not a pure namespace in Common Lisp; consider that a name can simultaneously name both a special-operator and either a macro or a compiler-macro, or it can name a macro or function and a compiler-macro simultaneously. Of course, any lexical definition created for that name (such as an flet, labels, or macrolet) will shadow all of these potential combinations, but if no such shadowing occurs, there is a necessity for function-information to be able to make the distinctions between the various combinations of definition that are possible.

If the fourth argument (the special-operators argument) to function-information is true, and if the name is a non-shadowed special-operator, then :special-operator is returned, even if it has a macro or a compiler-macro definition as well. If the argument is nil, then for a special-operator which also has a compiler-macro, :compiler-macro is returned only for :compiler or :compilation environments (otherwise :special-operator is returned), and for a special-operator which also has a macro definition, :macro is returned only for :interpreter and :evaluation environments (otherwise :special-operator is returned).

We do not define what occurs if a special-operator has both a macro and a compiler-macro definition, beause Allegro CL has none of these situations. There should be a normalized behavior for such situation.

If a name defines a compiler-macro as well as either a macro or a function, then which is returned depends on the environment kind: a :compiler or :compilation environment will cause the :compiler-macro to be returned, and an :interpreter or an :evaluation environment will result in the :function or :macro being returned.

See environments.html for more information on environments.

gc-parameter

Function, system package

Arguments: gc-parameter

This function returns the current value of the parameter gc-parameter. Where appropriate, it can be used with setf to set the parameter value:

cg-user(16): (sys:gc-parameter :free-percent-new)
25
cg-user(17): (setf (sys:gc-parameter :free-percent-new) 30)
30
cg-user(18): (sys:gc-parameter :free-percent-new)
30

The function sys:gc-switch performs the same role for switches. The function sys:gc-parameters prints all switches and parameters along with their current values.

See gc.html for more information on the garbage collector. The section System parameters and switches in that document describes all parameters and switches.

gc-parameters

Function, system package

Arguments:

This function prints all the gc parameters and switches and their current values:

cg-user(5): (sys:gc-parameters)
gc-monitor [version 100] (multithreaded global gc)
:helper-threads-requested 4 (limit is 8)
:packets-in-use-limit 16,777,215    :minimum-recovery-bytes 8,192
:generation-spread 4     :current-generation 5    :tenure-limit 1

:free-bytes-new-other 131,072       :free-percent-new 25
:free-bytes-new-pages 262,144       :expansion-free-percent-new (3329
                                                                 2050
                                                                 3332)
:free-bytes-old-code 35             :expansion-free-percent-old 35
:quantum 32                         :open-old-area-fence 0

(switch :auto-step) t               (switch :use-remap) t
(switch :hook-after-gc) t           (switch :clip-new) nil
(switch :gc-old-before-expand) nil  (switch :next-gc-is-global) nil
(switch :print) nil                 (switch :stats) t
(switch :verbose) nil               (switch :mark-trace) nil
(switch :dump-on-error) nil  (switch :clean-temp-code-vectors) t               

The functions sys:gc-parameter and sys:gc-switch return the value of specific parameters and switches (respectively) and for settable values, can be used with setf to set them.

See gc.html for more information on the garbage collector. The section System parameters and switches in that document describes all parameters and switches.

gc-switch

Function, system package

Arguments: gc-switch

This function returns the current value of the switch gc-switch. Where appropriate, it can be used with setf to set the switch value:

cg-user(11): (sys:gc-switch :print)
nil
cg-user(12): (setf (sys:gc-switch :print) t)
t
cg-user(13): (sys:gc-switch :print)
t

The function sys:gc-parameter performs the same role for parameters. The function sys:gc-parameters prints all switches and parameters along with their current values.

See gc.html for more information on the garbage collector. The section System parameters and switches in that document describes all parameters and switches.

getenv

Function, system package

Arguments: string

The :osi module, has additional functionality relating to environment variables, including setenv and unsetenv. See OSI miscellaneous low-level functionality in os-interface.html. The symbol system:getenv is exported from the new excl.osi package (as well as from the system package).

This function returns the value (a string) of an environment variable (such as TERM, SHELL, and DISPLAY). If the environment variable is not defined, nil is returned. This function may be used with setf to set an environment variable. For example:

;; The current values of the environment variable on your system may, 
;; of course, be different from what appears in this example. 
user(2): (sys:getenv "SHELL")
"/bin/csh" 
user(3): (setf (sys:getenv "SHELL") "/bin/sh") 
"/bin/sh" 
user(4): (sys:getenv "SHELL") 
"/bin/sh"

Warning: When you use setf with sys:getenv to set an environment variable, the string specifying the new value is stored in malloc'ed space and that space cannot be freed (in any practical way). This creates a small memory leak in the system, but it should only be significant if you set many, many environment variables.

Note that there is no pre-defined, programmatic way to unset an environment variable from within Lisp. It is an error to setf sys:getenv to anything other than a string and the effect of doing so is undefined (an error is typically not signaled but the behavior is likely not what is intended). Specifically.

(setf (sys:getenv "VAR") nil) 

does not unset VAR in the environment.

See os-interface.html.

global-symbol-value

Function, system package

Arguments: sym

This function returns two values. The first is the global value for the special variable named by the symbol sym, ignoring any bindings on the current stack-group (unix) or thread (windows) and the second is t if the variable has a value (in the sense of boundp). Otherwise the first value will be nil and the second will be the symbol :unbound. (Returning two values allows distinguishing between bound with value nil and unbound. Note that this function does not error if the symbol has no global value.)

This function may be setf. This is not a normal thing to do (except with setq-default usually as part of initialization) and is intended only for obscure system-hacking purposes. This function is intended for use by debuggers and other systems and is not appropriate for normal programming.

The macro setq-default sets the global-symbol-value.

gsgc-parameter

Function, system package

Arguments: name

This function is obsolete and should not be used. It is replaced by sys:gc-parameter.

gsgc-parameters

Function, system package

Arguments:

This function is obsolete and should not be used. It is replaced by sys:gc-parameters.

gsgc-step-generation

Function, system package

Arguments:

Calling this function, which returns the new value of the :current-generation parameter, increases the current generation number and, if necessary, the value of :tenure-limit as well. Since tenuring only occurs at scavenge time and calling this function does not cause a scavenge, objects are not tenured simply by a call to this function. Users should be sure that this function is called regularly, either by having the value of the switch :auto-step be true, or by explicitly calling this function.

See System parameters and switches in gc.html for more information on garbage collection and gsgc switches.

gsgc-switch

Function, system package

Arguments: name

This function is obsolete and should not be used. It is replaced by sys:gc-switch.

initialize-sigio-handling

Function, system package

Arguments:

Sigio handling is not supported on Windows.

Initializes sigio handling. Note that SIGIO handlers will only work if the sigio interface is available, as indicated by the return value of the function sigio-supported-p. See set-sigio-handler.

Note that only input signals are available to Allegro CL. (Output signals are filtered out.)

lispval-storage-type

Function, system package

Arguments: object &optional type

Returns information about storage classifications or of the storage-classification of an object.

If type is not given, then the object's storage attributes are examined, and the most specific description of these attributes is returned in the form of a keyword. The possible keywords are:

1. :immediate, which means the object is not referenced with a pointer (fixnums, e.g.)

2. :static, which means the object is stored in an area which is not garbage collected.

3. :tenured, which means the object is stored in oldspace (also called tenured space).

4. :new, which means the object is stored in newspace but will, if it survives, eventually be tenured.

5. :panified, which means that the object is stored in newspace and will never be tenured. (The name comes from Peter Pan, who never grew old.) See the note just below.

6. :weak, which means the object is in newspace, will not be tenured, and is a weak vector.

7. :finalized, which means that the object is a finalization.

8. :weak-key-non-panified, which means that the object is a weak-key vector in newspace, but may be tenured (after which it will no longer be weak).

9. :weak-key-panified, which means that the object is a weak-key vector in newspace which will not be tenured.

10. :stack-allocated, which means the object resides on a stack somewhere. Note that on a non-os-threads Lisp the value may be seen as :stack-allocated even if it is outside of the stack it resides and should have been called :static. An object for which lispval-storage-type returns :stack-allocated will still cause sys:pointer-storage-type to return :static when passed as an argument to it.

11. :pure, which means the object is in the pll (pure-lisp-library) space, and is thus read-only/shared. A :pure object will still cause sys:pointer-storage-type to return :static when passed as an argument to it. See pll-file (and links from there) and also Getting information on memory management using cl:room in gc.html for more information on pure space.

Note on :panified objects: Only system-created objects can have storage type :panified but sometimes these objects are created as a consequnce of user action. The key vector of a weak-keys hashtable is typically a :panified object, though this can be controlled. See cl:make-hash-table in implementation.html.

type can be :all or one of the storage types keywords in the list above.

If type is :all, a list of possible storage types is returned (and the object argument is ignored). Thus, when type is :all, the call is for information about the current implementation of lispval-storage-type, which may be modified in a patch subsequent to the release.

If type is a storage type, lispval-storage-type returns true or nil as the storage type of object matches or does not match type. Here match means is of that storage type', not is eq to the value returned by lispval-storage-type when type is not specified'. If lispval-storage-type returns :weak when type is not specified, it will return true when type is :weak and when type is :new.

See gc.html for a discussion of where Lisp objects are stored. lispval-storage-type replaces the now deprecated pointer-storage-type.

Example

;; A 1-d static array has storage type :STATIC
;; (2-d and higher dimension
;; static arrays have headers that are Lisp objects so they will have
;; storage type :NEW or :TENURED, but their data vectors
;; (available via INSPECT) 
;; will have storage type :STATIC):
CL-USER(24): (sys:lispval-storage-type 
               (make-array 3 :allocation :static
                           :element-type 'fixnum :initial-element 2))
:STATIC
;; Fixnums are immediates:
CL-USER(25): (sys:lispval-storage-type 22)
:IMMEDIATE
;; Most Lisp objects start in new space:
CL-USER(26): (setq a (cons 1 2))
(1 . 2)
CL-USER(27): (sys:lispval-storage-type a)
:NEW
;; And after surviving several scavenges, they typically
;; move to oldspace:
CL-USER(28): (gc) (gc) (gc) (gc) (gc)
CL-USER(29): (sys:lispval-storage-type a)
:TENURED

;;  Here we show the use of the TYPE argument:
CL-USER(30): (setq a (make-array 10 :weak t))
#(NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)
CL-USER(31): (sys:lispval-storage-type a)
:WEAK
CL-USER(32): (sys:lispval-storage-type a :new)
T
CL-USER(5): (sys:lispval-storage-type a :weak)
T
CL-USER(6): 

load-patches

Function, system package

Arguments: &key update-directory product patch-file-filter patch-file-sorter

This function loads patch files from update-directory and does useful checks on the consistency of the patch files, described below.

The arguments are:

There is also a obsolete libfasl keyword argument which is accepted for backward compatibility but ignored.

There should be an update/ subdirectory to your application directory (or wherever sys: translates to in your application). Allegro CL patches will be loaded from that directory. You can make patches for your own applications if desired. See Patching your application after delivery in delivery.html.

As patches are loaded, information on them is recorded in Lisp. This information includes the patch id, the version and the description (the three required arguments in the defpatch form at the top of the patch file). Information about loaded patches is placed in the list that is the value of *patches*.

The loading of the body of the patch file (everything after the defpatch form) is aborted if the defpatch version specified in the defpatch form is out-of-date (this should be very rare) or if the patch is marked not-post-loadable (the post-loadable argument to defpatch is nil), or withdrawn (the withdrawn argument is true). Loading will also be aborted if featurep, applied to the value of the feature argument in the defpatch form, returns nil. If loading is aborted, no error is signaled (because the condition signaled is caught by the appropriate restart in sys:load-patches) and subsequent patch files are loaded (but information on why the loading was aborted is saved).

As each patch file is loaded, its id is compared to already loaded (and not aborted) patches. If any patch with the same id is seen to already be loaded, the conflicting patch is placed on a special list. After all patches are loaded, that list is checked, and if it is non-empty, sys:load-patches signals an error.

It is important to be clear on what we mean by two loaded patches with the same id because we have used the word load loosely up to this point. We describe just above how a patch file is loaded and its defpatch form is examined. Information in the defpatch form might cause the load to be aborted. Such patches are not loaded in the sense of this paragraph because everything after the defpatch form is ignored.

Patches for your application are described in Patching your application after delivery in delivery.html. Patches for Allegro CL products are described in Patches and updates in index.html. See also sys:update-allegro for information on automatically downloading Allegro CL patches.

make-compilation-unit-environment

Function, system package

Arguments: &optional complex

Returns an environment object suitable for compile-file or compile processing. When the compile argument is omitted or nil, the environment includes a lexical portion for use with augment-environment and the *-information functions, and a global portion for use with sys:ce-get and sys:ce-putprop, and the environment is suitable for compile-file. If compile is specified and is non-nil, then the resultant environment contains only the lexical component, making the environment suitable for compile.

See environments.html for more information on environments.

make-compile-file-environment

Function, system package

Arguments:

Use of this function is deprecated. Use the new function make-compilation-unit-environment instead. Although that function accepts one (optional) argument, calling it with no arguments replaces a call to this function with no arguments. That is, replace

(sys:make-compile-file-environment)

with

(sys:make-compilation-unit-environment)

Returns an environment object suitable for compile-file processing, which includes a lexical portion for use with augment-environment and the *-information functions, and a global portion for use with sys:ce-get and sys:ce-putprop.

See environments.html for more information on environments.

make-temp-file-name

Function, system package

Arguments: &optional (prefix "temp") directory

Returns the namestring of a pathname of a non-existent file in directory. The filename will begin with prefix and additional characters added after prefix will ensure the file does not exist. prefix should be a string. The resulting filename will have no type.

The value of directory, if specified and non-nil, should be a pathname or a string coerceable to a pathname. If directory is relative, the resulting filename will have a relative directory component. That filename's existence will be tested by merging the directory with the current value of *default-pathname-defaults* and searching the resulting directory for the candidate file. The namestring of the successful candidate is returned as the file which does not exist. There is no guarantee that the result, merged with a different value of *default-pathname-defaults*, does not exist.

If directory (when merged with *default-pathname-defaults* if relative) does not exist, any candidate filename will of course not exist and the namestring of the first one tried will be returned. Users should ensure that the resulting directory component exists (with, say, ensure-directories-exist) before trying to use the resulting file.

If directory is nil or unspecified, the value returned by sys:temporary-directory is used as the directory component of the resulting file.

This function does not create the file named by the returned value (that is, probe-file applied to the filename will return nil unless something other than the current Lisp process has created it). Neither will Lisp remove the file or ensure that the file is removed when Lisp exits. This function is for use by programs to determine suitable filenames for temporary use, but the program must take responsibility for creating and later deleting the file.

Filenames returned by this function should actually be created before this function is called again with the same arguments. Subsequent calls to this function with the same arguments are not guaranteed to be different unless the files named by earlier calls to this function are in fact created. (That is, this function simply looks at the existing files in directory and returns a filename that does not name an existing file.)

This function is used internally by Allegro CL.

Examples

cg-user(14): (sys:make-temp-file-name "foo" "c:/acl10.1.64/")
"c:/acl10.1.64/fooa90201527236"

;; A relative directory path returns a relative result:
cg-user(15): (sys:make-temp-file-name "foo" "tmp/")
"tmp/fooa90201527237"

;; The directory specified need not exist.
cg-user(45): (sys:make-temp-file-name "fooxxx" "/does/not/exist/")
"/does/not/exist/fooxxxa902015272314"

;; That file cannot be used (by, say, passing it to OPEN) unless
;; PROBE-FILE applied to its directory returns true.
;; In this case it does not:

cg-user(45): (sys:make-temp-file-name "fooxxx" "/does/not/exist/")
"/does/not/exist/fooxxxa902015272314"
cg-user(46): (probe-file (directory-namestring *))
nil
cg-user(47): 

memref

Function, system package

Arguments: *object offset pos type &optional coerce

This function and the related function memref-int calculate an address in memory and performs a read from that address. This function takes an object as an argument while memref-int takes an address.

The width and style of the read depends upon the type. The possible values for the type argument are shown in a table below.

Except when the type argument is :lisp, the result is always a number, either an integer or float. The type and possible range of that number depends on the type argument. This function is setf'able. The setf function writes to the addressed memory instead of reading from it.

The object argument may be any Lisp value. If the Lisp value represents an object in the heap, the address of the object (including its tag) is used as the base address in the memory reference. If the Lisp value is an immediate value (a fixnum, a character, ...), then the actual bit representation of the Lisp value (including its tag) is used as the base address in the memory reference.

The offset and pos arguments must be fixnum values. The sum of these two arguments is added to the base address value and the result is treated as an address in memory from which data is fetched, or to which data is stored.

When the coerce argument is non-nil some checking is done in the setf form. The value to be stored is coerced to the required type.

This function provides low-level memory access in Allegro CL. However, even though the name is exported and documented, we recommend against using this function in user code. Instead, we recommend using higher-level functions, such as those linked to below. However, the function is useful in the development cycle for debugging purposes.

WARNING about setf: except when the type is :lisp, the setf function does not do any setf-protection. If it is used to store non-Lisp values into a memory location that was intended to hold a Lisp value, then a non-recoverable error is very likely to occur during the next GC.

The access-types (possible values of type) that are available are as follows:

:unsigned-byte, :signed-byte (1-byte access, 1-byte integer result)  
:unsigned-word, :signed-word (2-byte access, 2-byte integer result)  
:unsigned-long, :signed-long 
  ;; 4-byte access, 4-byte integer result in 32-bit lisps
  ;; undetermined (4-byte or 8-byte) in 64-bit lisps
:unsigned-long32 (4-byte access, 4-byte integer result)
:unsigned-long64 (8-byte access, 8-byte integer result on 64-bit
                  Lisps but 4-byte access, 4-byte integer result
                  on all others)
:fixnum (in 32-bit lisp, 4-byte access, 
         fixnum result [top bits lost on overflow]
         in 64-bit lisp, 8-byte access, 
         fixnum result [top bits lost on overflow])  
:lisp (in 32-bit lisp, 4-byte access, lisp result 
       in 64-bit lisp, 8-byte access, lisp result
       [careful, could confuse gc])  
:single-float (or single-float) (4-byte access, 4-byte single-float result)  
:double-float (or double-float) (8-byte access, 8-byte double-float result) 
:signed-natural 
:unsigned-natural
  ;; For these last two, in 32-bit lisps, these will 
  ;; construct 32-bit values, and in 64-bit lisps, it will construct 
  ;; 64-bit values
:nybble (4-bit -- half-byte -- value)

Be aware that though the access types might look similar to C types, they are not actually identical.

For more information on :signed-natural and :unsigned-natural, see 64 bit Allegro CL Implementations in implementation.html.

Programming Notes

1. The function memref is very similar to the memref-int function, but because the base address determination is significantly different the descriptions are different in several subtle but important ways.

2. In place of using memref and memref-int, operators like single-float-to-shorts, double-float-to-shorts, shorts-to-single-float, shorts-to-double-float may be used for accessing/creating floats. A foreign type can be defined (see ftype.html) to access arbitrary memory areas. See also write-vector.

3. When optimization is declared at a sufficient level, the call to memref and to the setf form, is compiled in line and is thus very efficient. Note that when the optional coerce argument is supplied, then the call is not open-coded when compiled.

4. When the coerce argument is non-nil some checking is done in the setf form. The value to be stored is coerced to the required type. This is especially useful when the argument is a float value, but of the wrong type, as in

   (setf (sys:memref-int array-address 0 0 :double-float :coerce) 1.0s0)

5. The offset and pos are equivalent and interchangeable. They are both added as byte-offsets to the base address to determine the final memory address. Usually, the offset is some constant that adjusts for the start of the data in some object being accessed.

   An offset is necessary to access Lisp objects because a Lisp object pointer contains tag bits in the low-order positions. When the pointer is treated as a machine address, the numeric value is not the address of the Lisp data object in memory. The address is normally lower than the address of the object, by a fixed amount determined by the tag bits in the pointer.

   Some of the offsets for Lisp objects are described in [Allegro directory]/misc/lisp.h in the Allegro CL distribution. In an earlier version of this documentation, it was stated that the offsets are available in Lisp itself by calling certain otherwise undocumented functions. That statement was incorrect. The offsets are not reliably available with Lisp.

6. In all 32-bit implementations, a Lisp fixnum is represented by the numeric value shifted left by 2 bits. Thus, the fixnum 1 is represented by the machine word #x00000004. When a fixnum is passed as the object argument to memref, the effective memory address is the (32-bit) word in memory indexed by the fixnum value. Thus, the fixnum 0 addresses the 0-th word at address 0, the fixnum 1 addresses the 1-th word at address 4, etc. This feature is very useful when referencing blocks of foreign storage aligned on a word boundary. The numeric address of the block is divided by 4 to obtain the fixnum word index of the block. The index is always a fixnum since all memory addresses must fit within a 32-bit machine word. The foreign type facility recognizes this interpretation of fixnums as the :aligned foreign pointer type.

7. In the 64-bit implementations, a Lisp fixnum is a numeric value shifted left by 3 bits. Thus a fixnum represents a double-word index and the above discussion must be modified accordingly.

8. One application of memref-int is to access large blocks of memory (larger than array-total-size-limit).

   For example, if the variable addr holds the foreign address of a large block of memory with a length stored in the size variable, the following loop could be used to extract bytes from the block:

   ((let ((addr/4 (ash addr -2)))
      (dotimes (i (size) (memref addr/4 i 0 :byte)))

   If the index i can rise above the fixnum limit, the address arithmetic must be performed before the call to sys:memref:

   (let ((addr/4 (ash addr -2))
     (size/4 (ash size -2)))
     (dotimes (i size/4)
   (dotimes (j 4)
     (memref (+ addr/4 i) j 0 :byte))))

   The second inner loop is needed since only the offset and pos arguments allow byte addresses to be reached.

   If the addresses in the memory block cross over into the negative fixnum range we need to break up the ranges of iteration:

   (let ((addr/4 (ash addr -2))
     (size/4 (ash size -2)))
     (if* (and (< addr/4 most-positive-fixnum)
       (<= size/4 (- most-positive-fixnum addr/4)))
       then 
       ;; this is the simple case, all addresses in the positive
       ;; fixnum range
       (dotimes (i size/4)
          (dotimes (j 4)
            (memref (+ addr/4 i) j 0 :byte))))
       elseif (< addr/4 most-positive-fixnum)
       then 
       ;; the starting address is in the positive range
       ;; but the increment will cross over eventually
       ;; do the positive range first
       (dotimes (i (- most-positive-fixnum addr/4))
          (dotimes (j 4)
            (memref (+ addr/4 i) j 0 :byte)))
       ;; then the negative range
       (dotimes (i (- size/4 (- most-positive-fixnum addr/4)))
          (dotimes (j 4)
            (memref (+ most-negative-fixnum i) j 0 :byte)))
       else  
       ;; starting address is in the negative fixnum range
       ;; we create a negative fixnum that represents the word index
       (setq addr/4 (+ most-negative-fixnum (- addr/4 most-positive-fixnum)))
       (dotimes (i size/4)
          (dotimes (j 4)
        (memref (+ addr/4 i) j 0 :byte)))

memref-int

Function, system package

Arguments: address offset pos type &optional coerce

This function and the related function memref calculate an address in memory and performs a read from that address. This function takes an address as an argument while memref takes a Lisp object.

The width and style of the read depends upon the type. The possible values for the type argument are shown in a table below.

Except when the type argument is :lisp, the result is always a number, either an integer or float. The type and possible range of that number depends on the type argument. This function is setf'able. The setf function writes to the addressed memory instead of reading from it.

The address argument must be an integer and the offset and pos arguments must be fixnum values. The sum of the three arguments is treated as an address in memory from which data is fetched, or to which data is stored.

When the coerce argument is non-nil some checking is done in the setf form. The value to be stored is coerced to the required type.

This function provides low-level memory access in Allegro CL. However, even though the name is exported and documented, we recommend against using this function in user code. Instead, we recommend using higher-level functions, such as those linked to below. However, the function is useful in the development cycle for debugging purposes.

WARNING about setf: except when the type is :lisp, the setf function does not do any setf-protection. If it is used to store non-Lisp values into a memory location that was intended to hold a Lisp value, then a non-recoverable error is very likely to occur during the next GC.

The access-types (possible values of type) that are available are as follows:

:unsigned-byte, :signed-byte (1-byte access, 1-byte integer result)  
:unsigned-word, :signed-word (2-byte access, 2-byte integer result)  
:unsigned-long, :signed-long 
  ;; 4-byte access, 4-byte integer result in 32-bit lisps
  ;; undetermined (4-byte or 8-byte) in 64-bit lisps
:unsigned-long32 (4-byte access, 4-byte integer result)
:unsigned-long64 (8-byte access, 8-byte integer result on 64-bit
                  Lisps but 4-byte access, 4-byte integer result
                  on all others)
:fixnum (4-byte access, fixnum result [top bits lost on overflow])  
:lisp (4-byte access, lisp result [careful, could confuse gc])  
:single-float (or single-float) (4-byte access, 4-byte single-float result)  
:double-float (or double-float) (8-byte access, 8-byte double-float result) 
:signed-natural 
:unsigned-natural
  ;; For these last two, in 32-bit lisps, these will 
  ;; construct 32-bit values, and in 64-bit lisps, it will construct 
  ;; 64-bit values
:nybble (4-bit -- half-byte -- value)

Be aware that though the access types might look similar to C types, they are not actually identical.

For more information on :signed-natural and :unsigned-natural, see 64 bit Allegro CL Implementations in implementation.html.

Programming Notes

1. The function memref-int is very similar to the memref function, but because the base address determination is significantly different the descriptions are different in several subtle but important ways.

2. In place of using memref-int and memref, operators like single-float-to-shorts, double-float-to-shorts, shorts-to-single-float, shorts-to-double-float may be used for accessing/creating floats. A foreign type can be defined (see ftype.html) to access arbitrary memory areas. See also write-vector.

3. When optimization is declared at a sufficient level, the call to memref-int and to its setf form, is compiled in line and is thus very efficient. Note that when the optional coerce argument is supplied, then the call is not open-coded when compiled.

4. When the coerce argument is non-nil some checking is done in the setf form. The value to be stored is coerced to the required type. This is especially useful when the argument is a float value, but of the wrong type, as in

(setf (sys:memref-int array-address 0 0 :double-float :coerce) 1.0s0)

5. The offset and pos arguments are equivalent and interchangeable. They are both added as byte-offsets to the base address to determine the final memory address. Usually, the offset is some constant that adjusts for the start of the data in some object being accessed. Some of the offsets for lisp objects are described in [Allegro directory]/misc/lisp.h in the Allegro CL distribution. In an earlier version of this documentation, it was stated that the offsets are available in Lisp itself by calling certain otherwise undocumented functions. That statement was incorrect. The offsets are not reliably available with Lisp.

6. One application of memref-int is to access large blocks of memory (larger than array-total-size-limit).

   For example, if the variable addr holds the foreign address of a large block of memory with a length stored in the size variable, the following loop could be used to extract bytes from the block:

   (dotimes (i size) (memref-int (+ addr i) 0 0 :byte))

   Note how the address arithmetic is performed before the call to memref-int. If the index were passed as the offset or the pos argument, it would be subject to the fixnum limitation.

   To avoid bignum boxing in this iteration, memref with a fixnum argument may be used to keep all numbers in the fixnum range. See the description of memref for a detailed analysis of this technique.

mplog

Function, system package

Arguments: code &optional data

This is a utility function for the mplog facility described in The multiprocessing logging (mplog) facility in miscellaneous.html. See description of the function mplog for details.

os-wait

Function, system package

Arguments: &optional nowait pid

This function has been replaced with reap-os-subprocess, which has the same functionality. reap-os-subprocess uses keyword arguments and so gives more control over behavior. Except for the changed argument list, and the fact that reap-os-subprocess has a wait keyword argument rather than a nowait argument (and so :wait t means what a nil value of nowait meant), the description of this function and reap-os-subprocess are the same.

See os-interface.html for information on running shell programs.

pointer-storage-type

Function, system package

Arguments: object

Use of this function is deprecated. Please use lispval-storage-type instead. Calls to pointer-storage-type can be changed to a call to lispval-storage-type with the same argument (and lispval-storage-type also accepts a second, optional argument). Thus

(sys:pointer-storage-type object)

can be changed to

(sys:lispval-storage-type object)

Returns a keyword denoting where object is stored. The possible return values are:

1. :immediate, which means the object is not referenced with a pointer (fixnums, e.g.)

2. :static, which means the object is stored in an area which is not garbage collected.

3. :tenured, which means the object is stored in oldspace (also called tenured space).

4. :new, which means the object is stored in newspace but will, if it survives, eventually be tenured.

5. :pan, which means that the object is stored in newspace and will never be tenured. (The name comes from Peter Pan, who never grew old.) See the note just below. (Note that lispval-storage-type returns the keyword :panified rather than :pan.)

Note on :pan objects: Only system-created objects can have storage type :pan but sometimes these objects are created as a consequnce of user action. The key vector of a weak-keys hashtable is typically a :pan object, though this can be controlled. See cl:make-hash-table in implementation.html.

See gc.html for a discussion of where Lisp objects are stored.

;; A 1-d static array has storage type :STATIC
;; (2-d and higher dimension
;; static arrays have headers that are Lisp objects so they will have
;; storage type :NEW or :TENURED, but their data vectors
;; (available via INSPECT) 
;; will have storage type :STATIC):
USER(24): (sys:pointer-storage-type 
             (make-array 3 :allocation :static
                         :element-type 'fixnum :initial-element 2))
:static
;; Fixnums are immediates:
USER(25): (sys:pointer-storage-type 22)
:immediate
;; Most Lisp objects start in new space:
USER(26): (setq a (cons 1 2))
(1 . 2)
USER(27): (sys:pointer-storage-type a)
:new
;; And after surviving several scavenges, move to oldspace:
USER(28): (gc) (gc) (gc) (gc) (gc)
USER(29): (sys:pointer-storage-type a)
:tenured

presto-build-lib

Function, system package

Arguments: fname

This obsolete function, keep for backward compatibility only, is a no-op (does nothing) and a warning is signaled if it is called.

presto-fasl-set

Function, system package

Arguments:

This function is obsolete and is kept for backward compatibility only. It always returns nil.

prestop

Function, system package

Arguments:

This function is obsolete, is kept for backward compatibility only and always returns nil.

processor-affinity-mask

Function, system package

Arguments:

Windows only.

The processor affinity in Windows is a number which specifies the number of processors (i.e. chips) that will be used by the running process. In Allegro CL 7.0, the best affinity is 1 and there are known problems with higher affinities. The startup code on Windows sets the affinity to 1.

This function is defined on Windows versions only. It uses a Microsoft routine which is documented as working on Windows 98/NT/2000/XP. (On Unix versions, the symbol exists but has no function definition.)

On Windows, return the current process' processor affinity mask (a non-negative integer). It does this by calling GetProcessAffinityMask(), and an error is signaled if this routine returns an error (0).

setf'ing sys:processor-affinity-mask

The setf value is the new processor affinity mask--see the Microsoft documentation on SetProcessAffinityMask(). Our startup code sets the mask to 1 (see the (internal) function start-lisp-execution defined in [Allegro directory]/src/aclstart.cl). An error is signalled if the call to SetProcessAffinityMask() fails.

purep

Function, system package

Arguments: object

Returns true if and only if the object is pure (i.e, resides in the pure-lisp-library (.pll) area), and is thus read-only and shareable. See pll-file (and links from there) and also Getting information on memory management using cl:room in gc.html for more information on pure space.

reap-os-subprocess

Function, system package

Arguments: &key (pid -1) (wait t)

This function replaces os-wait, which has the same functionality. This function has a better interface (using keyword rather than optional arguments).

If a process is started by the run-shell-command with the wait keyword argument to that function nil, then the process will remain in the system after it completes until either Lisp exits or Lisp executes reap-os-subprocess to inquire about the exit status. To prevent the system becoming clogged with processes, a program that spawns a number of processes with :wait nil must be sure to call reap-os-subprocess after each process finishes.

The arguments, as described below, specify what reap-os-subprocess does and what processes it looks for but the function always returns three values:

1. The exit status of the reaped process or nil, if no process was reaped. The cases when no process is reaped are described below (basically, there are not suitable processes to be reaped).

2. The pid of the reaped process, or, when no process was reaped, the argument pid in some cases and nil in other cases. When a process is reaped, this second returned value is its process id. When there are suitable processes running but none to reap, and the wait keyword argument is nil, the pid argument is returned as the second value. When there are no suitable processes running or suitable to reap, the second returned value is nil. (The first returned value tells you whether or not a process was reaped. If the first returned value is nil, no process was reaped regardless of the second returned value.)

3. On UNIX, the number of the signal that caused the reaped process to exit, and nil if no process was reaped, and always nil on Windows. On UNIX/Linux platforms, it allows you to ensure the process exited normally. A status of 0 alone does not guarantee that: you must also examine the signal number. On Windows, that information is not available and nil is always returned as the third value.

Exactly what reap-os-subprocess does depends on the status of spawned processes and the keyword arguments. The pid argument controls what processes might be considered by reap-os-subprocess. If pid is -1 (the default), all processes are considered. If pid is 0, only processes in the same process group as the executing Lisp image are considered. If pid is a positive integer, only the process with that process id is considered. In the rest of this description, processes means `processes considered by reap-os-subprocess'. See the Unix system documentation of the waitpid() system call (you can usually see this by typing "man waitpid" at a Unix prompt).

If there are any processes started by run-shell-command with the argument :wait nil which have exited but for which reap-os-subprocess has not been run, one of them is selected by the operating system and is reaped, with reap-os-subprocess returning three values: (1) the exit status of the reaped process; (2) process id of the reaped process, and (3) the number of the signal that caused the reaped process to exit on UNIX/Linux platforms, and nil on Windows.

If there are no such processes which have exited but there are processes which are still running, then the behavior of reap-os-subprocess depends on the wait keyword argument. If it is t (the default), sys:reap-os-subprocess will wait (disabling multiprocessing, if necessary) until one of the running processes exits. Then reap-os-subprocess returns that process's status; id; and the relevant signal number on UNIX/Linux and nil on Windows.

If wait is nil (the default is t), reap-os-subprocess will immediately return three values: nil, nil, and nil if there are no processes to clean up; a status, pid, and signal number or nil if the process with number pid is cleaned up; nil, the pid argument to reap-os-subprocess, and nil if processes are still running and none has yet exited.

If there are no running processes, reap-os-subprocess returns immediately with the three values nil, nil, nil.

This function simply calls the Unix system function waitpid with the pid and nohang flags. Its behavior is determined by the behavior of that function.

Here are some examples of return values:

1. nil nil nil: there are no processes, running or not, suitable to reap (based on the value of the pid argument). The wait keyword argument can be true or nil.

2. nil -1 nil: there are processes that are suitable to reap but they are all still running, so none reaped; pid was -1 (the default, so unspecified or specified -1) and it is returned as the second value, as specified when there are suitable processes but none ready to reap. wait must be nil.

3. nil 0 nil: same as 2 (processes suitable to reap but all still running). pid was specified as 0 (meaning only look for processes in the same group as the Lisp process), so 0 is the second returned value. wait must be nil.

4. nil 12345 nil: as in 2 and 3, there is a processes suitable to reap (the process with pid 12345) but it is still running. pid was specified as 12345 (meaning consider the process with that pid, if it exists), so 12345 is the second returned value. wait must be nil.

5. 0 12345 nil: process with pid 12345 reaped, it exited with status 0, no signal caused it to exit (or Lisp is on Windows). The wait keyword argument can be true or nil.

6. 0 12345 9: process with pid 12345 reaped, it exited with status 0, signal 9 caused it to exit (and Lisp is not on Windows). The wait keyword argument can be true or nil.

A note on the order of execution when reading from a program to be reaped in a non-multiprocessing environment

Code written similar to the following skeleton of code may hang:

(multiple-value-bind (shell-stream error-stream process)
    (excl:run-shell-command cmd
       :input :stream :output :stream :error :stream)

  (when process
    (loop (when (sys:reap-os-subprocesses :pid process :wait nil)
         (return))))

  ;; now read from shell-stream and then close the streams

  )

In the code sample, the process is reaped prior to reading the process output. While this often works, because many programs don't bother to wait for all of their writes to complete before exiting, it may cause hanging if the pipe to which the data is sent fills up and thus not all data can be written until some reading is done, or the child program waits until each input has been read before writing more data. Some operating systems will cause select() to not return ready status on the output descriptor if any data at all is in that pipe, regardless of whether a call to write() would have succeeded.

The correct outline for the code is:

(multiple-value-bind (shell-stream error-stream process)
    (excl:run-shell-command cmd
       :input :stream :output :stream :error :stream)

  ;; do all the reading from shell-stream

  (when process
    (loop (when (sys:reap-os-subprocesses :pid process :wait nil)
         (return))))

  ;;  close the streams  
)

When you are using multiprocessing, you can use multiprocessing tools such as process-wait to ensure that no hanging occurs.

See os-interface.html for information on running shell programs.

record-code-vectors

Macro, system package

Arguments: (file &key verbose) &body body*

record-code-vectors combines the use of flush-codevectors and write-codevectors in a way that makes easy the recording of heap-allocated code vectors used during the evaluation of body to the file given by the file argument. Essentially, this macro calls flush-codevectors with nil as its argument, then executes body, then calls write-codevectors.

A filename must be supplied as the value of the file argument. The value of file specifies a filename to which code vectors are written by write-codevectors.
(flush-codevectors is called with nil as its argument so the initial flushing of code vectors is to an anonymous file.)

If the verbose argument is specified true, information about the process is printed.

The file written by this macro can be used with the program cvdcvt to create pll files. See Creating and using pll files in miscellaneous.html for information on pll files.

record-strings

Macro, system package

Arguments: file &body body

Like record-code-vectors, sys:record-strings provides a mechanism for building input to the cvdcvt program, which creates .pll files (see Creating and using pll files in miscellaneous.html). The specified file is opened for writing. It should have type .str. All strings that are seen as constants during load carried out in the body are written to this .str file. Also, any strings that are seen in pure-string calls in the body are also written to the .str file.

The body of the macro should perform some system building activity, like loading in fasl files. Any load-time execution can also make a string look like a constant by calling pure-string. Symbol-names are not automatically added to the .str file; The following paradigm should be used as one of the forms inside the body:

(do-symbols (sym (find-package :my-package)) 
(excl:maybe-purify-string (symbol-name sym)))

This reduction of automation was done purely as an optimization, to minimize the number of strings that are written to the .str file, since symbol-names show up so often in fasl files. When the symbol-name is later encountered in a fasl file being loaded into a Lisp that already has a .pll file, the pure name is automatically used.

remove-sigio-handler

Function, system package

Arguments: fd

This function is called for its side effects and its return value is not specified.

fd should be an integer identifying a Unix file descriptor. (We assume that the file descriptor has been established by a call to a Unix I/O operation such as open() and returned to Lisp via a call to a foreign function.)

Calling this function causes Unix to suppress issuing SIGIO signals on the Unix file descriptor identified by fd.

Sigio handlers are added by set-sigio-handler. See that page for an example.

Note that SIGIO handlers will only work if the sigio interface is available, as indicated by the return value of the function sigio-supported-p.

resize-areas

Function, system package

Arguments: &key old old-symbols old-code new global-gc tenure expand sift-old-areas pack-heap verbose

This function attempts to restructure the Lisp heap according to the programmer's wishes. These wishes may call for old, new, or old-code space to be increased in size (usually doable unless the operating system refuses to give up the needed extra space) or to be reduced in size (sometimes doable, but gaps -- foreign data -- above newspace or between the top oldspace and newspace may prevent resizing). Note that other gsgc parameters or requirements may also prevent resizing. This function can modify newspace, the top oldspace, and can coalesce two or more adjacent oldspace areas into one. It can also modify old-code space on systems that separate code vectors. Arguments control whether a global gc and/or tenuring of objects in newspace are forced prior to resizing.

As a general rule, you should not call this function as part of the actions of the *gc-after-hook*. Doing so carelessly can cause Lisp to fail.** See *gc-after-hook* for more discussion about this issue.

Be careful if you call resize-areas more than once: if :pack-heap is true (the default), the system will reduce the sizes of areas (old, new, old-code) which are not specified if possible and that may not be what you want. So

(resize-areas :old 8000000000)
(resize-areas :new 4000000000) ;; This signals a warning

The second call reduces the size of old space, and undoes the first call. Because calling resize-areas without a value specified for the old keyword argument reduces the available space in the old area to a minimum (which is rarely what is desired), a warning is signaled when old is not specified.

The same applies to the old-code space. If its size is increased and then a second call does not specify a size for old-code, the action of the first call can be undone.

See gc.html for more information on garbage collection and gsgc parameters.

scheduler-in-control-p

Function, system package

Arguments:

This function returns true when scheduler-like functions are taking place. This may be in a separate non-process thread in native-thread implementations. It may be running in a user process that has gone idle in virtual-thread implementations.

scheduler-running-p

Function, system package

Arguments:

Returns true if start-scheduler has been called, returns nil otherwise.

See multiprocessing.html for general information on multiprocessing in Allegro CL.

set-sigio-handler

Function, system package

Arguments: fd function

Sigio handling is not supported on Windows.

This function is used for its side effects. Its return value is not specified. Calling this function establishes function as the sigio handler for the Unix file descriptor fd. Sigio handling should be initialized before using the function with initialize-sigio-handling.

fd should be an integer identifying a Unix file descriptor. (We assume that the file descriptor has been established by a call to a Unix I/O operation such as open() and returned to Lisp via a call to a foreign function.)

function should be a symbol naming a function. The function must accept one argument. The system will pass it the file descriptor number fd when it is called.

Note that only input signals are available to Allegro CL. (Output signals are filtered out.) Note too that SIGIO handlers will only work if the SIGIO interface is available, as indicated by the return value of the function sigio-supported-p.

Signal handlers are removed with remove-sigio-handler.

Here is an example of a SIGIO function.

;; Assume that MY-FD is a UNIX file descriptor
;; returned by a foreign
;; function and that the function MY-GET-EVENT-HANDLER returns a
;; process
;;
;; This function shows how to schedule an event-handler associated
;; with the file descriptor to execute as soon as safely possible.
;; This way, data (from say a window or other input device) can be
;; processed sooner than it normally would be were lisp to wait for
;; the event-handler to be run by normal scheduling sequence.

(defun my-sigio-handler (fd)
  (mp:without-interrupts
     (let ((event-handler (my-get-event-handler fd)))
       (when (and mp:*current-process* ; Not in scheduler stack group
                  (not sys:*disallow-scheduling*) ; Avoid MP hazards
         (process-active-p event-handler)
         (not (eq mp:*current-process* event-handler)))
         (mp:process-allow-schedule event-handler)))))

(sys:set-sigio-handler my-fd 'my-sigio-handler)

Note the polling of *disallow-scheduling* to avoid multiprocessing hazards.

set-splash-bitmap

Function, system package

Arguments: &key filename data title

Windows only.

Sets the splash bitmap to be stored in subsequent dumplisp images and then displayed when those images are started.

The value of the title keyword argument should be a string. If unsupplied, "Allegro starting" (the string used by Allegro CL) is used. The title does not appear in the window displaying the splash bitmap but in tools such as the icon bar.

Exactly one of the keywords filename and data should be supplied. If filename is supplied -- the value should be a namestring or pathname -- then it is the name of a file that contains a device independent bitmap. Such a file typically has the extension .bmp or .dib and the contents must begin with the two characters "BM". When set-splash-bitmap is called, it reads the contents of that file into the Lisp heap, thus the bitmap file needn't exist later when the dumplisp is done or the image is restarted. It need only exist when this function is called.

If the data keyword is given, then its value must be an one-dimensional simple-array of type (unsigned-byte 8). The contents of the array is the bitmap, beginning with the bitmapinfo header. This is different than a bitmap stored on the disk (and read when the filename keyword is given) which begins with a 14 byte bitmap file header.

The user-defined splash bitmap used when an image starts will be saved by subsequent calls to dumplisp, except when the +B command line option is used for the image doing the dumplisp.

set-stack-cushion

Function, system package

Arguments: spread

This function and stack-cushion allow inspection (stack-cushion) and modification (this function) of the current process's soft stack limit. The cushion value is either:

• number of nats between the current frame pointer and the soft stack limit (see The :nat and :unsigned-nat types in implementation.html for a discussion of the nat type), or

• nil if there is no effective soft stack limit.

The value can be set when it is not nil. That is, when stack-cushion returns a true value, set-stack-cushion can be used to change the value (usually to provide a bigger cushion).

sigio-supported-p

Function, system package

Arguments:

This function is called with no arguments. If the return value is t, SIGIO signals can be received on the machine where Lisp is running. If it is nil, SIGIO signals cannot be received because the operating system does not support it.

A SIGIO handler is a function that is associated with a specific Unix file descriptor. It is called whenever Unix generates a SIGIO signal on that file descriptor. Such signals are generated whenever input is available. (SIGIO signals are also generated when output can be performed without the operating system needing to block, but all output signals are filtered out by Allegro CL. We will not discuss output-generated signals further.)

See initialize-sigio-handling, set-sigio-handler and remove-sigio-handler.

stack-cushion

Function, system package

Arguments:

This function and set-stack-cushion allow inspection (this function) and modification (set-stack-cushion) of the current process's soft stack limit. The cushion value is either:

• number of nats between the current frame pointer and the soft stack limit (see The :nat and :unsigned-nat types in implementation.html for a discussion of the nat type), or

• nil if there is no effective soft stack limit.

Typically, each process has a hard limit and a soft limit. Exceeding the hard limit causes Lisp to fail. Each operating system has a different way of setting the hard limit. Exceeding the soft limit signals an error (a signal 1000). Usually things are set up so the soft limit is hit before the hard limit. Exceeding the soft limit is a continuable error.

Stack allocation on windows

• The initial Lisp process gets a hard limit of 16 megabytes and a soft limit of 4 megabytes. Functions that create new processes (such as make-process accept a keyword argument stack-allocation to specify the size to request from the OS.

tag-information

Function, system package

Arguments: name &optional env

This function returns information about the tag named by name in the environment env. env may an environment object or nil, indicating the null lexical environment.

Three values are returned: :tag, a locative, and declaration list. The car of the locative is a catch tag (usually a unique cons cell) for throwing to its target in the interpreter, and the cdr of the locative is the portion of the interpreted code that immedately follows the tag in the code.

See environments.html for more information on environments.

temporary-directory

Function, system package

Arguments:

Returns the pathname of the temporary directory used by the current running Lisp for writing temporary files and sets, if necessary, the value of *temporary-directory* to that directory.

This function works as follows:

1. The value of *temporary-directory* is examined. If its value is nil, a new temporary directory is selected using the algorithm below.

2. The value of (probe-file sys:temporary-directory) is examined. If it is true, the value of *temporary-directory* is returned. If the value returned by probe-file is nil, then a new temporary directory is selected using the algorithm below.

In a freshly installed Lisp image, the initial value of *temporary-directory* is nil. However, in a user-built image (made with dumplisp or build-lisp-image or generate-application), *temporary-directory* may have been given a value, which might or might not be a valid value on the machine where the image is run. If it is not a valid value, the behavior is the same as when the value is nil. But it can happen (perhaps unexpectedly) that the value is valid and in that case it is used.

Algorithm for choosing a temporary directory

If a temporary directory must be chosen, it is chosen according to the following algorithms.

On UNIX and the Mac: #p"/tmp/".

On Windows: the first of the following to be a valid directory is used:

• the value of the environment variable TEMP

• the value of the environment variable TMP

• [current-drive]:\tmp

• C:\ (the last presumably always exists)

When a directory is chosen by this algorithm, the value of *temporary-directory* is set to it.

This function does not work with setf. It is informational only. You can change the temporary directory by changing the value of *temporary-directory* to the desired directory pathname. Whenever this function is called, it tests whether (probe-file sys:*temporary-directory*) returns true, returning the value of *temporary-directory* when it is. If (probe-file sys:*temporary-directory*) returns nil, a new value is chosen using the algorithm above. Changing the temporary directory is not recommended.

tmp-mnt-frobber

Function, system package

Arguments: pathname

The behavior of this function depends on whether "/tmp_mnt" appears at the beginning of pathname. If it does, this function removes "/tmp_mnt" from the head of pathname and returns a modified pathname object. If "/tmp_mnt" is not there, this function returns nil.

Therefore, the correct way to use this function is as in the following form:

(or (sys:tmp-mnt-frobber <pathname>) <pathname>)

A "/tmp_mnt" head is typically an artifact of the NFS automounter.

update-allegro

Function, system package

Arguments: &key documentation-only destination-directory except-patches force host list patches platform verbose version (keep-old-patches t) proxy proxy-basic-authorization auto-rebuild-images

See the section Updating Allegro CL and the update program in the Installation Guide for general information on patches and updates and a description or the update.sh/.exe program which can be used to get patches and to rebuild Allegro CL standard images.

This function, the update program just mentioned, and the Download Patches dialog in the Integrated Development Environment (IDE) all can obtain patches. This function and the Download Patches dialog can be used to get specific patches only, if desired. The update program always gets all new patches.

Downloading files from an external website is sometimes complicated since doing so can be dangerous. Firewalls and the like can interfere, and some OS's restrict the ability to download files into specific locations. The proxy and proxy-basic-authorization arguments help with firewalls as described below.

Updating images after patch download

Once new patches have been downloaded, images (files with type dxl) nust be rebuilt to include the new patches (this may be automatic on the Mac). This is done with the update program mentioned above. (update takes -u argument which will cause all needed patches to be downloaded prior to image rebuilds and thus combine everything into one operation, making calling this function unnecessary.

Description of sys:update-allegro

This function contacts the Franz Inc. website and downloads the patches appropriate for your platform (computer type) and version of Allegro CL. In order to work, the computer running Allegro CL must be able to make an FTP connection to the internet. If the connection is not made for any reason, sys:update-allegro signals an error.

On Windows using the IDE, the Download Patches dialog can be used to call this function.

Calling this function with no arguments will download and install all patches.

If you have AllegroCache or AllegroGraph installed, sys:update-allegro will tell you if there are newer versions available (but it does not itself download these newer versions).

Unless the force argument is true, a patch file is not downloaded if the size and CRC (checksum) of an existing local file with the same name and location is the same as the remote file (but this does not cause an error or prevent downloading of other files).

Fasl file (destined for the update/ and various other directories), shared library (UNIX), and Dynamically Linked Library (DLL) patches are all handled by sys:update-allegro. On Windows, because "in use" files cannot be replaced, you will be asked to reboot your computer to finish the update process. Without rebooting, you will not see the patched DLL.

As noted below, you must rebuild images after downloading patches. This is done automatically on Macs unless the auto-rebuild-images keyword argument is specified nil.

The keyword arguments to sys:update-allegro are as follows:

• documentation-only: retrieve only the DESCRIPTIONS files. Useful when you want to see what the current set of patches is. Note that new documentation files may be downloaded, but this argument has nothing to do with those files.

• destination-directory: put the patches in this directory. Useful when you want to pick and choose which patches to install. If you use a directory other than ";sys:" (the Allegro directory), you will then be responsible for installing the patches. (In earlier Windows versions of this function, DLL files were installed in the Windows system directory. This is no longer done. No files are installed in the Windows system directory by sys:update-allegro.

• except-patches: a list of patches (by location and name) to skip downloading and installing. The location should be relative to the Allegro directory (see the example below). If a name does not correspond to an actual patch file, it is ignored and no error is signaled.

• force: cause patches that have been previously downloaded to be downloaded again. In other words, the file size and CRC check mentioned above is not performed.

• host: never specify a value for this argument unless instructed to do so by Franz Inc. Technical Support.

• keep-old-patches: defaults to t. If true, old patch files are renamed to end in "bak" (or if a "bak" file is present, a numbered "bak" file -- "bak2", "bak3", etc.) Thus, if a new, modified code/streams.fasl is downloaded, the older one becomes streams.faslbak and if a new p2a002.001 is downloaded, the old one becomes p2a002.001bak. (This makes it easier to back out of a patch, particularly a patched fasl file in the code/ directory.) If the value of this argument is nil, the old file is overwritten.

• list: if specified true, no files are downloaded. Instead, sys:update-allegro returns a list of the patches that would have otherwise downloaded and installed if this argument were nil.

• patches: if true, the value should be a list of specific patches to download and install. The list should contain relative pathnames from the /pub/patches/[version]/[arch] directory on the FTP site. Only those files are downloaded.

• platform: the platform for which you wish to download patches. If you change this from the default value, you must also specify a destination-directory (an error is signaled if you do not). Installing patches for the incorrect architecture would cause serious problems, probably making your Lisp unusable (requiring uninstallation and installation to make it work again).

  We recommend that if possible you do not specify this argument and instead call sys:update-allegro on the platform of interest. (However, there might be cases, such as where the desired platform is not connected to the internet, where using this argument is necessary.)

• proxy: defaults to nil. Allows using an http proxy. See Note on using proxies below the argument descriptions.

• proxy-basic-authorization: this argument is passed to do-htpp-request, the AllegroServe function which is used during the update (see aserve.html). It allows specifying a username and a password to the proxy. The value, if non-nil, can be in one of two formats. The first allowable format is a cons of two strings: the username and the password, like this:

  :proxy-basic-authorization (cons "username" "password")

  The second allowable format for this argument is a string of the form "username:password". See Note on using proxies below the argument descriptions.

• verbose: if true, various status messages are printed.

• version: a specific version for which patches should be downloaded. As with platform, if you change this from the default value, you must also specify a destination-directory (an error is signaled if you do not). Installing patches for the incorrect version would cause serious problems, probably making your Lisp unusable (requiring uninstallation and installation to make it work again).

• auto-rebuild-images: Mac only. If true (the default on the Mac, default is nil on other platforms) images will be rebuilt automatically when all patches have been downloaded (the running Lisp will exit in order that the rebuild can occur). Specify nil if you do not want auto-rebuilding on the Mac. Do not specify a value on other platforms.

Note on using proxies

Users that surf through an http proxy (usually as a security measure on sites with firewalls) can specify the proxy name and port number using the proxy keyword argument, and, if necessary, a username and password using the proxy-basic-authorization keyword argument. Suppose the proxy is www.foo.com and it uses port 8000, then such users would specify the sys:update-allegro form like this (specifying other arguments as desired, of course):

(sys:update-allegro :proxy "www.foo.com:8000")

If a username and a password is also, needed, they can be specified like this (replacing "username" and "password" with the actual strings and also specifying other arguments as desired):

(sys:update-allegro :proxy "www.foo.com:8000" 
                    :proxy-basic-authorization (cons "username" "password")
  )

or, using the second allowable format for proxy-basic-authorization:

(sys:update-allegro :proxy "www.foo.com:8000" 
                    :proxy-basic-authorization (cons "username:password")
  )

Without proxy specified, sys:update-allegro will try and contact franz.com directly. In the case where users are using a proxy, that would not work. The failure symptom would be that sys:update-allegro would just hang and finally time out.

Examples:

To download all available patches for your platform and version, do:

(sys:update-allegro)

If you want all patches except update/p2a001.001, then do this:

(sys:update-allegro :except-patches
                    '("update/p2a001.001"))

If you want a list of patches that would be downloaded but do not want to download anything, then do this:

(sys:update-allegro :list t)

After downloading is complete

On the Mac, if the auto-rebuild-images keyword argument has its default value, which is true, images will be rebuilt when the pattches have downloaded (and the running Lisp will exit). If that argument is nil, you must rebuild images by hand as on other platforms.

It is important that you follow the instructions given to you by sys:update-allegro. It may ask you to rebuild your images or, on Windows only, to reboot your machine. If you do not follow the instructions, the update procedure will not be complete.

On Windows, when a reboot is necessary, sys:update-allegro displays a dialog asking you if you want to reboot immediately, and performs the reboot if you answer yes. Even if you do not reboot immediately, you should reboot before using Allegro CL further.

Patches are described in section Patches and updates of index.html. The sections after that one also contain information about patches.

user-name

Function, system package

Arguments:

Returns a string identifying the user name of the user running Lisp. This function works on all platforms. On UNIX platforms,

(or (sys:getenv "USER") (sys:getenv "LOGNAME"))

is called and the result returned. On Windows, GetUserName() is called.

The behavior on Windows when there is no user name (that is whether nil or the empty string or something else is returned) is undefined since the MS documentation is unclear on this point.

variable-information

Function, system package

Arguments: symbol &optional env all-declarations

This function returns information about the variable named by symbol in the environment env. env may be an environment object or nil, indicating the null lexical environment.

all-declarations is a boolean which requests a building of the full alist to be provided as the third return value from this function. It is provided in order to reduce consing when its value is nil, since most declarations are ignorable by an implementation and thus it is not necessary to cons the alist every time.

Four values are returned.

1. The first value returned is one of the following values, providing information about the binding of the variable named by symbol:

   • nil: there is no binding or definition of symbol.

   • :special: symbol names a special variable.

   • :lexical: symbol names a lexical variable.

   • :symbol-macro: symbol refers to a symbol-macroletbinding.

   • :constant: symbol names a constant defined by defconstant or symbol is a keyword.

2. The second returned value is a locative cons (a cons whose car and/or cdr may be used as a mutable value). This locative cons is used to provide the local binding of the value (for :evaluation environments) or local compiler structure information (for the two compilation environments). To reduce consing at critical points in the environments implementation, there are a few exceptions where the second value is not a cons representing a locative:

   • When the first return value from variable-information is :constant, then the second value returned is an actual value, and not a value housed within a locative. This ensures that the value is not changed by replacing it in the (non-existent) locative.

   • When the first return value from variable-information is :special, then the second value is nil, because the value is dynamic and can be best accessed via symbol-value.

3. The third returned value is an alist containing information declarations that apply to the bindings of symbol. The keys are symbols that name declaration specifiers (such as dynamic-extent, ignore, type, etc.) and the value (that is, the cadr of the alist element) is the associated value. This alist may not be complete if the all-declarations argument is not specified or is nil. If this is the case, only those declarations which have been actually stored into the environment object will be present in the alist; in general, if the symbol has no lexical binding and all-declarations is nil, then this third return value will also be nil. If all-declarations is true, then applicable declarations are also be gathered from the global environment. Note: the special declaration has special meaning in the context of variable-information; it never shows up in a declaration list, but instead shows up with the label :special in the first return value.

4. The fourth returned value is a boolean indicating whether binding is local or global: the value is true if the binding is local, nil if not. (In CLtL-2, this local/global boolean is the second returned value.)

See environments.html for more information on environments.

with-command-line-arguments

Macro, system package

Arguments: (&rest **) (restvar &key command-line-arguments usage posixly-correct long-abbrev) &body body

Any arguments that followed the old format are accepted in the new macro (which accepts more than one option-list and accepts more keyword arguments).

This macro makes the task of parsing command line arguments easier, in the style similar to the UNIX getopt(3) and getopt(1). During parsing, command line arguments are scanned from left to right. An argument named -- terminates option scanning. This macro works on both UNIX and Windows platforms. It works on Windows as it does on UNIX. Windows users should, like UNIX users refer to UNIX documentation on this (you can enter getopt(1) and getopt(3) into the Google (tm) search engine to find such documentation). We believe, however, that this documentation is stand-alone and should be sufficient for you to understand all the issues surrounding command line arguments and their use.

The main task of with-command-line-arguments is to bind Lisp variables to the given command line arguments.

option-lists, the first argument, is a list of (for the old form) an option-string and any number of variable names or (for the new form) a list of lists described below. Note that with-command-line-arguments will signal an error if a command line argument (option) is found without a corresponding entry in the option-lists.

The old form specification of option-lists

The old form, which preserves for compatibility with the older version of this macro, is therefore (in the lambda-list specification above, the parentheses around option-lists are the parentheses shown here):

  (option-string [variable-names]*)

option-string is a getopt(3) style string describing the expected options. variable-names are the symbols to which values are bound. The order of the options in option-string is the order in which the variables are bound. From the complete example below, we have

("ab:c" aflag bflag cflag)

The getopt(3) allows one character for each option, so the options in the example are a, b, and c. The corresponding variables are aflag, bflag, and cflag.

The new form specification of option-lists

In the new form, option-lists is a list of items with the following form:

  (name style varname [modifiers ...])

name is a string naming the argument, such as "a" or "foo".

style must be either :short or :long. For :short options, the string must be of length 1 (e.g., "a" for the command line option -a). For :long options, the string can be any length (e.g., "foo" for --foo). Long options are typically specified on a command line preceded with two dashes (hence --foo) while short options are preceded with one dash (hence -a). However, the long-abbrev keyword argument can allow single dashes to precede long options.

varname is a symbol to which a value is bound. This should be a Lisp symbol, for example aflag or foo.

modifiers may be unspecified or one or more of the following keyword selections:

• :required-companion (:required is accepted to mean :required-companion) or :optional-companion (:optional is accepted to mean :optional-companion), either of which indicate a companion argument is accepted (and is required or optional). A companion argument is often a value or a modifier of some sort, see the examples below. If modifiers does not include either :required-companion or :optional-companion, the option cannot have a companion argument.

• :allow-multiple-options: when this appears as a modifier, the option being described can appear multiple times in the command line. The value bound to varname will reflect the presence or absence of this modifier as follows:

  • If :required-companion or :optional-companion is also a modifier, then varname is bound to a list of the values corresponding to the given command-line values.

  • If neither :required-companion or :optional-companion is also a modifier, then varname is bound to a number indicating the number of times the option is specified in the command line (or nil, not 0, if it does not appear at all).

  If :allow-multiple-options is not specified as a modifier, an error is signaled if an option appears more than once.

Consider the following example which does not allow multiple options:

        ("foo" :long foo :required-companion)
        ("a" :short aflag :required-companion)   

The required-companion arguments can be specified in the following ways:

        --foo bar
        --foo=bar
        -abar
        -a bar

In each case the companion argument is "bar". Note that long form options are separated from their companions by a space or by =. Short form options are separated by a space or are not separated. The fact that no separation is allowed for short form options can lead to ambiguity. See the discussion of the long-abbrev keyword argument below for details.

Now consider these examples which do (for some options) allow multiple options:

;;  Option `o' allows multiple options, and requires companions
;;  so the `oflag' variable is bound to a list of the companion 
;;  values specified:
cl-user(13): (sys:with-command-line-arguments
                 (("o" :short oflag :required-companion 
                   :allow-multiple-options))
                 (rest :command-line-arguments '("-ofoo" "-o" "bar"))
               oflag)
("foo" "bar")

;;  Option `x' does not allow multiple options but option `v' does.
;;  Neither accepts companions. `xflag' is either T or NIL while
;;  `vflag' is a number, indicating how many times it appears
;;  (if it does not appear, `vflag' is NIL, not 0):
cl-user(14): (sys:with-command-line-arguments
                 (("x" :short xflag)
                  ("v" :short vflag :allow-multiple-options))
                 (rest :command-line-arguments '("-v" "-x" "-v"))
               (list vflag xflag))
(2 t)
cl-user(15): (sys:with-command-line-arguments
                 (("x" :short xflag)
                  ("v" :short vflag :allow-multiple-options))
                 (rest :command-line-arguments '("-x"))
               (list vflag xflag))
(nil t)

;;  The same specification as just above, but `x' is specified
;;  twice, causing an error:
cl-user(16): (sys:with-command-line-arguments
                 (("x" :short xflag)
                  ("v" :short vflag :allow-multiple-options))
                 (rest :command-line-arguments '("-v" "-x" "-v" "-x"))
               (list vflag xflag))
Error: Option `x' cannot be specified more than once.

Restart actions (select using :continue):
 0: Return to Top Level (an "abort" restart).
 1: Abort entirely from this process.
[1] cl-user(17): :reset

;;  The same specification as just above. `x' is not specified and
;;  `v' is specified three times with `-vvv':
cl-user(18): (sys:with-command-line-arguments
                 (("x" :short xflag)
                  ("v" :short vflag :allow-multiple-options))
                 (rest :command-line-arguments '("-vvv"))
               (list vflag xflag))
(3 nil)
;;  Here `v' has an optional-companion, and appears as `"-v" "2" "-vv"'.
;;  Note that `-vv' is `v' appearing once with companion "v" rather than
;;  `v' appearing twice (an unavoidable ambiguity discussed further
;;  below):

cl-user(19): (sys:with-command-line-arguments
                 (("x" :short xflag)
                  ("v" :short vflag
                       :optional-companion :allow-multiple-options))
                 (rest :command-line-arguments '("-v" "2" "-vv"))
               (list vflag xflag))
(("2" "v") nil)

;;  Again `v' has an optional-companion and is specified with
;;  and without a companion value. The unspecified value appears
;;  as the empty string in the values of v list (`x' also appears 
;;  once):
cl-user(20): (sys:with-command-line-arguments
                 (("x" :short xflag)
                  ("v" :short vflag
                       :optional-companion :allow-multiple-options))
                 (rest :command-line-arguments '("-v" "2" "-v" "-x"))
               (list vflag xflag))
(("2" "") t)
cl-user(23): 

Although either form, old or new, can be used for the option-lists, the new form is preferred since it offers long form arguments and does not require positional synchronization of the options in option-string with the variables given by [variable-names]*.

The other arguments to with-command-line-arguments

restvar should be a symbol. It is bound to all command line arguments that are not options. A command line argument of -- terminates option scanning and causes all remaining arguments to be put into restvar. The order of arguments in restvar will have the same order as the arguments on the command line, or in the value of the keyword command-line-arguments.

The command-line-arguments keyword argument is used to initialize the command line arguments. If not given, then the function command-line-arguments, called with a true value for the application keyword argument, is used to retrieve the actual command line arguments given to the invoked image. If command-line-arguments is specified nil, then the actual command line arguments are not substituted in (as they are when no value for this argument is specified). Instead, the with-command-line-arguments form is rendered a no-op and does nothing. (Obviously there is no point in calling this macro with :command-line-arguments nil, but you might call it with the value of :command-line-arguments a variable whose value might happen to be nil. If you do that, the macro will do what you want when the variable has value nil as well as when it has a non-nil value.)

The posixly-correct keyword argument, ignored in the old form, says what to do when a non-option is encountered in the left to right scan of the command line arguments. If posixly-correct is non-nil, then processing of the command line terminates when a non-option is seen, otherwise the non-option is put into restvar.

The usage keyword argument, if specified, should be a string. This string is printed when errors are found while parsing the command line arguments according to the given specification. (Possible errors would be not supplying a companion argument, supplying an unknown command line argument, etc.)

The long-abbrev keyword argument, ignored in the old form, allows long form arguments to be specified with a single -. Otherwise they must be specified with double dashes, --.

Allowing a single dash to specify a long form argument can introduce ambiguity. Consider the following case illustrated by a partial with-command-line-arguments form:

(sys:with-command-line-arguments
    (("foo" :long foo :optional-companion)
     ("f" :short aflag :required-companion))
    (:long-abbrev t) ...) 

Now suppose the argument -foo is provided. Does this mean the long form argument -foo or the short form argument -f with companion (or value) oo? Both interpretations are valid, and so the argument is ambiguous. When long-abbrev is specified true, the system will always assume that an argument is a long form argument if it can be so intrepreted. If the argument cannot be interpreted as a long form argument, the short form argument interpretation will be used. Programmers should avoid any possibility of ambiguity, of course. Again, if long-abbrev is nil, short form and long form arguments are designated differently and there can be no ambiguity in interpretation. The downside is that it may be harder for users of an application to specify arguments correctly (that is to remember which require two dashes and which require one).

Here is the example above shown in a script:

cl-user(1): (system:with-command-line-arguments
        (("foo" :long foo :optional-companion)
         ("f" :short fflag :optional-companion))
        (rest :command-line-arguments
              '("-foo") :long-abbrev nil)
          (list foo fflag rest))
(nil "oo" nil)

;;  -foo is parsed as a short option since the long form "foo"
;;  must be specified --foo.

cl-user(2): (system:with-command-line-arguments
        (("foo" :long foo :optional-companion)
         ("f" :short fflag :optional-companion))
        (rest :command-line-arguments '("-foo")
              :long-abbrev t)
          (list foo fflag rest))
(t nil nil)

;;  -foo is parsed as a long option.

The body argument to with-command-line-arguments

body is a list of forms, executed in a lexical environment where the variables discussed above are bound for use by the macro's body.

Examples using with-command-line-arguments

Here are some more examples of the new form:

cl-user(15): (sys:with-command-line-arguments
                 (("foo" :long foo :required-companion)
                  ("bar" :long bar :optional-companion)
                  ("baz" :long baz nil)
                  ("a" :short aflag :required-companion)
                  ("b" :short bflag :optional-companion)
                  ("c" :short cflag nil))
                 (rest :long-abbrev t
                       :command-line-arguments
                       '("--foo" "xxx" "--bar" "-afoo" "-b" "-c" "1" "2" "3"))
               (format t "foo=~a, bar=~a, baz=~a, a=~a, b=~a, c=~a, rest=~a~%"
                       foo bar baz aflag bflag cflag rest))
foo=xxx, bar=t, baz=nil, a=foo, b=t, c=t, rest=(1 2 3)
nil
cl-user(16): (sys:with-command-line-arguments
                 (("foo" :long foo :required-companion)
                  ("bar" :long bar :optional-companion)
                  ("baz" :long baz nil)
                  ("a" :short aflag :required-companion)
                  ("b" :short bflag :optional)
                  ("c" :short cflag nil))
                 (rest :long-abbrev t
                       :command-line-arguments
                       '("--foo=xxx" "--bar" "-a" "foo" "-b" "-c" "1" "2" "3"))
               (format t "foo=~a, bar=~a, baz=~a, a=~a, b=~a, c=~a, rest=~a~%"
                       foo bar baz aflag bflag cflag rest))
foo=xxx, bar=t, baz=nil, a=foo, b=t, c=t, rest=(1 2 3)
nil
cl-user(17): (sys:with-command-line-arguments
                 (("foo" :long foo :required-companion)
                  ("f" :short fflag :required-companion)
                  ("foo2" :long foo2 :required-companion))
                 (rest :command-line-arguments
                       '("--foo" "xxx" "--foo2=blah" "-foo" "foo"))
               (format t "foo=~a, foo2=~a, f=~a, rest=~a~%"
                       foo foo2 fflag rest))
foo=xxx, foo2=blah, f=oo, rest=(foo)
nil
cl-user(18): (sys:with-command-line-arguments
                 (("f" :short fflag :required-companion))
                 (rest :command-line-arguments '("-foo" "xxx" "foo"))
               (format t "f=~a, rest=~a~%"
                       fflag rest))
f=oo, rest=(xxx foo)
nil
cl-user(19): 

Note: the command-line-arguments keyword would normally not be used since the actual command line arguments would come from the command line of the running application.

Here is an example of the old form:

cl-user(18): (sys:with-command-line-arguments
                 ("ab:c" aflag bflag cflag)
                 (rest :command-line-arguments
                       '("-a" "-b" "xxx" "1" "2" "3"))
               (format t "a=~a, b=~a, c=~a, rest=~a~%"
                       aflag bflag cflag rest))
a=t, b=xxx, c=nil, rest=(1 2 3)
nil
cl-user(19): 

See Command line arguments in startup.html for a list of command-line arguments accepted by Allegro CL.

with-timeout

macro, system package

Arguments: (seconds &body timeout-body) body

This macro evaluates the body as a progn body. If the evaluation of body does not complete within the specified interval (but see Timeouts when writing to an SSL stream below), execution throws out of the body and the timeout-body forms are evaluated as a progn body, returning the result of the last form. The timeout-body forms are not evaluated if the body completes within seconds.

The value of seconds may be any real number. A negative or zero value causes the timeout-body to be executed immediately. This macro uses operating system utilities for timing so its granularity depends on the granularity of the operating system functions. We cannot in this page specify the granularity you will see (since this page is generic over many systems and environmental factors affect the result) but we can say that seconds of less than about 0.08 will always time out on most Unix systems. We strongly recommend that you test this macro to find out the granularity on your system.

When the debugger takes control on a Lisp thread, it temporarily blocks the triggering of any dynamically-enclosing with-timeout forms. The block goes away when the debugger returns to wherever it's going.

Here is an example of code using with-timeout. We define a variant of y-or-n-p which times out after a specified number of seconds, taking the default value specified in the arguments.

(defun y-or-n-p-with-timeout (seconds default &rest args)
  (sys:with-timeout (seconds (format t "[Timed out] ~a~%" default)
         default)
     (apply #'y-or-n-p args)))

Timeouts when reading from or writing to an SSL stream

The process of reading from or writing to an SSL stream (such as created by make-ssl-client-stream and make-ssl-server-stream) involves breaking what is to be read/written into blocks which are then encrypted and read/written one at a time. Interrupting the encrypting/reading or writing of a block can introduce problems that are masked by the interruption and execution of timeout forms. To avoid those problems, if the timeout occurs while a read from/write to an SSL stream is being executed, the system will allow the entire read/write to finish without timing out. In that case, when the read/write finishes, the timeout will take effect and the timeout-body forms will be run. (This delay in timing out applies to reading from/writing to SSL streams only.)

But this protection of reading from/writing to SSL streams introduces another issue: if for whatever reason reading from/writing to the SSL stream hangs or fails (such as the connection is broken), the thread reading from/writing to the stream will itself hang.

To handle this possibility, you can specify separate read and write timeouts for an SSL stream. These can be set with the generic function acl-socket:socket-control, which has keyword arguments read-timeout and write-timeout. (Do not specify values for the other keyword arguments if you only want to specify timeouts.) If the processing of a single block read or a block write times out because it exceeds the read-timeout or write-timeout value (**and note the timeout set by socket:socket-control apply to the processing of single blocks, not the entire read or write), the entire read/write will fail with a socket-error. After such an error, it is very likely the SSL stream will be in a broken state and should be closed (with the abort keyword argument to close specified true).

Related functionality

See with-virtual-timeout, which is a similar macro but restricts time counting to the timeout to non-gc time actually spent in the process running when the macro was called. Also see multiprocessing.html for general information on multiprocessing in Allegro CL.

without-scheduling

macro, system package

Arguments: &body body

Use of this macro and the related without-interrupts is deprecated and a warning will be signaled if they are used. See smp.html for full details, but in brief, without-interrupts and sys:without-scheduling effectively provided object locking -- because they prevented process switches, and only one Lisp process could ever run at a time, no object could be modified by another process while code wrapped in the macros was being run. In an SMP Lisp, that is no longer true because processes can run on separate processors simultaneously. Therefore, object locking must be achieved in some other fashion. See smp.html for links to object locking functionality.

Uses of without-interrupts and sys:without-scheduling will signal a warning. That warning can be muffled by evaluating (setq excl::*warn-smp-usage* nil).

Even though its use is deprecated, sys:without-scheduling and without-interrupts will continue to exist and work in non-SMP images as they have in earlier releases and currently. Users who do not wish to use SMP can use non-SMP images, which will be available on platforms which support SMP along with SMP images and need not modify their code at all because of the introduction of SMP (beyond suppressing the compiler warning as described above).

This macro inhibits the system from suspending a process involuntarily (asynchronously) during the execution of body. However, the system will run another process if the current process blocks, waits, or executes a process-allow-schedule. Note that sys:without-scheduling returns a single value, not multiple values. sys:without-scheduling is intended to be used around short critical sections of code, and perhaps to be called frequently, so possible overhead of allocating multiple returns is avoided by returning a single value.

See also without-interrupts and multiprocessing.html for general information on multiprocessing in Allegro CL.

write-codevectors

Function, system package

Arguments: fname &optional verbose

This function creates a file named fname and writes all heap-allocated code vectors for heap-allocated functions to it. (Our convention is that the filename should have the extension .cvs.) The code vectors written to file are not flushed from the heap, as with flush-codevectors, they are just written to file. The file written is appropriate as a command-line argument to the program cvdcvt to create a pll file. system:write-codevectors cannot extend or append to an existing code-vector file, so different output filenames should be used if this function is called more than once.

If the verbose argument is specified true, information about what is written to file will be printed.

See miscellaneous.html for information on pll files.

Copyright (c) Franz Inc. Lafayette, CA., USA. All rights reserved.