chap-25.texi

@node Environment
@chapter Environment
@menu
* The External Environment::
* Environment Dictionary::
@end menu

@node The External Environment
@section The External Environment

@menu
* Top level loop::
* Debugging Utilities::
* Environment Inquiry::
* Time::
@end menu
@node Top level loop
@subsection Top level loop
The top level loop is the @clisp{}@spc{}mechanism by which the user normally
interacts with the @clisp{}@spc{}system. This loop is sometimes referred to
as the @term{Lisp read-eval-print loop}
because it typically consists of an endless loop that reads an expression,
evaluates it and prints the results.

The top level loop is not completely specified; thus the user
interface is @term{implementation-defined}.
The top level loop
prints all values resulting from the evaluation of a
@term{form}.
@Thenextfigure{}@spc{}lists variables that are maintained by the @term{Lisp read-eval-print loop}.


@float Figure,fig25.1
@cartouche
@multitable{***}{+++}{///}{-}

@item * @tab + @tab / @tab -
@item ** @tab ++ @tab // @tab
@item *** @tab +++ @tab /// @tab
@end multitable
@end cartouche
@caption{Variables maintained by the Read-Eval-Print Loop}
@end float



@node Debugging Utilities
@subsection Debugging Utilities

@Thenextfigure{}@spc{}shows @term{defined names} relating to
debugging.


@float Figure,fig25.2
@cartouche
@multitable{*debugger-hook*}{invoke-debugger}{untrace}

@item *debugger-hook* @tab documentation @tab step
@item apropos @tab dribble @tab time
@item apropos-list @tab ed @tab trace
@item break @tab inspect @tab untrace
@item describe @tab invoke-debugger @tab
@end multitable
@end cartouche
@caption{Defined names relating to debugging}
@end float



@node Environment Inquiry
@subsection Environment Inquiry
Environment inquiry @term{defined names} provide information about
the hardware and software configuration on which a @clisp{}@spc{}program is
being executed.

@Thenextfigure{}@spc{}shows @term{defined names} relating to environment inquiry.


@float Figure,fig25.3
@cartouche
@multitable{lisp-implementation-version}{machine-instance}{software-version}

@item *features* @tab machine-instance @tab short-site-name
@item lisp-implementation-type @tab machine-type @tab software-type
@item lisp-implementation-version @tab machine-version @tab software-version
@item long-site-name @tab room @tab
@end multitable
@end cartouche
@caption{Defined names relating to environment inquiry.}
@end float



@node Time
@subsection Time

Time is represented in four different ways in @clisp{}:
@term{decoded time},
@term{universal time},
@term{internal time},
and seconds.
@term{Decoded time} and @term{universal time} are used primarily to represent calendar time,
and are precise only to one second.
@term{Internal time} is used primarily to represent measurements of computer
time (such as run time) and is precise to some @term{implementation-dependent}
fraction of a second called an @term{internal time unit},
as specified by @symbolref{internal-time-units-per-second, SYM}.
An @term{internal time} can be used
for either @term{absolute} and @term{relative} @term{time} measurements.
Both a @term{universal time} and a @term{decoded time} can be used
only for @term{absolute} @term{time} measurements.
In the case of one function, @symbolref{sleep, SYM},
time intervals are represented as a non-negative @symbolref{real, SYM} number of seconds.

@Thenextfigure{}@spc{}shows @term{defined names} relating to @term{time}.


@float Figure,fig25.4
@cartouche
@multitable{get-internal-real-time}{internal-time-units-per-second}

@item decode-universal-time @tab get-internal-run-time
@item encode-universal-time @tab get-universal-time
@item get-decoded-time @tab internal-time-units-per-second
@item get-internal-real-time @tab sleep
@end multitable
@end cartouche
@caption{Defined names involving Time.}
@end float


@node Decoded Time
@subsubsection Decoded Time
A @newterm{decoded time} is an ordered series of nine values that, taken together,
represent a point in calendar time (ignoring @term{leap seconds}):


@table @asis
@item @id{@b{Second}}


An @term{integer} between 0 and@tie{}59, inclusive.

@item @id{@b{Minute}}


An @term{integer} between 0 and@tie{}59, inclusive.

@item @id{@b{Hour}}


An @term{integer} between 0 and@tie{}23, inclusive.

@item @id{@b{Date}}


An @term{integer} between 1 and@tie{}31, inclusive (the upper limit actually
depends on the month and year, of course).

@item @id{@b{Month}}


An @term{integer} between 1 and 12, inclusive;
1@tie{}means January, 2@tie{}means February, and so on; 12@tie{}means December.

@item @id{@b{Year}}


An @term{integer} indicating the year A.D.  However, if this
@term{integer}
is between 0 and 99, the ``obvious'' year is used; more precisely,
that year is assumed that is equal to the
@term{integer} modulo 100 and
within fifty years of the current year (inclusive backwards
and exclusive forwards).
Thus, in the year 1978, year 28 is 1928
but year 27 is 2027.  (Functions that return time in this format always return
a full year number.)

@item @id{@b{Day of week}}


An @term{integer} between@tie{}0 and@tie{}6, inclusive;
0@tie{}means Monday, 1@tie{}means Tuesday, and so on; 6@tie{}means Sunday.

@item @id{@b{Daylight saving time flag}}


A @term{generalized boolean} that,
if @term{true}, indicates that daylight saving time is in effect.

@item @id{@b{Time zone}}


A @term{time zone}.
@end table


@Thenextfigure{}@spc{}shows @term{defined names} relating to @term{decoded time}.


@float Figure,fig25.5
@cartouche
@multitable{decode-universal-time}{get-decoded-time}

@item decode-universal-time @tab get-decoded-time
@end multitable
@end cartouche
@caption{Defined names involving time in Decoded Time.}
@end float



@node Universal Time
@subsubsection Universal Time
@cindex universal time
@dfn{Universal time} is an @term{absolute} @term{time} represented as a
single non-negative @term{integer}---the number of seconds since
midnight, January 1, 1900 GMT (ignoring @term{leap seconds}).
Thus the time 1 is 00:00:01 (that is, 12:00:01 a.m.) on January 1, 1900 GMT.
Similarly, the time 2398291201 corresponds to time 00:00:01 on January 1,
1976 GMT.
Recall that the year 1900 was not a leap year; for the purposes of
@clisp{}, a year is a leap year if and only if its number is divisible by 4,
except that years divisible by 100 are not leap years, except that years
divisible by 400 are leap years.  Therefore the year 2000 will
be a leap year.
Because @term{universal time} must be a non-negative @term{integer},
times before the base time of midnight, January 1, 1900 GMT cannot be processed by @clisp{}.


@float Figure,fig25.6
@cartouche
@multitable{decode-universal-time}{get-universal-time}

@item decode-universal-time @tab get-universal-time
@item encode-universal-time @tab
@end multitable
@end cartouche
@caption{Defined names involving time in Universal Time.}
@end float



@node Internal Time
@subsubsection Internal Time
@cindex internal time
@dfn{Internal time} represents time as a single @term{integer},
in terms of an @term{implementation-dependent} unit called an @term{internal time unit}.
Relative time is measured as a number of these units.
Absolute time is relative to an arbitrary time base.

@Thenextfigure{}@spc{}shows @term{defined names} related to @term{internal time}.


@float Figure,fig25.7
@cartouche
@multitable{get-internal-real-time}{internal-time-units-per-second}

@item get-internal-real-time @tab internal-time-units-per-second
@item get-internal-run-time @tab
@end multitable
@end cartouche
@caption{Defined names involving time in Internal Time.}
@end float



@node Seconds
@subsubsection Seconds

One function, @symbolref{sleep, SYM}, takes its argument as a non-negative @symbolref{real, SYM} number
of seconds.  Informally, it may be useful to think of this as
a @term{relative} @term{universal time}, but it differs in one important way:
@term{universal times} are always non-negative @term{integers}, whereas the argument to
@symbolref{sleep, SYM} can be any kind of non-negative @symbolref{real, SYM}, in order to allow for
the possibility of fractional seconds.


@float Figure,fig25.8
@cartouche
@multitable{sleep}{}

@item sleep @tab
@end multitable
@end cartouche
@caption{Defined names involving time in Seconds.}
@end float


@node Environment Dictionary
@section Environment Dictionary


@menu
* decode-universal-time::
* encode-universal-time::
* get-universal-time; get-decoded-time::
* sleep::
* apropos; apropos-list::
* describe::
* describe-object::
* trace; untrace::
* step::
* time (Macro)::
* internal-time-units-per-second::
* get-internal-real-time::
* get-internal-run-time::
* disassemble::
* documentation; setf documentation::
* room::
* ed::
* inspect::
* dribble::
* - (Variable)::
* +; ++; +++::
* *; **; ***::
* /; //; ///::
* lisp-implementation-type; lisp-implementation-version::
* short-site-name; long-site-name::
* machine-instance::
* machine-type::
* machine-version::
* software-type; software-version::
* user-homedir-pathname::
@end menu

@node decode-universal-time
@syindexanchor{decode-universal-time, SYM}
@subsection decode-universal-time (Function)
@cindex decode-universal-time


@subsubheading Syntax:

@DefunWithValuesNewline{decode-universal-time, universal-time @opt{} time-zone, second\, minute\, hour\, date\, month\, year\, day\, daylight-p\, zone}

@subsubheading Arguments and Values:

@param{universal-time}---a @term{universal time}.

@param{time-zone}---a @term{time zone}.

@param{second}, @param{minute}, @param{hour}, @param{date}, @param{month},
@param{year}, @param{day}, @param{daylight-p}, @param{zone}---a @term{decoded time}.

@subsubheading Description:

Returns the @term{decoded time} represented by the given @term{universal time}.

If @param{time-zone} is not supplied,
it defaults to the current time zone adjusted for daylight saving time.
If @param{time-zone} is supplied, daylight saving time information is ignored.
The daylight saving time flag is @nil{}@spc{}if @param{time-zone} is supplied.

@subsubheading Examples:

@lisp
 (decode-universal-time 0 0) @EV{} 0, 0, 0, 1, 1, 1900, 0, @term{false}, 0

;; The next two examples assume Eastern Daylight Time.
 (decode-universal-time 2414296800 5) @EV{} 0, 0, 1, 4, 7, 1976, 6, @term{false}, 5
 (decode-universal-time 2414293200) @EV{} 0, 0, 1, 4, 7, 1976, 6, @term{true}, 5

;; This example assumes that the time zone is Eastern Daylight Time
;; (and that the time zone is constant throughout the example).
 (let* ((here (nth 8 (multiple-value-list (get-decoded-time)))) ;Time zone
        (recently (get-universal-time))
        (a (nthcdr 7 (multiple-value-list (decode-universal-time recently))))
        (b (nthcdr 7 (multiple-value-list (decode-universal-time recently here)))))
   (list a b (equal a b))) @EV{} ((T 5) (NIL 5) NIL)
@end lisp


@subsubheading Affected By:

@term{Implementation-dependent} mechanisms for calculating when or if daylight
savings time is in effect for any given session.

@subsubheading See Also:

@ref{encode-universal-time}, @ref{get-universal-time},
@ref{Time}


@node encode-universal-time
@syindexanchor{encode-universal-time, SYM}
@subsection encode-universal-time (function)
@cindex encode-universal-time


@subsubheading Syntax:

@DefunWithValuesNewline{encode-universal-time, @vtop{@hbox{second minute hour date month year} @hbox{@opt{} time-zone}}, universal-time}

@subsubheading Arguments and Values:

@param{second}, @param{minute}, @param{hour},
@param{date}, @param{month}, @param{year},
@param{time-zone}---the corresponding parts of a @term{decoded time}.
(Note that some of the nine values in a full @term{decoded time} are redundant,
and so are not used as inputs to this function.)

@param{universal-time}---a @term{universal time}.

@subsubheading Description:

@symbolref{encode-universal-time, SYM} converts a time from Decoded Time format
to a @term{universal time}.

If @param{time-zone} is supplied, no adjustment for daylight savings time is performed.

@subsubheading Examples:

@lisp
 (encode-universal-time 0 0 0 1 1 1900 0) @EV{} 0
 (encode-universal-time 0 0 1 4 7 1976 5) @EV{} 2414296800
;; The next example assumes Eastern Daylight Time.
 (encode-universal-time 0 0 1 4 7 1976) @EV{} 2414293200
@end lisp


@subsubheading See Also:

@ref{decode-universal-time}, @ref{get-decoded-time}


@node get-universal-time; get-decoded-time
@syindexanchor{get-universal-time, SYM}
@syindexanchor{get-decoded-time, SYM}
@subsection get-universal-time, get-decoded-time (Function)
@cindex get-universal-time
@cindex get-decoded-time
@anchor{get-universal-time}
@anchor{get-decoded-time}


@subsubheading Syntax:

@DefunWithValues{get-universal-time, @noargs{}, universal-time}

@DefunWithValuesNewline{get-decoded-time, @noargs{}, second\, minute\, hour\, date\, month\, year\, day\, daylight-p\, zone}

@subsubheading Arguments and Values:

@param{universal-time}---a @term{universal time}.

@param{second}, @param{minute}, @param{hour},
@param{date}, @param{month}, @param{year},
@param{day}, @param{daylight-p}, @param{zone}---a @term{decoded time}.

@subsubheading Description:

@symbolref{get-universal-time, SYM} returns the current time, represented as a @term{universal time}.

@symbolref{get-decoded-time, SYM} returns the current time, represented as a @term{decoded time}.

@subsubheading Examples:

@lisp
;; At noon on July 4, 1976 in Eastern Daylight Time.
 (get-decoded-time) @EV{} 0, 0, 12, 4, 7, 1976, 6, @term{true}, 5
;; At exactly the same instant.
 (get-universal-time) @EV{} 2414332800
;; Exactly five minutes later.
 (get-universal-time) @EV{} 2414333100
;; The difference is 300 seconds (five minutes)
 (- * **) @EV{} 300
@end lisp


@subsubheading Affected By:

The time of day (@ie{} the passage of time),
the system clock's ability to keep accurate time,
and the accuracy of the system clock's initial setting.

@subsubheading Exceptional Situations:

An error @oftype{error} might be signaled if the current time cannot be determined.

@subsubheading See Also:

@ref{decode-universal-time},
@ref{encode-universal-time},
@ref{Time}

@subsubheading Notes:

@lisp
 (get-decoded-time) @EQ{} (decode-universal-time (get-universal-time))
@end lisp


No @term{implementation} is required to have a way to verify that the
time returned is correct.  However, if an @term{implementation} provides
a validity check (@eg{} the failure to have properly initialized the system
clock can be reliably detected) and that validity check fails,
the @term{implementation} is strongly encouraged (but not required)
to signal an error @oftype{error} (rather than, for example, returning a
known-to-be-wrong value) that is @term{correctable} by allowing the user
to interactively set the correct time.


@node sleep
@syindexanchor{sleep, SYM}
@subsection sleep (Function)
@cindex sleep


@subsubheading Syntax:

@DefunWithValues{sleep, seconds, @nil{}}

@subsubheading Arguments and Values:

@param{seconds}---a non-negative @symbolref{real, SYM}.

@subsubheading Description:

Causes execution to cease and become dormant for approximately the
seconds of real time indicated by @param{seconds},
whereupon execution is resumed.

@subsubheading Examples:

@lisp
 (sleep 1) @EV{} NIL

;; Actually, since SLEEP is permitted to use approximate timing,
;; this might not always yield true, but it will often enough that
;; we felt it to be a productive example of the intent.
 (let ((then (get-universal-time))
       (now  (progn (sleep 10) (get-universal-time))))
   (>= (- now then) 10))
@EV{} @term{true}
@end lisp


@subsubheading Side Effects:

Causes processing to pause.

@subsubheading Affected By:

The granularity of the scheduler.

@subsubheading Exceptional Situations:

@Shouldchecktype{seconds, a non-negative @symbolref{real, SYM}}


@node apropos; apropos-list
@syindexanchor{apropos, SYM}
@syindexanchor{apropos-list, SYM}
@subsection apropos, apropos-list (Function)
@cindex apropos-list
@cindex apropos


@subsubheading Syntax:

@DefunWithValues{apropos, string @opt{} package, @novalues{}}

@DefunWithValues{apropos-list, string @opt{} package, symbols}

@subsubheading Arguments and Values:

@param{string}---a @term{@symbolnamedesignator{}}.

@param{package}---a @term{package designator} or @nil{}.
@Default{@nil{}}

@param{symbols}---a @term{list} of @term{symbols}.

@subsubheading Description:

These functions search for @term{interned} @term{symbols}
whose @term{names} contain the substring @param{string}.

For @symbolref{apropos, SYM}, as each such @term{symbol} is found,
its name is printed on @term{standard output}.
In addition,
if such a @term{symbol} is defined as a @term{function} or @term{dynamic variable},
information about those definitions might also be printed.

For @symbolref{apropos-list, SYM},
no output occurs as the search proceeds;
instead a list of the matching @term{symbols} is returned when the search is complete.

If @param{package} is @term{non-nil},
only the @term{symbols} @term{accessible} in that @param{package} are searched;
otherwise all @term{symbols} @term{accessible} in any @term{package} are searched.

Because a @term{symbol} might be available
by way of more than one inheritance path,
@symbolref{apropos, SYM} might print information about the @term{same} @term{symbol} more than once,
or @symbolref{apropos-list, SYM} might return a @term{list} containing duplicate @term{symbols}.

Whether or not the search is case-sensitive is @term{implementation-defined}.

@subsubheading Affected By:

The set of @term{symbols} which are currently @term{interned}
in any @term{packages} being searched.

@symbolref{apropos, SYM} is also affected by @symbolref{*standard-output*, SYM}.


@node describe
@syindexanchor{describe, SYM}
@subsection describe (Function)
@cindex describe


@subsubheading Syntax:

@DefunWithValues{describe, object @opt{} stream, @novalues{}}

@subsubheading Arguments and Values:

@param{object}---an @term{object}.

@param{stream}---an @term{output} @term{stream designator}.
@Default{@term{standard output}}

@subsubheading Description:

@symbolref{describe, SYM} displays information about @param{object}
to @param{stream}.

For example, @symbolref{describe, SYM} of a @term{symbol} might show the
@term{symbol}'s value, its definition, and each of its properties.
@symbolref{describe, SYM} of a @term{float} might show the number's
internal representation in a way that is useful for tracking
down round-off errors.  In all cases, however, the nature and format of the
output of @symbolref{describe, SYM} is @term{implementation-dependent}.

@symbolref{describe, SYM} can describe something that it finds inside the @param{object};
in such cases, a notational device such as increased indentation or positioning in a
table is typically used in order to visually distinguish such recursive descriptions
from descriptions of the argument @param{object}.

The actual act of describing the object is implemented by @symbolref{describe-object, SYM}.
@symbolref{describe, SYM} exists as an interface primarily to manage argument defaulting (including
conversion of arguments @symbolref{t, SC}@spc{}and @nil{}@spc{}into @term{stream} @term{objects}) and to inhibit
any return values from @symbolref{describe-object, SYM}.

@symbolref{describe, SYM} is not intended to be an interactive function.  In a
@term{conforming implementation}, @symbolref{describe, SYM} must not, by default,
prompt for user input.  User-defined methods for @symbolref{describe-object, SYM}
are likewise restricted.

@subsubheading Side Effects:

Output to @term{standard output} or @term{terminal I/O}.

@subsubheading Affected By:

@symbolref{*standard-output*, SYM} and @symbolref{*terminal-io*, SYM},
methods on @symbolref{describe-object, SYM} and @symbolref{print-object, SYM}
for @term{objects} having user-defined @term{classes}.

@subsubheading See Also:

@ref{inspect}, @ref{describe-object}


@node describe-object
@syindexanchor{describe-object, SYM}
@subsection describe-object (Standard Generic Function)
@cindex describe-object



@subsubheading Syntax:

@DefgenWithValues{describe-object, object stream, @term{implementation-dependent}}

@subsubheading Method Signatures:

 describe-object (@param{object} standard-object) @param{stream}

@subsubheading Arguments and Values:

@param{object}---an @term{object}.

@param{stream}---a @term{stream}.

@subsubheading Description:

The generic function @symbolref{describe-object, SYM} prints a description of
@param{object} to a @param{stream}.  @symbolref{describe-object, SYM} is called
by @symbolref{describe, SYM}; it must not be called by the user.

Each implementation is required to provide a @term{method} on
@theclass{standard-object} and @term{methods} on enough other
@term{classes} so as to ensure that there is always an applicable @term{method}.
Implementations are free to add @term{methods} for other @term{classes}.
Users can write @term{methods} for @symbolref{describe-object, SYM} for their
own @term{classes} if they do not wish to inherit an implementation-supplied
@term{method}.

@term{Methods} on @symbolref{describe-object, SYM} can recursively call
@symbolref{describe, SYM}.  Indentation, depth limits, and circularity detection
are all taken care of automatically, provided that each @term{method}
handles exactly one level of structure and calls @symbolref{describe, SYM}
recursively if there are more structural levels.  The consequences are
undefined if this rule is not obeyed.

In some implementations the @param{stream} argument passed to a
@symbolref{describe-object, SYM} method is not the original @param{stream}, but is
an intermediate @term{stream} that implements parts of @symbolref{describe, SYM}.
@term{Methods} should therefore not depend on the identity of this
@term{stream}.


@subsubheading Examples:

@lisp
 (defclass spaceship ()
   ((captain :initarg :captain :accessor spaceship-captain)
    (serial# :initarg :serial-number :accessor spaceship-serial-number)))

 (defclass federation-starship (spaceship) ())

 (defmethod describe-object ((s spaceship) stream)
   (with-slots (captain serial#) s
     (format stream "~&~S is a spaceship of type ~S,~
                     ~%with ~A at the helm ~
                       and with serial number ~D.~%"
             s (type-of s) captain serial#)))

 (make-instance 'federation-starship
                :captain "Rachel Garrett"
                :serial-number "NCC-1701-C")
@EV{} #<FEDERATION-STARSHIP 26312465>

 (describe *)
@OUT{} #<FEDERATION-STARSHIP 26312465> is a spaceship of type FEDERATION-STARSHIP,
@OUT{} with Rachel Garrett at the helm and with serial number NCC-1701-C.
@EV{} @novalues{}
@end lisp


@subsubheading See Also:

@ref{describe}

@subsubheading Notes:

The same implementation techniques that are applicable to @symbolref{print-object, SYM} are
applicable to @symbolref{describe-object, SYM}.

The reason for making the return values for @symbolref{describe-object, SYM}
unspecified is to  avoid forcing users to include explicit @f{(values)}
in all of their @term{methods}.  @symbolref{describe, SYM} takes care of that.



@node trace; untrace
@syindexanchor{trace, SYM}
@syindexanchor{untrace, SYM}
@subsection trace, untrace (Macro)
@cindex trace
@cindex untrace
@anchor{trace}


@subsubheading Syntax:

@DefmacWithValues{trace, @starparam{function-name}, trace-result}
@DefmacWithValues{untrace, @starparam{function-name}, untrace-result}

@subsubheading Arguments and Values:

@param{function-name}---a @term{function name}.

@param{trace-result}---@term{implementation-dependent},
unless no @param{function-names} are supplied,
in which case @param{trace-result} is a @term{list} of @term{function names}.

@param{untrace-result}---@term{implementation-dependent}.

@subsubheading Description:

@symbolref{trace, SYM} and @symbolref{untrace, SYM} control the invocation of the trace facility.

Invoking @symbolref{trace, SYM} with one or more @param{function-names} causes
the denoted @term{functions} to be ``traced.''
Whenever a traced @term{function} is invoked, information
about the call,
about the arguments passed,
and about any eventually returned values
is printed to @term{trace output}.
If @symbolref{trace, SYM} is used with no @param{function-names},
no tracing action is performed;
instead, a list of the @term{functions} currently being traced is returned.

Invoking @symbolref{untrace, SYM} with one or more function names causes those
functions to be ``untraced'' (@ie{} no longer traced).
If @symbolref{untrace, SYM} is used with no @param{function-names},
all @term{functions} currently being traced are untraced.

If a @term{function} to be traced has been open-coded
(@eg{} because it was declared @symbolref{inline, SYM}),
a call to that @term{function} might not produce trace output.

@subsubheading Examples:

@lisp
 (defun fact (n) (if (zerop n) 1 (* n (fact (- n 1)))))
@EV{} FACT
 (trace fact)
@EV{} (FACT)
;; Of course, the format of traced output is implementation-dependent.
 (fact 3)
@OUT{} 1 Enter FACT 3
@OUT{} | 2 Enter FACT 2
@OUT{} |   3 Enter FACT 1
@OUT{} |   | 4 Enter FACT 0
@OUT{} |   | 4 Exit FACT 1
@OUT{} |   3 Exit FACT 1
@OUT{} | 2 Exit FACT 2
@OUT{} 1 Exit FACT 6
@EV{} 6
@end lisp


@subsubheading Side Effects:

Might change the definitions of the @term{functions} named by @param{function-names}.

@subsubheading Affected By:

Whether the functions named are defined or already being traced.

@subsubheading Exceptional Situations:

Tracing an already traced function,
or untracing a function not currently being traced,
should produce no harmful effects, but might signal a warning.

@subsubheading See Also:

@ref{*trace-output*},
@ref{step}

@subsubheading Notes:

@symbolref{trace, SYM} and @symbolref{untrace, SYM} may also accept additional
@term{implementation-dependent} argument formats.  The format of the trace
output is @term{implementation-dependent}.

Although @symbolref{trace, SYM} can be extended to permit non-standard options,
@term{implementations} are nevertheless encouraged (but not required)
to warn about the use of syntax or options
that are neither specified by this standard
nor added as an extension by the @term{implementation},
since they could be symptomatic of typographical errors
or of reliance on features supported in @term{implementations}
other than the current @term{implementation}.


@node step
@syindexanchor{step, SYM}
@subsection step (Macro)
@cindex step


@subsubheading Syntax:

@DefmacWithValues{step, form, @starparam{result}}

@subsubheading Arguments and Values:

@param{form}---a @term{form}; @evalspecial{}.

@param{results}---the @term{values} returned by the @param{form}.

@subsubheading Description:

@symbolref{step, SYM} implements a debugging paradigm wherein the programmer
is allowed to @term{step} through the @term{evaluation} of a @term{form}.
The specific nature of the interaction,
including which I/O streams are used and
whether the stepping has lexical or dynamic scope,
is @term{implementation-defined}.

@symbolref{step, SYM} evaluates @param{form} in the current @term{environment}.
A call to @symbolref{step, SYM} can be compiled, but it is acceptable for an
implementation to interactively step through only those parts of the computation
that are interpreted.

It is technically permissible for a @term{conforming implementation}
to take no action at all other than normal @i{execution} of the @param{form}.
In such a situation,
@f{(step @i{form})}
is equivalent to, for example,
@f{(let () @i{form})}.
In implementations where this is the case, the associated documentation
should mention that fact.

@subsubheading See Also:

@ref{trace}


@subsubheading Notes:

@term{Implementations} are encouraged to respond to the typing of @f{?}
or the pressing of a ``help key'' by providing help including a list of
commands.



@node time (Macro)
@syindexanchor{time, SYM}
@subsection time (Macro)
@cindex time


@subsubheading Syntax:

@DefmacWithValues{time, form, @starparam{result}}

@subsubheading Arguments and Values:

@param{form}---a @term{form}; @evalspecial{}.

@param{results}---the @term{values} returned by the @param{form}.

@subsubheading Description:

@symbolref{time, SYM} evaluates @param{form} in the current @term{environment} (lexical and dynamic).
A call to @symbolref{time, SYM} can be compiled.

@symbolref{time, SYM} prints various timing data and other information to @term{trace output}.
The nature and format of the printed information is @term{implementation-defined}.
Implementations are encouraged to provide such information as
elapsed real time,
machine run time,
and storage management statistics.

@subsubheading Affected By:

The accuracy of the results depends, among other things, on the accuracy
of the corresponding functions provided by the underlying operating system.

The magnitude of the results may depend on
the hardware,
the operating system,
the lisp implementation,
and the state of the global environment.
Some specific issues which frequently affect the outcome are
hardware speed,
nature of the scheduler (if any),
number of competing processes (if any),
system paging,
whether the call is interpreted or compiled,
whether functions called are compiled,
the kind of garbage collector involved and whether it runs,
whether internal data structures (e.g., hash tables) are implicitly reorganized,
@etc{}.

@subsubheading See Also:

@ref{get-internal-real-time},
@ref{get-internal-run-time}

@subsubheading Notes:

In general, these timings are not guaranteed to be reliable enough for
marketing comparisons. Their value is primarily heuristic, for tuning
purposes.

For useful background information on the complicated issues involved in
interpreting timing results, see @GabrielBenchmarks{}.


@node internal-time-units-per-second
@syindexanchor{internal-time-units-per-second, SYM}
@subsection internal-time-units-per-second (Constant Variable)
@cindex internal-time-units-per-second


@subsubheading Constant Value:

A positive @term{integer}, the magnitude of which is @term{implementation-dependent}.

@subsubheading Description:

The number of @term{internal time units} in one second.

@subsubheading See Also:

@ref{get-internal-run-time}, @ref{get-internal-real-time}

@subsubheading Notes:

These units form the basis of the Internal Time format representation.


@node get-internal-real-time
@syindexanchor{get-internal-real-time, SYM}
@subsection get-internal-real-time (Function)
@cindex get-internal-real-time


@subsubheading Syntax:

@DefunWithValues{get-internal-real-time, @noargs{}, internal-time}

@subsubheading Arguments and Values:

@param{internal-time}---a non-negative @term{integer}.

@subsubheading Description:

@symbolref{get-internal-real-time, SYM} returns as an @term{integer} the
current time in @term{internal time units}, relative to an arbitrary
time base.  The difference between the values of two calls to this
function is the amount of elapsed real time (@ie{} clock time) between the two calls.

@subsubheading Affected By:

Time of day (@ie{} the passage of time).
The time base affects the result magnitude.

@subsubheading See Also:

@ref{internal-time-units-per-second}


@node get-internal-run-time
@syindexanchor{get-internal-run-time, SYM}
@subsection get-internal-run-time (Function)
@cindex get-internal-run-time


@subsubheading Syntax:

@DefunWithValues{get-internal-run-time, @noargs{}, internal-time}

@subsubheading Arguments and Values:

@param{internal-time}---a non-negative @term{integer}.

@subsubheading Description:

Returns as an @term{integer} the current
run time in @term{internal time units}.  The precise meaning of this quantity is
@term{implementation-defined};  it may measure real time, run time, CPU cycles, or some
other quantity.  The intent is that the difference between the values of two calls
to this function be the amount of time between the two calls during which
computational effort was expended on behalf of the executing program.

@subsubheading Affected By:

The @term{implementation},
the time of day (@ie{} the passage of time).

@subsubheading See Also:

@ref{internal-time-units-per-second}

@subsubheading Notes:

Depending on the @term{implementation}, paging time and garbage
collection time might be included in this measurement.  Also, in a
multitasking environment, it might not be possible to show the time for
just the running process, so in some @term{implementations}, time taken
by other processes during the same time interval might be included in
this measurement as well.


@node disassemble
@syindexanchor{disassemble, SYM}
@subsection disassemble (Function)
@cindex disassemble


@subsubheading Syntax:

@DefunWithValues{disassemble, fn, @nil{}}

@subsubheading Arguments and Values:

@param{fn}---an @term{extended function designator}
or a @term{lambda expression}.

@subsubheading Description:

@Thefunction{disassemble} is a debugging aid that composes symbolic
instructions or expressions in some @term{implementation-dependent}
language which represent the code used to produce the @term{function}
which is or is named by the argument @param{fn}.  The result is displayed
to @term{standard output} in an @term{implementation-dependent} format.

If @param{fn} is a @term{lambda expression} or @term{interpreted function},
it is compiled first and the result is disassembled.

If the @param{fn} @term{designator} is a @term{function name},
the @term{function} that it @term{names} is disassembled.
(If that @term{function} is an @term{interpreted function},
it is first compiled but the result of this implicit compilation is not installed.)

@subsubheading Examples:
@lisp
 (defun f (a) (1+ a)) @EV{} F
 (eq (symbol-function 'f)
     (progn (disassemble 'f)
            (symbol-function 'f))) @EV{} @term{true}
@end lisp


@subsubheading Affected By:

@symbolref{*standard-output*, SYM}.

@subsubheading Exceptional Situations:

@Shouldchecktype{fn, an @term{extended function designator} or a @term{lambda expression}}



@node documentation; setf documentation
@syindexanchor{documentation, SYM}
@syindexanchor{(setf documentation), SYM}
@subsection documentation, (setf documentation) (Standard Generic Function)
@cindex documentation
@cindex (setf documentation)
@anchor{documentation}



@subsubheading Syntax:

@DefgenWithValues{documentation, x doc-type, documentation}

@DefgenWithValues{(setf documentation), new-value x doc-type, new-value}

@subsubheading Argument Precedence Order:

@param{doc-type}, @param{object}

@subsubheading Method Signatures:



Functions, Macros, and Special Forms

documentation (@var{x} @symbolref{symbol, SYM}) (@var{doc-type} @f{(eql 'symbol)}) symbol

documentation (@var{x} @symbolref{symbol, SYM}) (@var{doc-type} @f{(eql 'symbol)}) symbol

documentation (@var{x} @symbolref{symbol, SYM}) (@var{doc-type} @f{(eql 'symbol)}) symbol

documentation (@var{x} @symbolref{list, SC}) (@var{doc-type} @f{(eql 'list)}) list

documentation (@var{x} @symbolref{list, SC}) (@var{doc-type} @f{(eql 'list)}) list

documentation (@var{x} @symbolref{function, SC}) (@var{doc-type} @f{(eql 'function)}) function

documentation (@var{x} @symbolref{function, SC}) (@var{doc-type} @f{(eql 'function)}) function

(setf documentation) @var{new-value} (@var{x} @symbolref{symbol, SYM}) (@var{doc-type} @f{(eql 'symbol)}) symbol

(setf documentation) @var{new-value} (@var{x} @symbolref{symbol, SYM}) (@var{doc-type} @f{(eql 'symbol)}) symbol

(setf documentation) @var{new-value} (@var{x} @symbolref{symbol, SYM}) (@var{doc-type} @f{(eql 'symbol)}) symbol

(setf documentation) @var{new-value} (@var{x} @symbolref{list, SC}) (@var{doc-type} @f{(eql 'list)}) list

(setf documentation) @var{new-value} (@var{x} @symbolref{list, SC}) (@var{doc-type} @f{(eql 'list)}) list

(setf documentation) @var{new-value} (@var{x} @symbolref{function, SC}) (@var{doc-type} @f{(eql 'function)}) function

(setf documentation) @var{new-value} (@var{x} @symbolref{function, SC}) (@var{doc-type} @f{(eql 'function)}) function



Method Combinations

documentation (@var{x} @symbolref{symbol, SYM}) (@var{doc-type} @f{(eql 'symbol)}) symbol

documentation (@var{x} @symbolref{method-combination, SYM}) (@var{doc-type} @f{(eql 'method-combination)}) method-combination

documentation (@var{x} @symbolref{method-combination, SYM}) (@var{doc-type} @f{(eql 'method-combination)}) method-combination

(setf documentation) @var{new-value} (@var{x} @symbolref{symbol, SYM}) (@var{doc-type} @f{(eql 'symbol)}) symbol

(setf documentation) @var{new-value} (@var{x} @symbolref{method-combination, SYM}) (@var{doc-type} @f{(eql 'method-combination)}) method-combination

(setf documentation) @var{new-value} (@var{x} @symbolref{method-combination, SYM}) (@var{doc-type} @f{(eql 'method-combination)}) method-combination



Methods

documentation (@var{x} @symbolref{standard-method, SYM}) (@var{doc-type} @f{(eql 'standard-method)}) standard-method

(setf documentation) @var{new-value} (@var{x} @symbolref{standard-method, SYM}) (@var{doc-type} @f{(eql 'standard-method)}) standard-method



Packages

documentation (@var{x} @symbolref{package, SYM}) (@var{doc-type} @f{(eql 'package)}) package

(setf documentation) @var{new-value} (@var{x} @symbolref{package, SYM}) (@var{doc-type} @f{(eql 'package)}) package



Types, Classes, and Structure Names

documentation (@var{x} @symbolref{symbol, SYM}) (@var{doc-type} @f{(eql 'symbol)}) symbol

documentation (@var{x} @symbolref{symbol, SYM}) (@var{doc-type} @f{(eql 'symbol)}) symbol

documentation (@var{x} @symbolref{structure-class, SYM}) (@var{doc-type} @f{(eql 'structure-class)}) structure-class

documentation (@var{x} @symbolref{structure-class, SYM}) (@var{doc-type} @f{(eql 'structure-class)}) structure-class

documentation (@var{x} @symbolref{standard-class, SYM}) (@var{doc-type} @f{(eql 'standard-class)}) standard-class

documentation (@var{x} @symbolref{standard-class, SYM}) (@var{doc-type} @f{(eql 'standard-class)}) standard-class

(setf documentation) @var{new-value} (@var{x} @symbolref{symbol, SYM}) (@var{doc-type} @f{(eql 'symbol)}) symbol

(setf documentation) @var{new-value} (@var{x} @symbolref{symbol, SYM}) (@var{doc-type} @f{(eql 'symbol)}) symbol

(setf documentation) @var{new-value} (@var{x} @symbolref{structure-class, SYM}) (@var{doc-type} @f{(eql 'structure-class)}) structure-class

(setf documentation) @var{new-value} (@var{x} @symbolref{structure-class, SYM}) (@var{doc-type} @f{(eql 'structure-class)}) structure-class

(setf documentation) @var{new-value} (@var{x} @symbolref{standard-class, SYM}) (@var{doc-type} @f{(eql 'standard-class)}) standard-class

(setf documentation) @var{new-value} (@var{x} @symbolref{standard-class, SYM}) (@var{doc-type} @f{(eql 'standard-class)}) standard-class



Variables

documentation (@var{x} @symbolref{symbol, SYM}) (@var{doc-type} @f{(eql 'symbol)}) symbol

(setf documentation) @var{new-value} (@var{x} @symbolref{symbol, SYM}) (@var{doc-type} @f{(eql 'symbol)}) symbol




@subsubheading Arguments and Values:

@param{x}---an @term{object}.

@param{doc-type}---a @term{symbol}.

@param{documentation}---a @term{string}, or @nil{}.

@param{new-value}---a @term{string}.

@subsubheading Description:

@TheGF{documentation} returns the @term{documentation string}
associated with the given @term{object} if it is available;
otherwise it returns @nil{}.

The @term{generic function} @f{(setf documentation)} updates the
@term{documentation string} associated with @param{x} to @param{new-value}.
If @param{x} is a @term{list},
it must be of the form @f{(setf @param{symbol})}.

@term{Documentation strings} are made available for debugging purposes.
@term{Conforming programs} are permitted to use @term{documentation strings}
when they are present, but should not depend for their correct behavior on
the presence of those @term{documentation strings}.
An @term{implementation} is permitted to discard @term{documentation strings}
at any time for @term{implementation-defined} reasons.

The nature of the @term{documentation string} returned depends on the
@param{doc-type}, as follows:


@table @asis

@item @id{@t{compiler-macro}}


Returns the @term{documentation string} of the @term{compiler macro}
whose @term{name} is the @term{function name} @param{x}.

@item @id{@t{function}}


If @param{x} is a @term{function name},
returns the @term{documentation string} of
the @term{function}, @term{macro}, or @term{special operator}
whose @term{name} is @param{x}.

If @param{x} is a @term{function},
returns the @term{documentation string} associated with @param{x}.

@item @id{@t{method-combination}}


If @param{x} is a @term{symbol},
returns the @term{documentation string} of
the @term{method combination}
whose @term{name} is @param{x}.

If @param{x} is a @term{method combination},
returns the @term{documentation string} associated with @param{x}.

@item @id{@t{setf}}


Returns the @term{documentation string} of
the @term{setf expander}
whose @term{name} is the @term{symbol} @param{x}.

@item @id{@t{structure}}


Returns the @term{documentation string}
associated with the @term{structure name} @param{x}.

@item @id{@t{t}}


Returns a @term{documentation string} specialized on the @term{class} of
the argument @param{x} itself.
For example, if @param{x} is a @term{function},
the @term{documentation string} associated with the @term{function} @param{x} is returned.

@item @id{@t{type}}


If @param{x} is a @term{symbol},
returns the @term{documentation string} of the @term{class}
whose @term{name} is the @term{symbol} @param{x},
if there is such a @term{class}.
Otherwise, it returns the @term{documentation string} of the @term{type}
which is the @term{type specifier} @term{symbol} @param{x}.

If @param{x} is a @term{structure class} or @term{standard class},
returns the @term{documentation string} associated with
the @term{class} @param{x}.

@item @id{@t{variable}}


Returns the @term{documentation string} of
the @term{dynamic variable} or @term{constant variable}
whose @term{name} is the @term{symbol} @param{x}.
@end table


A @term{conforming implementation} or a @term{conforming program}
may extend the set of @term{symbols} that are acceptable as the @param{doc-type}.

@subsubheading Notes:

This standard prescribes no means to retrieve the @term{documentation strings}
for individual slots specified in a @symbolref{defclass, SYM} form, but
@term{implementations} might still provide debugging tools and/or
programming language extensions which manipulate this information.
Implementors wishing to provide such support are encouraged to consult the
@term{Metaobject Protocol} for suggestions about how this might be done.



@node room
@syindexanchor{room, SYM}
@subsection room (Function)
@cindex room


@subsubheading Syntax:

@DefunWithValues{room, @opt{} x, @term{implementation-dependent}}

@subsubheading Arguments and Values:

@param{x}---one of @symbolref{t, SC}, @nil{}, or @kwd{default}.

@subsubheading Description:

@symbolref{room, SYM} prints, to @term{standard output},
information about the state of internal storage and its management.
This might include descriptions of the amount of memory in use and
the degree of memory compaction, possibly broken down by internal data type if that
is appropriate.  The nature and format of the printed information is
@term{implementation-dependent}.
The intent is to provide information that a @term{programmer}
might use to tune a @term{program} for a particular @term{implementation}.

@f{(room nil)} prints out a minimal amount of information.
@f{(room t)} prints out a maximal amount of information.
@f{(room)} or @f{(room :default)} prints out an intermediate amount
of information that is likely to be useful.

@subsubheading Side Effects:

Output to @term{standard output}.

@subsubheading Affected By:

@symbolref{*standard-output*, SYM}.


@node ed
@syindexanchor{ed, SYM}
@subsection ed (Function)
@cindex ed


@subsubheading Syntax:

@DefunWithValues{ed, @opt{} x, @term{implementation-dependent}}

@subsubheading Arguments and Values:

@param{x}---@nil{}, a @term{pathname}, a @term{string}, or a @term{function name}.
@Default{@nil{}}

@subsubheading Description:

@symbolref{ed, SYM} invokes the editor if the @term{implementation} provides a resident editor.

If @param{x} is @nil{}, the editor is entered.
If the editor had been previously entered, its prior state is resumed, if possible.

If @param{x} is a @term{pathname} or @term{string},
it is taken as the @term{pathname designator} for a @term{file} to be edited.

If @param{x} is a @term{function name}, the text of its definition is edited.
The means by which the function text is obtained is @term{implementation-defined}.

@subsubheading Exceptional Situations:

The consequences are undefined if the @term{implementation} does not provide a resident editor.

Might signal @symbolref{type-error, SYM} if its argument is supplied but is not
a @term{symbol}, a @term{pathname}, or @nil{}.

If a failure occurs when performing some operation on the @term{file system}
while attempting to edit a @term{file},
an error @oftype{file-error} is signaled.

An error @oftype{file-error} might be signaled if @param{x}
is a @term{designator} for a @term{wild} @term{pathname}.

@term{Implementation-dependent} additional conditions might be signaled as well.

@subsubheading See Also:

@ref{pathname (System Class)},
@ref{logical-pathname (System Class)},
@ref{compile-file},
@ref{load},
@ref{Pathnames as Filenames}



@node inspect
@syindexanchor{inspect, SYM}
@subsection inspect (Function)
@cindex inspect


@subsubheading Syntax:

@DefunWithValues{inspect, object, @term{implementation-dependent}}

@subsubheading Arguments and Values:

@param{object}---an @term{object}.

@subsubheading Description:

@symbolref{inspect, SYM} is an interactive version of @symbolref{describe, SYM}.
The nature of the interaction is @term{implementation-dependent},
but the purpose of @symbolref{inspect, SYM} is to make it easy to wander
through a data structure, examining and modifying parts of it.

@subsubheading Side Effects:

@term{implementation-dependent}.

@subsubheading Affected By:

@term{implementation-dependent}.

@subsubheading Exceptional Situations:

@term{implementation-dependent}.

@subsubheading See Also:

@ref{describe}

@subsubheading Notes:

Implementations are encouraged to respond to the typing
of @f{?} or a ``help key'' by providing help, including a list
of commands.


@node dribble
@syindexanchor{dribble, SYM}
@subsection dribble (Function)
@cindex dribble


@subsubheading Syntax:

@DefunWithValues{dribble, @opt{} pathname, @term{implementation-dependent}}

@subsubheading Arguments and Values:

@param{pathname}---a @term{pathname designator}.

@subsubheading Description:

Either @term{binds} @symbolref{*standard-input*, SYM} and @symbolref{*standard-output*, SYM}
or takes other appropriate action,
so as to send a record of the input/output interaction to a file
named by @param{pathname}.  @symbolref{dribble, SYM} is intended to create
a readable record of an interactive session.

If @param{pathname} is a @term{logical pathname}, it is translated
into a physical pathname as if by calling @symbolref{translate-logical-pathname, SYM}.

@f{(dribble)} terminates the recording of input and output
and closes the dribble file.

If @symbolref{dribble, SYM} is @term{called} while a @term{stream} to a ``dribble file''
is still open from a previous @term{call} to @symbolref{dribble, SYM},
the effect is @term{implementation-defined}.  For example,
the already-@term{open} @term{stream} might be @term{closed},
or dribbling might occur both to the old @term{stream} and to a new one,
or the old @term{stream} might stay open but not receive any further output,
or the new request might be ignored,
or some other action might be taken.

@subsubheading Affected By:

The @term{implementation}.

@subsubheading Exceptional Situations:

If a failure occurs when performing some operation on the @term{file system}
while creating the dribble file,
an error @oftype{file-error} is signaled.

An error @oftype{file-error} might be signaled if @param{pathname}
is a @term{designator} for a @term{wild} @term{pathname}.

@subsubheading See Also:

@ref{Pathnames as Filenames}

@subsubheading Notes:


@symbolref{dribble, SYM} can return before subsequent
@term{forms} are executed. It also
can enter a recursive interaction loop,
returning only when @f{(dribble)} is done.

@symbolref{dribble, SYM} is intended primarily for interactive debugging;
its effect cannot be relied upon when used in a program.

@node - (Variable)
@syindexanchor{-, V}
@subsection - (Variable)
@cindex -


@subsubheading Value Type:

a @term{form}.

@subsubheading Initial Value:

@term{implementation-dependent}.

@subsubheading Description:

@Thevalueof{-} is the @term{form} that is currently being evaluated by
the @term{Lisp read-eval-print loop}.

@subsubheading Examples:

@lisp
(format t "~&Evaluating ~S~%" -)
@OUT{} Evaluating (FORMAT T "~&Evaluating ~S~%" -)
@EV{} NIL
@end lisp


@subsubheading Affected By:

@term{Lisp read-eval-print loop}.

@subsubheading See Also:

@ref{+ (Function)} (@term{variable}),
@ref{* (Function)} (@term{variable}),
@ref{/ (Function)} (@term{variable}),
@ref{Top level loop}


@node +; ++; +++
@syindexanchor{+, V}
@syindexanchor{++, SYM}
@syindexanchor{+++, SYM}
@subsection +, ++, +++ (Variable)
@cindex +
@cindex +++
@cindex ++


@subsubheading Value Type:

an @term{object}.

@subsubheading Initial Value:

@term{implementation-dependent}.

@subsubheading Description:

@Thevariables{+}, @t{++}, and @t{+++} are maintained by the
@term{Lisp read-eval-print loop} to save @term{forms} that were
recently @term{evaluated}.

@Thevalueof{+}   is the last @term{form} that was @term{evaluated},
@thevalueof{++}  is the previous value of @t{+}, and
@thevalueof{+++} is the previous value of @t{++}.

@subsubheading Examples:
@lisp
(+ 0 1) @EV{} 1
(- 4 2) @EV{} 2
(/ 9 3) @EV{} 3
(list + ++ +++) @EV{} ((/ 9 3) (- 4 2) (+ 0 1))
(setq a 1 b 2 c 3 d (list a b c)) @EV{} (1 2 3)
(setq a 4 b 5 c 6 d (list a b c)) @EV{} (4 5 6)
(list a b c) @EV{} (4 5 6)
(eval +++) @EV{} (1 2 3)
#.`(,@@++ d) @EV{} (1 2 3 (1 2 3))
@end lisp


@subsubheading Affected By:

@term{Lisp read-eval-print loop}.

@subsubheading See Also:

@ref{- (Function)} (@term{variable}),
@ref{* (Function)} (@term{variable}),
@ref{/ (Function)} (@term{variable}),
@ref{Top level loop}


@node *; **; ***
@syindexanchor{*, V}
@syindexanchor{**, SYM}
@syindexanchor{***, SYM}
@subsection *, **, *** (Variable)
@cindex **
@cindex ***
@cindex *


@subsubheading Value Type:

an @term{object}.

@subsubheading Initial Value:

@term{implementation-dependent}.

@subsubheading Description:

@Thevariables{*}, @t{**}, and @t{***} are
maintained by the @term{Lisp read-eval-print loop} to save the
values of results that are printed each time through the loop.

@Thevalueof{*}   is the most recent @term{primary value} that was printed,
@thevalueof{**}  is the previous value of @t{*}, and
@thevalueof{***} is the previous value of @t{**}.

If several values are produced, @t{*} contains the first value only;
@t{*} contains @nil{}@spc{}if zero values are produced.

The @term{values} of @t{*}, @t{**}, and @t{***} are updated immediately
prior to printing the @term{return value} of a top-level @term{form} by the
@term{Lisp read-eval-print loop}.  If the @term{evaluation} of such a @term{form}
is aborted prior to its normal return, the values of @t{*}, @t{**}, and @t{***}
are not updated.

@subsubheading Examples:
@lisp
(values 'a1 'a2) @EV{} A1, A2
'b @EV{} B
(values 'c1 'c2 'c3) @EV{} C1, C2, C3
(list * ** ***) @EV{} (C1 B A1)

(defun cube-root (x) (expt x 1/3)) @EV{} CUBE-ROOT
(compile *) @EV{} CUBE-ROOT
(setq a (cube-root 27.0)) @EV{} 3.0
(* * 9.0) @EV{} 27.0
@end lisp


@subsubheading Affected By:

@term{Lisp read-eval-print loop}.

@subsubheading See Also:

@ref{- (Function)} (@term{variable}),
@ref{+ (Function)} (@term{variable}),
@ref{/ (Function)} (@term{variable}),
@ref{Top level loop}

@subsubheading Notes:

@lisp
 *   @EQ{} (car /)
 **  @EQ{} (car //)
 *** @EQ{} (car ///)
@end lisp



@node /; //; ///
@syindexanchor{/, V}
@syindexanchor{//, SYM}
@syindexanchor{///, SYM}
@subsection /, //, /// (Variable)
@cindex //
@cindex ///
@cindex /


@subsubheading Value Type:

a @term{proper list}.

@subsubheading Initial Value:

@term{implementation-dependent}.

@subsubheading Description:

@Thevariables{/}, @t{//}, and @t{///} are maintained by
the @term{Lisp read-eval-print loop} to save the values of results that
were printed at the end of the loop.

@Thevalueof{/}   is a @term{list} of the most recent @term{values} that were printed,
@thevalueof{//}  is the previous value of @t{/}, and
@thevalueof{///} is the previous value of @t{//}.

The @term{values} of @t{/}, @t{//}, and @t{///} are updated immediately
prior to printing the @term{return value} of a top-level @term{form} by the
@term{Lisp read-eval-print loop}.  If the @term{evaluation} of such a @term{form}
is aborted prior to its normal return, the values of @t{/}, @t{//}, and @t{///}
are not updated.

@subsubheading Examples:
@lisp
 (floor 22 7) @EV{} 3, 1
 (+ (* (car /) 7) (cadr /)) @EV{} 22
@end lisp


@subsubheading Affected By:

@term{Lisp read-eval-print loop}.

@subsubheading See Also:

@ref{- (Function)} (@term{variable}),
@ref{+ (Function)} (@term{variable}),
@ref{* (Function)} (@term{variable}),
@ref{Top level loop}


@node lisp-implementation-type; lisp-implementation-version
@syindexanchor{lisp-implementation-type, SYM}
@syindexanchor{lisp-implementation-version, SYM}
@subsection lisp-implementation-type, lisp-implementation-version (Function)
@cindex lisp-implementation-version
@cindex lisp-implementation-type


@subsubheading Syntax:

@DefunWithValues{lisp-implementation-type, @noargs{}, description}

@DefunWithValues{lisp-implementation-version, @noargs{}, description}

@subsubheading Arguments and Values:

@param{description}---a @term{string} or @nil{}.

@subsubheading Description:

@symbolref{lisp-implementation-type, SYM} and @symbolref{lisp-implementation-version, SYM}
identify the current implementation of @clisp{}.

@symbolref{lisp-implementation-type, SYM} returns a @term{string}
that identifies the generic name of
the particular @clisp{}@spc{}implementation.

@symbolref{lisp-implementation-version, SYM}
returns a @term{string} that identifies the version of
the particular @clisp{}@spc{}implementation.

If no appropriate
and relevant result can be produced, @nil{}@spc{}is returned instead
of a @term{string}.

@subsubheading Examples:

@lisp
 (lisp-implementation-type)
@EV{} "ACME Lisp"
@OV{} "Joe's Common Lisp"
 (lisp-implementation-version)
@EV{} "1.3a"
@EV{} "V2"
@OV{} "Release 17.3, ECO #6"
@end lisp



@node short-site-name; long-site-name
@syindexanchor{short-site-name, SYM}
@syindexanchor{long-site-name, SYM}
@subsection short-site-name, long-site-name (Function)
@cindex short-site-name
@cindex long-site-name


@subsubheading Syntax:

@DefunWithValues{short-site-name, @noargs{}, description}

@DefunWithValues{long-site-name, @noargs{}, description}

@subsubheading Arguments and Values:

@param{description}---a @term{string} or @nil{}.

@subsubheading Description:

@symbolref{short-site-name, SYM} and @symbolref{long-site-name, SYM} return
a @term{string} that identifies the physical location
of the computer hardware,
or @nil{}@spc{}if no appropriate @param{description} can be produced.

@subsubheading Examples:

@lisp
 (short-site-name)
@EV{} "MIT AI Lab"
@OV{} "CMU-CSD"
 (long-site-name)
@EV{} "MIT Artificial Intelligence Laboratory"
@OV{} "CMU Computer Science Department"
@end lisp


@subsubheading Affected By:

The implementation,
the location of the computer hardware,
and the installation/configuration process.


@node machine-instance
@syindexanchor{machine-instance, SYM}
@subsection machine-instance (Function)
@cindex machine-instance


@subsubheading Syntax:

@DefunWithValues{machine-instance, @noargs{}, description}

@subsubheading Arguments and Values:

@param{description}---a @term{string} or @nil{}.

@subsubheading Description:

Returns a @term{string} that identifies the particular instance of
the computer hardware on which @clisp{}@spc{}is running,
or @nil{}@spc{}if no such @term{string} can be computed.

@subsubheading Examples:

@lisp
 (machine-instance)
@EV{} "ACME.COM"
@OV{} "S/N 123231"
@OV{} "18.26.0.179"
@OV{} "AA-00-04-00-A7-A4"
@end lisp


@subsubheading Affected By:

The machine instance,
and the @term{implementation}.

@subsubheading See Also:

@ref{machine-type}, @ref{machine-version}


@node machine-type
@syindexanchor{machine-type, SYM}
@subsection machine-type (Function)
@cindex machine-type


@subsubheading Syntax:

@DefunWithValues{machine-type, @noargs{}, description}

@subsubheading Arguments and Values:

@param{description}---a @term{string} or @nil{}.

@subsubheading Description:

Returns a @term{string} that identifies the generic name of
the computer hardware on which @clisp{}@spc{}is running.

@subsubheading Examples:

@lisp
 (machine-type)
@EV{} "DEC PDP-10"
@OV{} "Symbolics LM-2"
@end lisp


@subsubheading Affected By:

The machine type.
The implementation.

@subsubheading See Also:

@ref{machine-version}


@node machine-version
@syindexanchor{machine-version, SYM}
@subsection machine-version (Function)
@cindex machine-version


@subsubheading Syntax:

@DefunWithValues{machine-version, @noargs{}, description}

@subsubheading Arguments and Values:

@param{description}---a @term{string} or @nil{}.

@subsubheading Description:

Returns a @term{string} that identifies the version of the computer hardware
on which @clisp{}@spc{}is running, or @nil{}@spc{}if no such value can be computed.

@subsubheading Examples:

@lisp
 (machine-version) @EV{} "KL-10, microcode 9"
@end lisp


@subsubheading Affected By:

The machine version,
and the @term{implementation}.

@subsubheading See Also:

@ref{machine-type}, @ref{machine-instance}


@node software-type; software-version
@syindexanchor{software-type, SYM}
@syindexanchor{software-version, SYM}
@subsection software-type, software-version (Function)
@cindex software-type
@cindex software-version


@subsubheading Syntax:

@DefunWithValues{software-type, @noargs{}, description}
@DefunWithValues{software-version, @noargs{}, description}

@subsubheading Arguments and Values:

@param{description}---a @term{string} or @nil{}.

@subsubheading Description:

@symbolref{software-type, SYM} returns a @term{string} that identifies the
generic name of any relevant supporting software, or @nil{}@spc{}if no
appropriate or relevant result can be produced.

@symbolref{software-version, SYM} returns a @term{string} that identifies
the version of any relevant supporting software, or @nil{}@spc{}if no
appropriate or relevant result can be produced.

@subsubheading Examples:

@lisp
 (software-type) @EV{} "Multics"
 (software-version) @EV{} "1.3x"
@end lisp


@subsubheading Affected By:

Operating system environment.

@subsubheading Notes:

This information should be of use to maintainers of the @term{implementation}.


@node user-homedir-pathname
@syindexanchor{user-homedir-pathname, SYM}
@subsection user-homedir-pathname (Function)
@cindex user-homedir-pathname


@subsubheading Syntax:

@DefunWithValues{user-homedir-pathname, @opt{} host, pathname}

@subsubheading Arguments and Values:

@param{host}---a @term{string}, a @term{list} of @term{strings}, or @kwd{unspecific}.

@param{pathname}---a @term{pathname}, or @nil{}.

@subsubheading Description:

@symbolref{user-homedir-pathname, SYM} determines the @term{pathname} that corresponds
to the user's home directory on @param{host}.
If @param{host} is not supplied, its value is @term{implementation-dependent}.
For a description of @kwd{unspecific}, see @ref{Pathname Components}.

The definition of home directory is @term{implementation-dependent},
but defined in @clisp{}@spc{}to mean the directory where the user
keeps personal files such as initialization files and mail.

@symbolref{user-homedir-pathname, SYM} returns a @term{pathname} without any name,
type, or version component (those components are all @nil{})
for the user's home directory on @param{host}.

If it is impossible to determine the user's home directory on @param{host},
then @nil{}@spc{}is returned.
@symbolref{user-homedir-pathname, SYM} never returns @nil{}@spc{}if @param{host} is not supplied.

@subsubheading Examples:

@lisp
 (pathnamep (user-homedir-pathname)) @EV{} @term{true}
@end lisp


@subsubheading Affected By:

The host computer's file system,
and the @term{implementation}.