3
@node Environment, Glossary (Glossary), System Construction, Top
7
* The External Environment::
8
* Environment Dictionary::
11
@node The External Environment, Environment Dictionary, Environment, Environment
12
@section The External Environment
14
@c including concept-environment
18
* Debugging Utilities::
19
* Environment Inquiry::
23
@node Top level loop, Debugging Utilities, The External Environment, The External Environment
24
@subsection Top level loop
26
The top level loop is the @r{Common Lisp} mechanism by which the user normally
27
interacts with the @r{Common Lisp} system. This loop is sometimes referred to
28
as the @i{Lisp read-eval-print loop}
29
because it typically consists of an endless loop that reads an expression,
30
evaluates it and prints the results.
32
The top level loop is not completely specified; thus the user
33
interface is @i{implementation-defined}.
35
prints all values resulting from the evaluation of a
37
Figure 25--1 lists variables that are maintained by the @i{Lisp read-eval-print loop}.
47
@w{ Figure 25--1: Variables maintained by the Read-Eval-Print Loop}
52
@node Debugging Utilities, Environment Inquiry, Top level loop, The External Environment
53
@subsection Debugging Utilities
55
Figure 25--2 shows @i{defined names} relating to
61
@w{ *debugger-hook* documentation step }
62
@w{ apropos dribble time }
63
@w{ apropos-list ed trace }
64
@w{ break inspect untrace }
65
@w{ describe invoke-debugger }
68
@w{ Figure 25--2: Defined names relating to debugging}
73
@node Environment Inquiry, Time, Debugging Utilities, The External Environment
74
@subsection Environment Inquiry
76
Environment inquiry @i{defined names} provide information about
77
the hardware and software configuration on which a @r{Common Lisp} program is
80
Figure 25--3 shows @i{defined names} relating to environment inquiry.
85
@w{ *features* machine-instance short-site-name }
86
@w{ lisp-implementation-type machine-type software-type }
87
@w{ lisp-implementation-version machine-version software-version }
88
@w{ long-site-name room }
91
@w{ Figure 25--3: Defined names relating to environment inquiry. }
96
@node Time, , Environment Inquiry, The External Environment
99
Time is represented in four different ways in @r{Common Lisp}:
104
@i{Decoded time} and @i{universal time} are used primarily to represent calendar time,
105
and are precise only to one second.
106
@i{Internal time} is used primarily to represent measurements of computer
107
time (such as run time) and is precise to some @i{implementation-dependent}
108
fraction of a second called an @i{internal time unit},
109
as specified by @b{internal-time-units-per-second}.
110
An @i{internal time} can be used
111
for either @i{absolute} and @i{relative} @i{time} measurements.
112
Both a @i{universal time} and a @i{decoded time} can be used
113
only for @i{absolute} @i{time} measurements.
114
In the case of one function, @b{sleep},
115
time intervals are represented as a non-negative @i{real} number of seconds.
117
Figure 25--4 shows @i{defined names} relating to @i{time}.
122
@w{ decode-universal-time get-internal-run-time }
123
@w{ encode-universal-time get-universal-time }
124
@w{ get-decoded-time internal-time-units-per-second }
125
@w{ get-internal-real-time sleep }
128
@w{ Figure 25--4: Defined names involving Time. }
140
@node Decoded Time, Universal Time, Time, Time
141
@subsubsection Decoded Time
144
@IGindex{decoded time}
145
is an ordered series of nine values that, taken together,
146
represent a point in calendar time (ignoring @i{leap seconds}):
151
An @i{integer} between 0 and~59, inclusive.
154
An @i{integer} between 0 and~59, inclusive.
157
An @i{integer} between 0 and~23, inclusive.
160
An @i{integer} between 1 and~31, inclusive (the upper limit actually
161
depends on the month and year, of course).
164
An @i{integer} between 1 and 12, inclusive;
165
1~means January, 2~means February, and so on; 12~means December.
168
An @i{integer} indicating the year A.D. However, if this
170
is between 0 and 99, the ``obvious'' year is used; more precisely,
171
that year is assumed that is equal to the
172
@i{integer} modulo 100 and
173
within fifty years of the current year (inclusive backwards
174
and exclusive forwards).
175
Thus, in the year 1978, year 28 is 1928
176
but year 27 is 2027. (Functions that return time in this format always return
179
@item @b{Day of week}
180
An @i{integer} between~0 and~6, inclusive;
181
0~means Monday, 1~means Tuesday, and so on; 6~means Sunday.
183
@item @b{Daylight saving time flag}
184
A @i{generalized boolean} that,
185
if @i{true}, indicates that daylight saving time is in effect.
192
Figure 25--5 shows @i{defined names} relating to @i{decoded time}.
197
@w{ decode-universal-time get-decoded-time }
200
@w{ Figure 25--5: Defined names involving time in Decoded Time.}
205
@node Universal Time, Internal Time, Decoded Time, Time
206
@subsubsection Universal Time
209
@IGindex{universal time}
210
is an @i{absolute} @i{time} represented as a
211
single non-negative @i{integer}---the number of seconds since
212
midnight, January 1, 1900 GMT (ignoring @i{leap seconds}).
213
Thus the time 1 is 00:00:01 (that is, 12:00:01 a.m.) on January 1, 1900 GMT.
214
Similarly, the time 2398291201 corresponds to time 00:00:01 on January 1,
216
Recall that the year 1900 was not a leap year; for the purposes of
217
@r{Common Lisp}, a year is a leap year if and only if its number is divisible by 4,
218
except that years divisible by 100 are not leap years, except that years
219
divisible by 400 are leap years. Therefore the year 2000 will
221
Because @i{universal time} must be a non-negative @i{integer},
222
times before the base time of midnight, January 1, 1900 GMT cannot be processed by @r{Common Lisp}.
227
@w{ decode-universal-time get-universal-time }
228
@w{ encode-universal-time }
231
@w{ Figure 25--6: Defined names involving time in Universal Time.}
236
@node Internal Time, Seconds, Universal Time, Time
237
@subsubsection Internal Time
240
@IGindex{internal time}
241
represents time as a single @i{integer},
242
in terms of an @i{implementation-dependent} unit called an @i{internal time unit}.
243
Relative time is measured as a number of these units.
244
Absolute time is relative to an arbitrary time base.
246
Figure 25--7 shows @i{defined names} related to @i{internal time}.
251
@w{ get-internal-real-time internal-time-units-per-second }
252
@w{ get-internal-run-time }
255
@w{ Figure 25--7: Defined names involving time in Internal Time.}
260
@node Seconds, , Internal Time, Time
261
@subsubsection Seconds
263
One function, @b{sleep}, takes its argument as a non-negative @i{real} number
264
of seconds. Informally, it may be useful to think of this as
265
a @i{relative} @i{universal time}, but it differs in one important way:
266
@i{universal times} are always non-negative @i{integers}, whereas the argument to
267
@b{sleep} can be any kind of non-negative @i{real}, in order to allow for
268
the possibility of fractional seconds.
276
@w{ Figure 25--8: Defined names involving time in Seconds.}
281
@c end of including concept-environment
283
@node Environment Dictionary, , The External Environment, Environment
284
@section Environment Dictionary
286
@c including dict-environment
289
* decode-universal-time::
290
* encode-universal-time::
291
* get-universal-time::
299
* internal-time-units-per-second::
300
* get-internal-real-time::
301
* get-internal-run-time::
312
* lisp-implementation-type::
318
* user-homedir-pathname::
321
@node decode-universal-time, encode-universal-time, Environment Dictionary, Environment Dictionary
322
@subsection decode-universal-time [Function]
324
@code{decode-universal-time} @i{universal-time @r{&optional} time-zone}@*
325
@result{} @i{second, minute, hour, date, month, year, day, daylight-p, zone}
327
@subsubheading Arguments and Values::
329
@i{universal-time}---a @i{universal time}.
331
@i{time-zone}---a @i{time zone}.
333
@i{second}, @i{minute}, @i{hour}, @i{date}, @i{month},
334
@i{year}, @i{day}, @i{daylight-p}, @i{zone}---a @i{decoded time}.
336
@subsubheading Description::
338
Returns the @i{decoded time} represented by the given @i{universal time}.
340
If @i{time-zone} is not supplied,
341
it defaults to the current time zone adjusted for daylight saving time.
343
If @i{time-zone} is supplied, daylight saving time information is ignored.
344
The daylight saving time flag is @b{nil} if @i{time-zone} is supplied.
346
@subsubheading Examples::
349
(decode-universal-time 0 0) @result{} 0, 0, 0, 1, 1, 1900, 0, @i{false}, 0
351
;; The next two examples assume Eastern Daylight Time.
352
(decode-universal-time 2414296800 5) @result{} 0, 0, 1, 4, 7, 1976, 6, @i{false}, 5
353
(decode-universal-time 2414293200) @result{} 0, 0, 1, 4, 7, 1976, 6, @i{true}, 5
355
;; This example assumes that the time zone is Eastern Daylight Time
356
;; (and that the time zone is constant throughout the example).
357
(let* ((here (nth 8 (multiple-value-list (get-decoded-time)))) ;Time zone
358
(recently (get-universal-time))
359
(a (nthcdr 7 (multiple-value-list (decode-universal-time recently))))
360
(b (nthcdr 7 (multiple-value-list (decode-universal-time recently here)))))
361
(list a b (equal a b))) @result{} ((T 5) (NIL 5) NIL)
364
@subsubheading Affected By::
366
@i{Implementation-dependent} mechanisms for calculating when or if daylight
367
savings time is in effect for any given session.
369
@subsubheading See Also::
371
@ref{encode-universal-time}
373
@ref{get-universal-time}
377
@node encode-universal-time, get-universal-time, decode-universal-time, Environment Dictionary
378
@subsection encode-universal-time [function]
380
@subsubheading Syntax::
382
@code{encode-universal-time} @i{second minute hour date month year
383
@r{&optional} time-zone}@*
384
@result{} @i{universal-time}
386
@subsubheading Arguments and Values::
388
@i{second}, @i{minute}, @i{hour},
389
@i{date}, @i{month}, @i{year},
390
@i{time-zone}---the corresponding parts of a @i{decoded time}.
391
(Note that some of the nine values in a full @i{decoded time} are redundant,
392
and so are not used as inputs to this function.)
394
@i{universal-time}---a @i{universal time}.
396
@subsubheading Description::
398
@b{encode-universal-time} converts a time from Decoded Time format
399
to a @i{universal time}.
401
If @i{time-zone} is supplied, no adjustment for daylight savings time is performed.
403
@subsubheading Examples::
406
(encode-universal-time 0 0 0 1 1 1900 0) @result{} 0
407
(encode-universal-time 0 0 1 4 7 1976 5) @result{} 2414296800
408
;; The next example assumes Eastern Daylight Time.
409
(encode-universal-time 0 0 1 4 7 1976) @result{} 2414293200
412
@subsubheading See Also::
414
@ref{decode-universal-time}
415
, @b{get-decoded-time}
417
@node get-universal-time, sleep, encode-universal-time, Environment Dictionary
418
@subsection get-universal-time, get-decoded-time [Function]
420
@code{get-universal-time} @i{<@i{no @i{arguments}}>} @result{} @i{universal-time}
422
@code{get-decoded-time} @i{<@i{no @i{arguments}}>}@*
423
@result{} @i{second, minute, hour, date, month, year, day, daylight-p, zone}
425
@subsubheading Arguments and Values::
427
@i{universal-time}---a @i{universal time}.
429
@i{second}, @i{minute}, @i{hour},
430
@i{date}, @i{month}, @i{year},
431
@i{day}, @i{daylight-p}, @i{zone}---a @i{decoded time}.
433
@subsubheading Description::
435
@b{get-universal-time} returns the current time, represented as a @i{universal time}.
437
@b{get-decoded-time} returns the current time, represented as a @i{decoded time}.
439
@subsubheading Examples::
442
;; At noon on July 4, 1976 in Eastern Daylight Time.
443
(get-decoded-time) @result{} 0, 0, 12, 4, 7, 1976, 6, @i{true}, 5
444
;; At exactly the same instant.
445
(get-universal-time) @result{} 2414332800
446
;; Exactly five minutes later.
447
(get-universal-time) @result{} 2414333100
448
;; The difference is 300 seconds (five minutes)
449
(- * **) @result{} 300
452
@subsubheading Affected By::
454
The time of day (@i{i.e.}, the passage of time),
455
the system clock's ability to keep accurate time,
456
and the accuracy of the system clock's initial setting.
458
@subsubheading Exceptional Situations::
460
An error of @i{type} @b{error} might be signaled if the current time cannot be determined.
462
@subsubheading See Also::
464
@ref{decode-universal-time}
466
@ref{encode-universal-time}
470
@subsubheading Notes::
473
(get-decoded-time) @equiv{} (decode-universal-time (get-universal-time))
476
No @i{implementation} is required to have a way to verify that the
477
time returned is correct. However, if an @i{implementation} provides
478
a validity check (@i{e.g.}, the failure to have properly initialized the system
479
clock can be reliably detected) and that validity check fails,
480
the @i{implementation} is strongly encouraged (but not required)
481
to signal an error of @i{type} @b{error} (rather than, for example, returning a
482
known-to-be-wrong value) that is @i{correctable} by allowing the user
483
to interactively set the correct time.
485
@node sleep, apropos, get-universal-time, Environment Dictionary
486
@subsection sleep [Function]
488
@code{sleep} @i{seconds} @result{} @i{@b{nil}}
490
@subsubheading Arguments and Values::
492
@i{seconds}---a non-negative @i{real}.
494
@subsubheading Description::
496
Causes execution to cease and become dormant for approximately the
497
seconds of real time indicated by @i{seconds},
498
whereupon execution is resumed.
500
@subsubheading Examples::
503
(sleep 1) @result{} NIL
505
;; Actually, since SLEEP is permitted to use approximate timing,
506
;; this might not always yield true, but it will often enough that
507
;; we felt it to be a productive example of the intent.
508
(let ((then (get-universal-time))
509
(now (progn (sleep 10) (get-universal-time))))
510
(>= (- now then) 10))
514
@subsubheading Side Effects::
516
Causes processing to pause.
518
@subsubheading Affected By::
520
The granularity of the scheduler.
522
@subsubheading Exceptional Situations::
524
Should signal an error of @i{type} @b{type-error}
525
if @i{seconds} is not a non-negative @i{real}.
527
@node apropos, describe, sleep, Environment Dictionary
528
@subsection apropos, apropos-list [Function]
530
@code{apropos} @i{string @r{&optional} package} @result{} @i{<@i{no @i{values}}>}
532
@code{apropos-list} @i{string @r{&optional} package} @result{} @i{symbols}
534
@subsubheading Arguments and Values::
536
@i{string}---a @i{string designator}.
538
@i{package}---a @i{package designator} or @b{nil}.
539
The default is @b{nil}.
541
@i{symbols}---a @i{list} of @i{symbols}.
543
@subsubheading Description::
545
These functions search for @i{interned} @i{symbols}
546
whose @i{names} contain the substring @i{string}.
548
For @b{apropos}, as each such @i{symbol} is found,
549
its name is printed on @i{standard output}.
551
if such a @i{symbol} is defined as a @i{function} or @i{dynamic variable},
552
information about those definitions might also be printed.
554
For @b{apropos-list},
555
no output occurs as the search proceeds;
556
instead a list of the matching @i{symbols} is returned when the search is complete.
558
If @i{package} is @i{non-nil},
559
only the @i{symbols} @i{accessible} in that @i{package} are searched;
560
otherwise all @i{symbols} @i{accessible} in any @i{package} are searched.
562
Because a @i{symbol} might be available
563
by way of more than one inheritance path,
564
@b{apropos} might print information about the @i{same} @i{symbol} more than once,
565
or @b{apropos-list} might return a @i{list} containing duplicate @i{symbols}.
567
Whether or not the search is case-sensitive is @i{implementation-defined}.
569
@subsubheading Affected By::
571
The set of @i{symbols} which are currently @i{interned}
572
in any @i{packages} being searched.
574
@b{apropos} is also affected by @b{*standard-output*}.
576
@node describe, describe-object, apropos, Environment Dictionary
577
@subsection describe [Function]
579
@code{describe} @i{object @r{&optional} stream} @result{} @i{<@i{no @i{values}}>}
581
@subsubheading Arguments and Values::
583
@i{object}---an @i{object}.
585
@i{stream}---an @i{output} @i{stream designator}.
586
The default is @i{standard output}.
588
@subsubheading Description::
590
@b{describe} displays information about @i{object}
594
For example, @b{describe} of a @i{symbol} might show the
595
@i{symbol}'s value, its definition, and each of its properties.
596
@b{describe} of a @i{float} might show the number's
597
internal representation in a way that is useful for tracking
598
down round-off errors. In all cases, however, the nature and format of the
599
output of @b{describe} is @i{implementation-dependent}.
601
@b{describe} can describe something that it finds inside the @i{object};
602
in such cases, a notational device such as increased indentation or positioning in a
603
table is typically used in order to visually distinguish such recursive descriptions
604
from descriptions of the argument @i{object}.
606
The actual act of describing the object is implemented by @b{describe-object}.
607
@b{describe} exists as an interface primarily to manage argument defaulting (including
608
conversion of arguments @b{t} and @b{nil} into @i{stream} @i{objects}) and to inhibit
609
any return values from @b{describe-object}.
611
@b{describe} is not intended to be an interactive function. In a
612
@i{conforming implementation}, @b{describe} must not, by default,
613
prompt for user input. User-defined methods for @b{describe-object}
614
are likewise restricted.
616
@subsubheading Side Effects::
618
Output to @i{standard output} or @i{terminal I/O}.
620
@subsubheading Affected By::
622
@b{*standard-output*} and @b{*terminal-io*},
623
methods on @b{describe-object} and @b{print-object}
624
for @i{objects} having user-defined @i{classes}.
626
@subsubheading See Also::
630
@ref{describe-object}
632
@node describe-object, trace, describe, Environment Dictionary
633
@subsection describe-object [Standard Generic Function]
635
@subsubheading Syntax::
637
@code{describe-object} @i{object stream} @result{} @i{@i{implementation-dependent}}
639
@subsubheading Method Signatures::
641
@code{describe-object} @i{(@i{object} standard-object) @i{stream}}
643
@subsubheading Arguments and Values::
645
@i{object}---an @i{object}.
647
@i{stream}---a @i{stream}.
649
@subsubheading Description::
651
The generic function @b{describe-object} prints a description of
652
@i{object} to a @i{stream}. @b{describe-object} is called
653
by @b{describe}; it must not be called by the user.
655
Each implementation is required to provide a @i{method} on
656
the @i{class} @b{standard-object} and @i{methods} on enough other
657
@i{classes} so as to ensure that there is always an applicable @i{method}.
658
Implementations are free to add @i{methods} for other @i{classes}.
659
Users can write @i{methods} for @b{describe-object} for their
660
own @i{classes} if they do not wish to inherit an implementation-supplied
663
@i{Methods} on @b{describe-object} can recursively call
664
@b{describe}. Indentation, depth limits, and circularity detection
665
are all taken care of automatically, provided that each @i{method}
666
handles exactly one level of structure and calls @b{describe}
667
recursively if there are more structural levels. The consequences are
668
undefined if this rule is not obeyed.
670
In some implementations the @i{stream} argument passed to a
671
@b{describe-object} method is not the original @i{stream}, but is
672
an intermediate @i{stream} that implements parts of @b{describe}.
673
@i{Methods} should therefore not depend on the identity of this
676
@subsubheading Examples::
679
(defclass spaceship ()
680
((captain :initarg :captain :accessor spaceship-captain)
681
(serial# :initarg :serial-number :accessor spaceship-serial-number)))
683
(defclass federation-starship (spaceship) ())
685
(defmethod describe-object ((s spaceship) stream)
686
(with-slots (captain serial#) s
687
(format stream "~&~S is a spaceship of type ~S,~
689
and with serial number ~D.~
690
s (type-of s) captain serial#)))
692
(make-instance 'federation-starship
693
:captain "Rachel Garrett"
694
:serial-number "NCC-1701-C")
695
@result{} #<FEDERATION-STARSHIP 26312465>
698
@t{ |> } #<FEDERATION-STARSHIP 26312465> is a spaceship of type FEDERATION-STARSHIP,
699
@t{ |> } with Rachel Garrett at the helm and with serial number NCC-1701-C.
700
@result{} <@i{no @i{values}}>
703
@subsubheading See Also::
707
@subsubheading Notes::
709
The same implementation techniques that are applicable to @b{print-object} are
710
applicable to @b{describe-object}.
712
The reason for making the return values for @b{describe-object}
713
unspecified is to avoid forcing users to include explicit @t{(values)}
714
in all of their @i{methods}. @b{describe} takes care of that.
716
@node trace, step, describe-object, Environment Dictionary
717
@subsection trace, untrace [Macro]
719
@code{trace} @i{@{@i{function-name}@}*} @result{} @i{trace-result}
721
@code{untrace} @i{@{@i{function-name}@}*} @result{} @i{untrace-result}
723
@subsubheading Arguments and Values::
725
@i{function-name}---a @i{function name}.
727
@i{trace-result}---@i{implementation-dependent},
728
unless no @i{function-names} are supplied,
729
in which case @i{trace-result} is a @i{list} of @i{function names}.
731
@i{untrace-result}---@i{implementation-dependent}.
733
@subsubheading Description::
735
@b{trace} and @b{untrace} control the invocation of the trace facility.
737
Invoking @b{trace} with one or more @i{function-names} causes
738
the denoted @i{functions} to be ``traced.''
739
Whenever a traced @i{function} is invoked, information
741
about the arguments passed,
742
and about any eventually returned values
743
is printed to @i{trace output}.
744
If @b{trace} is used with no @i{function-names},
745
no tracing action is performed;
746
instead, a list of the @i{functions} currently being traced is returned.
748
Invoking @b{untrace} with one or more function names causes those
749
functions to be ``untraced'' (@i{i.e.}, no longer traced).
750
If @b{untrace} is used with no @i{function-names},
751
all @i{functions} currently being traced are untraced.
753
If a @i{function} to be traced has been open-coded
754
(@i{e.g.}, because it was declared @b{inline}),
755
a call to that @i{function} might not produce trace output.
757
@subsubheading Examples::
760
(defun fact (n) (if (zerop n) 1 (* n (fact (- n 1)))))
764
;; Of course, the format of traced output is implementation-dependent.
766
@t{ |> } 1 Enter FACT 3
767
@t{ |> } | 2 Enter FACT 2
768
@t{ |> } | 3 Enter FACT 1
769
@t{ |> } | | 4 Enter FACT 0
770
@t{ |> } | | 4 Exit FACT 1
771
@t{ |> } | 3 Exit FACT 1
772
@t{ |> } | 2 Exit FACT 2
773
@t{ |> } 1 Exit FACT 6
777
@subsubheading Side Effects::
779
Might change the definitions of the @i{functions} named by @i{function-names}.
781
@subsubheading Affected By::
783
Whether the functions named are defined or already being traced.
785
@subsubheading Exceptional Situations::
787
Tracing an already traced function,
788
or untracing a function not currently being traced,
789
should produce no harmful effects, but might signal a warning.
791
@subsubheading See Also::
796
@subsubheading Notes::
798
@b{trace} and @b{untrace} may also accept additional
799
@i{implementation-dependent} argument formats. The format of the trace
800
output is @i{implementation-dependent}.
802
Although @b{trace} can be extended to permit non-standard options,
803
@i{implementations} are nevertheless encouraged (but not required)
804
to warn about the use of syntax or options
805
that are neither specified by this standard
806
nor added as an extension by the @i{implementation},
807
since they could be symptomatic of typographical errors
808
or of reliance on features supported in @i{implementations}
809
other than the current @i{implementation}.
811
@node step, time, trace, Environment Dictionary
812
@subsection step [Macro]
814
@code{step} @i{form} @result{} @i{@{@i{result}@}*}
816
@subsubheading Arguments and Values::
818
@i{form}---a @i{form}; evaluated as described below.
820
@i{results}---the @i{values} returned by the @i{form}.
822
@subsubheading Description::
824
@b{step} implements a debugging paradigm wherein the programmer
825
is allowed to @i{step} through the @i{evaluation} of a @i{form}.
826
The specific nature of the interaction,
828
including which I/O streams are used and
829
whether the stepping has lexical or dynamic scope,
831
is @i{implementation-defined}.
833
@b{step} evaluates @i{form} in the current @i{environment}.
834
A call to @b{step} can be compiled, but it is acceptable for an
835
implementation to interactively step through only those parts of the computation
836
that are interpreted.
838
It is technically permissible for a @i{conforming implementation}
839
to take no action at all other than normal @i{execution} of the @i{form}.
842
is equivalent to, for example,
843
@t{(let () @i{form})}.
844
In implementations where this is the case, the associated documentation
845
should mention that fact.
847
@subsubheading See Also::
851
@subsubheading Notes::
853
@i{Implementations} are encouraged to respond to the typing of @t{?}
854
or the pressing of a ``help key'' by providing help including a list of
857
@node time, internal-time-units-per-second, step, Environment Dictionary
858
@subsection time [Macro]
860
@code{time} @i{form} @result{} @i{@{@i{result}@}*}
862
@subsubheading Arguments and Values::
864
@i{form}---a @i{form}; evaluated as described below.
866
@i{results}---the @i{values} returned by the @i{form}.
868
@subsubheading Description::
870
@b{time} evaluates @i{form} in the current @i{environment} (lexical and dynamic).
871
A call to @b{time} can be compiled.
873
@b{time} prints various timing data and other information to @i{trace output}.
874
The nature and format of the printed information is @i{implementation-defined}.
875
Implementations are encouraged to provide such information as
878
and storage management statistics.
880
@subsubheading Affected By::
882
The accuracy of the results depends, among other things, on the accuracy
883
of the corresponding functions provided by the underlying operating system.
885
The magnitude of the results may depend on
887
the operating system,
888
the lisp implementation,
889
and the state of the global environment.
890
Some specific issues which frequently affect the outcome are
892
nature of the scheduler (if any),
893
number of competing processes (if any),
895
whether the call is interpreted or compiled,
896
whether functions called are compiled,
897
the kind of garbage collector involved and whether it runs,
898
whether internal data structures (e.g., hash tables) are implicitly reorganized,
901
@subsubheading See Also::
903
@ref{get-internal-real-time}
905
@ref{get-internal-run-time}
907
@subsubheading Notes::
909
In general, these timings are not guaranteed to be reliable enough for
910
marketing comparisons. Their value is primarily heuristic, for tuning
913
For useful background information on the complicated issues involved in
914
interpreting timing results, see @i{Performance and Evaluation of Lisp Programs}.
916
@node internal-time-units-per-second, get-internal-real-time, time, Environment Dictionary
917
@subsection internal-time-units-per-second [Constant Variable]
919
@subsubheading Constant Value::
921
A positive @i{integer}, the magnitude of which is @i{implementation-dependent}.
923
@subsubheading Description::
925
The number of @i{internal time units} in one second.
927
@subsubheading See Also::
929
@ref{get-internal-run-time}
931
@ref{get-internal-real-time}
933
@subsubheading Notes::
935
These units form the basis of the Internal Time format representation.
937
@node get-internal-real-time, get-internal-run-time, internal-time-units-per-second, Environment Dictionary
938
@subsection get-internal-real-time [Function]
940
@code{get-internal-real-time} @i{<@i{no @i{arguments}}>} @result{} @i{internal-time}
942
@subsubheading Arguments and Values::
944
@i{internal-time}---a non-negative @i{integer}.
946
@subsubheading Description::
948
@b{get-internal-real-time} returns as an @i{integer} the
949
current time in @i{internal time units}, relative to an arbitrary
950
time base. The difference between the values of two calls to this
951
function is the amount of elapsed real time (@i{i.e.}, clock time) between the two calls.
953
@subsubheading Affected By::
955
Time of day (@i{i.e.}, the passage of time).
956
The time base affects the result magnitude.
958
@subsubheading See Also::
960
@ref{internal-time-units-per-second}
962
@node get-internal-run-time, disassemble, get-internal-real-time, Environment Dictionary
963
@subsection get-internal-run-time [Function]
965
@code{get-internal-run-time} @i{<@i{no @i{arguments}}>} @result{} @i{internal-time}
967
@subsubheading Arguments and Values::
969
@i{internal-time}---a non-negative @i{integer}.
971
@subsubheading Description::
973
Returns as an @i{integer} the current
974
run time in @i{internal time units}. The precise meaning of this quantity is
975
@i{implementation-defined}; it may measure real time, run time, CPU cycles, or some
976
other quantity. The intent is that the difference between the values of two calls
977
to this function be the amount of time between the two calls during which
978
computational effort was expended on behalf of the executing program.
980
@subsubheading Affected By::
982
The @i{implementation},
983
the time of day (@i{i.e.}, the passage of time).
985
@subsubheading See Also::
987
@ref{internal-time-units-per-second}
989
@subsubheading Notes::
991
Depending on the @i{implementation}, paging time and garbage
992
collection time might be included in this measurement. Also, in a
993
multitasking environment, it might not be possible to show the time for
994
just the running process, so in some @i{implementations}, time taken
995
by other processes during the same time interval might be included in
996
this measurement as well.
998
@node disassemble, documentation, get-internal-run-time, Environment Dictionary
999
@subsection disassemble [Function]
1001
@code{disassemble} @i{fn} @result{} @i{@b{nil}}
1003
@subsubheading Arguments and Values::
1005
@i{fn}---an @i{extended function designator}
1006
or a @i{lambda expression}.
1008
@subsubheading Description::
1010
The @i{function} @b{disassemble} is a debugging aid that composes symbolic
1011
instructions or expressions in some @i{implementation-dependent}
1012
language which represent the code used to produce the @i{function}
1013
which is or is named by the argument @i{fn}. The result is displayed
1014
to @i{standard output} in an @i{implementation-dependent} format.
1016
If @i{fn} is a @i{lambda expression} or @i{interpreted function},
1017
it is compiled first and the result is disassembled.
1019
If the @i{fn} @i{designator} is a @i{function name},
1020
the @i{function} that it @i{names} is disassembled.
1022
(If that @i{function} is an @i{interpreted function},
1023
it is first compiled but the result of this implicit compilation is not installed.)
1025
@subsubheading Examples::
1028
(defun f (a) (1+ a)) @result{} F
1029
(eq (symbol-function 'f)
1030
(progn (disassemble 'f)
1031
(symbol-function 'f))) @result{} @i{true}
1034
@subsubheading Affected By::
1036
@b{*standard-output*}.
1038
@subsubheading Exceptional Situations::
1040
Should signal an error of @i{type} @b{type-error}
1041
if @i{fn} is not an @i{extended function designator}
1042
or a @i{lambda expression}.
1044
@node documentation, room, disassemble, Environment Dictionary
1045
@subsection documentation, (setf documentation) [Standard Generic Function]
1047
@subsubheading Syntax::
1049
@code{documentation} @i{x doc-type} @result{} @i{documentation}
1051
@code{(setf documentation)} @i{new-value x doc-type} @result{} @i{new-value}
1053
@subsubheading Argument Precedence Order::
1055
@i{doc-type}, @i{object}
1057
@subsubheading Method Signatures::
1059
@subsubheading Functions, Macros, and Special Forms
1061
documentation (@i{x} @code{function}) (doc-type (eql 't))@*
1062
(setf documentation) @i{new-value}(@i{x} @code{function}) (doc-type (eql 't))
1064
documentation (@i{x} @code{function}) (doc-type (eql 'function))@*
1065
(setf documentation) @i{new-value}(@i{x} @code{function}) (doc-type (eql 'function))
1067
documentation (@i{x} @code{list}) (doc-type (eql 'function))@*
1068
(setf documentation) @i{new-value}(@i{x} @code{list}) (doc-type (eql 'function))
1070
documentation (@i{x} @code{list}) (doc-type (eql 'compiler-macro))@*
1071
(setf documentation) @i{new-value}(@i{x} @code{list}) (doc-type (eql 'compiler-macro))
1073
documentation (@i{x} @code{symbol}) (doc-type (eql 'function))@*
1074
(setf documentation) @i{new-value}(@i{x} @code{symbol}) (doc-type (eql 'function))
1076
documentation (@i{x} @code{symbol}) (doc-type (eql 'compiler-macro))@*
1077
(setf documentation) @i{new-value}(@i{x} @code{symbol}) (doc-type (eql 'compiler-macro))
1079
documentation (@i{x} @code{symbol}) (doc-type (eql 'setf))@*
1080
(setf documentation) @i{new-value}(@i{x} @code{symbol}) (doc-type (eql 'setf))
1082
@subsubheading Method Combinations
1084
documentation (@i{x} @code{method-combination}) (doc-type (eql 't))@*
1085
(setf documentation) @i{new-value}(@i{x} @code{method-combination}) (doc-type (eql 't))
1087
documentation (@i{x} @code{method-combination}) (doc-type (eql 'method-combination))@*
1088
(setf documentation) @i{new-value}(@i{x} @code{method-combination}) (doc-type (eql 'method-combination))
1090
documentation (@i{x} @code{symbol}) (doc-type (eql 'method-combination))@*
1091
(setf documentation) @i{new-value}(@i{x} @code{symbol}) (doc-type (eql 'method-combination))
1093
@subsubheading Methods
1095
documentation (@i{x} @code{standard-method}) (doc-type (eql 't))@*
1096
(setf documentation) @i{new-value}(@i{x} @code{standard-method}) (doc-type (eql 't))
1098
@subsubheading Packages
1100
documentation (@i{x} @code{package}) (doc-type (eql 't))@*
1101
(setf documentation) @i{new-value}(@i{x} @code{package}) (doc-type (eql 't))
1103
@subsubheading Types, Classes, and Structure Names
1105
documentation (@i{x} @code{standard-class}) (doc-type (eql 't))@*
1106
(setf documentation) @i{new-value}(@i{x} @code{standard-class}) (doc-type (eql 't))
1108
documentation (@i{x} @code{standard-class}) (doc-type (eql 'type))@*
1109
(setf documentation) @i{new-value}(@i{x} @code{standard-class}) (doc-type (eql 'type))
1111
documentation (@i{x} @code{structure-class}) (doc-type (eql 't))@*
1112
(setf documentation) @i{new-value}(@i{x} @code{structure-class}) (doc-type (eql 't))
1114
documentation (@i{x} @code{structure-class}) (doc-type (eql 'type))@*
1115
(setf documentation) @i{new-value}(@i{x} @code{structure-class}) (doc-type (eql 'type))
1117
documentation (@i{x} @code{symbol}) (doc-type (eql 'type))@*
1118
(setf documentation) @i{new-value}(@i{x} @code{symbol}) (doc-type (eql 'type))
1120
documentation (@i{x} @code{symbol}) (doc-type (eql 'structure))@*
1121
(setf documentation) @i{new-value}(@i{x} @code{symbol}) (doc-type (eql 'structure))
1123
@subsubheading Variables
1125
documentation (@i{x} @code{symbol}) (doc-type (eql 'variable))@*
1126
(setf documentation) @i{new-value}(@i{x} @code{symbol}) (doc-type (eql 'variable))
1128
@subsubheading Arguments and Values::
1130
@i{x}---an @i{object}.
1132
@i{doc-type}---a @i{symbol}.
1134
@i{documentation}---a @i{string}, or @b{nil}.
1136
@i{new-value}---a @i{string}.
1138
@subsubheading Description::
1140
The @i{generic function} @b{documentation} returns the @i{documentation string}
1141
associated with the given @i{object} if it is available;
1142
otherwise it returns @b{nil}.
1144
The @i{generic function} @t{(setf documentation)} updates the
1145
@i{documentation string} associated with @i{x} to @i{new-value}.
1146
If @i{x} is a @i{list},
1147
it must be of the form @t{(setf @i{symbol})}.
1149
@i{Documentation strings} are made available for debugging purposes.
1150
@i{Conforming programs} are permitted to use @i{documentation strings}
1151
when they are present, but should not depend for their correct behavior on
1152
the presence of those @i{documentation strings}.
1153
An @i{implementation} is permitted to discard @i{documentation strings}
1154
at any time for @i{implementation-defined} reasons.
1156
The nature of the @i{documentation string} returned depends on the
1157
@i{doc-type}, as follows:
1161
@item @b{compiler-macro}
1162
Returns the @i{documentation string} of the @i{compiler macro}
1163
whose @i{name} is the @i{function name} @i{x}.
1166
If @i{x} is a @i{function name},
1167
returns the @i{documentation string} of
1168
the @i{function}, @i{macro}, or @i{special operator}
1169
whose @i{name} is @i{x}.
1171
If @i{x} is a @i{function},
1172
returns the @i{documentation string} associated with @i{x}.
1174
@item @b{method-combination}
1175
If @i{x} is a @i{symbol},
1176
returns the @i{documentation string} of
1177
the @i{method combination}
1178
whose @i{name} is @i{x}.
1180
If @i{x} is a @i{method combination},
1181
returns the @i{documentation string} associated with @i{x}.
1184
Returns the @i{documentation string} of
1186
the @i{setf expander}
1188
whose @i{name} is the @i{symbol} @i{x}.
1191
Returns the @i{documentation string}
1192
associated with the @i{structure name} @i{x}.
1195
Returns a @i{documentation string} specialized on the @i{class} of
1196
the argument @i{x} itself.
1197
For example, if @i{x} is a @i{function},
1198
the @i{documentation string} associated with the @i{function} @i{x} is returned.
1201
If @i{x} is a @i{symbol},
1202
returns the @i{documentation string} of the @i{class}
1203
whose @i{name} is the @i{symbol} @i{x},
1204
if there is such a @i{class}.
1205
Otherwise, it returns the @i{documentation string} of the @i{type}
1206
which is the @i{type specifier} @i{symbol} @i{x}.
1208
If @i{x} is a @i{structure class} or @i{standard class},
1209
returns the @i{documentation string} associated with
1210
the @i{class} @i{x}.
1213
Returns the @i{documentation string} of
1214
the @i{dynamic variable} or @i{constant variable}
1215
whose @i{name} is the @i{symbol} @i{x}.
1219
A @i{conforming implementation} or a @i{conforming program}
1220
may extend the set of @i{symbols} that are acceptable as the @i{doc-type}.
1222
@subsubheading Notes::
1224
This standard prescribes no means to retrieve the @i{documentation strings}
1225
for individual slots specified in a @b{defclass} form, but
1226
@i{implementations} might still provide debugging tools and/or
1227
programming language extensions which manipulate this information.
1228
Implementors wishing to provide such support are encouraged to consult the
1229
@i{Metaobject Protocol} for suggestions about how this might be done.
1231
@node room, ed, documentation, Environment Dictionary
1232
@subsection room [Function]
1234
@code{room} @i{@r{&optional} x} @result{} @i{@i{implementation-dependent}}
1236
@subsubheading Arguments and Values::
1238
@i{x}---one of @b{t}, @b{nil}, or @t{:default}.
1240
@subsubheading Description::
1242
@b{room} prints, to @i{standard output},
1243
information about the state of internal storage and its management.
1244
This might include descriptions of the amount of memory in use and
1245
the degree of memory compaction, possibly broken down by internal data type if that
1246
is appropriate. The nature and format of the printed information is
1247
@i{implementation-dependent}.
1248
The intent is to provide information that a @i{programmer}
1249
might use to tune a @i{program} for a particular @i{implementation}.
1251
@t{(room nil)} prints out a minimal amount of information.
1252
@t{(room t)} prints out a maximal amount of information.
1254
@t{(room)} or @t{(room :default)} prints out an intermediate amount
1255
of information that is likely to be useful.
1257
@subsubheading Side Effects::
1259
Output to @i{standard output}.
1261
@subsubheading Affected By::
1263
@b{*standard-output*}.
1265
@node ed, inspect, room, Environment Dictionary
1266
@subsection ed [Function]
1268
@code{ed} @i{@r{&optional} x} @result{} @i{@i{implementation-dependent}}
1270
@subsubheading Arguments and Values::
1272
@i{x}---@b{nil}, a @i{pathname}, a @i{string}, or a @i{function name}.
1274
The default is @b{nil}.
1276
@subsubheading Description::
1278
@b{ed} invokes the editor if the @i{implementation} provides a resident editor.
1280
If @i{x} is @b{nil}, the editor is entered.
1281
If the editor had been previously entered, its prior state is resumed, if possible.
1283
If @i{x} is a @i{pathname} or @i{string},
1284
it is taken as the @i{pathname designator} for a @i{file} to be edited.
1286
If @i{x} is a @i{function name}, the text of its definition is edited.
1287
The means by which the function text is obtained is @i{implementation-defined}.
1289
@subsubheading Exceptional Situations::
1291
The consequences are undefined if the @i{implementation} does not provide a resident editor.
1293
Might signal @b{type-error} if its argument is supplied but is not
1294
a @i{symbol}, a @i{pathname}, or @b{nil}.
1296
If a failure occurs when performing some operation on the @i{file system}
1297
while attempting to edit a @i{file},
1298
an error of @i{type} @b{file-error} is signaled.
1300
An error of @i{type} @b{file-error} might be signaled if @i{x}
1301
is a @i{designator} for a @i{wild} @i{pathname}.
1303
@i{Implementation-dependent} additional conditions might be signaled as well.
1305
@subsubheading See Also::
1309
@b{logical-pathname},
1316
@ref{Pathnames as Filenames}
1318
@node inspect, dribble, ed, Environment Dictionary
1319
@subsection inspect [Function]
1321
@code{inspect} @i{object} @result{} @i{@i{implementation-dependent}}
1323
@subsubheading Arguments and Values::
1325
@i{object}---an @i{object}.
1327
@subsubheading Description::
1329
@b{inspect} is an interactive version of @b{describe}.
1330
The nature of the interaction is @i{implementation-dependent},
1331
but the purpose of @b{inspect} is to make it easy to wander
1332
through a data structure, examining and modifying parts of it.
1334
@subsubheading Side Effects::
1336
@i{implementation-dependent}.
1338
@subsubheading Affected By::
1340
@i{implementation-dependent}.
1342
@subsubheading Exceptional Situations::
1344
@i{implementation-dependent}.
1346
@subsubheading See Also::
1350
@subsubheading Notes::
1352
Implementations are encouraged to respond to the typing
1353
of @t{?} or a ``help key'' by providing help, including a list
1356
@node dribble, - (Variable), inspect, Environment Dictionary
1357
@subsection dribble [Function]
1359
@code{dribble} @i{@r{&optional} pathname} @result{} @i{@i{implementation-dependent}}
1361
@subsubheading Arguments and Values::
1363
@i{pathname}---a @i{pathname designator}.
1365
@subsubheading Description::
1367
Either @i{binds} @b{*standard-input*} and @b{*standard-output*}
1368
or takes other appropriate action,
1369
so as to send a record of the input/output interaction to a file
1370
named by @i{pathname}. @b{dribble} is intended to create
1371
a readable record of an interactive session.
1373
If @i{pathname} is a @i{logical pathname}, it is translated
1374
into a physical pathname as if by calling @b{translate-logical-pathname}.
1376
@t{(dribble)} terminates the recording of input and output
1377
and closes the dribble file.
1379
If @b{dribble} is @i{called} while a @i{stream} to a ``dribble file''
1380
is still open from a previous @i{call} to @b{dribble},
1381
the effect is @i{implementation-defined}. For example,
1382
the already-@i{open} @i{stream} might be @i{closed},
1383
or dribbling might occur both to the old @i{stream} and to a new one,
1384
or the old @i{stream} might stay open but not receive any further output,
1385
or the new request might be ignored,
1386
or some other action might be taken.
1388
@subsubheading Affected By::
1390
The @i{implementation}.
1392
@subsubheading Exceptional Situations::
1394
If a failure occurs when performing some operation on the @i{file system}
1395
while creating the dribble file,
1396
an error of @i{type} @b{file-error} is signaled.
1398
An error of @i{type} @b{file-error} might be signaled if @i{pathname}
1399
is a @i{designator} for a @i{wild} @i{pathname}.
1401
@subsubheading See Also::
1403
@ref{Pathnames as Filenames}
1405
@subsubheading Notes::
1407
@b{dribble} can return before subsequent
1408
@i{forms} are executed. It also
1409
can enter a recursive interaction loop,
1410
returning only when @t{(dribble)} is done.
1412
@b{dribble} is intended primarily for interactive debugging;
1413
its effect cannot be relied upon when used in a program.
1415
@node - (Variable), + (Variable), dribble, Environment Dictionary
1416
@subsection - [Variable]
1418
@subsubheading Value Type::
1422
@subsubheading Initial Value::
1424
@i{implementation-dependent}.
1426
@subsubheading Description::
1428
The @i{value} of @b{-} is the @i{form} that is currently being evaluated by
1429
the @i{Lisp read-eval-print loop}.
1431
@subsubheading Examples::
1434
(format t "~&Evaluating ~S~
1435
@t{ |> } Evaluating (FORMAT T "~&Evaluating ~S~
1439
@subsubheading Affected By::
1441
@i{Lisp read-eval-print loop}.
1443
@subsubheading See Also::
1445
@b{+} (@i{variable}),
1446
@b{*} (@i{variable}),
1449
@ref{Top level loop}
1451
@node + (Variable), * (Variable), - (Variable), Environment Dictionary
1452
@subsection +, ++, +++ [Variable]
1454
@subsubheading Value Type::
1458
@subsubheading Initial Value::
1460
@i{implementation-dependent}.
1462
@subsubheading Description::
1464
The @i{variables} @b{+}, @b{++}, and @b{+++} are maintained by the
1465
@i{Lisp read-eval-print loop} to save @i{forms} that were
1466
recently @i{evaluated}.
1468
The @i{value} of @b{+} is the last @i{form} that was @i{evaluated},
1469
the @i{value} of @b{++} is the previous value of @b{+}, and
1470
the @i{value} of @b{+++} is the previous value of @b{++}.
1472
@subsubheading Examples::
1477
(list + ++ +++) @result{} ((/ 9 3) (- 4 2) (+ 0 1))
1478
(setq a 1 b 2 c 3 d (list a b c)) @result{} (1 2 3)
1479
(setq a 4 b 5 c 6 d (list a b c)) @result{} (4 5 6)
1480
(list a b c) @result{} (4 5 6)
1481
(eval +++) @result{} (1 2 3)
1482
#.`(,@@++ d) @result{} (1 2 3 (1 2 3))
1485
@subsubheading Affected By::
1487
@i{Lisp read-eval-print loop}.
1489
@subsubheading See Also::
1493
@b{*} (@i{variable}),
1496
@ref{Top level loop}
1498
@node * (Variable), / (Variable), + (Variable), Environment Dictionary
1499
@subsection *, **, *** [Variable]
1501
@subsubheading Value Type::
1505
@subsubheading Initial Value::
1507
@i{implementation-dependent}.
1509
@subsubheading Description::
1511
The @i{variables} @b{*}, @b{**}, and @b{***} are
1512
maintained by the @i{Lisp read-eval-print loop} to save the
1513
values of results that are printed each time through the loop.
1515
The @i{value} of @b{*} is the most recent @i{primary value} that was printed,
1516
the @i{value} of @b{**} is the previous value of @b{*}, and
1517
the @i{value} of @b{***} is the previous value of @b{**}.
1519
If several values are produced, @b{*} contains the first value only;
1520
@b{*} contains @b{nil} if zero values are produced.
1522
The @i{values} of @b{*}, @b{**}, and @b{***} are updated immediately
1523
prior to printing the @i{return value} of a top-level @i{form} by the
1524
@i{Lisp read-eval-print loop}. If the @i{evaluation} of such a @i{form}
1525
is aborted prior to its normal return, the values of @b{*}, @b{**}, and @b{***}
1528
@subsubheading Examples::
1530
(values 'a1 'a2) @result{} A1, A2
1532
(values 'c1 'c2 'c3) @result{} C1, C2, C3
1533
(list * ** ***) @result{} (C1 B A1)
1535
(defun cube-root (x) (expt x 1/3)) @result{} CUBE-ROOT
1536
(compile *) @result{} CUBE-ROOT
1537
(setq a (cube-root 27.0)) @result{} 3.0
1538
(* * 9.0) @result{} 27.0
1541
@subsubheading Affected By::
1543
@i{Lisp read-eval-print loop}.
1545
@subsubheading See Also::
1549
@b{+} (@i{variable}),
1552
@ref{Top level loop}
1554
@subsubheading Notes::
1558
** @equiv{} (car //)
1559
*** @equiv{} (car ///)
1562
@node / (Variable), lisp-implementation-type, * (Variable), Environment Dictionary
1563
@subsection /, //, /// [Variable]
1565
@subsubheading Value Type::
1569
@subsubheading Initial Value::
1571
@i{implementation-dependent}.
1573
@subsubheading Description::
1575
The @i{variables} @b{/}, @b{//}, and @b{///} are maintained by
1576
the @i{Lisp read-eval-print loop} to save the values of results that
1577
were printed at the end of the loop.
1579
The @i{value} of @b{/} is a @i{list} of the most recent @i{values} that were printed,
1580
the @i{value} of @b{//} is the previous value of @b{/}, and
1581
the @i{value} of @b{///} is the previous value of @b{//}.
1583
The @i{values} of @b{/}, @b{//}, and @b{///} are updated immediately
1584
prior to printing the @i{return value} of a top-level @i{form} by the
1585
@i{Lisp read-eval-print loop}. If the @i{evaluation} of such a @i{form}
1586
is aborted prior to its normal return, the values of @b{/}, @b{//}, and @b{///}
1589
@subsubheading Examples::
1591
(floor 22 7) @result{} 3, 1
1592
(+ (* (car /) 7) (cadr /)) @result{} 22
1595
@subsubheading Affected By::
1597
@i{Lisp read-eval-print loop}.
1599
@subsubheading See Also::
1603
@b{+} (@i{variable}),
1604
@b{*} (@i{variable}),
1605
@ref{Top level loop}
1607
@node lisp-implementation-type, short-site-name, / (Variable), Environment Dictionary
1608
@subsection lisp-implementation-type,
1609
@subheading lisp-implementation-version
1614
@code{lisp-implementation-type} @i{<@i{no @i{arguments}}>} @result{} @i{description}
1616
@code{lisp-implementation-version} @i{<@i{no @i{arguments}}>} @result{} @i{description}
1618
@subsubheading Arguments and Values::
1620
@i{description}---a @i{string} or @b{nil}.
1622
@subsubheading Description::
1624
@b{lisp-implementation-type} and @b{lisp-implementation-version}
1625
identify the current implementation of @r{Common Lisp}.
1627
@b{lisp-implementation-type} returns a @i{string}
1628
that identifies the generic name of
1629
the particular @r{Common Lisp} implementation.
1631
@b{lisp-implementation-version}
1632
returns a @i{string} that identifies the version of
1633
the particular @r{Common Lisp} implementation.
1636
and relevant result can be produced, @b{nil} is returned instead
1639
@subsubheading Examples::
1642
(lisp-implementation-type)
1643
@result{} "ACME Lisp"
1644
@i{OR}@result{} "Joe's Common Lisp"
1645
(lisp-implementation-version)
1648
@i{OR}@result{} "Release 17.3, ECO #6"
1651
@node short-site-name, machine-instance, lisp-implementation-type, Environment Dictionary
1652
@subsection short-site-name, long-site-name [Function]
1654
@code{short-site-name} @i{<@i{no @i{arguments}}>} @result{} @i{description}
1656
@code{long-site-name} @i{<@i{no @i{arguments}}>} @result{} @i{description}
1658
@subsubheading Arguments and Values::
1660
@i{description}---a @i{string} or @b{nil}.
1662
@subsubheading Description::
1664
@b{short-site-name} and @b{long-site-name} return
1665
a @i{string} that identifies the physical location
1666
of the computer hardware,
1667
or @b{nil} if no appropriate @i{description} can be produced.
1669
@subsubheading Examples::
1673
@result{} "MIT AI Lab"
1674
@i{OR}@result{} "CMU-CSD"
1676
@result{} "MIT Artificial Intelligence Laboratory"
1677
@i{OR}@result{} "CMU Computer Science Department"
1680
@subsubheading Affected By::
1683
the location of the computer hardware,
1684
and the installation/configuration process.
1686
@node machine-instance, machine-type, short-site-name, Environment Dictionary
1687
@subsection machine-instance [Function]
1689
@code{machine-instance} @i{<@i{no @i{arguments}}>} @result{} @i{description}
1691
@subsubheading Arguments and Values::
1693
@i{description}---a @i{string} or @b{nil}.
1695
@subsubheading Description::
1697
Returns a @i{string} that identifies the particular instance of
1698
the computer hardware on which @r{Common Lisp} is running,
1699
or @b{nil} if no such @i{string} can be computed.
1701
@subsubheading Examples::
1705
@result{} "ACME.COM"
1706
@i{OR}@result{} "S/N 123231"
1707
@i{OR}@result{} "18.26.0.179"
1708
@i{OR}@result{} "AA-00-04-00-A7-A4"
1711
@subsubheading Affected By::
1713
The machine instance,
1714
and the @i{implementation}.
1716
@subsubheading See Also::
1720
@ref{machine-version}
1722
@node machine-type, machine-version, machine-instance, Environment Dictionary
1723
@subsection machine-type [Function]
1725
@code{machine-type} @i{<@i{no @i{arguments}}>} @result{} @i{description}
1727
@subsubheading Arguments and Values::
1729
@i{description}---a @i{string} or @b{nil}.
1731
@subsubheading Description::
1733
Returns a @i{string} that identifies the generic name of
1734
the computer hardware on which @r{Common Lisp} is running.
1736
@subsubheading Examples::
1740
@result{} "DEC PDP-10"
1741
@i{OR}@result{} "Symbolics LM-2"
1744
@subsubheading Affected By::
1749
@subsubheading See Also::
1751
@ref{machine-version}
1753
@node machine-version, software-type, machine-type, Environment Dictionary
1754
@subsection machine-version [Function]
1756
@code{machine-version} @i{<@i{no @i{arguments}}>} @result{} @i{description}
1758
@subsubheading Arguments and Values::
1760
@i{description}---a @i{string} or @b{nil}.
1762
@subsubheading Description::
1764
Returns a @i{string} that identifies the version of the computer hardware
1765
on which @r{Common Lisp} is running, or @b{nil} if no such value can be computed.
1767
@subsubheading Examples::
1770
(machine-version) @result{} "KL-10, microcode 9"
1773
@subsubheading Affected By::
1775
The machine version,
1776
and the @i{implementation}.
1778
@subsubheading See Also::
1782
@ref{machine-instance}
1784
@node software-type, user-homedir-pathname, machine-version, Environment Dictionary
1785
@subsection software-type, software-version [Function]
1787
@code{software-type} @i{<@i{no @i{arguments}}>} @result{} @i{description}
1789
@code{software-version} @i{<@i{no @i{arguments}}>} @result{} @i{description}
1791
@subsubheading Arguments and Values::
1793
@i{description}---a @i{string} or @b{nil}.
1795
@subsubheading Description::
1797
@b{software-type} returns a @i{string} that identifies the
1798
generic name of any relevant supporting software, or @b{nil} if no
1799
appropriate or relevant result can be produced.
1801
@b{software-version} returns a @i{string} that identifies
1802
the version of any relevant supporting software, or @b{nil} if no
1803
appropriate or relevant result can be produced.
1805
@subsubheading Examples::
1808
(software-type) @result{} "Multics"
1809
(software-version) @result{} "1.3x"
1812
@subsubheading Affected By::
1814
Operating system environment.
1816
@subsubheading Notes::
1818
This information should be of use to maintainers of the @i{implementation}.
1820
@node user-homedir-pathname, , software-type, Environment Dictionary
1821
@subsection user-homedir-pathname [Function]
1823
@code{user-homedir-pathname} @i{@r{&optional} host} @result{} @i{pathname}
1825
@subsubheading Arguments and Values::
1827
@i{host}---a @i{string}, a @i{list} of @i{strings}, or @t{:unspecific}.
1829
@i{pathname}---a @i{pathname}, or @b{nil}.
1831
@subsubheading Description::
1833
@b{user-homedir-pathname} determines the @i{pathname} that corresponds
1834
to the user's home directory on @i{host}.
1835
If @i{host} is not supplied, its value is @i{implementation-dependent}.
1837
For a description of @t{:unspecific}, see @ref{Pathname Components}.
1839
The definition of home directory is @i{implementation-dependent},
1840
but defined in @r{Common Lisp} to mean the directory where the user
1841
keeps personal files such as initialization files and mail.
1843
@b{user-homedir-pathname} returns a @i{pathname} without any name,
1844
type, or version component (those components are all @b{nil})
1845
for the user's home directory on @i{host}.
1847
If it is impossible to determine the user's home directory on @i{host},
1848
then @b{nil} is returned.
1849
@b{user-homedir-pathname} never returns @b{nil} if @i{host} is not supplied.
1851
@subsubheading Examples::
1854
(pathnamep (user-homedir-pathname)) @result{} @i{true}
1857
@subsubheading Affected By::
1859
The host computer's file system,
1860
and the @i{implementation}.
1862
@c end of including dict-environment
1864
@c %**end of chapter
added
removed
info/chap-25.texi
