dotfiles/gcl-info/chap-25.texi

@node Environment, Glossary (Glossary), System Construction, Top
@chapter Environment

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

@node The External Environment, Environment Dictionary, Environment, Environment
@section The External Environment

@c including concept-environment

@menu
* Top level loop::		
* Debugging Utilities::		
* Environment Inquiry::		
* Time::			
@end menu

@node Top level loop, Debugging Utilities, The External Environment, The External Environment
@subsection Top level loop

The top level loop is the @r{Common Lisp} mechanism by which the user normally
interacts with the @r{Common Lisp} system. This loop is sometimes referred to 
as the @i{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 @i{implementation-defined}.
The top level loop 
prints all values resulting from the evaluation of a 
@i{form}.
Figure 25--1 lists variables that are maintained by the @i{Lisp read-eval-print loop}.

@group
@noindent
@w{  *    +    /    -  }
@w{  **   ++   //      }
@w{  ***  +++  ///     }

@noindent
@w{  Figure 25--1: Variables maintained by the Read-Eval-Print Loop}

@end group

@node Debugging Utilities, Environment Inquiry, Top level loop, The External Environment
@subsection Debugging Utilities

Figure 25--2 shows @i{defined names} relating to
debugging.

@group
@noindent
@w{  *debugger-hook*  documentation    step     }
@w{  apropos          dribble          time     }
@w{  apropos-list     ed               trace    }
@w{  break            inspect          untrace  }
@w{  describe         invoke-debugger           }

@noindent
@w{  Figure 25--2: Defined names relating to debugging}

@end group

@node Environment Inquiry, Time, Debugging Utilities, The External Environment
@subsection Environment Inquiry

Environment inquiry @i{defined names} provide information about
the hardware and software configuration on which a @r{Common Lisp} program is
being executed.

Figure 25--3 shows @i{defined names} relating to environment inquiry.

@group
@noindent
@w{  *features*                   machine-instance  short-site-name   }
@w{  lisp-implementation-type     machine-type      software-type     }
@w{  lisp-implementation-version  machine-version   software-version  }
@w{  long-site-name               room                                }

@noindent
@w{    Figure 25--3: Defined names relating to environment inquiry.   }

@end group

@node Time,  , Environment Inquiry, The External Environment
@subsection Time

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

Figure 25--4 shows @i{defined names} relating to @i{time}.

@group
@noindent
@w{  decode-universal-time   get-internal-run-time           }
@w{  encode-universal-time   get-universal-time              }
@w{  get-decoded-time        internal-time-units-per-second  }
@w{  get-internal-real-time  sleep                           }

@noindent
@w{        Figure 25--4: Defined names involving Time.       }

@end group

@menu
* Decoded Time::		
* Universal Time::		
* Internal Time::		
* Seconds::			
@end menu

@node Decoded Time, Universal Time, Time, Time
@subsubsection Decoded Time

A @i{decoded time}
@IGindex{decoded time}
 is an ordered series of nine values that, taken together,
represent a point in calendar time (ignoring @i{leap seconds}):

@table @asis

@item @b{Second}  
An @i{integer} between 0 and~59, inclusive.

@item @b{Minute}  
An @i{integer} between 0 and~59, inclusive.

@item @b{Hour}  
An @i{integer} between 0 and~23, inclusive.

@item @b{Date}  
An @i{integer} between 1 and~31, inclusive (the upper limit actually
depends on the month and year, of course).

@item @b{Month}  
An @i{integer} between 1 and 12, inclusive;
1~means January, 2~means February, and so on; 12~means December.

@item @b{Year}  
An @i{integer} indicating the year A.D.  However, if this 
@i{integer}
is between 0 and 99, the ``obvious'' year is used; more precisely,
that year is assumed that is equal to the 
@i{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 @b{Day of week}  
An @i{integer} between~0 and~6, inclusive;
0~means Monday, 1~means Tuesday, and so on; 6~means Sunday.

@item @b{Daylight saving time flag}  
A @i{generalized boolean} that,
if @i{true}, indicates that daylight saving time is in effect.

@item @b{Time zone}  
A @i{time zone}.

@end table

Figure 25--5 shows @i{defined names} relating to @i{decoded time}.

@group
@noindent
@w{  decode-universal-time  get-decoded-time  }

@noindent
@w{  Figure 25--5: Defined names involving time in Decoded Time.}

@end group

@node Universal Time, Internal Time, Decoded Time, Time
@subsubsection Universal Time

@i{Universal time}
@IGindex{universal time}
 is an @i{absolute} @i{time} represented as a
single non-negative @i{integer}---the number of seconds since
midnight, January 1, 1900 GMT (ignoring @i{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
@r{Common Lisp}, 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 @i{universal time} must be a non-negative @i{integer},
times before the base time of midnight, January 1, 1900 GMT cannot be processed by @r{Common Lisp}.

@group
@noindent
@w{  decode-universal-time  get-universal-time  }
@w{  encode-universal-time                      }

@noindent
@w{  Figure 25--6: Defined names involving time in Universal Time.}

@end group

@node Internal Time, Seconds, Universal Time, Time
@subsubsection Internal Time

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

Figure 25--7 shows @i{defined names} related to @i{internal time}.

@group
@noindent
@w{  get-internal-real-time  internal-time-units-per-second  }
@w{  get-internal-run-time                                   }

@noindent
@w{  Figure 25--7: Defined names involving time in Internal Time.}

@end group

@node Seconds,  , Internal Time, Time
@subsubsection Seconds

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

@group
@noindent
@w{  sleep    }

@noindent
@w{  Figure 25--8: Defined names involving time in Seconds.}

@end group

@c end of including concept-environment

@node Environment Dictionary,  , The External Environment, Environment
@section Environment Dictionary

@c including dict-environment

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

@node decode-universal-time, encode-universal-time, Environment Dictionary, Environment Dictionary
@subsection decode-universal-time                                            [Function]

@code{decode-universal-time}  @i{universal-time {&optional} time-zone}@*
   @result{}  @i{second, minute, hour, date, month, year, day, daylight-p, zone}

@subsubheading  Arguments and Values::

@i{universal-time}---a @i{universal time}.

@i{time-zone}---a @i{time zone}.

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

@subsubheading  Description::

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

If @i{time-zone} is not supplied,
it defaults to the current time zone adjusted for daylight saving time.  

If @i{time-zone} is supplied, daylight saving time information is ignored.
The daylight saving time flag is @b{nil} if @i{time-zone} is supplied.

@subsubheading  Examples::

@example
 (decode-universal-time 0 0) @result{}  0, 0, 0, 1, 1, 1900, 0, @i{false}, 0

;; The next two examples assume Eastern Daylight Time.
 (decode-universal-time 2414296800 5) @result{}  0, 0, 1, 4, 7, 1976, 6, @i{false}, 5
 (decode-universal-time 2414293200) @result{}  0, 0, 1, 4, 7, 1976, 6, @i{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))) @result{}  ((T 5) (NIL 5) NIL)
@end example

@subsubheading  Affected By::

@i{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; get-decoded-time}
, 
@ref{Time}

@node encode-universal-time, get-universal-time, decode-universal-time, Environment Dictionary
@subsection encode-universal-time                                            [function]

@subsubheading  Syntax::

@code{encode-universal-time}  @i{second minute hour date month year
                               {&optional} time-zone}@*
   @result{}  @i{universal-time}

@subsubheading  Arguments and Values::

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

@i{universal-time}---a @i{universal time}.

@subsubheading  Description::

@b{encode-universal-time} converts a time from Decoded Time format
to a @i{universal time}.

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

@subsubheading  Examples::

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

@subsubheading  See Also::

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

@node get-universal-time, sleep, encode-universal-time, Environment Dictionary
@subsection get-universal-time, get-decoded-time                             [Function]

@code{get-universal-time}  @i{<@i{no @i{arguments}}>} @result{}  @i{universal-time}

@code{get-decoded-time}  @i{<@i{no @i{arguments}}>}@*
   @result{}  @i{second, minute, hour, date, month, year, day, daylight-p, zone}

@subsubheading  Arguments and Values::

@i{universal-time}---a @i{universal time}.

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

@subsubheading  Description::

@b{get-universal-time} returns the current time, represented as a @i{universal time}.

@b{get-decoded-time} returns the current time, represented as a @i{decoded time}.

@subsubheading  Examples::

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

@subsubheading  Affected By::

The time of day (@i{i.e.}, 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 of @i{type} @b{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::

@example
 (get-decoded-time) @equiv{} (decode-universal-time (get-universal-time))
@end example

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

@node sleep, apropos, get-universal-time, Environment Dictionary
@subsection sleep                                                            [Function]

@code{sleep}  @i{seconds} @result{}  @i{@b{nil}}

@subsubheading  Arguments and Values::

@i{seconds}---a non-negative @i{real}.

@subsubheading  Description::

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

@subsubheading  Examples::

@example
 (sleep 1) @result{}  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))
@result{}  @i{true}
@end example

@subsubheading  Side Effects::

Causes processing to pause.

@subsubheading  Affected By::

The granularity of the scheduler.

@subsubheading  Exceptional Situations::

Should signal an error of @i{type} @b{type-error}
			      if @i{seconds} is not a non-negative @i{real}.

@node apropos, describe, sleep, Environment Dictionary
@subsection apropos, apropos-list                                            [Function]

@code{apropos}  @i{string {&optional} package} @result{}  @i{<@i{no @i{values}}>}

@code{apropos-list}  @i{string {&optional} package} @result{}  @i{symbols}

@subsubheading  Arguments and Values::

@i{string}---a @i{string designator}.

@i{package}---a @i{package designator} or @b{nil}.
 The default is @b{nil}.

@i{symbols}---a @i{list} of @i{symbols}.

@subsubheading  Description::

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

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

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

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

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

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

@subsubheading  Affected By::

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

@b{apropos} is also affected by @b{*standard-output*}.

@node describe, describe-object, apropos, Environment Dictionary
@subsection describe                                                         [Function]

@code{describe}  @i{object {&optional} stream} @result{}  @i{<@i{no @i{values}}>}

@subsubheading  Arguments and Values::

@i{object}---an @i{object}.

@i{stream}---an @i{output} @i{stream designator}.
 The default is @i{standard output}.

@subsubheading  Description::

@b{describe} displays information about @i{object}

to @i{stream}.

For example, @b{describe} of a @i{symbol} might show the
@i{symbol}'s value, its definition, and each of its properties. 
@b{describe} of a @i{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 @b{describe} is @i{implementation-dependent}.

@b{describe} can describe something that it finds inside the @i{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 @i{object}.

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

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

@subsubheading  Side Effects::

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

@subsubheading  Affected By::

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

@subsubheading  See Also::

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

@node describe-object, trace, describe, Environment Dictionary
@subsection describe-object                                 [Standard Generic Function]

@subsubheading  Syntax::

@code{describe-object}  @i{object stream} @result{}  @i{@i{implementation-dependent}}

@subsubheading  Method Signatures::

@code{describe-object}  @i{(@i{object} standard-object) @i{stream}}

@subsubheading  Arguments and Values::

@i{object}---an @i{object}.

@i{stream}---a @i{stream}.

@subsubheading  Description::

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

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

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

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

@subsubheading  Examples::

@example
 (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,~
                     ~
                       and with serial number ~D.~
             s (type-of s) captain serial#)))

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

 (describe *)
@t{ |> } #<FEDERATION-STARSHIP 26312465> is a spaceship of type FEDERATION-STARSHIP,
@t{ |> } with Rachel Garrett at the helm and with serial number NCC-1701-C.
@result{}  <@i{no @i{values}}>
@end example

@subsubheading  See Also::

@ref{describe}

@subsubheading  Notes::

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

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

@node trace, step, describe-object, Environment Dictionary
@subsection trace, untrace                                                      [Macro]

@code{trace}  @i{@{@i{function-name}@}{*}} @result{}  @i{trace-result}

@code{untrace}  @i{@{@i{function-name}@}{*}} @result{}  @i{untrace-result}

@subsubheading  Arguments and Values::

@i{function-name}---a @i{function name}.

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

@i{untrace-result}---@i{implementation-dependent}.

@subsubheading  Description::

@b{trace} and @b{untrace} control the invocation of the trace facility.  

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

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

If a @i{function} to be traced has been open-coded
(@i{e.g.}, because it was declared @b{inline}),
a call to that @i{function} might not produce trace output.

@subsubheading  Examples::

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

@subsubheading  Side Effects::

Might change the definitions of the @i{functions} named by @i{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::

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

@subsubheading  Notes::

@b{trace} and @b{untrace} may also accept additional
@i{implementation-dependent} argument formats.  The format of the trace
output is @i{implementation-dependent}.

Although @b{trace} can be extended to permit non-standard options,
@i{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 @i{implementation},
since they could be symptomatic of typographical errors
or of reliance on features supported in @i{implementations} 
other than the current @i{implementation}.

@node step, time, trace, Environment Dictionary
@subsection step                                                                [Macro]

@code{step}  @i{form} @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values:: 

@i{form}---a @i{form}; evaluated as described below.

@i{results}---the @i{values} returned by the @i{form}.

@subsubheading  Description::

@b{step} implements a debugging paradigm wherein the programmer
is allowed to @i{step} through the @i{evaluation} of a @i{form}.
The specific nature of the interaction,

including which I/O streams are used and
whether the stepping has lexical or dynamic scope,

is @i{implementation-defined}.

@b{step} evaluates @i{form} in the current @i{environment}.
A call to @b{step} 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 @i{conforming implementation} 
to take no action at all other than normal @i{execution} of the @i{form}.
In such a situation, 
@t{(step @i{form})}
is equivalent to, for example,
@t{(let () @i{form})}. 
In implementations where this is the case, the associated documentation
should mention that fact.

@subsubheading  See Also::

@ref{trace; untrace}

@subsubheading  Notes::

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

@node time, internal-time-units-per-second, step, Environment Dictionary
@subsection time                                                                [Macro]

@code{time}  @i{form} @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{form}---a @i{form}; evaluated as described below.

@i{results}---the @i{values} returned by the @i{form}.

@subsubheading  Description::

@b{time} evaluates @i{form} in the current @i{environment} (lexical and dynamic).
A call to @b{time} can be compiled.

@b{time} prints various timing data and other information to @i{trace output}.
The nature and format of the printed information is @i{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,
  @i{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 {Performance and Evaluation of Lisp Programs}.

@node internal-time-units-per-second, get-internal-real-time, time, Environment Dictionary
@subsection internal-time-units-per-second                          [Constant Variable]

@subsubheading  Constant Value::

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

@subsubheading  Description::

The number of @i{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, get-internal-run-time, internal-time-units-per-second, Environment Dictionary
@subsection get-internal-real-time                                           [Function]

@code{get-internal-real-time}  @i{<@i{no @i{arguments}}>} @result{}  @i{internal-time}

@subsubheading  Arguments and Values::

@i{internal-time}---a non-negative @i{integer}.

@subsubheading  Description::

@b{get-internal-real-time} returns as an @i{integer} the 
current time in @i{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 (@i{i.e.}, clock time) between the two calls. 

@subsubheading  Affected By::

Time of day (@i{i.e.}, 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, disassemble, get-internal-real-time, Environment Dictionary
@subsection get-internal-run-time                                            [Function]

@code{get-internal-run-time}  @i{<@i{no @i{arguments}}>} @result{}  @i{internal-time}

@subsubheading  Arguments and Values::

@i{internal-time}---a non-negative @i{integer}.

@subsubheading  Description::

Returns as an @i{integer} the current 
run time in @i{internal time units}.  The precise meaning of this quantity is
@i{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 @i{implementation},
the time of day (@i{i.e.}, the passage of time).

@subsubheading  See Also::

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

@subsubheading  Notes::

Depending on the @i{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 @i{implementations}, time taken
by other processes during the same time interval might be included in
this measurement as well.

@node disassemble, documentation, get-internal-run-time, Environment Dictionary
@subsection disassemble                                                      [Function]

@code{disassemble}  @i{fn} @result{}  @i{@b{nil}}

@subsubheading  Arguments and Values::

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

@subsubheading  Description::

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

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

If the @i{fn} @i{designator} is a @i{function name},
the @i{function} that it @i{names} is disassembled.

(If that @i{function} is an @i{interpreted function},
it is first compiled but the result of this implicit compilation is not installed.)

@subsubheading  Examples::

@example
 (defun f (a) (1+ a)) @result{}  F
 (eq (symbol-function 'f)
     (progn (disassemble 'f)
            (symbol-function 'f))) @result{}  @i{true}
@end example

@subsubheading  Affected By::

@b{*standard-output*}.

@subsubheading  Exceptional Situations::

Should signal an error of @i{type} @b{type-error}
			      if @i{fn} is not an @i{extended function designator}
		  or a @i{lambda expression}.

@node documentation, room, disassemble, Environment Dictionary
@subsection documentation, (setf documentation)             [Standard Generic Function]

@subsubheading  Syntax::

@code{documentation}  @i{x doc-type} @result{}  @i{documentation}

@code{(setf documentation)}  @i{new-value x doc-type} @result{}  @i{new-value}

@subsubheading  Argument Precedence Order::

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

@subsubheading  Method Signatures::

@subsubheading Functions, Macros, and Special Forms

documentation (@i{x} @code{function}) (doc-type (eql 't))@*
(setf documentation) @i{new-value}(@i{x} @code{function}) (doc-type (eql 't))

documentation (@i{x} @code{function}) (doc-type (eql 'function))@*
(setf documentation) @i{new-value}(@i{x} @code{function}) (doc-type (eql 'function))

documentation (@i{x} @code{list}) (doc-type (eql 'function))@*
(setf documentation) @i{new-value}(@i{x} @code{list}) (doc-type (eql 'function))

documentation (@i{x} @code{list}) (doc-type (eql 'compiler-macro))@*
(setf documentation) @i{new-value}(@i{x} @code{list}) (doc-type (eql 'compiler-macro))

documentation (@i{x} @code{symbol}) (doc-type (eql 'function))@*
(setf documentation) @i{new-value}(@i{x} @code{symbol}) (doc-type (eql 'function))

documentation (@i{x} @code{symbol}) (doc-type (eql 'compiler-macro))@*
(setf documentation) @i{new-value}(@i{x} @code{symbol}) (doc-type (eql 'compiler-macro))

documentation (@i{x} @code{symbol}) (doc-type (eql 'setf))@*
(setf documentation) @i{new-value}(@i{x} @code{symbol}) (doc-type (eql 'setf))

@subsubheading Method Combinations

documentation (@i{x} @code{method-combination}) (doc-type (eql 't))@*
(setf documentation) @i{new-value}(@i{x} @code{method-combination}) (doc-type (eql 't))

documentation (@i{x} @code{method-combination}) (doc-type (eql 'method-combination))@*
(setf documentation) @i{new-value}(@i{x} @code{method-combination}) (doc-type (eql 'method-combination))

documentation (@i{x} @code{symbol}) (doc-type (eql 'method-combination))@*
(setf documentation) @i{new-value}(@i{x} @code{symbol}) (doc-type (eql 'method-combination))

@subsubheading Methods

documentation (@i{x} @code{standard-method}) (doc-type (eql 't))@*
(setf documentation) @i{new-value}(@i{x} @code{standard-method}) (doc-type (eql 't))

@subsubheading Packages

documentation (@i{x} @code{package}) (doc-type (eql 't))@*
(setf documentation) @i{new-value}(@i{x} @code{package}) (doc-type (eql 't))

@subsubheading Types, Classes, and Structure Names

documentation (@i{x} @code{standard-class}) (doc-type (eql 't))@*
(setf documentation) @i{new-value}(@i{x} @code{standard-class}) (doc-type (eql 't))

documentation (@i{x} @code{standard-class}) (doc-type (eql 'type))@*
(setf documentation) @i{new-value}(@i{x} @code{standard-class}) (doc-type (eql 'type))

documentation (@i{x} @code{structure-class}) (doc-type (eql 't))@*
(setf documentation) @i{new-value}(@i{x} @code{structure-class}) (doc-type (eql 't))

documentation (@i{x} @code{structure-class}) (doc-type (eql 'type))@*
(setf documentation) @i{new-value}(@i{x} @code{structure-class}) (doc-type (eql 'type))

documentation (@i{x} @code{symbol}) (doc-type (eql 'type))@*
(setf documentation) @i{new-value}(@i{x} @code{symbol}) (doc-type (eql 'type))

documentation (@i{x} @code{symbol}) (doc-type (eql 'structure))@*
(setf documentation) @i{new-value}(@i{x} @code{symbol}) (doc-type (eql 'structure))

@subsubheading Variables

documentation (@i{x} @code{symbol}) (doc-type (eql 'variable))@*
(setf documentation) @i{new-value}(@i{x} @code{symbol}) (doc-type (eql 'variable))

@subsubheading  Arguments and Values::

@i{x}---an @i{object}.

@i{doc-type}---a @i{symbol}.

@i{documentation}---a @i{string}, or @b{nil}.

@i{new-value}---a @i{string}.

@subsubheading  Description::

The @i{generic function} @b{documentation} returns the @i{documentation string}
associated with the given @i{object} if it is available;
otherwise it returns @b{nil}.

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

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

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

@table @asis

@item @b{compiler-macro}  
Returns the @i{documentation string} of the @i{compiler macro}
whose @i{name} is the @i{function name} @i{x}.

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

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

@item @b{method-combination}  
If @i{x} is a @i{symbol},
returns the @i{documentation string} of
the @i{method combination}
whose @i{name} is @i{x}.

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

@item @b{setf}  
Returns the @i{documentation string} of 

the @i{setf expander}

whose @i{name} is the @i{symbol} @i{x}.

@item @b{structure}  
Returns the @i{documentation string} 
associated with the @i{structure name} @i{x}.

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

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

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

@item @b{variable}  
Returns the @i{documentation string} of
the @i{dynamic variable} or @i{constant variable}
whose @i{name} is the @i{symbol} @i{x}.

@end table

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

@subsubheading  Notes::

This standard prescribes no means to retrieve the @i{documentation strings}
for individual slots specified in a @b{defclass} form, but 
@i{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
@i{Metaobject Protocol} for suggestions about how this might be done.

@node room, ed, documentation, Environment Dictionary
@subsection room                                                             [Function]

@code{room}  @i{{&optional} x} @result{}  @i{@i{implementation-dependent}}

@subsubheading  Arguments and Values:: 

@i{x}---one of @b{t}, @b{nil}, or @t{:default}.

@subsubheading  Description::

@b{room} prints, to @i{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
@i{implementation-dependent}.
The intent is to provide information that a @i{programmer}
might use to tune a @i{program} for a particular @i{implementation}.

@t{(room nil)} prints out a minimal amount of information.
@t{(room t)} prints out a maximal amount of information.

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

@subsubheading  Side Effects::

Output to @i{standard output}.

@subsubheading  Affected By::

@b{*standard-output*}.

@node ed, inspect, room, Environment Dictionary
@subsection ed                                                               [Function]

@code{ed}  @i{{&optional} x} @result{}  @i{@i{implementation-dependent}}

@subsubheading  Arguments and Values::

@i{x}---@b{nil}, a @i{pathname}, a @i{string}, or a @i{function name}.

 The default is @b{nil}.

@subsubheading  Description::

@b{ed} invokes the editor if the @i{implementation} provides a resident editor.

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

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

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

@subsubheading  Exceptional Situations::

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

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

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

An error of @i{type} @b{file-error} might be signaled if @i{x}
is a @i{designator} for a @i{wild} @i{pathname}.

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

@subsubheading  See Also::

@b{pathname},

@b{logical-pathname},

@ref{compile-file}
,
@ref{load}
,

@ref{Pathnames as Filenames}

@node inspect, dribble, ed, Environment Dictionary
@subsection inspect                                                          [Function]

@code{inspect}  @i{object} @result{}  @i{@i{implementation-dependent}}

@subsubheading  Arguments and Values::

@i{object}---an @i{object}.

@subsubheading  Description::

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

@subsubheading  Side Effects::

@i{implementation-dependent}.

@subsubheading  Affected By::

@i{implementation-dependent}.

@subsubheading  Exceptional Situations::

@i{implementation-dependent}.

@subsubheading  See Also::

@ref{describe}

@subsubheading  Notes::

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

@node dribble, -, inspect, Environment Dictionary
@subsection dribble                                                          [Function]

@code{dribble}  @i{{&optional} pathname} @result{}  @i{@i{implementation-dependent}}

@subsubheading  Arguments and Values::

@i{pathname}---a @i{pathname designator}.

@subsubheading  Description::

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

If @i{pathname} is a @i{logical pathname}, it is translated
into a physical pathname as if by calling @b{translate-logical-pathname}.

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

If @b{dribble} is @i{called} while a @i{stream} to a ``dribble file'' 
is still open from a previous @i{call} to @b{dribble},
the effect is @i{implementation-defined}.  For example, 
    the already-@i{open} @i{stream} might be @i{closed}, 
 or dribbling might occur both to the old @i{stream} and to a new one,
 or the old @i{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 @i{implementation}.

@subsubheading  Exceptional Situations::

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

An error of @i{type} @b{file-error} might be signaled if @i{pathname}
is a @i{designator} for a @i{wild} @i{pathname}.

@subsubheading  See Also::

@ref{Pathnames as Filenames}

@subsubheading  Notes::

@b{dribble} can return before subsequent 
@i{forms} are executed. It also
can enter a recursive interaction loop, 
returning only when @t{(dribble)} is done.

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

@node -, +, dribble, Environment Dictionary
@subsection -                                                              [Variable]

@subsubheading  Value Type::

a @i{form}.

@subsubheading  Initial Value::

@i{implementation-dependent}.

@subsubheading  Description::

The @i{value} of @b{-} is the @i{form} that is currently being evaluated by
the @i{Lisp read-eval-print loop}.

@subsubheading  Examples::

@example
(format t "~&Evaluating ~S~
@t{ |> } Evaluating (FORMAT T "~&Evaluating ~S~
@result{}  NIL
@end example

@subsubheading  Affected By::

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

@subsubheading  See Also::

@b{+} (@i{variable}),
@b{*} (@i{variable}),
@ref{/}
 (@i{variable}), 
@ref{Top level loop}

@node +, *, -, Environment Dictionary
@subsection +, ++, +++                                                       [Variable]

@subsubheading  Value Type::

an @i{object}.

@subsubheading  Initial Value::

@i{implementation-dependent}.

@subsubheading  Description::

The @i{variables} @b{+}, @b{++}, and @b{+++} are maintained by the
@i{Lisp read-eval-print loop} to save @i{forms} that were
recently @i{evaluated}.

The @i{value} of @b{+}   is the last @i{form} that was @i{evaluated},
the @i{value} of @b{++}  is the previous value of @b{+}, and
the @i{value} of @b{+++} is the previous value of @b{++}.

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

@subsubheading  Affected By:: 

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

@subsubheading  See Also::

@ref{-}
 (@i{variable}),
@b{*} (@i{variable}),
@ref{/}
 (@i{variable}), 
@ref{Top level loop}

@node *, /, +, Environment Dictionary
@subsection *, **, ***                                                       [Variable]

@subsubheading  Value Type::

an @i{object}.

@subsubheading  Initial Value::

@i{implementation-dependent}.

@subsubheading  Description::

The @i{variables} @b{*}, @b{**}, and @b{***} are 
maintained by the @i{Lisp read-eval-print loop} to save the 
values of results that are printed each time through the loop.

The @i{value} of @b{*}   is the most recent @i{primary value} that was printed,
the @i{value} of @b{**}  is the previous value of @b{*}, and 
the @i{value} of @b{***} is the previous value of @b{**}.

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

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

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

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

@subsubheading  Affected By::

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

@subsubheading  See Also::

@ref{-}
 (@i{variable}),
@b{+} (@i{variable}),
@ref{/}
 (@i{variable}), 
@ref{Top level loop}

@subsubheading  Notes::

@example
 *   @equiv{} (car /)
 **  @equiv{} (car //)
 *** @equiv{} (car ///)
@end example

@node /, lisp-implementation-type, *, Environment Dictionary
@subsection /, //, ///                                                       [Variable]

@subsubheading  Value Type::

a @i{proper list}.

@subsubheading  Initial Value::

@i{implementation-dependent}.

@subsubheading  Description::

The @i{variables} @b{/}, @b{//}, and @b{///} are maintained by
the @i{Lisp read-eval-print loop} to save the values of results that
were printed at the end of the loop.

The @i{value} of @b{/}   is a @i{list} of the most recent @i{values} that were printed,
the @i{value} of @b{//}  is the previous value of @b{/}, and
the @i{value} of @b{///} is the previous value of @b{//}.

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

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

@subsubheading  Affected By::

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

@subsubheading  See Also::

@ref{-}
 (@i{variable}),
@b{+} (@i{variable}),
@b{*} (@i{variable}),
@ref{Top level loop}

@node lisp-implementation-type, short-site-name, /, Environment Dictionary
@subsection lisp-implementation-type,
@subheading lisp-implementation-version
@flushright
@i{[Function]}
@end flushright

@code{lisp-implementation-type}  @i{<@i{no @i{arguments}}>} @result{}  @i{description}

@code{lisp-implementation-version}  @i{<@i{no @i{arguments}}>} @result{}  @i{description}

@subsubheading  Arguments and Values::

@i{description}---a @i{string} or @b{nil}.

@subsubheading  Description::

@b{lisp-implementation-type} and @b{lisp-implementation-version} 
identify the current implementation of @r{Common Lisp}.

@b{lisp-implementation-type} returns a @i{string} 
that identifies the generic name of
the particular @r{Common Lisp} implementation.

@b{lisp-implementation-version} 
returns a @i{string} that identifies the version of
the particular @r{Common Lisp} implementation.

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

@subsubheading  Examples::

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

@node short-site-name, machine-instance, lisp-implementation-type, Environment Dictionary
@subsection short-site-name, long-site-name                                  [Function]

@code{short-site-name}  @i{<@i{no @i{arguments}}>} @result{}  @i{description}

@code{long-site-name}  @i{<@i{no @i{arguments}}>} @result{}  @i{description}

@subsubheading  Arguments and Values:: 

@i{description}---a @i{string} or @b{nil}.

@subsubheading  Description::

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

@subsubheading  Examples::

@example
 (short-site-name)
@result{}  "MIT AI Lab"
@i{OR}@result{} "CMU-CSD"
 (long-site-name)
@result{}  "MIT Artificial Intelligence Laboratory"
@i{OR}@result{} "CMU Computer Science Department"
@end example

@subsubheading  Affected By::

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

@node machine-instance, machine-type, short-site-name, Environment Dictionary
@subsection machine-instance                                                 [Function]

@code{machine-instance}  @i{<@i{no @i{arguments}}>} @result{}  @i{description}

@subsubheading  Arguments and Values::

@i{description}---a @i{string} or @b{nil}.

@subsubheading  Description::

Returns a @i{string} that identifies the particular instance of
the computer hardware on which @r{Common Lisp} is running, 
or @b{nil} if no such @i{string} can be computed.

@subsubheading  Examples::

@example
 (machine-instance)
@result{}  "ACME.COM"
@i{OR}@result{} "S/N 123231"
@i{OR}@result{} "18.26.0.179"
@i{OR}@result{} "AA-00-04-00-A7-A4"
@end example

@subsubheading  Affected By::

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

@subsubheading  See Also::

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

@node machine-type, machine-version, machine-instance, Environment Dictionary
@subsection machine-type                                                     [Function]

@code{machine-type}  @i{<@i{no @i{arguments}}>} @result{}  @i{description}

@subsubheading  Arguments and Values::

@i{description}---a @i{string} or @b{nil}.

@subsubheading  Description::

Returns a @i{string} that identifies the generic name of
the computer hardware on which @r{Common Lisp} is running.

@subsubheading  Examples::

@example
 (machine-type)
@result{}  "DEC PDP-10"
@i{OR}@result{} "Symbolics LM-2"
@end example

@subsubheading  Affected By::

The machine type.
The implementation.

@subsubheading  See Also::

@ref{machine-version}

@node machine-version, software-type, machine-type, Environment Dictionary
@subsection machine-version                                                  [Function]

@code{machine-version}  @i{<@i{no @i{arguments}}>} @result{}  @i{description}

@subsubheading  Arguments and Values::

@i{description}---a @i{string} or @b{nil}.

@subsubheading  Description::

Returns a @i{string} that identifies the version of the computer hardware
on which @r{Common Lisp} is running, or @b{nil} if no such value can be computed.

@subsubheading  Examples::

@example
 (machine-version) @result{}  "KL-10, microcode 9"
@end example

@subsubheading  Affected By::

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

@subsubheading  See Also::

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

@node software-type, user-homedir-pathname, machine-version, Environment Dictionary
@subsection software-type, software-version                                  [Function]

@code{software-type}  @i{<@i{no @i{arguments}}>} @result{}  @i{description}

@code{software-version}  @i{<@i{no @i{arguments}}>} @result{}  @i{description}

@subsubheading  Arguments and Values:: 

@i{description}---a @i{string} or @b{nil}.

@subsubheading  Description::

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

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

@subsubheading  Examples::

@example
 (software-type) @result{}  "Multics"
 (software-version) @result{}  "1.3x"
@end example

@subsubheading  Affected By::

Operating system environment.

@subsubheading  Notes::

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

@node user-homedir-pathname,  , software-type, Environment Dictionary
@subsection user-homedir-pathname                                            [Function]

@code{user-homedir-pathname}  @i{{&optional} host} @result{}  @i{pathname}

@subsubheading  Arguments and Values::

@i{host}---a @i{string}, a @i{list} of @i{strings}, or @t{:unspecific}.

@i{pathname}---a @i{pathname}, or @b{nil}.

@subsubheading  Description::

@b{user-homedir-pathname} determines the @i{pathname} that corresponds
to the user's home directory on @i{host}.  
If @i{host} is not supplied, its value is @i{implementation-dependent}.

For a description of @t{:unspecific}, see @ref{Pathname Components}.

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

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

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

@subsubheading  Examples::

@example
 (pathnamep (user-homedir-pathname)) @result{}  @i{true}
@end example

@subsubheading  Affected By::

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

@c end of including dict-environment

@c %**end of chapter