source: trunk/source/doc/src/using.xml @ 14399

Last change on this file since 14399 was 14399, checked in by rme, 9 years ago

Some documentation for ccl:wait-for-signal.

File size: 121.1 KB
Line 
1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
3          <!ENTITY rest "<varname>&amp;rest</varname>">
4          <!ENTITY key "<varname>&amp;key</varname>">
5          <!ENTITY optional "<varname>&amp;optional</varname>">
6          <!ENTITY body "<varname>&amp;body</varname>">
7          <!ENTITY aux "<varname>&amp;aux</varname>">
8          <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
9          <!ENTITY CCL "Clozure CL">
10          ]>
11
12<chapter id="using-ccl"><title>Using &CCL;</title>
13 
14  <!-- ============================================================ -->
15  <sect1 id="using-ccl-introduction"><title>Introduction</title>
16   
17    <para>The Common Lisp standard allows considerable latitude in the
18      details of an implementation, and each particular Common Lisp
19      system has some idiosyncrasies. This chapter describes ordinary
20      user-level features of &CCL;, including features that may be
21      part of the Common Lisp standard, but which may have quirks or
22      details in the &CCL; implementation that are not described by
23      the standard. It also describes extensions to the standard; that
24      is, features of &CCL; that are not part of the Common Lisp
25      standard at all.</para>
26
27  </sect1>
28
29  <!-- ============================================================ -->
30  <sect1 id="Trace"><title>Trace</title>
31
32    <para>
33      &CCL;'s tracing facility is invoked by an extended version of the Common Lisp
34      <varname>trace</varname> macro.  Extensions allow tracing of methods, as well as finer control
35      over tracing actions.
36    </para>
37
38    <para>
39      <indexterm zone="trace"/>
40      <command><varname id="trace">TRACE</varname> {<replaceable>keyword</replaceable>
41        <replaceable>global-value</replaceable>}* {<replaceable>spec</replaceable> |
42        (<replaceable>spec</replaceable> {<replaceable>keyword</replaceable>
43        <replaceable>local-value</replaceable>}*)}* [Macro]</command>
44    </para>
45
46    <para>
47      The <varname>trace</varname> macro encapsulates the functions named by
48      <replaceable>spec</replaceable>s, causing trace actions to take place on entry and
49      exit from each function.  The default actions print a message on function entry and
50      exit. <replaceable>Keyword</replaceable>/<replaceable>value</replaceable> options
51      can be used to specify changes in the default behavior.
52    </para>
53
54    <para>
55      Invoking <varname>(trace)</varname> without arguments returns a list of functions being traced.
56    </para>
57   
58    <para>
59      A <replaceable>spec</replaceable> is either a symbol that is the name of a function, or an
60      expression of the form <varname>(setf <replaceable>symbol</replaceable>)</varname>, or a
61      specific method of a generic function in the form <varname>(:method
62        <replaceable>gf-name</replaceable> {<replaceable>qualifier</replaceable>}*
63        ({<replaceable>specializer</replaceable>}*))</varname>, where a
64      <replaceable>specializer</replaceable> can be the name of a class or an <varname>EQL</varname>
65      specializer.
66    </para>
67
68    <para>
69      A <replaceable>spec</replaceable> can also be a string naming a package, or equivalently a
70      list <varname>(:package <replaceable>package-name</replaceable>)</varname>, in order to
71      request that all functions in the package to be traced.
72    </para>
73
74    <para>
75      By default, whenever a traced function is entered or exited, a short message is
76      printed on <varname>*trace-output*</varname> showing the arguments on entry and
77      values on exit.  Options specified as key/value pairs can be used to modify this
78      behavior.  Options preceding the function <replaceable>spec</replaceable>s apply to
79      all the functions being traced.  Options specified along with a
80      <replaceable>spec</replaceable> apply to that spec only and override any
81      global options. The following options are supported:
82    </para>
83
84    <variablelist>
85
86      <varlistentry>
87            <term><varname>:methods {T | nil}</varname></term>
88            <listitem>
89              <para> If true, and if applied to a <replaceable>spec</replaceable> naming a generic
90                function, arranges to trace all the methods of the generic function in addition to the
91                generic function itself.
92              </para>
93            </listitem>
94      </varlistentry>
95
96      <varlistentry>
97            <term><varname>:inside <replaceable>outside-spec</replaceable>
98                | ({<replaceable>outside-spec</replaceable>}*)</varname></term>
99            <listitem>
100              <para>Inhibits all trace actions unless the current
101                invocation of the function being traced is inside one of the
102                <replaceable>outside-spec</replaceable>'s, i.e. unless a function named by one of the
103                <replaceable>outside-spec</replaceable>'s is currently on the stack.
104                <replaceable>outside-spec</replaceable> can name a function, a
105                method, or a package, as above.
106              </para>
107            </listitem>
108      </varlistentry>
109
110      <varlistentry>
111            <term><varname>:if <replaceable>form</replaceable></varname></term>
112            <term><varname>:condition <replaceable>form</replaceable></varname></term>
113            <listitem>
114              <para> Evaluates <replaceable>form</replaceable> whenever the function being traced is
115                about to be entered, and inhibits all trace actions if <replaceable>form</replaceable>
116                returns nil. The form may reference the lexical variable <varname>ccl::args</varname>,
117                which is a list of the arguments in this call. <varname>:condition</varname> is just a
118                synonym for <varname>:if</varname>, though if both are specified, both must return non-nil.
119              </para>
120            </listitem>
121      </varlistentry>
122
123      <varlistentry>
124            <term><varname>:before-if <replaceable>form</replaceable></varname></term>
125            <listitem>
126              <para> Evaluates <replaceable>form</replaceable> whenever the function being traced is
127                about to be entered, and inhibits the entry trace actions if
128                <replaceable>form</replaceable> returns nil.  The form may reference the lexical variable
129                <varname>ccl::args</varname>, which is a list of the arguments in this call. If both
130                <varname>:if</varname> and <varname>:before-if</varname> are specified, both must return
131                non-nil in order for the before entry actions to happen.
132              </para>
133            </listitem>
134      </varlistentry>
135
136      <varlistentry>
137            <term><varname>:after-if <replaceable>form</replaceable></varname></term>
138            <listitem>
139              <para> Evaluates <replaceable>form</replaceable> whenever the function being traced has
140                just exited, and inhibits the exit trace actions if <replaceable>form</replaceable>
141                returns nil.  The form may reference the lexical variable <varname>ccl::vals</varname>,
142                which is a list of values returned by this call. If both <varname>:if</varname> and
143                <varname>:after-if</varname> are specified, both must return non-nil in order for the
144                after exit actions to happen.
145              </para>
146            </listitem>
147      </varlistentry>
148
149      <varlistentry>
150            <term><varname>:print-before <replaceable>form</replaceable></varname></term>
151            <listitem>
152              <para> Evaluates <replaceable>form</replaceable> whenever the function being traced is
153                about to be entered, and prints the result before printing the standard entry message.
154                The form may reference the lexical variable <varname>ccl::args</varname>, which is a list
155                of the arguments in this call.  To see multiple forms, use <varname>values</varname>:
156                <varname>:print-before (values (one-thing) (another-thing))</varname>.
157              </para>
158            </listitem>
159      </varlistentry>
160
161      <varlistentry>
162            <term><varname>:print-after <replaceable>form</replaceable></varname></term>
163            <listitem>
164              <para> Evaluates <replaceable>form</replaceable> whenever the function being traced has
165                just exited, and prints the result after printing the standard exit message.  The form may
166                reference the lexical variable <varname>ccl::vals</varname>, which is a list of values
167                returned by this call. To see multiple forms, use <varname>values</varname>:
168                <varname>:print-after (values (one-thing) (another-thing))</varname>.
169              </para>
170            </listitem>
171      </varlistentry>
172
173      <varlistentry>
174            <term><varname>:print <replaceable>form</replaceable></varname></term>
175            <listitem>
176              <para>Equivalent to <varname>:print-before <replaceable>form</replaceable> :print-after <replaceable>form</replaceable></varname>.
177              </para>
178            </listitem>
179      </varlistentry>
180
181      <varlistentry>
182            <term><varname>:eval-before <replaceable>form</replaceable></varname></term>
183            <listitem>
184              <para>Evaluates <replaceable>form</replaceable> whenever the function being traced is
185                about to be entered.  The form may reference the lexical variable
186                <varname>ccl::args</varname>, which is a list of the arguments in this call.
187              </para>
188            </listitem>
189      </varlistentry>
190
191      <varlistentry>
192            <term><varname>:eval-after <replaceable>form</replaceable></varname></term>
193            <listitem>
194              <para>Evaluates <replaceable>form</replaceable> whenever the function being has just
195                exited.  The form may reference the lexical variable <varname>ccl::vals</varname>, which
196                is a list of values returned by this call.
197              </para>
198            </listitem>
199      </varlistentry>
200
201      <varlistentry>
202            <term><varname>:eval <replaceable>form</replaceable></varname></term>
203            <listitem>
204              <para>Equivalent to <varname>:eval-before <replaceable>form</replaceable>
205                  :eval-after <replaceable>form</replaceable></varname>.
206              </para>
207            </listitem>
208      </varlistentry>
209
210      <varlistentry>
211            <term><varname>:break-before <replaceable>form</replaceable></varname></term>
212            <listitem>
213              <para>Evaluates <replaceable>form</replaceable> whenever the function being traced is
214                about to be entered, and if the result is non-nil, enters a debugger break loop.  The form
215                may reference the lexical variable <varname>ccl::args</varname>, which is a list of the
216                arguments in this call.
217              </para>
218            </listitem>
219      </varlistentry>
220
221      <varlistentry>
222            <term><varname>:break-after <replaceable>form</replaceable></varname></term>
223            <listitem>
224              <para>Evaluates <replaceable>form</replaceable> whenever the function being traced has
225                just exited, and if the result is non-nil, enters a debugger break loop. The form may
226                reference the lexical variable <varname>ccl::vals</varname>, which is a list of values
227                returned by this call.
228              </para>
229            </listitem>
230      </varlistentry>
231
232      <varlistentry>
233            <term><varname>:break <replaceable>form</replaceable></varname></term>
234            <listitem>
235              <para>Equivalent to <varname>:break-before <replaceable>form</replaceable> :break-after <replaceable>form</replaceable></varname>.
236              </para>
237            </listitem>
238      </varlistentry>
239
240      <varlistentry>
241            <term><varname>:backtrace-before <replaceable>form</replaceable></varname></term>
242            <term><varname>:backtrace <replaceable>form</replaceable></varname></term>
243            <listitem>
244              <para>Evaluates <replaceable>form</replaceable> whenever the function being traced is
245                about to be entered.  The form may reference the lexical variable
246                <varname>ccl::args</varname>, which is a list of the arguments in this call. The value
247                returned by <replaceable>form</replaceable> is intepreted as follows:
248              </para>
249
250              <variablelist>
251
252                <varlistentry>
253                  <term><varname>nil</varname></term>
254                  <listitem><para>does nothing</para></listitem>
255                </varlistentry>
256
257                <varlistentry>
258                  <term><varname>:detailed</varname></term>
259                  <listitem><para>prints a detailed backtrace to
260                      <varname>*trace-output*</varname>.</para></listitem>
261                </varlistentry>
262
263                <varlistentry>
264                  <term><varname>(:detailed <replaceable>integer</replaceable>)</varname></term>
265                  <listitem><para>prints the top <replaceable>integer</replaceable> frames of detailed
266                      backtrace to <varname>*trace-output*</varname>.
267                  </para></listitem>
268                </varlistentry>
269
270                <varlistentry>
271                  <term><replaceable>integer</replaceable></term>
272                  <listitem><para>prints top <replaceable>integer</replaceable> frames of a terse
273                      backtrace to <varname>*trace-output*</varname>.
274                  </para></listitem>
275                </varlistentry>
276
277                <varlistentry>
278                  <term>anything else</term>
279                  <listitem><para>prints a terse backtrace to <varname>*trace-output*</varname>.
280                  </para></listitem>
281                </varlistentry>
282              </variablelist>
283              <para>
284                Note that unlike with the other options, <varname>:backtrace</varname> is equivalent to
285                <varname>:backtrace-before</varname> only, not both before and after, since it's usually
286                not helpful to print the same backtrace both before and after the function call.
287              </para>
288            </listitem>
289      </varlistentry>
290
291      <varlistentry>
292            <term><varname>:backtrace-after <replaceable>form</replaceable></varname></term>
293            <listitem>
294              <para>Evaluates <replaceable>form</replaceable> whenever the function being traced has
295                just exited.  The form may reference the lexical variable <varname>ccl::vals</varname>,
296                which is a list of values returned by this call. The value returned by
297                <replaceable>form</replaceable> is intepreted as follows:
298              </para>
299
300              <variablelist>
301
302                <varlistentry>
303                  <term><varname>nil</varname></term>
304                  <listitem><para>does nothing</para></listitem>
305                </varlistentry>
306
307                <varlistentry>
308                  <term><varname>:detailed</varname></term>
309                  <listitem><para>prints a detailed backtrace to
310                      <varname>*trace-output*</varname>.</para></listitem>
311                </varlistentry>
312
313                <varlistentry>
314                  <term><varname>(:detailed <replaceable>integer</replaceable>)</varname></term>
315                  <listitem><para>prints the top <replaceable>integer</replaceable> frames of detailed
316                      backtrace to <varname>*trace-output*</varname>.
317                  </para></listitem>
318                </varlistentry>
319
320                <varlistentry>
321                  <term><replaceable>integer</replaceable></term>
322                  <listitem><para>prints top <replaceable>integer</replaceable> frames of a terse
323                      backtrace to <varname>*trace-output*</varname>.
324                  </para></listitem>
325                </varlistentry>
326
327                <varlistentry>
328                  <term>anything else</term>
329                  <listitem><para>prints a terse backtrace to <varname>*trace-output*</varname>.
330                  </para></listitem>
331                </varlistentry>
332              </variablelist>
333            </listitem>
334      </varlistentry>
335
336      <varlistentry>
337        <term><varname>:before</varname> <replaceable>action</replaceable></term>
338        <listitem>
339              <para>specifies the action to be taken just before the traced function is entered.  <replaceable>action</replaceable> is one of:</para>
340
341              <variablelist>
342                <varlistentry>
343                  <term><varname>:print</varname></term>
344                  <listitem>
345                        <para>The default, prints a short indented message showing the function name and the invocation arguments</para>
346                  </listitem>
347                </varlistentry>
348
349                <varlistentry>
350                  <term><varname>:break</varname></term>
351                  <listitem>
352                        <para>Equivalent to <varname>:before :print :break-before t</varname></para>
353                  </listitem>
354                </varlistentry>
355
356                <varlistentry>
357                  <term><varname>:backtrace</varname></term>
358                  <listitem>
359                        <para>Equivalent to <varname>:before :print :backtrace-before t</varname></para>
360                  </listitem>
361                </varlistentry>
362
363
364                <varlistentry>
365                  <term><replaceable>function</replaceable></term>
366                  <listitem>
367                        <para>
368                  Any other value is interpreted as a function to call on entry instead of
369                  printing the standard entry message.  It is called with its first
370                  argument being the name of the function being traced, the remaining
371                  arguments being all the arguments to the function being traced, and
372                  <varname>ccl:*trace-level*</varname> bound to the current nesting level
373                  of trace actions. </para>
374                  </listitem>
375                </varlistentry>
376              </variablelist>
377            </listitem>
378      </varlistentry>
379
380      <varlistentry>
381
382        <term><varname>:after</varname> <replaceable>action</replaceable></term>
383        <listitem>
384
385              <para>specifies the action to be taken just after the traced function exits.  <replaceable>action</replaceable> is one of:</para>
386
387              <variablelist>
388                <varlistentry>
389                  <term><varname>:print</varname></term>
390                  <listitem>
391                    <para>The default, prints a short indented message showing the function name and the
392                      returned values </para>
393                  </listitem>
394                </varlistentry>
395
396                <varlistentry>
397                  <term><varname>:break</varname></term>
398                  <listitem>
399                    <para>Equivalent to <varname>:after :print :break-after t</varname></para>
400                  </listitem>
401                </varlistentry>
402
403                    <varlistentry>
404                      <term><varname>:backtrace</varname></term>
405                      <listitem>
406                        <para>Equivalent to <varname>:after :print :backtrace-after t</varname></para>
407                      </listitem>
408                    </varlistentry>
409
410                <varlistentry>
411                  <term><replaceable>function</replaceable></term>
412                  <listitem>
413                    <para>Any other value is interpreted as a function to
414                      call on exit instead of printing the standard exit
415                      message.  It is called with its first argument being
416                      the name of the function being traced, the
417                      remaining arguments being all the values returned by the function
418                      being traced, and ccl:*trace-level* bound to the current
419                      nesting level of trace actions.
420                    </para>
421                  </listitem>
422                </varlistentry>
423              </variablelist>
424        </listitem>
425      </varlistentry>
426
427    </variablelist>
428
429
430    <para>
431      <indexterm zone="trace-level"/>
432      <command><varname id="trace-level">CCL:*TRACE-LEVEL*</varname>    [Variable]</command>
433    </para>
434
435    <para>Variable bound to the current nesting level during execution of before and after trace actions.  The default printing actions use it to determine the amount of indentation.</para>
436
437    <para>
438      <indexterm zone="trace-max-indent"/>
439      <command><varname id="trace-max-indent">CCL:*TRACE-MAX-INDENT*</varname>    [Variable]</command>
440    </para>
441
442    <para>The default before and after print actions will not indent by more than the value of <varname>ccl:*trace-max-indent*</varname> regardless of the current trace level.</para>
443
444    <para>
445      <indexterm zone="trace-function"/>
446      <command><varname id="trace-function">CCL:TRACE-FUNCTION</varname> <replaceable>spec</replaceable> &key; {<replaceable>keyword</replaceable> <replaceable>value</replaceable>}*    [Function]</command>
447    </para>
448   
449    <para>
450      This is a functional version of the TRACE macro.  <replaceable>spec</replaceable> and
451      <replaceable>keyword</replaceable>s are as for TRACE, except that all arguments are evaluated.
452    </para>
453
454    <para>
455      <indexterm zone="trace-print-level"/>
456      <command><varname id="trace-print-level">CCL:*TRACE-PRINT-LEVEL*</varname>   [Variable]</command>
457    </para>
458
459    <para>The default print actions bind <varname>CL:*PRINT-LEVEL*</varname> to this value while
460      printing. Note that this rebinding is only in effect during the default entry and exit messages.
461      It does not apply to printing of <varname>:print-before/:print-after</varname> forms or any
462      explicit printing done by user code.</para>
463
464    <para>
465      <indexterm zone="trace-print-length"/>
466      <command><varname id="trace-print-length">CCL:*TRACE-PRINT-LENGTH*</varname>    [Variable]</command>
467    </para>
468   
469    <para>The default print actions bind <varname>CL:*PRINT-LENGTH*</varname> to this value while
470      printing. Note that this rebinding is only in effect during the default entry and exit messages.
471      It does not apply to printing of <varname>:print-before/:print-after</varname> forms or any
472      explicit printing done by user code.</para>
473
474    <para>
475      <indexterm zone="trace-bar-frequency"/>
476      <command><varname id="trace-bar-frequency">CCL:*TRACE-BAR-FREQUENCY*</varname>    [Variable]</command>
477    </para>
478
479    <para>By default, this is nil. If non-nil it should be a integer,
480    and the default entry and exit messages will print a | instead of
481    space every this many levels of indentation.</para>
482
483
484  </sect1>
485
486  <sect1 id="Advising"><title>Advising</title>
487  <para>
488    The <literal>advise</literal> macro can be thought of as a more
489    general version of <literal>trace</literal>. It allows code that
490    you specify to run before, after, or around a given function, for
491    the purpose of changing the behavior of the function. Each piece
492    of added code is called a piece of advice. Each piece of advice
493    has a unique name, so that you can have multiple pieces of advice
494    on the same function, including multiple
495    <literal>:before</literal>, <literal>:after</literal>, and
496    <literal>:around</literal> pieces of advice.
497  </para>
498  <para>
499    The <literal>:name</literal> and <literal>:when</literal>
500    keywords serve to identify the piece of advice.  A later call to
501    <literal>advise</literal> with the same values of
502    <literal>:name</literal> and <literal>:when</literal> will replace
503    the existing piece of advice; a call with different values will not.
504  </para>
505
506  <refentry id="m_advise">
507    <indexterm zone="m_advise">
508      <primary>advise</primary>
509    </indexterm>
510
511    <refnamediv>
512      <refname>ADVISE</refname>
513      <refpurpose>
514        Add a piece of advice to the function or method specified by
515        <varname>spec</varname> according to
516        <varname>form</varname>.
517      </refpurpose>
518      <refclass>Macro</refclass>
519    </refnamediv>
520   
521    <refsynopsisdiv>
522      <synopsis><function>advise</function> spec form &key; when name</synopsis>
523    </refsynopsisdiv>
524
525    <refsect1>
526      <title>Arguments and Values</title>
527      <variablelist>
528        <varlistentry>
529          <term>spec</term>
530          <listitem>
531            <para>
532              A specification of the function on which to put the
533              advice.  This is either a symbol that is the name of a
534              function or generic function, or an expression of the
535              form (setf <replaceable>symbol</replaceable>), or a
536              specific method of a generic function in the form
537              (:method symbol {qualifiers} (specializer {specializer})).
538            </para>
539          </listitem>
540        </varlistentry>
541        <varlistentry>
542          <term>form</term>
543          <listitem>
544            <para>
545              A form to execute before, after, or around the advised
546              function. The form can refer to the variable arglist
547              that is bound to the arguments with which the advised
548              function was called. You can exit from form with
549              (return).
550            </para>
551          </listitem>
552        </varlistentry>
553        <varlistentry>
554          <term>name</term>
555          <listitem>
556            <para>
557              A name that identifies the piece of advice.
558            </para>
559          </listitem>
560        </varlistentry>
561        <varlistentry>
562          <term>when</term>
563          <listitem>
564            <para>
565              An argument that specifies when the piece of advice is
566              run. There are three allowable values. The default is
567              <literal>:before</literal>, which specifies that form is
568              executed before the advised function is called. Other
569              possible values are <literal>:after</literal>, which
570              specifies that form is executed after the advised
571              function is called, and <literal>:around</literal>,
572              which specifies that form is executed around the call to
573              the advised function. Use <literal>(:do-it)</literal>
574              within form to indicate invocation of the original
575              definition.
576            </para>
577          </listitem>
578        </varlistentry>
579      </variablelist>
580    </refsect1>
581   
582    <refsect1>
583      <title>Examples</title>
584      <para>
585        The function <literal>foo</literal>, already defined, does
586        something with a list of numbers. The following code uses a
587        piece of advice to make foo return zero if any of its
588        arguments is not a number. Using :around advice, you can do
589        the following:
590        <programlisting>
591(advise foo (if (some #'(lambda (n) (not (numberp n))) arglist)
592              0
593              (:do-it))
594        :when :around :name :zero-if-not-nums)
595        </programlisting>
596      </para>
597      <para>
598        To do the same thing using a :before piece of advice:
599        <programlisting>
600(advise foo (if (some #'(lambda (n) (not (numberp n))) arglist)
601              (return 0))
602        :when :before :name :zero-if-not-nums)
603        </programlisting>
604      </para>
605    </refsect1>
606  </refentry>
607
608  <refentry id="m_unadvise">
609    <indexterm zone="m_unadvise">
610      <primary>unadvise</primary>
611    </indexterm>
612
613    <refnamediv>
614      <refname>UNADVISE</refname>
615      <refpurpose>
616        Remove the piece or pieces of advice matching <varname>spec</varname>,
617        <varname>when</varname>, and <varname>name</varname>.
618      </refpurpose>
619      <refclass>Macro</refclass>
620    </refnamediv>
621   
622    <refsynopsisdiv>
623      <synopsis><function>unadvise</function> spec &key; when name</synopsis>
624    </refsynopsisdiv>
625
626    <refsect1>
627      <title>Description</title>
628      <para>
629        The unadvise macro removes the piece or pieces of advice
630        matching <literal>spec</literal>, <literal>when</literal>,
631        and <literal>name</literal>. When the value of
632        <literal>spec</literal> is t and the values of <literal>when</literal>
633        and <literal>name</literal> are nil, unadvise
634        removes every piece of advice; when <literal>spec</literal> is
635        t, the argument <literal>when</literal> is nil, and
636        <literal>name</literal> is non-nil, unadvise removes all
637        pieces of advice with the given name.
638      </para>
639    </refsect1>
640    <refsect1>
641      <title>Arguments and Values</title>
642      <para>
643        The arguments have the same meaning as in
644        <xref linkend="m_advise"/>.
645      </para>
646    </refsect1>
647  </refentry>
648
649  <refentry id="m_advisedp">
650    <indexterm zone="m_advisedp">
651      <primary>advisedp</primary>
652    </indexterm>
653
654    <refnamediv>
655      <refname>ADVISEDP</refname>
656      <refpurpose>
657        Return a list of the pieces of advice matching <varname>spec</varname>,
658        <varname>when</varname>, and <varname>name</varname>.
659      </refpurpose>
660      <refclass>Macro</refclass>
661    </refnamediv>
662   
663    <refsynopsisdiv>
664      <synopsis><function>advisedp</function> spec &key; when name</synopsis>
665    </refsynopsisdiv>
666
667    <refsect1>
668      <title>Description</title>
669      <para>
670        The advisedp macro returns a list of existing pieces of advice
671        that match <literal>spec</literal>, <literal>when</literal>,
672        and <literal>name</literal>. When the value of
673        <literal>spec</literal> is t and the values of
674        <literal>when</literal> and <literal>name</literal> are nil,
675        advisedp returns all existing pieces of advice.
676      </para>
677    </refsect1>
678    <refsect1>
679      <title>Arguments and Values</title>
680      <para>
681        The arguments have the same meaning as in
682        <xref linkend="m_advise"/>.
683      </para>
684    </refsect1>
685  </refentry>
686
687  </sect1>
688
689  <sect1 id="Directory"><title>Directory</title>
690  <para>&CCL;'s <varname>DIRECTORY</varname> function accepts the following
691implementation-dependent keyword arguments:</para>
692  <variablelist>
693  <varlistentry>
694     <term><varname>:files</varname> <replaceable>boolean</replaceable></term>
695     <listitem>
696       <para> If true, includes regular (non-directory) files in DIRECTORY's output.  Defaults to T.</para>
697     </listitem>
698  </varlistentry>
699  <varlistentry>
700     <term><varname>:directories</varname> <replaceable>boolean</replaceable></term>
701     <listitem>
702       <para> If true, includes directories in DIRECTORY's output.  Defaults to NIL.</para>
703     </listitem>
704  </varlistentry>
705  <varlistentry>
706     <term><varname>:all</varname> <replaceable>boolean</replaceable></term>
707     <listitem>
708       <para> If true, includes files and directories whose names start with a dot character in DIRECTORY's output.  (Entries whose name is "." or ".." are never included.) Defaults to T.</para>
709     </listitem>
710  </varlistentry>
711  <varlistentry>
712     <term><varname>:follow-links</varname> <replaceable>boolean</replaceable></term>
713     <listitem>
714       <para> If true, includes the TRUENAMEs of symbolic or hard links in DIRECTORY's output; if false, includes the link filenames without attempting to resolve them. Defaults to T.</para>
715       <para>Note that legacy HFS alias files are treated as plain files.</para>
716     </listitem>
717  </varlistentry>
718  </variablelist>
719  </sect1>
720  <sect1 id="Unicode"><title>Unicode</title>
721
722    <para>All characters and strings in &CCL; fully support Unicode by
723    using UTF-32. There is only one <literal>CHARACTER</literal> type
724    and one <literal>STRING</literal> type in &CCL;.  There has been a
725    lot of discussion about this decision which can be found by
726    searching the openmcl-devel archives at <ulink
727    url="http://clozure.com/pipermail/openmcl-devel/"/>.  Suffice it
728    to say that we decided that the simplicity and speed advantages of
729    only supporting UTF-32 outweigh the space disadvantage.</para>
730
731
732
733  <sect2 id="unicode-characters"><title>Characters</title>
734    <para>There is one <literal>CHARACTER</literal> type in &CCL;.
735    All <literal>CHARACTER</literal>s are
736    <literal>BASE-CHAR</literal>s.  <varname>CHAR-CODE-LIMIT</varname>
737    is now <literal>#x110000</literal>, which means that all Unicode
738    characters can be directly represented.  As of Unicode 5.0, only
739    about 100,000 of 1,114,112 possible <literal>CHAR-CODE</literal>s
740    are actually defined. The function <function>CODE-CHAR</function>
741    knows that certain ranges of code values (notably
742    <literal>#xd800</literal>-<literal>#xddff</literal>) will never be
743    valid character codes and will return <literal>NIL</literal> for
744    arguments in that range, but may return a
745    non-<literal>NIL</literal> value (an undefined/non-standard
746    <literal>CHARACTER</literal> object) for other unassigned code
747    values.</para>
748
749    <para>&CCL; supports character names of the form
750    <literal>u+xxxx</literal>&mdash;where <literal>x</literal> is a
751    sequence of one or more hex digits.  The value of the hex digits
752    denotes the code of the character.  The <literal>+</literal>
753    character is optional, so <literal>#\u+0020</literal>,
754    <literal>#\U0020</literal>, and <literal>#\U+20</literal> all
755    refer to the <literal>#\Space</literal> character.</para>
756
757    <para>Characters with codes in the range
758    <literal>#xa0</literal>-<literal>#x7ff</literal> also have
759    symbolic names These are the names from the Unicode standard with
760    spaces replaced by underscores.  So
761    <literal>#\Greek_Capital_Letter_Epsilon</literal> can be used to
762    refer to the character whose <function>CHAR-CODE</function> is
763    <literal>#x395</literal>.  To see the complete list of supported
764    character names, look just below the definition for
765    <function>register-character-name</function> in
766    <literal>ccl:level-1;l1-reader.lisp</literal>.</para>
767  </sect2>
768
769
770  <sect2 id="External-Formats"><title>External Formats</title>
771    <para><function>OPEN</function>, <function>LOAD</function>, and
772    <function>COMPILE-FILE</function> all take an
773    <literal>:EXTERNAL-FORMAT</literal> keyword argument.  The value
774    of <literal>:EXTERNAL-FORMAT</literal> can be
775    <literal>:DEFAULT</literal> (the default value), a line
776    termination keyword (see <xref
777    linkend="Line-Termination-Keywords"/>), a character encoding
778    keyword (see <xref linkend="Character-Encodings"/>), an
779    external-format object created using
780    <function>CCL::MAKE-EXTERNAL-FORMAT</function> (see <xref
781    linkend="f_make-external-format"/>), or a plist with keys:
782    <literal>:DOMAIN</literal>, <literal>:CHARACTER-ENCODING</literal>
783    and <literal>:LINE-TERMINATION</literal>.  If
784    <parameter>argument</parameter> is a plist, the result of
785    <literal>(APPLY #'MAKE-EXTERNAL-FORMAT
786    <parameter>argument</parameter>)</literal> will be used.</para>
787
788    <para>If <literal>:DEFAULT</literal> is specified, then the value
789    of <varname>CCL:*DEFAULT-EXTERNAL-FORMAT*</varname> is used.  If
790    no line-termination is specified, then the value of
791    <varname>CCL:*DEFAULT-LINE-TERMINATION*</varname> is used, which
792    defaults to <literal>:UNIX</literal>.  If no character encoding is
793    specified, then
794    <varname>CCL:*DEFAULT-FILE-CHARACTER-ENCODING*</varname> is used
795    for file streams and
796    <varname>CCL:*DEFAULT-SOCKET-CHARACTER-ENCODING*</varname> is used
797    for socket streams.  The default, default character encoding is
798    <literal>NIL</literal> which is a synonym for
799    <literal>:ISO-8859-1</literal>.</para>
800
801    <para>Note that the set of keywords used to denote
802    CHARACTER-ENCODINGs and the set of keywords used to denote
803    line-termination conventions is disjoint: a keyword denotes at
804    most a character encoding or a line termination convention, but
805    never both.</para>
806
807    <para>EXTERNAL-FORMATs are objects (structures) with three
808    read-only fields that can be accessed via the functions:
809    <function>EXTERNAL-FORMAT-DOMAIN</function>,
810    <function>EXTERNAL-FORMAT-LINE-TERMINATION</function> and
811    <function>EXTERNAL-FORMAT-CHARACTER-ENCODING</function>.</para>
812
813 
814    <refentry id="f_make-external-format">
815      <indexterm zone="f_make-external-format">
816        <primary>make-external-format</primary>
817      </indexterm>
818     
819      <refnamediv>
820        <refname>MAKE-EXTERNAL-FORMAT</refname>
821        <refpurpose>Either creates a new external format object, or
822        return an existing one with the same specified slot
823        values.</refpurpose>
824        <refclass>Function</refclass>
825      </refnamediv>
826
827      <refsynopsisdiv>
828        <synopsis>
829          <function>make-external-format</function>
830          &key; domain character-encoding line-termination
831          => external-format
832        </synopsis>
833      </refsynopsisdiv>
834
835      <refsect1>
836        <title>Arguments and Values</title>
837       
838        <variablelist>
839          <varlistentry>
840            <term>domain</term>
841            <listitem>
842              <para>This is used to indicate where the external
843              format is to be used.  Its value can be almost
844              anything.  It defaults to <literal>NIL</literal>.
845              There are two domains that have a pre-defined meaning in
846              &CCL;: <literal>:FILE</literal> indicates
847              encoding for a file in the file system and
848              <literal>:SOCKET</literal> indicates i/o to/from a
849              socket.  The value of <parameter>domain</parameter>
850              affects the default values for
851              <parameter>character-encoding</parameter> and
852              <parameter>line-termination</parameter>.</para>
853            </listitem>
854          </varlistentry>
855          <varlistentry>
856            <term>character-encoding</term>
857            <listitem>
858              <para>A keyword that specifies the character encoding
859              for the external format. <xref
860              linkend="Character-Encodings"/>.  Defaults to
861              <literal>:DEFAULT</literal> which means if
862              <parameter>domain</parameter> is
863              <literal>:FILE</literal> use the value of the variable
864              <varname>CCL:*DEFAULT-FILE-CHARACTER-ENCODING*</varname>
865              and if <parameter>domain</parameter> is
866              <literal>:SOCKET</literal>, use the value of the
867              variable
868              <varname>CCL:*DEFAULT-SOCKET-CHARACTER-ENCODING*</varname>.
869              The initial value of both of these variables is
870              <literal>NIL</literal>, which means the
871              <literal>:ISO-8859-1</literal> encoding.</para>
872            </listitem>
873          </varlistentry>
874          <varlistentry>
875            <term>line-termination</term>
876            <listitem>
877              <para>A keyword that indicates a line termination
878              keyword <xref linkend="Line-Termination-Keywords"/>.
879              Defaults to <literal>:DEFAULT</literal> which means
880              use the value of the variable
881              <varname>CCL:*DEFAULT-LINE-TERMINATION*</varname>.</para>
882            </listitem>
883          </varlistentry>
884          <varlistentry>
885            <term>external-format</term>
886            <listitem>
887              <para>An external-format object as described above.</para>
888            </listitem>
889          </varlistentry>
890        </variablelist>
891      </refsect1>
892     
893      <refsect1>
894        <title>Description</title>
895       
896        <para>Despite the function's name, it doesn't necessarily create a
897        new, unique EXTERNAL-FORMAT object: two calls to
898        MAKE-EXTERNAL-FORMAT with the same arguments made in the same
899        dynamic environment return the same (eq) object.
900        </para>
901      </refsect1>
902    </refentry>
903
904  </sect2>
905
906  <sect2 id="Line-Termination-Keywords"><title>Line Termination Keywords</title>
907  <para>Line termination keywords indicate which characters are used
908  to indicate the end of a line.  On input, the external line
909  termination characters are replaced by <literal>#\Newline</literal>
910  and on output, <literal>#\Newline</literal>s are converted to the
911  external line termination characters.</para>
912  <table id="Line-Termination-Table" frame='all'><title>Line Termination Keywords</title>
913  <tgroup cols='2' align='left' colsep='1' rowsep='1'>
914    <thead>
915      <row>
916        <entry>keyword</entry>
917        <entry>character(s)</entry>
918      </row>
919    </thead>
920    <tbody>
921      <row>
922        <entry><literal>:UNIX</literal></entry>
923        <entry><literal>#\Linefeed</literal></entry>
924      </row>
925      <row>
926        <entry><literal>:MACOS</literal></entry>
927        <entry><literal>#\Return</literal></entry>
928      </row>
929      <row>
930        <entry><literal>:CR</literal></entry>
931        <entry><literal>#\Return</literal></entry>
932      </row>
933      <row>
934        <entry><literal>:CRLF</literal></entry>
935        <entry><literal>#\Return #\Linefeed</literal></entry>
936      </row>
937      <row>
938        <entry><literal>:CP/M</literal></entry>
939        <entry><literal>#\Return #\Linefeed</literal></entry>
940      </row>
941      <row>
942        <entry><literal>:MSDOS</literal></entry>
943        <entry><literal>#\Return #\Linefeed</literal></entry>
944      </row>
945      <row>
946        <entry><literal>:DOS</literal></entry>
947        <entry><literal>#\Return #\Linefeed</literal></entry>
948      </row>
949      <row>
950        <entry><literal>:WINDOWS</literal></entry>
951        <entry><literal>#\Return #\Linefeed</literal></entry>
952      </row>
953      <row>
954        <entry><literal>:INFERRED</literal></entry>
955        <entry>see below</entry>
956      </row>
957      <row>
958        <entry><literal>:UNICODE</literal></entry>
959        <entry><literal>#\Line_Separator</literal></entry>
960      </row>
961    </tbody>
962  </tgroup>
963  </table>
964  <para><literal>:INFERRED</literal> means that a stream's
965  line-termination convention is determined by looking at the contents
966  of a file.  It is only useful for <literal>FILE-STREAM</literal>s
967  that're open for <literal>:INPUT</literal> or
968  <literal>:IO</literal>.  The first buffer full of data is examined,
969  and if a <literal>#\Return</literal> character occurs before any
970  <literal>#\Linefeed</literal> character, then the line termination
971  type is set to <literal>:MACOS</literal>, otherwise it is set to
972  <literal>:UNIX</literal>.</para>
973  </sect2>
974 
975
976
977  <sect2 id="Character-Encodings"><title>Character Encodings</title>
978    <para>Internally, all characters and strings in &CCL; are in
979    UTF-32.  Externally, files or socket streams may encode characters
980    in a wide variety of ways.  The International Organization for
981    Standardization, widely known as ISO, defines many of these
982    character encodings.  &CCL; implements some of these encodings as
983    detailed below.  These encodings are part of the specification of
984    external formats <xref linkend="External-Formats"/>.  When reading
985    from a stream, characters are converted from the specified
986    external character encoding to UTF-32.  When writing to a stream,
987    characters are converted from UTF-32 to the specified character
988    encoding.</para>
989
990    <para>Internally, CHARACTER-ENCODINGs are objects (structures)
991    that are named by character encoding keywords (:ISO-8859-1,
992    :UTF-8, etc.).  The structures contain attributes of the encoding
993    and functions used to encode/decode external data, but unless
994    you're trying to define or debug an encoding there's little reason
995    to know much about the CHARACTER-ENCODING objects and it's usually
996    preferable to refer to a character encoding by its name.
997    </para>
998
999    <para>
1000    </para>
1001
1002    <sect3><title>Encoding Problems</title>
1003      <para>On output to streams with character encodings that can
1004      encode the full range of Unicode&mdash;and on input from any
1005      stream&mdash;"unencodable characters" are represented using the
1006      Unicode #\Replacement_Character (= #\U+fffd); the presence of
1007      such a character usually indicates that something got lost in
1008      translation.  Either data wasn't encoded properly or there was a
1009      bug in the decoding process.</para>
1010    </sect3>
1011
1012    <sect3><title>Byte Order Marks</title>
1013      <para>The endianness of a character encoding is sometimes
1014      explicit, and sometimes not.  For example,
1015      <literal>:UTF-16BE</literal> indicates big-endian, but
1016      <literal>:UTF-16</literal> does not specify endianness.  A byte
1017      order mark is a special character that may appear at the
1018      beginning of a stream of encoded characters to specify the
1019      endianness of a multi-byte character encoding.  (It may also be
1020      used with UTF-8 character encodings, where it is simply used to
1021      indicate that the encoding is UTF-8.)</para>
1022
1023      <para>&CCL; writes a byte order mark as the first character
1024      of a file or socket stream when the endianness of the character
1025      encoding is not explicit.  &CCL; also expects a byte order
1026      mark on input from streams where the endianness is not
1027      explicit. If a byte order mark is missing from input data, that
1028      data is assumed to be in big-endian order.</para>
1029
1030      <para>A byte order mark from a UTF-8 encoded input stream is not
1031      treated specially and just appears as a normal character from
1032      the input stream.  It is probably a good idea to skip over this
1033      character.</para>
1034    </sect3>
1035
1036  <sect3><title><function>DESCRIBE-CHARACTER-ENCODINGS</function></title>
1037    <para>The set of character encodings supported by &CCL; can be
1038    retrieved by calling
1039    <function>CCL:DESCRIBE-CHARACTER-ENCODINGS</function>.</para>
1040
1041
1042      <refentry id="f_describe-character-encodings">
1043        <indexterm zone="f_describe-character-encodings">
1044          <primary>[fn-name]</primary>
1045        </indexterm>
1046
1047        <refnamediv>
1048          <refname>DESCRIBE-CHARACTER-ENCODINGS</refname>
1049          <refpurpose>Writes descriptions of defined character
1050          encodings to <varname>*terminal-io*</varname>.</refpurpose>
1051          <refclass>Function</refclass>
1052        </refnamediv>
1053
1054        <refsynopsisdiv>
1055          <synopsis>
1056            <function>describe-character-encodings</function>
1057          </synopsis>
1058        </refsynopsisdiv>
1059
1060        <refsect1>
1061          <title>Description</title>
1062
1063          <para>Writes descriptions of all defined character encodings
1064          to <varname>*terminal-io*</varname>.  These descriptions
1065          include the names of the encoding's aliases and a doc string
1066          which briefly describes each encoding's properties and
1067          intended use.</para>
1068        </refsect1>
1069
1070        <refsect1>
1071          <title>See Also</title>
1072         
1073          <simplelist type="inline">
1074            <member><xref linkend="Character-Encodings"/></member>
1075            <member><xref linkend="External-Formats"/></member>
1076            <member><xref linkend="Supported-Character-Encodings"/></member>
1077          </simplelist>
1078        </refsect1>
1079      </refentry>
1080  </sect3>
1081
1082  <sect3 id="Supported-Character-Encodings"><title>Supported Character Encodings</title>
1083     <para>The list of supported encodings is reproduced here.  Most
1084     encodings have aliases, e.g. the encoding named
1085     <literal>:ISO-8859-1</literal> can also be referred to by the
1086     names <literal>:LATIN1</literal> and <literal>:IBM819</literal>,
1087     among others.  Where possible, the keywordized name of an
1088     encoding is equivalent to the preferred MIME charset name (and
1089     the aliases are all registered IANA charset names.)</para>
1090
1091  <variablelist>
1092    <varlistentry><term><literal>:ISO-8859-1</literal></term>
1093       <listitem><para>An 8-bit, fixed-width character encoding in
1094       which all character codes map to their Unicode
1095       equivalents. Intended to support most characters used in most
1096       Western European languages.</para>
1097       <para>&CCL; uses ISO-8859-1 encoding for
1098       <varname>*TERMINAL-IO*</varname> and for all streams whose
1099       EXTERNAL-FORMAT isn't explicitly specified.  The default for
1100       <varname>*TERMINAL-IO*</varname> can be set via the
1101       <literal>-K</literal> command-line argument (see <xref
1102       linkend="Command-Line-Options"/>).
1103       </para>
1104       <para>ISO-8859-1 just covers the first 256 Unicode code
1105       points, where the first 128 code points are equivalent to
1106       US-ASCII.  That should be pretty much equivalent to what
1107       earliers versions of &CCL; did that only supported 8-bit characters,
1108       but it may not be optimal for users working in a particular
1109       locale.</para>
1110       <para>Aliases: <literal>:ISO_8859-1, :LATIN1, :L1,
1111       :IBM819, :CP819, :CSISOLATIN1</literal></para></listitem>
1112     </varlistentry>
1113    <varlistentry><term><literal>:ISO-8859-2</literal></term>
1114       <listitem><para>An 8-bit, fixed-width character encoding in
1115       which codes #x00-#x9f map to their Unicode equivalents and
1116       other codes map to other Unicode character values.  Intended to
1117       provide most characters found in most languages used in
1118       Central/Eastern Europe.</para>
1119       <para>Aliases: <literal>:ISO_8859-2, :LATIN-2, :L2,
1120       :CSISOLATIN2</literal></para></listitem>
1121     </varlistentry>
1122    <varlistentry><term><literal>:ISO-8859-3</literal></term>
1123       <listitem><para>An 8-bit, fixed-width character encoding in
1124       which codes #x00-#x9f map to their Unicode equivalents and
1125       other codes map to other Unicode character values.  Intended to
1126       provide most characters found in most languages used in
1127       Southern Europe.</para>
1128       <para>Aliases: <literal>:ISO_8859-3, :LATIN,3 :L3,
1129       :CSISOLATIN3</literal></para></listitem>
1130     </varlistentry>
1131    <varlistentry><term><literal>:ISO-8859-4</literal></term>
1132       <listitem><para>An 8-bit, fixed-width character encoding in
1133       which codes #x00-#x9f map to their Unicode equivalents and
1134       other codes map to other Unicode character values.  Intended to
1135       provide most characters found in most languages used in
1136       Northern Europe.</para>
1137       <para>Aliases: <literal>:ISO_8859-4, :LATIN4, :L4, :CSISOLATIN4</literal></para></listitem>
1138     </varlistentry>
1139    <varlistentry><term><literal>:ISO-8859-5</literal></term>
1140       <listitem><para>An 8-bit, fixed-width character encoding in
1141       which codes #x00-#x9f map to their Unicode equivalents and
1142       other codes map to other Unicode character values.  Intended to
1143       provide most characters found in the Cyrillic
1144       alphabet.</para>
1145       <para>Aliases: <literal>:ISO_8859-5, :CYRILLIC, :CSISOLATINCYRILLIC,
1146       :ISO-IR-144</literal></para></listitem>
1147     </varlistentry>
1148    <varlistentry><term><literal>:ISO-8859-6</literal></term>
1149       <listitem><para>An 8-bit, fixed-width character encoding in
1150       which codes #x00-#x9f map to their Unicode equivalents and
1151       other codes map to other Unicode character values.  Intended to
1152       provide most characters found in the Arabic
1153       alphabet.</para>
1154       <para>Aliases: <literal>:ISO_8859-6, :ARABIC, :CSISOLATINARABIC,
1155       :ISO-IR-127</literal></para></listitem>
1156     </varlistentry>
1157    <varlistentry><term><literal>:ISO-8859-7</literal></term>
1158       <listitem><para>An 8-bit, fixed-width character encoding in
1159       which codes #x00-#x9f map to their Unicode equivalents and
1160       other codes map to other Unicode character values.  Intended to
1161       provide most characters found in the Greek
1162       alphabet.</para>
1163       <para>Aliases: <literal>:ISO_8859-7, :GREEK, :GREEK8, :CSISOLATINGREEK,
1164       :ISO-IR-126, :ELOT_928, :ECMA-118</literal></para></listitem>
1165     </varlistentry>
1166    <varlistentry><term><literal>:ISO-8859-8</literal></term>
1167       <listitem><para>An 8-bit, fixed-width character encoding in
1168       which codes #x00-#x9f map to their Unicode equivalents and
1169       other codes map to other Unicode character values.  Intended to
1170       provide most characters found in the Hebrew
1171       alphabet.</para>
1172       <para>Aliases: <literal>:ISO_8859-8, :HEBREW, :CSISOLATINHEBREW,
1173       :ISO-IR-138</literal></para></listitem>
1174     </varlistentry>
1175    <varlistentry><term><literal>:ISO-8859-9</literal></term>
1176       <listitem><para>An 8-bit, fixed-width character encoding in
1177       which codes #x00-#xcf map to their Unicode equivalents and
1178       other codes map to other Unicode character values.  Intended to
1179       provide most characters found in the Turkish
1180       alphabet.</para>
1181       <para>Aliases: <literal>:ISO_8859-9, :LATIN5, :CSISOLATIN5,
1182       :ISO-IR-148</literal></para></listitem>
1183     </varlistentry>
1184    <varlistentry><term><literal>:ISO-8859-10</literal></term>
1185       <listitem><para>An 8-bit, fixed-width character encoding in
1186       which codes #x00-#x9f map to their Unicode equivalents and
1187       other codes map to other Unicode character values.  Intended to
1188       provide most characters found in Nordic
1189       alphabets.</para>
1190       <para>Aliases: <literal>:ISO_8859-10, :LATIN6, :CSISOLATIN6,
1191       :ISO-IR-157</literal></para></listitem>
1192     </varlistentry>
1193    <varlistentry><term><literal>:ISO-8859-11</literal></term>
1194       <listitem><para>An 8-bit, fixed-width character encoding in
1195       which codes #x00-#x9f map to their Unicode equivalents and
1196       other codes map to other Unicode character values.  Intended to
1197       provide most characters found the Thai
1198       alphabet.</para></listitem>
1199     </varlistentry>
1200    <varlistentry><term><literal>:ISO-8859-13</literal></term>
1201       <listitem><para>An 8-bit, fixed-width character encoding in
1202       which codes #x00-#x9f map to their Unicode equivalents and
1203       other codes map to other Unicode character values.  Intended to
1204       provide most characters found in Baltic
1205       alphabets.</para></listitem>
1206     </varlistentry>
1207    <varlistentry><term><literal>:ISO-8859-14</literal></term>
1208       <listitem><para>An 8-bit, fixed-width character encoding in
1209       which codes #x00-#x9f map to their Unicode equivalents and
1210       other codes map to other Unicode character values.  Intended to
1211       provide most characters found in Celtic
1212       languages.</para>
1213       <para>Aliases: <literal>:ISO_8859-14, :ISO-IR-199, :LATIN8, :L8,
1214       :ISO-CELTIC</literal></para></listitem>
1215     </varlistentry>
1216    <varlistentry><term><literal>:ISO-8859-15</literal></term>
1217       <listitem><para>An 8-bit, fixed-width character encoding in
1218       which codes #x00-#x9f map to their Unicode equivalents and
1219       other codes map to other Unicode character values.  Intended to
1220       provide most characters found in Western European languages
1221       (including the Euro sign and some other characters missing from
1222       ISO-8859-1.</para>
1223       <para>Aliases: <literal>:ISO_8859-15, :LATIN9</literal></para></listitem>
1224     </varlistentry>
1225    <varlistentry><term><literal>:ISO-8859-16</literal></term>
1226       <listitem><para>An 8-bit, fixed-width character encoding in
1227       which codes #x00-#x9f map to their Unicode equivalents and
1228       other codes map to other Unicode character values.  Intended to
1229       provide most characters found in Southeast European
1230       languages.</para>
1231       <para>Aliases: <literal>:ISO_8859-16, :ISO-IR-199, :LATIN8, :L8,
1232       :ISO-CELTIC</literal></para></listitem>
1233     </varlistentry>
1234    <varlistentry><term><literal>:MACINTOSH</literal></term>
1235       <listitem><para>An 8-bit, fixed-width character encoding in
1236       which codes #x00-#x7f map to their Unicode equivalents and
1237       other codes map to other Unicode character values.
1238       Traditionally used on Classic MacOS to encode characters used
1239       in western languages.</para>
1240       <para>Aliases: <literal>:MACOS-ROMAN, :MACOSROMAN, :MAC-ROMAN,
1241       :MACROMAN</literal></para></listitem>
1242     </varlistentry>
1243    <varlistentry><term><literal>:UCS-2</literal></term>
1244       <listitem><para>A 16-bit, fixed-length encoding in which
1245       characters with CHAR-CODEs less than #x10000 can be encoded in
1246       a single 16-bit word.  The endianness of the encoded data is
1247       indicated by the endianness of a byte-order-mark character
1248       (#u+feff) prepended to the data; in the absence of such a
1249       character on input, the data is assumed to be in big-endian
1250       order.</para></listitem>
1251     </varlistentry>
1252    <varlistentry><term><literal>:UCS-2BE</literal></term>
1253       <listitem><para>A 16-bit, fixed-length encoding in which
1254       characters with CHAR-CODEs less than #x10000 can be encoded in
1255       a single 16-bit big-endian word. The encoded data is implicitly
1256       big-endian; byte-order-mark characters are not interpreted on
1257       input or prepended to output.</para></listitem>
1258     </varlistentry>
1259    <varlistentry><term><literal>:UCS-2LE</literal></term>
1260       <listitem><para>A 16-bit, fixed-length encoding in which
1261       characters with CHAR-CODEs less than #x10000 can be encoded in
1262       a single 16-bit little-endian word. The encoded data is
1263       implicitly little-endian; byte-order-mark characters are not
1264       interpreted on input or prepended to output.</para></listitem>
1265     </varlistentry>
1266    <varlistentry><term><literal>:US-ASCII</literal></term>
1267       <listitem><para>An 7-bit, fixed-width character encoding in
1268       which all character codes map to their Unicode
1269       equivalents. </para>
1270       <para>Aliases: <literal>:CSASCII, :CP63,7 :IBM637, :US,
1271       :ISO646-US, :ASCII, :ISO-IR-6</literal></para></listitem>
1272     </varlistentry>
1273    <varlistentry><term><literal>:UTF-16</literal></term>
1274       <listitem><para>A 16-bit, variable-length encoding in which
1275       characters with CHAR-CODEs less than #x10000 can be encoded in
1276       a single 16-bit word and characters with larger codes can be
1277       encoded in a pair of 16-bit words.  The endianness of the
1278       encoded data is indicated by the endianness of a
1279       byte-order-mark character (#u+feff) prepended to the data; in
1280       the absence of such a character on input, the data is assumed
1281       to be in big-endian order. Output is written in native
1282       byte-order with a leading byte-order mark.</para></listitem>
1283     </varlistentry>
1284    <varlistentry><term><literal>:UTF-16BE</literal></term>
1285       <listitem><para>A 16-bit, variable-length encoding in which
1286       characters with CHAR-CODEs less than #x10000 can be encoded in
1287       a single 16-bit big-endian word and characters with larger
1288       codes can be encoded in a pair of 16-bit big-endian words.  The
1289       endianness of the encoded data is implicit in the encoding;
1290       byte-order-mark characters are not interpreted on input or
1291       prepended to output.</para></listitem>
1292     </varlistentry>
1293    <varlistentry><term><literal>:UTF-16LE</literal></term>
1294       <listitem><para>A 16-bit, variable-length encoding in which
1295       characters with CHAR-CODEs less than #x10000 can be encoded in
1296       a single 16-bit little-endian word and characters with larger
1297       codes can be encoded in a pair of 16-bit little-endian words.
1298       The endianness of the encoded data is implicit in the encoding;
1299       byte-order-mark characters are not interpreted on input or
1300       prepended to output.</para></listitem>
1301     </varlistentry>
1302    <varlistentry><term><literal>:UTF-32</literal></term>
1303       <listitem><para>A 32-bit, fixed-length encoding in which all
1304       Unicode characters can be encoded in a single 32-bit word.  The
1305       endianness of the encoded data is indicated by the endianness
1306       of a byte-order-mark character (#u+feff) prepended to the data;
1307       in the absence of such a character on input, input data is
1308       assumed to be in big-endian order.  Output is written in native
1309       byte order with a leading byte-order mark.</para>
1310       <para>Alias: <literal>:UTF-4</literal></para></listitem>
1311     </varlistentry>
1312    <varlistentry><term><literal>:UTF-32BE</literal></term>
1313       <listitem><para>A 32-bit, fixed-length encoding in which all
1314       Unicode characters encoded in a single 32-bit word. The encoded
1315       data is implicitly big-endian; byte-order-mark characters are
1316       not interpreted on input or prepended to
1317       output.</para>
1318       <para>Alias: <literal>:UCS-4BE</literal></para></listitem>
1319     </varlistentry>
1320    <varlistentry><term><literal>:UTF-8</literal></term>
1321       <listitem><para>An 8-bit, variable-length character encoding in
1322       which characters with CHAR-CODEs in the range #x00-#x7f can be
1323       encoded in a single octet; characters with larger code values
1324       can be encoded in 2 to 4 bytes.</para></listitem>
1325     </varlistentry>
1326    <varlistentry><term><literal>:UTF-32LE</literal></term>
1327       <listitem><para>A 32-bit, fixed-length encoding in which all
1328       Unicode characters can encoded in a single 32-bit word. The
1329       encoded data is implicitly little-endian; byte-order-mark
1330       characters are not interpreted on input or prepended to
1331       output.</para>
1332       <para>Alias: <literal>:UCS-4LE</literal></para></listitem>
1333     </varlistentry>
1334     <varlistentry><term><literal>:Windows-31j</literal></term>
1335     <listitem><para>An 8-bit, variable-length character encoding in
1336     which character code points in the range #x00-#x7f can be encoded
1337     in a single octet; characters with larger code values can be
1338     encoded in 2 bytes.</para>
1339     <para>Aliases: <literal>:CP932, :CSWINDOWS31J</literal></para></listitem>
1340     </varlistentry>
1341     <varlistentry><term><literal>:EUC-JP</literal></term>
1342     <listitem><para>An 8-bit, variable-length character encoding in
1343     which character code points in the range #x00-#x7f can be encoded
1344     in a single octet; characters with larger code values can be
1345     encoded in 2 bytes.</para>
1346     <para>Alias: <literal>:EUCJP</literal></para></listitem>
1347     </varlistentry>
1348   </variablelist>
1349 </sect3>
1350
1351 <sect3><title>Encoding and Decoding Strings</title>
1352 <para>&CCL; provides functions to encode and decode strings
1353to and from vectors of type (simple-array (unsigned-byte 8)).</para>
1354
1355<refentry id="count-characters-in-octet-vector">
1356  <indexterm zone="count-characters-in-octet-vector">
1357    <primary>count-characters-in-octet-vector</primary>
1358  </indexterm>
1359
1360  <refnamediv>
1361    <refname>count-characters-in-octet-vector</refname>
1362    <refpurpose></refpurpose>
1363    <refclass>Function</refclass>
1364  </refnamediv>
1365
1366  <refsynopsisdiv>
1367    <synopsis>
1368        <function>count-characters-in-octet-vector</function>
1369        <parameter>vector</parameter>
1370        <parameter>&key;</parameter>
1371        <parameter>start</parameter>
1372        <parameter>end</parameter>
1373        <parameter>external-format</parameter>
1374    </synopsis>
1375  </refsynopsisdiv>
1376
1377  <refsect1><title>Description</title>
1378  <para>
1379    Returns the number of characters that would be produced by
1380    decoding <varname>vector</varname> (or the subsequence thereof
1381    delimited by <varname>start</varname> and <varname>end</varname>)
1382    according to <varname>external-format</varname>.
1383  </para>
1384  </refsect1>
1385</refentry>
1386
1387<refentry id="decode-string-from-octets">
1388  <indexterm zone="decode-string-from-octets">
1389    <primary>"decode-string-from-octets</primary>
1390  </indexterm>
1391
1392  <refnamediv>
1393    <refname>decode-string-from-octets</refname>
1394    <refpurpose></refpurpose>
1395    <refclass>Function</refclass>
1396  </refnamediv>
1397
1398  <refsynopsisdiv>
1399    <synopsis>
1400        <function>decode-string-from-octets</function>
1401        <parameter>vector</parameter>
1402        <parameter>&key;</parameter>
1403        <parameter>start</parameter>
1404        <parameter>end</parameter>
1405        <parameter>external-format</parameter>
1406        <parameter>string</parameter>
1407    </synopsis>
1408  </refsynopsisdiv>
1409
1410
1411  <refsect1><title>Description</title>
1412  <para>
1413    Decodes the octets in <varname>vector</varname> (or the subsequence
1414    of it delimited by <varname>start</varname> and
1415    <varname>end</varname>) into a string according
1416    to <varname>external-format</varname>.
1417  </para>
1418  <para>
1419    If <varname>string</varname> is supplied, output will be written into it.
1420    It must be large enough to hold the decoded characters.  If <varname>
1421    string</varname> is not supplied, a new string will be allocated to
1422    hold the decoded characters.
1423  </para>
1424  <para>
1425    Returns, as multiple values, the decoded string and the position in
1426    <varname>vector</varname> where the decoding ended.
1427  </para>
1428  </refsect1>
1429</refentry>
1430
1431<refentry id="encode-string-to-octets">
1432  <indexterm zone="encode-string-to-octets">
1433    <primary>encode-string-to-octets</primary>
1434  </indexterm>
1435
1436  <refnamediv>
1437    <refname>encode-string-to-octets</refname>
1438    <refpurpose></refpurpose>
1439    <refclass>Function</refclass>
1440  </refnamediv>
1441
1442  <refsynopsisdiv>
1443    <synopsis>
1444        <function>encode-string-to-octets</function>
1445        <parameter>string</parameter>
1446        <parameter>&key;</parameter>
1447        <parameter>start</parameter>
1448        <parameter>end</parameter>
1449        <parameter>external-format</parameter>
1450        <parameter>use-byte-order-mark</parameter>
1451        <parameter>vector</parameter>
1452        <parameter>vector-offset</parameter>
1453    </synopsis>
1454  </refsynopsisdiv>
1455
1456
1457  <refsect1><title>Description</title>
1458  <para>
1459    Encodes <varname>string</varname> (or the substring delimited by
1460    <varname>start</varname> and <varname>end</varname>)
1461    into <varname>external-format</varname> and returns, as multiple
1462    values, a vector of octets containing the encoded data and an integer
1463    that specifies the offset into the vector where the encoded data ends.
1464  </para>
1465  <para>
1466    When <varname>use-byte-order-mark</varname> is true, a byte-order mark
1467    will be included in the encoded data.
1468  </para>
1469  <para>
1470    If <varname>vector</varname> is supplied, output will be written
1471    to it.  It must be of type (simple-array (unsigned-byte 8)) and be
1472    large enough to hold the encoded data.  If it is not supplied, the function
1473    will allocate a new vector.
1474  </para>
1475  <para>
1476    If <varname>vector-offset</varname> is supplied, data will be written
1477    into the output vector starting at that offset.
1478  </para>
1479  </refsect1>
1480</refentry>
1481
1482<refentry id="string-size-in-octets">
1483  <indexterm zone="string-size-in-octets">
1484    <primary>string-size-in-octets</primary>
1485  </indexterm>
1486
1487  <refnamediv>
1488    <refname>string-size-in-octets</refname>
1489    <refpurpose></refpurpose>
1490    <refclass>Function</refclass>
1491  </refnamediv>
1492
1493  <refsynopsisdiv>
1494    <synopsis>
1495        <function>string-size-in-octets</function>
1496        <parameter>string</parameter>
1497        <parameter>&key;</parameter>
1498        <parameter>start</parameter>
1499        <parameter>end</parameter>
1500        <parameter>external-format</parameter>
1501        <parameter>use-byte-order-mark</parameter>
1502    </synopsis>
1503  </refsynopsisdiv>
1504
1505
1506  <refsect1><title>Description</title>
1507  <para>
1508    Returns the number of octets required to encode
1509    <varname>string</varname> (or the substring delimited by
1510    <varname>start</varname> and <varname>end</varname>) into
1511    <varname>external-format</varname>.
1512  </para>
1513  <para>
1514    When <varname>use-byte-order-mark</varname> is true, the returned
1515    size will include space for a byte-order marker.
1516  </para>
1517  </refsect1>
1518</refentry>
1519
1520 </sect3>
1521
1522
1523  </sect2>
1524
1525  </sect1>
1526
1527  <sect1 id="Pathanmes"><title>Pathnames</title>
1528
1529    <sect2 id="pathname-tilde-expansion">
1530      <title>Pathname Expansion</title>
1531      <para>Leading tilde (~) characters in physical pathname namestrings
1532        are expanded in the way that most shells do:</para>
1533     
1534      <para><literal>"~user/..."</literal> can be used to refer to an absolute pathname rooted
1535        at the home directory of the user named "user".</para>
1536     
1537      <para><literal>"~/..."</literal> can be used to refer to an absolute pathname rooted at
1538        the home directory of the current user.</para>
1539    </sect2>
1540
1541    <sect2 id="Predefined-Logical-Hosts"><title>Predefined Logical Hosts</title>
1542
1543      <para>&CCL; sets up logical pathname translations for logical hosts:  <literal>ccl</literal> and <literal>home</literal></para>
1544
1545      <indexterm><primary>CCL Logical Host</primary></indexterm>
1546      <para>The <literal>CCL</literal> logical host should point to the
1547        <literal>ccl</literal> directory.  It is used for a variety of
1548        purposes by &CCL; including: locating &CCL; source code,
1549        <literal>require</literal> and <literal>provide</literal>, accessing
1550        foreign function information, and the &CCL; build process. It
1551        is set to the value of the environment variable
1552        <varname>CCL_DEFAULT_DIRECTORY</varname>, which is set by the
1553        openmcl shell script <xref linkend="The-ccl-Shell-Script"/>.  If
1554        <varname>CCL_DEFAULT_DIRECTORY</varname> is not set, then it is set
1555        to the directory containing the current heap image.</para>
1556    </sect2>
1557   
1558   
1559    <sect2 id="pathnames-on-darwin">
1560      <title>OS X (Darwin)</title>
1561     
1562      <para>&CCL; assumes that pathname strings are decomposed UTF-8.</para>
1563    </sect2>
1564    <sect2 id="pathnames-on-linux">
1565      <title>Linux</title>
1566     
1567      <para>Pathname strings are treated as null-terminated strings
1568        coded in the encoding named by the value returned by the function
1569      <varname>CCL:PATHNAME-ENCODING-NAME</varname>.  This value may be changed
1570      with <varname>SETF</varname>.</para>
1571    </sect2>
1572    <sect2 id="pathnames-on-freebsd">
1573      <title>FreeBSD</title>
1574     
1575      <para>Pathname strings are treated as null-terminated strings
1576        encoded according to the current locale; a future release may
1577        change this convention to use UTF-8.</para>
1578    </sect2>
1579  </sect1>
1580
1581  <sect1 id="Memory-Mapped-Files">
1582    <title>Memory-mapped Files</title>
1583    <para>In release 1.2 and later, &CCL;
1584      supports <glossterm linkend="memory_mapped_file">memory-mapped
1585        files</glossterm>. On operating systems that support memory-mapped
1586      files (including Mac OS X, Linux, and FreeBSD), the operating
1587      system can arrange for a range of virtual memory addresses to
1588      refer to the contents of an open file. As long as the file remains
1589      open, programs can read values from the file by reading addresses
1590      in the mapped range.</para>
1591
1592    <para>Using memory-mapped files may in some cases be more
1593      efficient than reading the contents of a file into a data
1594      structure in memory.</para>
1595
1596    <para>&CCL; provides the
1597      functions <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
1598      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> to support
1599      memory-mapping. These functions return vectors whose contents are
1600      the contents of memory-mapped files. Reading an element of such a
1601      vector returns data from the corresponding position in the
1602      file.</para>
1603
1604    <para>Without memory-mapped files, a common idiom for reading the
1605      contents of files might be something like this:</para>
1606
1607    <programlisting>
1608(let* ((stream (open pathname :direction :input :element-type '(unsigned-byte 8)))
1609       (vector (make-array (file-size-to-vector-size stream)
1610                           :element-type '(unsigned-byte 8))))
1611  (read-sequence vector stream))
1612    </programlisting>
1613
1614    <para>Using a memory-mapped files has a result that is the same in
1615      that, like the above example, it returns a vector whose contents are
1616      the same as the contents of the file. It differs in that the above
1617      example creates a new vector in memory and copies the file's
1618      contents into it; using a memory-mapped file instead arranges for
1619      the vector's elements to point to the file's contents on disk
1620      directly, without copying them into memory first.</para>
1621
1622    <para>The vectors returned by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
1623      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> are read-only; any
1624      attempt to change an element of a vector returned by these
1625      functions results in a memory-access error. &CCL; does not
1626      currently support writing data to memory-mapped files.</para>
1627
1628    <para>Vectors created by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
1629      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> are required to
1630      respect &CCL;'s limit on the total size of an array. That means
1631      that you cannot use these functions to create a vector longer
1632      than <varname>ARRAY-TOTAL-SIZE-LIMIT</varname>, even if the filesystem
1633      supports file sizes that are larger. The value
1634      of <varname>ARRAY-TOTAL-SIZE-LIMIT</varname> is <varname>(EXPT 2 24)</varname>
1635      on 32-but platforms; and <varname>(EXPT 2 56)</varname> on 64-bit
1636      platforms.</para>
1637
1638    <para>
1639      <indexterm zone="map-file-to-ivector"/>
1640      <command><varname id="map-file-to-ivector">CCL:MAP-FILE-TO-IVECTOR</varname>
1641        <parameter>pathname</parameter>
1642        <parameter>element-type</parameter>
1643        [Function]</command>
1644    </para>
1645
1646    <variablelist>
1647      <varlistentry>
1648        <term><varname>pathname</varname></term>
1649        <listitem>
1650          <para>The pathname of the file to be memory-mapped.</para>
1651        </listitem>
1652      </varlistentry>
1653     
1654      <varlistentry>
1655        <term><varname>element-type</varname></term>
1656        <listitem>
1657          <para>The element-type of the vector to be
1658            created. Specified as
1659            a <glossterm linkend="type-specifier">type-specifier</glossterm>
1660            that names a subtype of either <varname>SIGNED-BYTE</varname>
1661            or <varname>UNSIGNED-BYTE</varname>.</para>
1662        </listitem>
1663      </varlistentry>
1664    </variablelist>
1665
1666
1667    <para>
1668      The <varname>map-file-to-ivector</varname> function tries to
1669      open the file at <parameter>pathname</parameter> for reading. If
1670      successful, the function maps the file's contents to a range of
1671      virtual addresses. If successful, it returns a read-only vector
1672      whose element-type is given
1673      by <parameter>element-type</parameter>, and whose contents are
1674      the contents of the memory-mapped file.
1675    </para>
1676
1677    <para>The returned vector is
1678      a <glossterm linkend="displaced-array">displaced-array</glossterm>
1679      whose element-type is <varname>(UPGRADED-ARRAY-ELEMENT-TYPE
1680        element-type)</varname>. The target of the displaced array is a
1681      vector of type <varname>(SIMPLE-ARRAY element-type (*))</varname> whose
1682      elements are the contents of the memory-mapped file.</para>
1683
1684    <para>Because of alignment issues, the mapped file's contents
1685      start a few bytes (4 bytes on 32-bit platforms, 8 bytes on
1686      64-bit platforms) into the vector. The displaced array returned
1687      by <varname>CCL:MAP-FILE-TO-IVECTOR</varname> hides this overhead, but
1688      it's usually more efficient to operate on the underlying simple
1689      1-dimensional array.  Given a displaced array (like the value
1690      returned by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>), the function
1691      <varname>ARRAY-DISPLACEMENT</varname> returns the underlying array and
1692      the displacement index in elements.
1693    </para>
1694
1695    <para>Currently, &CCL; supports only read operations on
1696      memory-mapped files. If you try to change the contents of an array
1697      returned by <varname>map-file-to-ivector</varname>, &CCL; signals
1698      a memory error.</para>
1699
1700    <para>
1701      <indexterm zone="unmap-ivector"/>
1702      <command><varname id="unmap-ivector">CCL:UNMAP-IVECTOR</varname>
1703        <parameter>displaced-array</parameter>
1704        [Function]</command>
1705    </para>
1706
1707    <para>If the argument is a displaced-array returned
1708      by <varname>map-file-to-ivector</varname>, and if it has not yet
1709      been unmapped by this function,
1710      then <varname>unmap-ivector</varname> undoes the memory mapping,
1711      closes the mapped file, and changes the displaced-array so that its
1712      target is an empty vector (of length zero).</para>
1713
1714    <para>
1715      <indexterm zone="map-file-to-octet-vector"/>
1716      <command><varname id="map-file-to-octet-vector">CCL:MAP-FILE-TO-OCTET-VECTOR</varname>
1717        <parameter>pathname</parameter>
1718        [Function]</command>
1719    </para>
1720
1721    <para>This function is a synonym for <varname>(CCL:MAP-FILE-TO-IVECTOR
1722        pathname '(UNSIGNED-BYTE 8))</varname> It is provided as a convenience
1723      for the common case of memory-mapping a file as a vector of
1724      bytes.</para>
1725
1726    <para>
1727      <indexterm zone="unmap-octet-vector"/>
1728      <command><varname id="unmap-octet-vector">CCL:UNMAP-OCTET-VECTOR</varname>
1729        <parameter>displaced-array</parameter>
1730        [Function]</command>
1731    </para>
1732
1733    <para>This function is a synonym
1734      for <varname>(CCL:UNMAP-IVECTOR)</varname></para>
1735  </sect1>
1736
1737  <!-- ============================================================ -->
1738  <sect1 id="Static_Variables">
1739    <title>Static Variables</title>
1740
1741    <para>&CCL; supports the definition
1742      of <glossterm linkend="static_variable">static
1743        variables</glossterm>, whose values are the same across threads,
1744      and which may not be dynamically bound. The value of a static
1745      variable is thus the same across all threads; changing the value
1746      in one thread changes it for all threads.</para> 
1747
1748    <para>Attempting to dynamically rebind a static variable (for
1749      instance, by using <varname>LET</varname>, or using the variable name as
1750      a parameter in a <varname>LAMBDA</varname> form) signals an
1751      error. Static variables are shared global resources; a dynamic
1752      binding is private to a single thread.</para>
1753
1754    <para>Static variables therefore provide a simple way to share
1755      mutable state across threads. They also provide a simple way to
1756      introduce race conditions and obscure bugs into your code, since
1757      every thread reads and writes the same instance of a given static
1758      variable. You must take care, therefore, in how you change the
1759      values of static variables, and use normal multithreaded
1760      programming techniques, such as locks or semaphores, to protect
1761      against race conditions.</para>
1762
1763    <para>In &CCL;, access to a static variable is usually faster than
1764      access to a special variable that has not been declared
1765      static.</para>
1766
1767    <para>
1768      <indexterm zone="defstatic"/>
1769      <command><varname id="defstatic">DEFSTATIC</varname>
1770        <parameter>var</parameter>
1771        <parameter>value</parameter>
1772        &key;
1773        <parameter>doc-string</parameter>
1774        [Macro]</command>
1775    </para>
1776   
1777    <variablelist>
1778      <varlistentry>
1779        <term><varname>var</varname></term>
1780        <listitem>
1781          <para>The name of the new static variable.</para>
1782        </listitem>
1783      </varlistentry>
1784     
1785      <varlistentry>
1786        <term><varname>value</varname></term>
1787        <listitem>
1788          <para>The initial value of the new static variable.</para>
1789        </listitem>
1790      </varlistentry>
1791     
1792      <varlistentry>
1793        <term><varname>doc-string</varname></term>
1794        <listitem>
1795          <para>A documentation string that is assigned to the new
1796            variable.</para>
1797        </listitem>
1798      </varlistentry>
1799    </variablelist>
1800
1801    <para>Proclaims the
1802      variable <glossterm linkend="special_variable">special</glossterm>,
1803      assigns the variable the supplied value, and assigns
1804      the <varname>doc-string</varname> to the
1805      variable's <varname>VARIABLE</varname> documentation. Marks the
1806      variable static, preventing any attempt to dynamically rebind
1807      it. Any attempt to dynamically rebind <varname>var</varname>
1808      signals an error.</para>
1809  </sect1>
1810
1811  <!-- ============================================================ -->
1812  <sect1 id="Saving-Applications">
1813    <title>Saving Applications</title>
1814    <indexterm zone="Saving-Applications">
1815      <primary>save-application</primary>
1816    </indexterm>
1817
1818    <para>&CCL; provides the
1819      function <literal>CCL:SAVE-APPLICATION</literal>, which creates a file
1820      containing an archived Lisp memory image.</para>
1821
1822    <para>&CCL; consists of a small executable called the
1823      Lisp <glossterm linkend="lisp_image">kernel</glossterm>, which
1824      implements the very lowest level features of the Lisp system, and
1825      an <glossterm linkend="lisp_image">image</glossterm>, which
1826      contains the in-memory representation of most of the Lisp system,
1827      including functions, data structures, variables, and so on. When
1828      you start &CCL;, you are launching the kernel, which then locates
1829      and reads an image file, restoring the archived image in
1830      memory. Once the image is fully restored, the Lisp system is
1831      running.</para>
1832
1833    <para>Using <literal>CCL:SAVE-APPLICATION</literal>, you can create a
1834      file that contains a modified image, one that includes any changes
1835      you've made to the running Lisp system. If you later pass your
1836      image file to the &CCL; kernel as a command-line parameter, it
1837      then loads your image file instead of its default one, and &CCL;
1838      starts up with your modifications.</para>
1839
1840    <para>If this scenario seems to you like a convenient way to
1841      create an application, that's just as intended. You can create an
1842      application by modifying the running Lisp until it does what you
1843      want, then use <literal>CCL:SAVE-APPLICATION</literal> to preserve your
1844      changes and later load them for use.</para>
1845
1846    <para>In fact, you can go further than that. You can replace
1847      &CCL;'s <glossterm linkend="toplevel_function">toplevel
1848        function</glossterm> with your own, and then, when the image is
1849      loaded, the Lisp system immediately performs your tasks rather
1850      than the default tasks that make it a Lisp development system. If
1851      you save an image in which you have done this, the resulting Lisp
1852      system is your tool rather than a Lisp development system.</para>
1853
1854    <para>You can go a step further still. You can
1855      tell <literal>CCL:SAVE-APPLICATION</literal> to prepend the Lisp kernel
1856      to the image file. Doing this makes the resulting image into a
1857      self-contained executable binary. When you run the resulting file,
1858      the Lisp kernel immediately loads the attached image file and runs
1859      your saved system. The Lisp system that starts up can have any
1860      behavior you choose. It can be a Lisp development system, but with
1861      your customizations; or it can immediately perform some task of
1862      your design, making it a specialized tool rather than a general
1863      development system.</para>
1864
1865    <para>In other words, you can develop any application you like by
1866      interactively modifying &CCL; until it does what you want, then
1867      using <literal>CCL:SAVE-APPLICATION</literal> to preserve your changes
1868      in an executable image.</para>
1869
1870    <para>On Mac OS X,
1871      the <link linkend="application_builder">application builder</link>
1872      uses <literal>CCL:SAVE-APPLICATION</literal> to create the executable
1873      portion of the <glossterm linkend="application_bundle">application
1874        bundle</glossterm>. Double-clicking the application bundle runs
1875      the executable image created
1876      by <literal>CCL:SAVE-APPLICATION</literal>.</para>
1877
1878    <para>Also on Mac OS X, &CCL; supports an object type
1879      called <literal>MACPTR</literal>, which is the type of pointers into the
1880      foreign (Mac OS) heap. Examples of
1881      commonly-user <literal>MACPTR</literal> objects are Cocoa windows and
1882      other dynamically-allocated Mac OS system objects.</para>
1883
1884    <para>Because a <literal>MACPTR</literal> object is a pointer into a
1885      foreign heap that exists for the lifetime of the running Lisp
1886      process, and because a saved image is used by loading it into a
1887      brand new Lisp process, saved <literal>MACPTR</literal> objects cannot
1888      be relied on to point to the same things when reconstituted from a
1889      saved image. In fact, a restored <literal>MACPTR</literal> object might
1890      point to anything at all&mdash;for example an arbitrary location
1891      in the middle of a block of code, or a completely nonexistent
1892      virtual address.</para> 
1893
1894    <para>For that reason, <literal>CCL:SAVE-APPLICATION</literal> converts
1895      all <literal>MACPTR</literal> objects to <literal>DEAD-MACPTR</literal>
1896      objects when writing them to an image
1897      file. A <literal>DEAD-MACPTR</literal> is functionally identical to
1898      a <literal>MACPTR</literal>, except that code that operates
1899      on <literal>MACPTR</literal> objects distinguishes them
1900      from <literal>DEAD-MACPTR</literal> objects and can handle them
1901      appropriately&mdash;signaling errors, for example.</para>
1902
1903    <para>As of &CCL; 1.2, there is one exception to the conversion
1904      of <literal>MACPTR</literal> to <literal>DEAD-MACPTR</literal> objects:
1905      a <literal>MACPTR</literal> object that points to the address 0 is not
1906      converted, because address 0 can always be relied upon to refer to
1907      the same thing.</para>
1908
1909        <indexterm zone="Saving-Applications">
1910          <primary>+NULL-PTR+</primary>
1911        </indexterm>
1912    <para>As of &CCL; 1.2, the constant <literal>CCL:+NULL-PTR+</literal>
1913      refers to a <literal>MACPTR</literal> object that points to address 0.</para>
1914
1915    <para>On all supported platforms, you can
1916      use <literal>CCL:SAVE-APPLICATION</literal> to create a command-line
1917      tool that runs the same way any command-line program
1918      does. Alternatively, if you choose not to prepend the kernel, you
1919      can save an image and then later run it by passing it as a
1920      command-line parameter to the <literal>opencml</literal>
1921      or <literal>opencml64</literal> script.</para>
1922
1923    <para>
1924      <indexterm zone="save-application"/>
1925      <command><varname id="save-application">SAVE-APPLICATION</varname>
1926        <parameter>filename</parameter>
1927        &key;
1928        <parameter>toplevel-function</parameter>
1929        <parameter>init-file</parameter>
1930        <parameter>error-handler</parameter>
1931        <parameter>application-class</parameter>
1932        <parameter>clear-clos-caches</parameter>
1933        <parameter>(purify t)</parameter>
1934        <parameter>impurify</parameter>
1935        <parameter>(mode #o644)</parameter>
1936        <parameter>prepend-kernel</parameter>
1937        [Function]</command>
1938    </para>
1939   
1940    <variablelist>
1941      <varlistentry>
1942        <term><varname>filename</varname></term>
1943        <listitem>
1944          <para>The pathname of the file to be created when &CCL;
1945            saves the application.</para>
1946        </listitem>
1947      </varlistentry>
1948     
1949      <varlistentry>
1950        <term><varname>toplevel-function</varname></term>
1951        <listitem>
1952          <para>The function to be executed after startup is
1953            complete. The toplevel is a function of no arguments that
1954            performs whatever actions the lisp system should perform
1955            when launched with this image.</para>
1956          <para>If this parameter is not supplied, &CCL; uses its
1957            default toplevel. The default toplevel runs
1958            the <glossterm linkend="REPL">read-eval-print
1959              loop</glossterm>.</para>
1960        </listitem>
1961      </varlistentry>
1962
1963      <varlistentry>
1964        <term><varname>init-file</varname></term>
1965        <listitem>
1966          <para>The pathname of a Lisp file to be loaded when the
1967            image starts up. You can place initialization expressions in
1968            this file, and use it to customize the behavior of the Lisp
1969            system when it starts up.</para>
1970        </listitem>
1971      </varlistentry>
1972     
1973      <varlistentry>
1974        <term><varname>error-handler</varname></term>
1975        <listitem>
1976          <para>The error-handling mode for the saved image. The
1977            supplied value determines what happens when an error is not
1978            handled by the saved image. Valid values
1979            are <literal>:quit</literal> (Lisp exits with an error
1980            message); <literal>:quit-quietly</literal> (Lisp exits without an
1981            error message); or <literal>:listener</literal> (Lisp enters a
1982            break loop, enabling you to debug the problem by interacting
1983            in a listener). If you don't supply this parameter, the
1984            saved image uses the default error handler
1985            (<literal>:listener</literal>).</para>
1986        </listitem>
1987      </varlistentry>
1988
1989      <varlistentry>
1990        <term><varname>application-class</varname></term>
1991        <listitem>
1992          <para>The CLOS class that represents the saved Lisp
1993            application. Normally you don't need to supply this
1994            parameter; <literal>CCL:SAVE-APPLICATION</literal> uses the
1995            class <literal>CCL:LISP-DEVELOPMENT-SYSTEM</literal>. In some
1996            cases you may choose to create a custom application class;
1997            in that case, pass the name of the class as the value for
1998            this parameter.</para>
1999        </listitem>
2000      </varlistentry>
2001     
2002      <varlistentry>
2003        <term><varname>clear-clos-caches</varname></term>
2004        <listitem>
2005          <para>If true, ensures that CLOS caches are emptied before
2006            saving the image. Normally you don't need to supply this
2007            parameter, but if for some reason you want to ensure the
2008            CLOS caches are clear when the image starts up, you can pass
2009            any true value.</para>
2010        </listitem>
2011      </varlistentry>
2012     
2013     
2014    </variablelist>
2015
2016    <para></para>
2017  </sect1>
2018
2019  <sect1 id="concatenating-fasl-files">
2020    <title>Concatenating FASL Files</title>
2021    <para>
2022      Multiple fasl files can be concatenated into a single file.
2023    </para>
2024  <refentry id="f_fasl-concatenate">
2025    <indexterm zone="f_fasl-concatenate">
2026      <primary>fasl-concatenate</primary>
2027    </indexterm>
2028
2029    <refnamediv>
2030      <refname>FASL-CONCATENATE</refname>
2031      <refpurpose>
2032        Concatenate several fasl files, producing a single output file.
2033      </refpurpose>
2034      <refclass>Function</refclass>
2035    </refnamediv>
2036   
2037    <refsynopsisdiv>
2038      <synopsis><function>fasl-concatenate</function> out-file fasl-files &key; (:if-exists :error)</synopsis>
2039    </refsynopsisdiv>
2040
2041    <refsect1>
2042      <title>Arguments and Values</title>
2043      <variablelist>
2044        <varlistentry>
2045          <term>out-file</term>
2046          <listitem>
2047            <para>
2048              Name of the file in which to store the concatenation.
2049            </para>
2050          </listitem>
2051        </varlistentry>
2052        <varlistentry>
2053          <term>fasl-files</term>
2054          <listitem>
2055            <para>
2056              List of names of fasl files to concatenate.
2057            </para>
2058          </listitem>
2059        </varlistentry>
2060        <varlistentry>
2061          <term>:if-exists</term>
2062          <listitem>
2063            <para>
2064              As for <function>OPEN</function>, defaults to <literal>
2065              :error</literal>
2066            </para>
2067          </listitem>
2068        </varlistentry>
2069      </variablelist>
2070    </refsect1>
2071   
2072    <refsect1>
2073      <title>Description</title>
2074      <para>
2075        Creates a fasl file which, when loaded, will have the same
2076        effect as loading the individual input fasl files in the
2077        specified order.  The single file might be easier to
2078        distribute or install, and loading it may be at least a little
2079        faster than loading the individual files (since it avoids the
2080        overhead of opening and closing each file in succession.)
2081      </para>
2082      <para>
2083        The PATHNAME-TYPE of the output file and of each input file
2084        defaults to the current platform's fasl file type (.dx64fsl or
2085        whatever.)  If any of the input files has a different
2086        type/extension an error will be signaled, but it doesn't
2087        otherwise try too hard to verify that the input files are real
2088        fasl files for the current platform.
2089      </para>
2090    </refsect1>
2091  </refentry>
2092  </sect1>
2093  <sect1 id="floating-point">
2094    <title>Floating Point Numbers</title>
2095
2096    <para>
2097      In &CCL;, the Common Lisp types short-float and single-float are
2098      implemented as IEEE single precision values; double-float and
2099      long-float are IEEE double precision values.  On 64-bit
2100      platforms, single-floats are immediate values (like fixnums and
2101      characters).
2102    </para>
2103
2104  <para>
2105    Floating-point exceptions are generally enabled and detected.  By
2106    default, threads start up with overflow, division-by-zero, and
2107    invalid enabled, and the rounding mode is set to nearest. The
2108    functions <varname>SET-FPU-MODE</varname> and
2109    <varname>GET-FPU-MODE</varname> provide user control over
2110    floating-point behavior.
2111  </para>
2112
2113  <refentry id="f_get-fpu-mode">
2114    <indexterm zone="f_get-fpu-mode">
2115      <primary>get-fpu-mode</primary>
2116    </indexterm>
2117
2118    <refnamediv>
2119      <refname>GET-FPU-MODE</refname>
2120      <refpurpose>
2121        Return the state of exception-enable and rounding-mode control
2122        flags for the current thread.
2123      </refpurpose>
2124      <refclass>Function</refclass>
2125    </refnamediv>
2126   
2127    <refsynopsisdiv>
2128      <synopsis><function>get-fpu-mode</function> &optional; mode</synopsis>
2129    </refsynopsisdiv>
2130
2131    <refsect1>
2132      <title>Arguments and Values</title>
2133      <variablelist>
2134        <varlistentry>
2135          <term>mode</term>
2136          <listitem>
2137            <para>
2138              One of the keywords :rounding-mode, :overflow,
2139              :underflow, :division-by-zero, :invalid, :inexact.
2140            </para>
2141          </listitem>
2142        </varlistentry>
2143      </variablelist>
2144    </refsect1>
2145   
2146    <refsect1>
2147      <title>Description</title>
2148      <para>
2149        If <varname>mode</varname> is supplied, returns the value of
2150        the corresponding control flag for the current thread.
2151      </para>
2152      <para>
2153        Otherwise, returns a list of keyword/value pairs which
2154        describe the floating-point exception-enable and rounding-mode
2155        control flags for the current thread.
2156      </para>
2157      <variablelist>
2158        <varlistentry>
2159          <term>rounding-mode</term>
2160          <listitem>
2161            <para>
2162              One of :nearest, :zero, :positive, :negative
2163            </para>
2164          </listitem>
2165        </varlistentry>
2166        <varlistentry>
2167          <term>overflow, underflow, division-by-zero, invalid, inexact
2168          </term>
2169          <listitem>
2170            <para>
2171              If true, the floating-point exception is signaled.
2172              If NIL, it is masked.
2173            </para>
2174          </listitem>
2175        </varlistentry>
2176      </variablelist>
2177    </refsect1>
2178  </refentry>
2179
2180  <refentry id="f_set-fpu-mode">
2181    <indexterm zone="f_set-fpu-mode">
2182      <primary>set-fpu-mode</primary>
2183    </indexterm>
2184
2185    <refnamediv>
2186      <refname>SET-FPU-MODE</refname>
2187      <refpurpose>
2188        Set the state of exception-enable and rounding-mode control
2189        flags for the current thread.
2190      </refpurpose>
2191      <refclass>Function</refclass>
2192    </refnamediv>
2193   
2194    <refsynopsisdiv>
2195      <synopsis><function>set-fpu-mode</function> &key;
2196      rounding-mode overflow underflow division-by-zero
2197      invalid inexact</synopsis>
2198    </refsynopsisdiv>
2199
2200    <refsect1>
2201      <title>Arguments and Values</title>
2202      <variablelist>
2203        <varlistentry>
2204          <term>rounding-mode</term>
2205          <listitem>
2206            <para>
2207              If supplied, must be one of :nearest, :zero, :positive, or
2208              :negative.
2209            </para>
2210          </listitem>
2211        </varlistentry>
2212        <varlistentry>
2213          <term>overflow, underflow, division-by-zero, invalid, inexact</term>
2214          <listitem>
2215            <para>NIL to mask the exception, T to signal it.</para>
2216          </listitem>
2217        </varlistentry>
2218      </variablelist>
2219    </refsect1>
2220   
2221    <refsect1>
2222      <title>Description</title>
2223      <para>
2224        Sets the current thread's exception-enable and rounding-mode
2225        control flags to the indicated values for arguments that are
2226        supplied, and preserves the values assoicated with those
2227        that aren't supplied.
2228      </para>
2229    </refsect1>
2230  </refentry>
2231  </sect1>
2232
2233  <sect1 id="watched-objects"><title>Watched Objects</title>
2234  <para>
2235    As of release 1.4, Clozure CL provides a way for lisp objects to
2236    be watched so that a condition will be signaled when a thread
2237    attempts to write to the watched object. For a certain class of
2238    bugs (someone is changing this value, but I don't know who), this
2239    can be extremely helpful.
2240  </para>
2241  <sect2 id="watched-watch"><title>WATCH</title>
2242  <refentry id="f_watch">
2243    <indexterm zone="f_watch">
2244      <primary>watch</primary>
2245    </indexterm>
2246   
2247    <refnamediv>
2248      <refname>WATCH</refname>
2249      <refpurpose>
2250        Monitor a lisp object for writes.
2251      </refpurpose>
2252      <refclass>Function</refclass>
2253    </refnamediv>
2254   
2255    <refsynopsisdiv>
2256      <synopsis><function>watch</function> &optional; object</synopsis>
2257    </refsynopsisdiv>
2258   
2259    <refsect1>
2260      <title>Arguments and Values</title>
2261      <variablelist>
2262        <varlistentry>
2263          <term>object</term>
2264          <listitem>
2265            <para>
2266              Any memory-allocated lisp object.
2267            </para>
2268          </listitem>
2269        </varlistentry>
2270      </variablelist>
2271    </refsect1>
2272
2273    <refsect1>
2274      <title>Description</title>
2275      <para>
2276        The WATCH function arranges for the specified object to be
2277        monitored for writes. This is accomplished by copying the
2278        object to its own set of virtual memory pages, which are then
2279        write-protected. This protection is enforced by the computer's
2280        memory-management hardware; the write-protection does not slow
2281        down reads at all.
2282      </para>
2283      <para>
2284        When any write to the object is attempted, a
2285        WRITE-TO-WATCHED-OBJECT condition will be signaled.
2286      </para>
2287      <para>
2288        When called with no arguments, WATCH returns a freshly-consed
2289        list of the objects currently being watched.
2290      </para>
2291      <para>
2292        WATCH returns NIL if the object cannot be watched (typically
2293        because the object is in a static or pure memory area).
2294      </para>
2295    </refsect1>
2296    <refsect1 id="watch-dwim"><title>DWIM</title>
2297    <para>
2298      WATCH operates at a fairly low level; it is not possible to
2299      avoid the details of the internal representation of objects.
2300      Nevertheless, as a convenience, WATCHing a standard-instance,
2301      a hash-table, or a multi-dimensional or non-simple CL array
2302      will watch the underlying slot-vector, hash-table-vector, or
2303      data-vector, respectively.
2304      </para>
2305    </refsect1>
2306    <refsect1 id="watch-discuss"><title>Discussion</title>
2307    <para>
2308      WATCH can monitor any memory-allocated lisp object.
2309    </para>
2310    <para>
2311      In Clozure CL, a memory-allocated object is either a cons cell
2312      or a uvector.
2313    </para>
2314    <para>
2315      WATCH operates on cons cells, not lists. In order to watch a
2316      chain of cons cells, each cons cell must be watched
2317      individually. Because each watched cons cell takes up its own
2318      own virtual memory page (4 Kbytes), it's only feasible to watch
2319      relatively short lists.
2320    </para>
2321    <para>
2322      If a memory-allocated object isn't a cons cell, then it is a
2323      vector-like object called a uvector. A uvector is a
2324      memory-allocated lisp object whose first word is a header that
2325      describes the object's type and the number of elements that it
2326      contains.
2327    </para>
2328    <para>
2329      So, a hash table is a uvector, as is a string, a standard
2330      instance, a double-float, a CL array or vector, and so forth.
2331    </para>
2332    <para>
2333      Some CL objects, like strings and other simple vectors, map in a
2334      straightforward way onto the uvector representation. It is easy
2335      to understand what happens in such cases. The uvector index
2336      corresponds directly to the vector index:
2337    </para>
2338    <programlisting>
2339<![CDATA[
2340? (defvar *s* "xxxxx")
2341*S*
2342? (watch *s*)
2343"xxxxx"
2344? (setf (char *s* 3) #\o)
2345> Error: Write to watched uvector "xxxxx" at index 3
2346>        Faulting instruction: (movl (% eax) (@ -5 (% r15) (% rcx)))
2347> While executing: SET-CHAR, in process listener(1).
2348> Type :POP to abort, :R for a list of available restarts.
2349> Type :? for other options.
2350]]>
2351    </programlisting>
2352    <para>
2353      In the case of more complicated objects (e.g., a hash-table, a
2354      standard-instance, a package, etc.), the elements of the uvector
2355      are like slots in a structure. It's necessary to know which one
2356      of those "slots" contains the data that will be changed when the
2357      object is written to.
2358    </para>
2359    <para>
2360      As mentioned above, watch knows about arrays, hash-tables, and
2361      standard-instances, and will automatically watch the appropriate
2362      data-containing element.
2363    </para>
2364    <para>
2365      An example might make this clearer.
2366    </para>
2367    <programlisting>
2368<![CDATA[
2369? (defclass foo ()
2370    (slot-a slot-b slot-c))
2371#<STANDARD-CLASS FOO>
2372? (defvar *a-foo* (make-instance 'foo))
2373*A-FOO*
2374? (watch *a-foo*)
2375#<SLOT-VECTOR #xDB00D>
2376;;; Note that WATCH has watched the internal slot-vector object
2377? (setf (slot-value *a-foo* 'slot-a) 'foo)
2378> Error: Write to watched uvector #<SLOT-VECTOR #xDB00D> at index 1
2379>        Faulting instruction: (movq (% rsi) (@ -5 (% r8) (% rdi)))
2380> While executing: %MAYBE-STD-SETF-SLOT-VALUE-USING-CLASS, in process listener(1).
2381> Type :POP to abort, :R for a list of available restarts.
2382> Type :? for other options.
2383]]>
2384    </programlisting>
2385    <para>
2386      Looking at a backtrace would presumably show what object and
2387      slot name were written.
2388    </para>
2389    <para>
2390      Note that even though the write was to slot-a, the uvector index
2391      was 1 (not 0). This is because the first element of a
2392      slot-vector is a pointer to the instance that owns the slots. We
2393      can retrieve that to look at the object that was modified:
2394    </para>
2395    <programlisting>
2396<![CDATA[
23971 > (uvref (write-to-watched-object-object *break-condition*) 0)
2398#<FOO #x30004113502D>
23991 > (describe *)
2400#<FOO #x30004113502D>
2401Class: #<STANDARD-CLASS FOO>
2402Wrapper: #<CLASS-WRAPPER FOO #x300041135EBD>
2403Instance slots
2404SLOT-A: #<Unbound>
2405SLOT-B: #<Unbound>
2406SLOT-C: #<Unbound>
24071 >
2408]]> 
2409    </programlisting>
2410    </refsect1>
2411  </refentry>
2412</sect2>
2413<sect2 id="watched-unwatch"><title>UNWATCH</title>
2414<refentry id="f_unwatch">
2415  <indexterm zone="f_unwatch">
2416    <primary>unwatch</primary>
2417  </indexterm>
2418 
2419  <refnamediv>
2420    <refname>UNWATCH</refname>
2421      <refpurpose>
2422        Stop monitoring a lisp object for writes.
2423      </refpurpose>
2424      <refclass>Function</refclass>
2425  </refnamediv>
2426 
2427  <refsynopsisdiv>
2428    <synopsis><function>unwatch</function> object</synopsis>
2429  </refsynopsisdiv>
2430 
2431  <refsect1><title>Description</title>
2432  <para>
2433    The UNWATCH function ensures that the specified object is in
2434    normal, non-monitored memory. If the object is not currently
2435    being watched, UNWATCH does nothing and returns NIL. Otherwise,
2436    the newly unwatched object is returned.
2437  </para>
2438  </refsect1>
2439</refentry>
2440</sect2>
2441<sect2 id="watched-write-to-watched-object">
2442  <title>WRITE-TO-WATCHED-OBJECT</title>
2443  <refentry id="c_write-to-watched-object">
2444    <indexterm zone="c_write-to-watched-object">
2445      <primary>write-to-watched-object</primary>
2446    </indexterm>
2447   
2448    <refnamediv>
2449      <refname>WRITE-TO-WATCHED-OBJECT</refname>
2450      <refpurpose>
2451        Condition signaled when a write to a watched object is attempted.
2452      </refpurpose>
2453      <refclass>Condition</refclass>
2454    </refnamediv>
2455
2456    <refsect1><title>Discussion</title>
2457    <para>
2458      This condition is signaled when a watched object is written
2459      to. There are three slots of interest:
2460    </para>
2461    <variablelist>
2462      <varlistentry>
2463        <term>object</term>
2464        <listitem>
2465          <para>
2466            The actual object that was the destination of the write.
2467          </para>
2468        </listitem>
2469      </varlistentry>
2470      <varlistentry>
2471        <term>offset</term>
2472        <listitem>
2473          <para>
2474            The byte offset from the tagged object pointer to the
2475            address of the write.
2476          </para>
2477        </listitem>
2478      </varlistentry>
2479      <varlistentry>
2480        <term>instruction</term>
2481        <listitem>
2482          <para>
2483            The disassembled machine instruction that attempted the write.
2484          </para>
2485        </listitem>
2486      </varlistentry>
2487    </variablelist>
2488    </refsect1>
2489
2490    <refsect1><title>Restarts</title>
2491    <para>
2492      A few restarts are provided: one will skip over the faulting
2493      write instruction and proceed; another offers to unwatch the
2494      object and continue.
2495    </para>
2496    <para>
2497      There is also an emulate restart. In some common cases, the
2498      faulting write instruction can be emulated, enabling the write
2499      to be performed without having to unwatch the object (and
2500      therefore let other threads potentially write to it). If the
2501      faulting instruction isn't recognized, the emulate restart will
2502      not be offered.
2503    </para>
2504    </refsect1>
2505  </refentry>
2506</sect2>
2507<sect2 id="watch-notes"><title>Notes</title>
2508<para>
2509  Although some care has been taken to minimize potential problems
2510  arising from watching and unwatching objects from multiple
2511  threads, there may well be subtle race conditions present that
2512  could cause bad behavior.
2513</para>
2514<para>
2515  For example, suppose that a thread attempts to write to a watched
2516  object. This causes the operating system to generate an
2517  exception. The lisp kernel figures out what the exception is, and
2518  calls back into lisp to signal the write-to-watched-object
2519  condition and perhaps handle the error.
2520</para>
2521<para>
2522  Now, as soon lisp code starts running again (for the callback),
2523  it's possible that some other thread could unwatch the very
2524  watched object that caused the exception, perhaps before we even
2525  have a chance to signal the condition, much less respond to it.
2526</para>
2527<para>
2528  Having the object unwatched out from underneath a handler may at
2529  least confuse it, if not cause deeper trouble. Use caution with
2530  unwatch.
2531</para>
2532</sect2>
2533<sect2 id="watch-examples"><title>Examples</title>
2534<para>
2535  Here are a couple more examples in addition to the above examples
2536  of watching a string and a standard-instance.
2537</para>
2538<sect3><title>Fancy arrays</title>
2539<programlisting>
2540?  (defvar *f* (make-array '(2 3) :element-type 'double-float))
2541*F*
2542? (watch *f*)
2543#(0.0D0 0.0D0 0.0D0 0.0D0 0.0D0 0.0D0)
2544;;; Note that the above vector is the underlying data-vector for the array
2545? (setf (aref *f* 1 2) pi)
2546> Error: Write to watched uvector #&lt;VECTOR 6 type DOUBLE-FLOAT, simple> at index 5
2547>        Faulting instruction: (movq (% rax) (@ -5 (% r8) (% rdi)))
2548> While executing: ASET, in process listener(1).
2549> Type :POP to abort, :R for a list of available restarts.
2550> Type :? for other options.
25511 >
2552  </programlisting>
2553  <para>
2554    In this case, uvector index in the report is the row-major index
2555    of the element that was written to.
2556  </para>
2557  </sect3>
2558  <sect3><title>Hash tables</title>
2559  <para>
2560    Hash tables are surprisingly complicated. The representation of a
2561    hash table includes an element called a hash-table-vector. The
2562    keys and values of the elements are stored pairwise in this
2563    vector.
2564  </para>
2565  <para>
2566    One problem with trying to monitor hash tables for writes is that
2567    the underlying hash-table-vector is replaced with an entirely new
2568    one when the hash table is rehashed. A previously-watched
2569    hash-table-vector will not be the used by the hash table after
2570    rehashing, and writes to the new vector will not be caught.
2571  </para>
2572  <programlisting>
2573? (defvar *h* (make-hash-table))
2574*H*
2575? (setf (gethash 'noise *h*) 'feep)
2576FEEP
2577? (watch *h*)
2578#&lt;HASH-TABLE-VECTOR #xDD00D>
2579;;; underlying hash-table-vector
2580? (setf (gethash 'noise *h*) 'ding)
2581> Error: Write to watched uvector #&lt;HASH-TABLE-VECTOR #xDD00D> at index 35
2582>        Faulting instruction: (lock)
2583>          (cmpxchgq (% rsi) (@ (% r8) (% rdx)))
2584> While executing: %STORE-NODE-CONDITIONAL, in process listener(1).
2585> Type :POP to abort, :R for a list of available restarts.
2586> Type :? for other options.
2587;;; see what value is being replaced...
25881 > (uvref (write-to-watched-object-object *break-condition*) 35)
2589FEEP
2590;;; backtrace shows useful context
25911 > :b
2592*(1A109F8) : 0 (%STORE-NODE-CONDITIONAL ???) NIL
2593 (1A10A50) : 1 (LOCK-FREE-PUTHASH NOISE #&lt;HASH-TABLE :TEST EQL size 1/60 #x30004117D47D> DING) 653
2594 (1A10AC8) : 2 (CALL-CHECK-REGS PUTHASH NOISE #&lt;HASH-TABLE :TEST EQL size 1/60 #x30004117D47D> DING) 229
2595 (1A10B00) : 3 (TOPLEVEL-EVAL (SETF (GETHASH # *H*) 'DING) NIL) 709
2596 ...
2597  </programlisting>
2598  </sect3>
2599  <sect3><title>Lists</title>
2600  <para>
2601    As previously mentioned, WATCH only watches individual cons cells.
2602  </para>
2603  <programlisting>
2604? (defun watch-list (list)
2605    (maplist #'watch list))
2606WATCH-LIST
2607? (defvar *l* (list 1 2 3))
2608*L*
2609? (watch-list *l*)
2610((1 2 3) (2 3) (3))
2611? (setf (nth 2 *l*) 'foo)
2612> Error: Write to the CAR of watched cons cell (3)
2613>        Faulting instruction: (movq (% rsi) (@ 5 (% rdi)))
2614> While executing: %SETNTH, in process listener(1).
2615> Type :POP to abort, :R for a list of available restarts.
2616> Type :? for other options.
2617  </programlisting>
2618  </sect3>
2619  </sect2>
2620</sect1>
2621
2622<sect1 id="code-coverage"><title>Code Coverage</title>
2623<sect2 id="code-coverage-overview"><title>Overview</title>
2624<para>
2625  In Clozure CL 1.4 and later, code coverage provides information
2626  about which paths through generated code have been executed and
2627  which haven't. For each source form, it can report one of three
2628  possible outcomes:
2629</para>
2630<itemizedlist>
2631  <listitem>
2632    <para>
2633      Not covered: this form was never entered.
2634    </para>
2635  </listitem>
2636  <listitem>
2637    <para>
2638      Partly covered: This form was entered, and some parts were
2639      executed and some weren't.
2640    </para>
2641  </listitem>
2642  <listitem>
2643    <para>
2644      Fully covered: Every bit of code generated from this form was
2645      executed.
2646    </para>
2647  </listitem>
2648</itemizedlist>
2649</sect2>
2650
2651<sect2 id="code-coverage-limitations"><title>Limitations</title>
2652<para>
2653  While the information gathered for coverage of generated code is
2654  complete and precise, the mapping back to source forms is of
2655  necessity heuristic, and depends a great deal on the behavior of
2656  macros and the path of the source forms through compiler
2657  transforms. Source information is not recorded for variables, which
2658  further limits the source mapping. In practice, there is often
2659  enough information scattered about a partially covered function to
2660  figure out which logical path through the code was taken and which
2661  wasn't. If that doesn't work, you can try disassembling to see which
2662  parts of the compiled code were not executed: in the disassembled
2663  code there will be references to #&lt;CODE-NOTE [xxx] ...> where xxx
2664  is NIL if the code that follows was never executed and non-NIL if it
2665  was.
2666</para>
2667<para>
2668  Sometimes the situation can be improved by modifying macros to try
2669  to preserve more of the input forms, rather than destructuring and
2670  rebuilding them.
2671</para>
2672<para>
2673  Because the code coverage information is associated with compiled
2674  functions, load-time toplevel expressions do not get reported
2675  on. You can work around this by creating a function and calling
2676  it. I.e. instead of
2677  <programlisting>
2678(progn
2679  (do-this)
2680  (setq that ...) ...))
2681  </programlisting>
2682  do:
2683  <programlisting>
2684(defun init-this-and-that ()
2685  (do-this)
2686  (setq that ...)  ...)
2687(init-this-and-that)
2688  </programlisting>
2689Then you can see the coverage information in the definition of
2690init-this-and-that.
2691</para>
2692</sect2>
2693
2694<sect2 id="code-coverage-usage"><title>Usage</title>
2695<para>
2696  In order to gather code coverage information, you first have to
2697  recompile all your code to include code coverage
2698  instrumentation. Compiling files will generate code coverage
2699  instrumentation if <literal>CCL:*COMPILE-CODE-COVERAGE*</literal>
2700  is true:
2701  <programlisting>
2702(setq ccl:*compile-code-coverage* t)
2703(recompile-all-your-files)
2704  </programlisting>
2705</para>
2706<para>
2707  The compilation process will be many times slower than normal, and
2708  the fasl files will be many times bigger.
2709</para>
2710<para>
2711  When you execute function loaded from instrumented fasl files, they
2712  will record coverage information every time they are executed. The
2713  system keeps track of which instrumented files have been loaded.
2714</para>
2715<para>
2716  The following functions can be used to manage the coverage data:
2717</para>
2718
2719<refentry id="f_report-coverage">
2720  <indexterm zone="f_report-coverage">
2721    <primary>report-coverage</primary>
2722  </indexterm>
2723 
2724  <refnamediv>
2725    <refname>REPORT-COVERAGE</refname>
2726    <refpurpose>Generate code coverage report</refpurpose>
2727    <refclass>Function</refclass>
2728  </refnamediv>
2729
2730  <refsynopsisdiv>
2731    <synopsis><function>report-coverage</function> &key;
2732    (external-format :default) (statistics t) (html t)
2733    </synopsis>
2734  </refsynopsisdiv>
2735
2736  <refsect1><title>Arguments and Values</title>
2737  <variablelist>
2738    <varlistentry>
2739      <term>html</term>
2740      <listitem>
2741        <para>
2742          If non-nil, this will generate an HTML report, consisting of
2743          an index file and one html file for each instrumented source
2744          file that has been loaded in the current session. The
2745          individual source file reports are stored in the same
2746          directory as the index file.
2747        </para>
2748      </listitem>
2749    </varlistentry>
2750    <varlistentry>
2751      <term>external-format</term>
2752      <listitem>
2753        <para>
2754          Controls the external format of the html files.
2755        </para>
2756      </listitem>
2757    </varlistentry>
2758    <varlistentry>
2759      <term>statistics</term>
2760      <listitem>
2761        <para>
2762          If :statistics is non-nil, a comma-separated file is also
2763          generated with the summary of statistics. You can specify a
2764          filename for the statistics argument, otherwise
2765          "statistics.csv" is created in the output directory. See
2766          documentation of ccl:coverage-statistics below for a
2767          description of the values in the statistics file.
2768        </para>
2769      </listitem>
2770    </varlistentry>
2771  </variablelist>
2772  </refsect1>
2773  <refsect1><title>Example</title>
2774    <para>
2775      If you've loaded <filename>foo.lx64fsl</filename> and
2776      <filename>bar.lx64fsl</filename>, and have run some tests, you could
2777      do
2778    <programlisting>
2779(CCL:REPORT-COVERAGE "/my/dir/coverage/report.html")
2780    </programlisting>
2781    and this would generate <filename>report.html</filename>,
2782    <filename>foo_lisp.html</filename> and
2783    <filename>bar_lisp.html</filename>, and
2784    <filename>statistics.csv</filename> all in
2785    <filename>/my/dir/coverage/</filename>.
2786    </para>
2787  </refsect1>
2788</refentry>
2789
2790<refentry id="f_reset-coverage">
2791  <indexterm zone="f_reset-coverage">
2792    <primary>reset-coverage</primary>
2793  </indexterm>
2794 
2795  <refnamediv>
2796    <refname>reset-coverage</refname>
2797    <refpurpose>
2798      Resets all coverage data back to the "Not Executed" state
2799    </refpurpose>
2800    <refclass>Function</refclass>
2801  </refnamediv>
2802
2803  <refsect1><title>Summary</title>
2804    <para>
2805      Resets all coverage data back to the "Not Executed" state
2806    </para>
2807  </refsect1>
2808</refentry>
2809
2810<refentry id="f_clear-coverage">
2811  <indexterm zone="f_clear-coverage">
2812    <primary>clear-coverage</primary>
2813  </indexterm>
2814 
2815  <refnamediv>
2816    <refname>clear-coverage</refname>
2817    <refpurpose>
2818      Forget about all instrumented files that have been loaded.
2819    </refpurpose>
2820    <refclass>Function</refclass>
2821  </refnamediv>
2822
2823  <refsect1><title>Summary</title>
2824    <para>
2825      Gets rid of the information about which instrumented files have
2826      been loaded, so ccl:report-coverage will not report any files,
2827      and ccl:save-coverage-in-file will not save any info, until more
2828      instrumented files are loaded.
2829    </para>
2830  </refsect1>
2831</refentry>
2832
2833<refentry id="f_save-coverage-in-file">
2834  <indexterm zone="f_save-coverage-in-file">
2835    <primary>save-coverage-in-file</primary>
2836  </indexterm>
2837 
2838  <refnamediv>
2839    <refname>save-coverage-in-file</refname>
2840    <refpurpose>
2841      Save all coverage into to a file so you can restore it later.
2842    </refpurpose>
2843    <refclass>Function</refclass>
2844  </refnamediv>
2845
2846  <refsynopsisdiv>
2847    <synopsis><function>save-coverage-in-file</function> pathname
2848    </synopsis>
2849  </refsynopsisdiv>
2850
2851  <refsect1><title>Summary</title>
2852    <para>
2853      Saves all coverage info in a file, so you can restore the
2854      coverage state later. This allows you to combine multiple runs
2855      or continue in a later session. Equivalent to
2856      (ccl:write-coverage-to-file (ccl:save-coverage) pathname).
2857    </para>
2858  </refsect1>
2859</refentry>
2860
2861<refentry id="f_restore-coverage-from-file">
2862  <indexterm zone="f_restore-coverage-from-file">
2863    <primary>restore-coverage-from-file</primary>
2864  </indexterm>
2865 
2866  <refnamediv>
2867    <refname>restore-coverage-from-file</refname>
2868    <refpurpose>
2869      Load coverage state from a file.
2870    </refpurpose>
2871    <refclass>Function</refclass>
2872  </refnamediv>
2873
2874  <refsynopsisdiv>
2875    <synopsis><function>restore-coverage-from-file</function> pathname
2876    </synopsis>
2877  </refsynopsisdiv>
2878
2879  <refsect1><title>Summary</title>
2880    <para>
2881      Restores the coverage data previously saved with
2882      CCL:SAVE-COVERAGE-IN-FILE, for the set of instrumented fasls
2883      that were loaded both at save and restore time. I.e. coverage
2884      info is only restored for files that have been loaded in this
2885      session. For example if in a previous session you had loaded
2886      "foo.lx86fsl" and then saved the coverage info, in this session
2887      you must load the same "foo.lx86fsl" before calling
2888      ccl:restore-coverage-from-file in order to retrieve the stored
2889      coverage info for "foo".  Equivalent to (ccl:restore-coverage
2890      (ccl:read-coverage-from-file pathname)).
2891    </para>
2892  </refsect1>
2893</refentry>
2894
2895<refentry id="f_save-coverage">
2896  <indexterm zone="f_save-coverage">
2897    <primary>save-coverage</primary>
2898  </indexterm>
2899 
2900  <refnamediv>
2901    <refname>save-coverage</refname>
2902    <refpurpose>
2903      Returns a snapshot of the current coverage data.
2904    </refpurpose>
2905    <refclass>Function</refclass>
2906  </refnamediv>
2907
2908  <refsect1><title>Summary</title>
2909    <para>
2910      Returns a snapshot of the current coverage data. A snapshot is a
2911      copy of the current coverage state. It can be saved in a file
2912      with ccl:write-coverage-to-file, reinstated back as the current
2913      state with ccl:restore-coverage, or combined with other
2914      snapshots with ccl:combine-coverage.
2915    </para>
2916  </refsect1>
2917</refentry>
2918
2919<refentry id="f_restore-coverage">
2920  <indexterm zone="f_restore-coverage">
2921    <primary>restore-coverage</primary>
2922  </indexterm>
2923 
2924  <refnamediv>
2925    <refname>RESTORE-COVERAGE</refname>
2926    <refpurpose>
2927      Reinstalls a coverage snapshot as the current coverage state.
2928    </refpurpose>
2929    <refclass>Function</refclass>
2930  </refnamediv>
2931
2932  <refsynopsisdiv>
2933    <synopsis><function>restore-coverage</function> snapshot
2934    </synopsis>
2935  </refsynopsisdiv>
2936
2937  <refsect1><title>Summary</title>
2938    <para>
2939      Reinstalls a coverage snapshot as the current coverage state.
2940    </para>
2941  </refsect1>
2942</refentry>
2943
2944<refentry id="f_write-coverage-to-file">
2945  <indexterm zone="f_write-coverage-to-file">
2946    <primary>write-coverage-to-file</primary>
2947  </indexterm>
2948 
2949  <refnamediv>
2950    <refname>WRITE-COVERAGE-TO-FILE</refname>
2951    <refpurpose>
2952      Save a coverage snapshot in a file.
2953    </refpurpose>
2954    <refclass>Function</refclass>
2955  </refnamediv>
2956
2957  <refsynopsisdiv>
2958    <synopsis><function>write-coverage-to-file</function> snapshot pathname
2959    </synopsis>
2960  </refsynopsisdiv>
2961
2962  <refsect1><title>Summary</title>
2963    <para>
2964      Saves the coverage snapshot in a file. The snapshot can be
2965      loaded back with ccl:read-coverage-from-file or loaded and
2966      restored with ccl:restore-coverage-from-file. Note that the file
2967      created is actually a lisp source file and can be compiled for
2968      faster loading.
2969    </para>
2970  </refsect1>
2971</refentry>
2972
2973<refentry id="f_read-coverage-from-file">
2974  <indexterm zone="f_read-coverage-from-file">
2975    <primary>read-coverage-from-file</primary>
2976  </indexterm>
2977 
2978  <refnamediv>
2979    <refname>READ-COVERAGE-FROM-FILE</refname>
2980    <refpurpose>
2981      Return the coverage snapshot saved in a file.
2982    </refpurpose>
2983    <refclass>Function</refclass>
2984  </refnamediv>
2985
2986  <refsynopsisdiv>
2987    <synopsis><function>read-coverage-from-file</function> pathname
2988    </synopsis>
2989  </refsynopsisdiv>
2990
2991  <refsect1><title>Summary</title>
2992    <para>
2993      Returns the snapshot saved in pathname. Doesn't affect the
2994      current coverage state. pathname can be the file previously
2995      created with ccl:write-coverage-to-file or
2996      ccl:save-coverage-in-file, or it can be the name of the fasl
2997      created from compiling such a file.
2998    </para>
2999  </refsect1>
3000</refentry>
3001
3002<refentry id="f_coverage-statistics">
3003  <indexterm zone="f_coverage-statistics">
3004    <primary>coverage-statistics</primary>
3005  </indexterm>
3006 
3007  <refnamediv>
3008    <refname>COVERAGE-STATISTICS</refname>
3009    <refpurpose>
3010      Returns a sequence of coverage-statistics objects, one per source file.
3011    </refpurpose>
3012    <refclass>Function</refclass>
3013  </refnamediv>
3014
3015  <refsynopsisdiv>
3016    <synopsis><function>coverage-statistics</function>
3017    </synopsis>
3018  </refsynopsisdiv>
3019
3020  <refsect1><title>Summary</title>
3021    <para>
3022      Returns a sequence ccl:coverage-statistics objects, one for each
3023      source file, containing the same information as that written to
3024      the statistics file by ccl:report-coverage. The following
3025      accessors are defined for ccl:coverage-statistics objects:
3026      <variablelist>
3027      <varlistentry>
3028        <term><function>ccl:coverage-source-file</function></term>
3029        <listitem>
3030          <para>
3031            the name of the source file corresponding to this information
3032          </para>
3033        </listitem>
3034      </varlistentry>
3035      <varlistentry>
3036        <term><function>ccl:coverage-expressions-total</function></term>
3037        <listitem>
3038          <para>
3039            the total number of expressions
3040          </para>
3041        </listitem>
3042      </varlistentry>
3043      <varlistentry>
3044        <term><function>ccl:coverage-expressions-entered</function></term>
3045        <listitem>
3046          <para>
3047            the number of source expressions that have been entered
3048            (i.e. at least partially covered)
3049          </para>
3050        </listitem>
3051      </varlistentry>
3052      <varlistentry>
3053        <term><function>ccl:coverage-expressions-covered</function></term>
3054        <listitem>
3055          <para>
3056            the number of source expressions that were fully covered
3057          </para>
3058        </listitem>
3059      </varlistentry>
3060      <varlistentry>
3061        <term><function>ccl:coverage-unreached-branches</function></term>
3062        <listitem>
3063          <para>
3064            the number of conditionals with one branch taken and one not taken
3065          </para>
3066        </listitem>
3067      </varlistentry>
3068      <varlistentry>
3069        <term><function>ccl:coverage-code-forms-total</function></term>
3070        <listitem>
3071          <para>
3072            the total number of code forms. A code form is an
3073            expression in the final stage of compilation, after all
3074            macroexpansion and compiler transforms and simplification
3075          </para>
3076        </listitem>
3077      </varlistentry>
3078      <varlistentry>
3079        <term><function>ccl:coverage-code-forms-covered</function></term>
3080        <listitem>
3081          <para>
3082            the number of code forms that have been entered
3083          </para>
3084        </listitem>
3085      </varlistentry>
3086      <varlistentry>
3087        <term><function>ccl:coverage-functions-total</function></term>
3088        <listitem>
3089          <para>
3090            the total number of functions
3091          </para>
3092        </listitem>
3093      </varlistentry>
3094      <varlistentry>
3095        <term><function>ccl:coverage-functions-fully-covered</function></term>
3096        <listitem>
3097          <para>
3098            the number of functions that were fully covered
3099          </para>
3100        </listitem>
3101      </varlistentry>
3102      <varlistentry>
3103        <term><function>ccl:coverage-functions-partly-covered</function></term>
3104        <listitem>
3105          <para>
3106            the number of functions that were partly covered
3107          </para>
3108        </listitem>
3109      </varlistentry>
3110      <varlistentry>
3111        <term><function>ccl:coverage-functions-not-entered</function></term>
3112        <listitem>
3113          <para>
3114            the number of functions never entered
3115          </para>
3116        </listitem>
3117      </varlistentry>
3118      </variablelist>
3119    </para>
3120  </refsect1>
3121</refentry>
3122
3123<refentry id="v_compile-code-coverage">
3124  <indexterm zone="v_compile-code-coverage">
3125    <primary>*COMPILE-CODE-COVERAGE*</primary>
3126  </indexterm>
3127 
3128  <refnamediv>
3129    <refname>*COMPILE-CODE-COVERAGE*</refname>
3130    <refpurpose>
3131      When true, instrument functions for code coverage.
3132    </refpurpose>
3133    <refclass>Variable</refclass>
3134  </refnamediv>
3135
3136  <refsynopsisdiv>
3137    <synopsis><varname>*compile-code-coverage*</varname>
3138    </synopsis>
3139  </refsynopsisdiv>
3140
3141  <refsect1><title>Summary</title>
3142    <para>
3143      This variable controls whether functions are instrumented for
3144      code coverage. Files compiled while this variable is true will
3145      contain code coverage instrumentation.
3146    </para>
3147  </refsect1>
3148</refentry>
3149
3150<refentry id="v_without-compiling-code-coverage">
3151  <indexterm zone="v_without-compiling-code-coverage">
3152    <primary>without-compiling-code-coverage</primary>
3153  </indexterm>
3154 
3155  <refnamediv>
3156    <refname>WITHOUT-COMPILING-CODE-COVERAGE</refname>
3157    <refpurpose>
3158      Don't record code coverange for forms within the body.
3159    </refpurpose>
3160    <refclass>Macro</refclass>
3161  </refnamediv>
3162
3163  <refsynopsisdiv>
3164    <synopsis><function>without-compiling-code-coverage</function>
3165    </synopsis>
3166  </refsynopsisdiv>
3167
3168  <refsect1><title>Summary</title>
3169    <para>
3170      This macro arranges so that body doesn't record internal details
3171      of code coverage. It will be considered totally covered if it's
3172      entered at all. The Common Lisp macros ASSERT and CHECK-TYPE use
3173      this macro.
3174    </para>
3175  </refsect1>
3176</refentry>
3177
3178</sect2>
3179</sect1>
3180<sect1 id="other-extensions"><title>Other Extensions</title>
3181<refentry id="v_quit">
3182  <indexterm zone="v_quit">
3183    <primary>quit</primary>
3184  </indexterm>
3185 
3186  <refnamediv>
3187    <refname>QUIT</refname>
3188    <refpurpose>
3189      Cleanly exit the lisp.
3190    </refpurpose>
3191    <refclass>Function</refclass>
3192  </refnamediv>
3193
3194  <refsynopsisdiv>
3195    <synopsis><function>quit</function> &optional; (exit 0) &key; error-handler
3196    </synopsis>
3197  </refsynopsisdiv>
3198
3199  <refsect1><title>Summary</title>
3200    <para>
3201      Cleanly exit from lisp.  If the exit argument is a value of type
3202      (signed-byte 32), that value will be passed to the C library
3203      function _exit() as the status code.  (A value of nil is treated
3204      as a zero.)
3205    </para>
3206    <para>
3207      Alternatively, exit may be a function of no arguments;  this function
3208      will be called instead of _exit() to exit the lisp.
3209    </para>
3210    <para>
3211      The error-handler argument, if supplied, must be a function of one
3212      argument, the condition, that will be called if an error occurs when
3213      preparing to quit.  The error-handler function should exit the lisp.
3214    </para>
3215  </refsect1>
3216</refentry>
3217
3218<refentry id="v_wait-for-signal">
3219  <indexterm zone="v_wait-for-signal">
3220    <primary>wait-for-signal</primary>
3221  </indexterm>
3222 
3223  <refnamediv>
3224    <refname>WAIT-FOR-SIGNAL</refname>
3225    <refpurpose>
3226      Wait for a particular signal to be received.
3227    </refpurpose>
3228    <refclass>Function</refclass>
3229  </refnamediv>
3230
3231  <refsynopsisdiv>
3232    <synopsis><function>wait-for-signal</function> s duration
3233    </synopsis>
3234  </refsynopsisdiv>
3235
3236  <refsect1><title>Summary</title>
3237    <para>
3238      Wait for the signal with signal number s to be received, or until
3239      duration seconds have elapsed.  If duration is nil, wait for an
3240      indeterminate "very long time" (many years).
3241    </para>
3242    <para>
3243      If signal number s is outside the range of valid signals, or is
3244      reserved by the lisp for its own use, an error is signaled.
3245      (An error is always signaled on Windows systems.)
3246    </para>
3247  </refsect1>
3248</refentry>
3249
3250
3251</sect1>
3252</chapter>
Note: See TracBrowser for help on using the repository browser.