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

Last change on this file since 14798 was 14798, checked in by gz, 8 years ago

Initial support for incremental code coverage info.

File size: 141.2 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 two
808    read-only fields that can be accessed via the functions:
809    <function>EXTERNAL-FORMAT-LINE-TERMINATION</function> and
810    <function>EXTERNAL-FORMAT-CHARACTER-ENCODING</function>.</para>
811
812 
813    <refentry id="v_default-external-format">
814        <indexterm zone="v_default-external-format">
815          <primary>*default-external-format*</primary>
816        </indexterm>
817           
818        <refnamediv>
819          <refname>CCL:*DEFAULT-EXTERNAL-FORMAT*</refname>
820          <refpurpose></refpurpose>
821          <refclass>Variable</refclass>
822        </refnamediv>
823
824        <refsect1>
825          <title>Description</title>
826
827          <para>The value of this variable is used when :EXTERNAL-FORMAT is
828                unspecified or specified as :DEFAULT. It can
829                meaningfully be given any value that can be used as an
830                external-format (except for the value :DEFAULT.)
831              </para>
832          <para>The initial value of this variable
833                in &CCL; is <literal>:UNIX</literal>, which is equivalent to
834                <literal>(:LINE-TERMINATION :UNIX)</literal>, among other
835                things.  </para>
836        </refsect1>
837    </refentry>
838
839    <refentry id="v_default-line-termination">
840        <indexterm zone="v_default-line-termination">
841          <primary>*default-line-termination*</primary>
842        </indexterm>
843           
844        <refnamediv>
845          <refname>CCL:*DEFAULT-LINE-TERMINATION*</refname>
846          <refpurpose></refpurpose>
847          <refclass>Variable</refclass>
848        </refnamediv>
849
850        <refsect1>
851          <title>Description</title>
852
853          <para>The value of this variable is used when an external-format
854                doesn't specify a line-termination convention (or specifies
855                it as :DEFAULT.) It can meaningfully be given any value
856                that can be used as a line termination keyword
857                (see <xref linkend="Line-Termination-Keywords"/>).
858              </para>
859          <para>The initial value of this variable
860                in &CCL; is <literal>:UNIX</literal>.
861          </para>
862        </refsect1>
863    </refentry>
864
865    <refentry id="f_make-external-format">
866      <indexterm zone="f_make-external-format">
867        <primary>make-external-format</primary>
868      </indexterm>
869     
870      <refnamediv>
871        <refname>MAKE-EXTERNAL-FORMAT</refname>
872        <refpurpose>Either creates a new external format object, or
873        return an existing one with the same specified slot
874        values.</refpurpose>
875        <refclass>Function</refclass>
876      </refnamediv>
877
878      <refsynopsisdiv>
879        <synopsis>
880          <function>make-external-format</function>
881          &key; domain character-encoding line-termination
882          => external-format
883        </synopsis>
884      </refsynopsisdiv>
885
886      <refsect1>
887        <title>Arguments and Values</title>
888       
889        <variablelist>
890          <varlistentry>
891            <term>domain</term>
892            <listitem>
893              <para>This is used to indicate where the external
894              format is to be used.  Its value can be almost
895              anything.  It defaults to <literal>NIL</literal>.
896              There are two domains that have a pre-defined meaning in
897              &CCL;: <literal>:FILE</literal> indicates
898              encoding for a file in the file system and
899              <literal>:SOCKET</literal> indicates i/o to/from a
900              socket.  The value of <parameter>domain</parameter>
901              affects the default values for
902              <parameter>character-encoding</parameter> and
903              <parameter>line-termination</parameter>.</para>
904            </listitem>
905          </varlistentry>
906          <varlistentry>
907            <term>character-encoding</term>
908            <listitem>
909              <para>A keyword that specifies the character encoding
910              for the external format. <xref
911              linkend="Character-Encodings"/>.  Defaults to
912              <literal>:DEFAULT</literal> which means if
913              <parameter>domain</parameter> is
914              <literal>:FILE</literal> use the value of the variable
915              <varname>CCL:*DEFAULT-FILE-CHARACTER-ENCODING*</varname>
916              and if <parameter>domain</parameter> is
917              <literal>:SOCKET</literal>, use the value of the
918              variable
919              <varname>CCL:*DEFAULT-SOCKET-CHARACTER-ENCODING*</varname>.
920              The initial value of both of these variables is
921              <literal>NIL</literal>, which means the
922              <literal>:ISO-8859-1</literal> encoding.</para>
923            </listitem>
924          </varlistentry>
925          <varlistentry>
926            <term>line-termination</term>
927            <listitem>
928              <para>A keyword that indicates a line termination
929              keyword <xref linkend="Line-Termination-Keywords"/>.
930              Defaults to <literal>:DEFAULT</literal> which means
931              use the value of the variable
932              <varname>CCL:*DEFAULT-LINE-TERMINATION*</varname>.</para>
933            </listitem>
934          </varlistentry>
935          <varlistentry>
936            <term>external-format</term>
937            <listitem>
938              <para>An external-format object as described above.</para>
939            </listitem>
940          </varlistentry>
941        </variablelist>
942      </refsect1>
943     
944      <refsect1>
945        <title>Description</title>
946       
947        <para>Despite the function's name, it doesn't necessarily create a
948        new, unique EXTERNAL-FORMAT object: two calls to
949        MAKE-EXTERNAL-FORMAT with the same arguments made in the same
950        dynamic environment return the same (eq) object.
951        </para>
952      </refsect1>
953    </refentry>
954
955  </sect2>
956
957  <sect2 id="Line-Termination-Keywords"><title>Line Termination Keywords</title>
958  <para>Line termination keywords indicate which characters are used
959  to indicate the end of a line.  On input, the external line
960  termination characters are replaced by <literal>#\Newline</literal>
961  and on output, <literal>#\Newline</literal>s are converted to the
962  external line termination characters.</para>
963  <table id="Line-Termination-Table" frame='all'><title>Line Termination Keywords</title>
964  <tgroup cols='2' align='left' colsep='1' rowsep='1'>
965    <thead>
966      <row>
967        <entry>keyword</entry>
968        <entry>character(s)</entry>
969      </row>
970    </thead>
971    <tbody>
972      <row>
973        <entry><literal>:UNIX</literal></entry>
974        <entry><literal>#\Linefeed</literal></entry>
975      </row>
976      <row>
977        <entry><literal>:MACOS</literal></entry>
978        <entry><literal>#\Return</literal></entry>
979      </row>
980      <row>
981        <entry><literal>:CR</literal></entry>
982        <entry><literal>#\Return</literal></entry>
983      </row>
984      <row>
985        <entry><literal>:CRLF</literal></entry>
986        <entry><literal>#\Return #\Linefeed</literal></entry>
987      </row>
988      <row>
989        <entry><literal>:CP/M</literal></entry>
990        <entry><literal>#\Return #\Linefeed</literal></entry>
991      </row>
992      <row>
993        <entry><literal>:MSDOS</literal></entry>
994        <entry><literal>#\Return #\Linefeed</literal></entry>
995      </row>
996      <row>
997        <entry><literal>:DOS</literal></entry>
998        <entry><literal>#\Return #\Linefeed</literal></entry>
999      </row>
1000      <row>
1001        <entry><literal>:WINDOWS</literal></entry>
1002        <entry><literal>#\Return #\Linefeed</literal></entry>
1003      </row>
1004      <row>
1005        <entry><literal>:INFERRED</literal></entry>
1006        <entry>see below</entry>
1007      </row>
1008      <row>
1009        <entry><literal>:UNICODE</literal></entry>
1010        <entry><literal>#\Line_Separator</literal></entry>
1011      </row>
1012    </tbody>
1013  </tgroup>
1014  </table>
1015  <para><literal>:INFERRED</literal> means that a stream's
1016  line-termination convention is determined by looking at the contents
1017  of a file.  It is only useful for <literal>FILE-STREAM</literal>s
1018  that're open for <literal>:INPUT</literal> or
1019  <literal>:IO</literal>.  The first buffer full of data is examined,
1020  and if a <literal>#\Return</literal> character occurs before any
1021  <literal>#\Linefeed</literal> character, then the line termination
1022  type is set to <literal>:WINDOWS</literal> if that
1023  <literal>#\Return</literal> character is immediately followed by a
1024  <literal>#\Linefeed</literal> character and to <literal>:MACOS</literal>
1025  otherwise.  If a <literal>#\Return</literal> character isn't found in
1026  the buffer or if <literal>#\Return</literal> is preceded by
1027  <literal>#\Linefeed</literal>, the file's line terminationt type
1028  is set to <literal>:UNIX</literal>.</para>
1029  </sect2>
1030 
1031
1032
1033  <sect2 id="Character-Encodings"><title>Character Encodings</title>
1034    <para>Internally, all characters and strings in &CCL; are in
1035    UTF-32.  Externally, files or socket streams may encode characters
1036    in a wide variety of ways.  The International Organization for
1037    Standardization, widely known as ISO, defines many of these
1038    character encodings.  &CCL; implements some of these encodings as
1039    detailed below.  These encodings are part of the specification of
1040    external formats <xref linkend="External-Formats"/>.  When reading
1041    from a stream, characters are converted from the specified
1042    external character encoding to UTF-32.  When writing to a stream,
1043    characters are converted from UTF-32 to the specified character
1044    encoding.</para>
1045
1046    <para>Internally, CHARACTER-ENCODINGs are objects (structures)
1047    that are named by character encoding keywords (:ISO-8859-1,
1048    :UTF-8, etc.).  The structures contain attributes of the encoding
1049    and functions used to encode/decode external data, but unless
1050    you're trying to define or debug an encoding there's little reason
1051    to know much about the CHARACTER-ENCODING objects and it's usually
1052    preferable to refer to a character encoding by its name.
1053    </para>
1054
1055    <para>
1056    </para>
1057
1058    <sect3><title>Encoding Problems</title>
1059      <para>On output to streams with character encodings that can
1060      encode the full range of Unicode&mdash;and on input from any
1061      stream&mdash;"unencodable characters" are represented using the
1062      Unicode #\Replacement_Character (= #\U+fffd); the presence of
1063      such a character usually indicates that something got lost in
1064      translation.  Either data wasn't encoded properly or there was a
1065      bug in the decoding process.</para>
1066    </sect3>
1067
1068    <sect3><title>Byte Order Marks</title>
1069      <para>The endianness of a character encoding is sometimes
1070      explicit, and sometimes not.  For example,
1071      <literal>:UTF-16BE</literal> indicates big-endian, but
1072      <literal>:UTF-16</literal> does not specify endianness.  A byte
1073      order mark is a special character that may appear at the
1074      beginning of a stream of encoded characters to specify the
1075      endianness of a multi-byte character encoding.  (It may also be
1076      used with UTF-8 character encodings, where it is simply used to
1077      indicate that the encoding is UTF-8.)</para>
1078
1079      <para>&CCL; writes a byte order mark as the first character
1080      of a file or socket stream when the endianness of the character
1081      encoding is not explicit.  &CCL; also expects a byte order
1082      mark on input from streams where the endianness is not
1083      explicit. If a byte order mark is missing from input data, that
1084      data is assumed to be in big-endian order.</para>
1085
1086      <para>A byte order mark from a UTF-8 encoded input stream is not
1087      treated specially and just appears as a normal character from
1088      the input stream.  It is probably a good idea to skip over this
1089      character.</para>
1090    </sect3>
1091
1092  <sect3><title><function>DESCRIBE-CHARACTER-ENCODINGS</function></title>
1093    <para>The set of character encodings supported by &CCL; can be
1094    retrieved by calling
1095    <function>CCL:DESCRIBE-CHARACTER-ENCODINGS</function>.</para>
1096
1097
1098      <refentry id="f_describe-character-encodings">
1099        <indexterm zone="f_describe-character-encodings">
1100          <primary>[fn-name]</primary>
1101        </indexterm>
1102
1103        <refnamediv>
1104          <refname>DESCRIBE-CHARACTER-ENCODINGS</refname>
1105          <refpurpose>Writes descriptions of defined character
1106          encodings to <varname>*terminal-io*</varname>.</refpurpose>
1107          <refclass>Function</refclass>
1108        </refnamediv>
1109
1110        <refsynopsisdiv>
1111          <synopsis>
1112            <function>describe-character-encodings</function>
1113          </synopsis>
1114        </refsynopsisdiv>
1115
1116        <refsect1>
1117          <title>Description</title>
1118
1119          <para>Writes descriptions of all defined character encodings
1120          to <varname>*terminal-io*</varname>.  These descriptions
1121          include the names of the encoding's aliases and a doc string
1122          which briefly describes each encoding's properties and
1123          intended use.</para>
1124        </refsect1>
1125
1126        <refsect1>
1127          <title>See Also</title>
1128         
1129          <simplelist type="inline">
1130            <member><xref linkend="Character-Encodings"/></member>
1131            <member><xref linkend="External-Formats"/></member>
1132            <member><xref linkend="Supported-Character-Encodings"/></member>
1133          </simplelist>
1134        </refsect1>
1135      </refentry>
1136  </sect3>
1137
1138  <sect3 id="Supported-Character-Encodings"><title>Supported Character Encodings</title>
1139     <para>The list of supported encodings is reproduced here.  Most
1140     encodings have aliases, e.g. the encoding named
1141     <literal>:ISO-8859-1</literal> can also be referred to by the
1142     names <literal>:LATIN1</literal> and <literal>:IBM819</literal>,
1143     among others.  Where possible, the keywordized name of an
1144     encoding is equivalent to the preferred MIME charset name (and
1145     the aliases are all registered IANA charset names.)</para>
1146
1147  <variablelist>
1148    <varlistentry><term><literal>:ISO-8859-1</literal></term>
1149       <listitem><para>An 8-bit, fixed-width character encoding in
1150       which all character codes map to their Unicode
1151       equivalents. Intended to support most characters used in most
1152       Western European languages.</para>
1153       <para>&CCL; uses ISO-8859-1 encoding for
1154       <varname>*TERMINAL-IO*</varname> and for all streams whose
1155       EXTERNAL-FORMAT isn't explicitly specified.  The default for
1156       <varname>*TERMINAL-IO*</varname> can be set via the
1157       <literal>-K</literal> command-line argument (see <xref
1158       linkend="Command-Line-Options"/>).
1159       </para>
1160       <para>ISO-8859-1 just covers the first 256 Unicode code
1161       points, where the first 128 code points are equivalent to
1162       US-ASCII.  That should be pretty much equivalent to what
1163       earliers versions of &CCL; did that only supported 8-bit characters,
1164       but it may not be optimal for users working in a particular
1165       locale.</para>
1166       <para>Aliases: <literal>:ISO_8859-1, :LATIN1, :L1,
1167       :IBM819, :CP819, :CSISOLATIN1</literal></para></listitem>
1168     </varlistentry>
1169    <varlistentry><term><literal>:ISO-8859-2</literal></term>
1170       <listitem><para>An 8-bit, fixed-width character encoding in
1171       which codes #x00-#x9f map to their Unicode equivalents and
1172       other codes map to other Unicode character values.  Intended to
1173       provide most characters found in most languages used in
1174       Central/Eastern Europe.</para>
1175       <para>Aliases: <literal>:ISO_8859-2, :LATIN-2, :L2,
1176       :CSISOLATIN2</literal></para></listitem>
1177     </varlistentry>
1178    <varlistentry><term><literal>:ISO-8859-3</literal></term>
1179       <listitem><para>An 8-bit, fixed-width character encoding in
1180       which codes #x00-#x9f map to their Unicode equivalents and
1181       other codes map to other Unicode character values.  Intended to
1182       provide most characters found in most languages used in
1183       Southern Europe.</para>
1184       <para>Aliases: <literal>:ISO_8859-3, :LATIN,3 :L3,
1185       :CSISOLATIN3</literal></para></listitem>
1186     </varlistentry>
1187    <varlistentry><term><literal>:ISO-8859-4</literal></term>
1188       <listitem><para>An 8-bit, fixed-width character encoding in
1189       which codes #x00-#x9f map to their Unicode equivalents and
1190       other codes map to other Unicode character values.  Intended to
1191       provide most characters found in most languages used in
1192       Northern Europe.</para>
1193       <para>Aliases: <literal>:ISO_8859-4, :LATIN4, :L4, :CSISOLATIN4</literal></para></listitem>
1194     </varlistentry>
1195    <varlistentry><term><literal>:ISO-8859-5</literal></term>
1196       <listitem><para>An 8-bit, fixed-width character encoding in
1197       which codes #x00-#x9f map to their Unicode equivalents and
1198       other codes map to other Unicode character values.  Intended to
1199       provide most characters found in the Cyrillic
1200       alphabet.</para>
1201       <para>Aliases: <literal>:ISO_8859-5, :CYRILLIC, :CSISOLATINCYRILLIC,
1202       :ISO-IR-144</literal></para></listitem>
1203     </varlistentry>
1204    <varlistentry><term><literal>:ISO-8859-6</literal></term>
1205       <listitem><para>An 8-bit, fixed-width character encoding in
1206       which codes #x00-#x9f map to their Unicode equivalents and
1207       other codes map to other Unicode character values.  Intended to
1208       provide most characters found in the Arabic
1209       alphabet.</para>
1210       <para>Aliases: <literal>:ISO_8859-6, :ARABIC, :CSISOLATINARABIC,
1211       :ISO-IR-127</literal></para></listitem>
1212     </varlistentry>
1213    <varlistentry><term><literal>:ISO-8859-7</literal></term>
1214       <listitem><para>An 8-bit, fixed-width character encoding in
1215       which codes #x00-#x9f map to their Unicode equivalents and
1216       other codes map to other Unicode character values.  Intended to
1217       provide most characters found in the Greek
1218       alphabet.</para>
1219       <para>Aliases: <literal>:ISO_8859-7, :GREEK, :GREEK8, :CSISOLATINGREEK,
1220       :ISO-IR-126, :ELOT_928, :ECMA-118</literal></para></listitem>
1221     </varlistentry>
1222    <varlistentry><term><literal>:ISO-8859-8</literal></term>
1223       <listitem><para>An 8-bit, fixed-width character encoding in
1224       which codes #x00-#x9f map to their Unicode equivalents and
1225       other codes map to other Unicode character values.  Intended to
1226       provide most characters found in the Hebrew
1227       alphabet.</para>
1228       <para>Aliases: <literal>:ISO_8859-8, :HEBREW, :CSISOLATINHEBREW,
1229       :ISO-IR-138</literal></para></listitem>
1230     </varlistentry>
1231    <varlistentry><term><literal>:ISO-8859-9</literal></term>
1232       <listitem><para>An 8-bit, fixed-width character encoding in
1233       which codes #x00-#xcf map to their Unicode equivalents and
1234       other codes map to other Unicode character values.  Intended to
1235       provide most characters found in the Turkish
1236       alphabet.</para>
1237       <para>Aliases: <literal>:ISO_8859-9, :LATIN5, :CSISOLATIN5,
1238       :ISO-IR-148</literal></para></listitem>
1239     </varlistentry>
1240    <varlistentry><term><literal>:ISO-8859-10</literal></term>
1241       <listitem><para>An 8-bit, fixed-width character encoding in
1242       which codes #x00-#x9f map to their Unicode equivalents and
1243       other codes map to other Unicode character values.  Intended to
1244       provide most characters found in Nordic
1245       alphabets.</para>
1246       <para>Aliases: <literal>:ISO_8859-10, :LATIN6, :CSISOLATIN6,
1247       :ISO-IR-157</literal></para></listitem>
1248     </varlistentry>
1249    <varlistentry><term><literal>:ISO-8859-11</literal></term>
1250       <listitem><para>An 8-bit, fixed-width character encoding in
1251       which codes #x00-#x9f map to their Unicode equivalents and
1252       other codes map to other Unicode character values.  Intended to
1253       provide most characters found the Thai
1254       alphabet.</para></listitem>
1255     </varlistentry>
1256    <varlistentry><term><literal>:ISO-8859-13</literal></term>
1257       <listitem><para>An 8-bit, fixed-width character encoding in
1258       which codes #x00-#x9f map to their Unicode equivalents and
1259       other codes map to other Unicode character values.  Intended to
1260       provide most characters found in Baltic
1261       alphabets.</para></listitem>
1262     </varlistentry>
1263    <varlistentry><term><literal>:ISO-8859-14</literal></term>
1264       <listitem><para>An 8-bit, fixed-width character encoding in
1265       which codes #x00-#x9f map to their Unicode equivalents and
1266       other codes map to other Unicode character values.  Intended to
1267       provide most characters found in Celtic
1268       languages.</para>
1269       <para>Aliases: <literal>:ISO_8859-14, :ISO-IR-199, :LATIN8, :L8,
1270       :ISO-CELTIC</literal></para></listitem>
1271     </varlistentry>
1272    <varlistentry><term><literal>:ISO-8859-15</literal></term>
1273       <listitem><para>An 8-bit, fixed-width character encoding in
1274       which codes #x00-#x9f map to their Unicode equivalents and
1275       other codes map to other Unicode character values.  Intended to
1276       provide most characters found in Western European languages
1277       (including the Euro sign and some other characters missing from
1278       ISO-8859-1.</para>
1279       <para>Aliases: <literal>:ISO_8859-15, :LATIN9</literal></para></listitem>
1280     </varlistentry>
1281    <varlistentry><term><literal>:ISO-8859-16</literal></term>
1282       <listitem><para>An 8-bit, fixed-width character encoding in
1283       which codes #x00-#x9f map to their Unicode equivalents and
1284       other codes map to other Unicode character values.  Intended to
1285       provide most characters found in Southeast European
1286       languages.</para>
1287       <para>Aliases: <literal>:ISO_8859-16, :ISO-IR-199, :LATIN8, :L8,
1288       :ISO-CELTIC</literal></para></listitem>
1289     </varlistentry>
1290    <varlistentry><term><literal>:MACINTOSH</literal></term>
1291       <listitem><para>An 8-bit, fixed-width character encoding in
1292       which codes #x00-#x7f map to their Unicode equivalents and
1293       other codes map to other Unicode character values.
1294       Traditionally used on Classic MacOS to encode characters used
1295       in western languages.</para>
1296       <para>Aliases: <literal>:MACOS-ROMAN, :MACOSROMAN, :MAC-ROMAN,
1297       :MACROMAN</literal></para></listitem>
1298     </varlistentry>
1299    <varlistentry><term><literal>:UCS-2</literal></term>
1300       <listitem><para>A 16-bit, fixed-length encoding in which
1301       characters with CHAR-CODEs less than #x10000 can be encoded in
1302       a single 16-bit word.  The endianness of the encoded data is
1303       indicated by the endianness of a byte-order-mark character
1304       (#u+feff) prepended to the data; in the absence of such a
1305       character on input, the data is assumed to be in big-endian
1306       order.</para></listitem>
1307     </varlistentry>
1308    <varlistentry><term><literal>:UCS-2BE</literal></term>
1309       <listitem><para>A 16-bit, fixed-length encoding in which
1310       characters with CHAR-CODEs less than #x10000 can be encoded in
1311       a single 16-bit big-endian word. The encoded data is implicitly
1312       big-endian; byte-order-mark characters are not interpreted on
1313       input or prepended to output.</para></listitem>
1314     </varlistentry>
1315    <varlistentry><term><literal>:UCS-2LE</literal></term>
1316       <listitem><para>A 16-bit, fixed-length encoding in which
1317       characters with CHAR-CODEs less than #x10000 can be encoded in
1318       a single 16-bit little-endian word. The encoded data is
1319       implicitly little-endian; byte-order-mark characters are not
1320       interpreted on input or prepended to output.</para></listitem>
1321     </varlistentry>
1322    <varlistentry><term><literal>:US-ASCII</literal></term>
1323       <listitem><para>An 7-bit, fixed-width character encoding in
1324       which all character codes map to their Unicode
1325       equivalents. </para>
1326       <para>Aliases: <literal>:CSASCII, :CP63,7 :IBM637, :US,
1327       :ISO646-US, :ASCII, :ISO-IR-6</literal></para></listitem>
1328     </varlistentry>
1329    <varlistentry><term><literal>:UTF-16</literal></term>
1330       <listitem><para>A 16-bit, variable-length encoding in which
1331       characters with CHAR-CODEs less than #x10000 can be encoded in
1332       a single 16-bit word and characters with larger codes can be
1333       encoded in a pair of 16-bit words.  The endianness of the
1334       encoded data is indicated by the endianness of a
1335       byte-order-mark character (#u+feff) prepended to the data; in
1336       the absence of such a character on input, the data is assumed
1337       to be in big-endian order. Output is written in native
1338       byte-order with a leading byte-order mark.</para></listitem>
1339     </varlistentry>
1340    <varlistentry><term><literal>:UTF-16BE</literal></term>
1341       <listitem><para>A 16-bit, variable-length encoding in which
1342       characters with CHAR-CODEs less than #x10000 can be encoded in
1343       a single 16-bit big-endian word and characters with larger
1344       codes can be encoded in a pair of 16-bit big-endian words.  The
1345       endianness of the encoded data is implicit in the encoding;
1346       byte-order-mark characters are not interpreted on input or
1347       prepended to output.</para></listitem>
1348     </varlistentry>
1349    <varlistentry><term><literal>:UTF-16LE</literal></term>
1350       <listitem><para>A 16-bit, variable-length encoding in which
1351       characters with CHAR-CODEs less than #x10000 can be encoded in
1352       a single 16-bit little-endian word and characters with larger
1353       codes can be encoded in a pair of 16-bit little-endian words.
1354       The endianness of the encoded data is implicit in the encoding;
1355       byte-order-mark characters are not interpreted on input or
1356       prepended to output.</para></listitem>
1357     </varlistentry>
1358    <varlistentry><term><literal>:UTF-32</literal></term>
1359       <listitem><para>A 32-bit, fixed-length encoding in which all
1360       Unicode characters can be encoded in a single 32-bit word.  The
1361       endianness of the encoded data is indicated by the endianness
1362       of a byte-order-mark character (#u+feff) prepended to the data;
1363       in the absence of such a character on input, input data is
1364       assumed to be in big-endian order.  Output is written in native
1365       byte order with a leading byte-order mark.</para>
1366       <para>Alias: <literal>:UTF-4</literal></para></listitem>
1367     </varlistentry>
1368    <varlistentry><term><literal>:UTF-32BE</literal></term>
1369       <listitem><para>A 32-bit, fixed-length encoding in which all
1370       Unicode characters encoded in a single 32-bit word. The encoded
1371       data is implicitly big-endian; byte-order-mark characters are
1372       not interpreted on input or prepended to
1373       output.</para>
1374       <para>Alias: <literal>:UCS-4BE</literal></para></listitem>
1375     </varlistentry>
1376    <varlistentry><term><literal>:UTF-8</literal></term>
1377       <listitem><para>An 8-bit, variable-length character encoding in
1378       which characters with CHAR-CODEs in the range #x00-#x7f can be
1379       encoded in a single octet; characters with larger code values
1380       can be encoded in 2 to 4 bytes.</para></listitem>
1381     </varlistentry>
1382    <varlistentry><term><literal>:UTF-32LE</literal></term>
1383       <listitem><para>A 32-bit, fixed-length encoding in which all
1384       Unicode characters can encoded in a single 32-bit word. The
1385       encoded data is implicitly little-endian; byte-order-mark
1386       characters are not interpreted on input or prepended to
1387       output.</para>
1388       <para>Alias: <literal>:UCS-4LE</literal></para></listitem>
1389     </varlistentry>
1390     <varlistentry><term><literal>:Windows-31j</literal></term>
1391     <listitem><para>An 8-bit, variable-length character encoding in
1392     which character code points in the range #x00-#x7f can be encoded
1393     in a single octet; characters with larger code values can be
1394     encoded in 2 bytes.</para>
1395     <para>Aliases: <literal>:CP932, :CSWINDOWS31J</literal></para></listitem>
1396     </varlistentry>
1397     <varlistentry><term><literal>:EUC-JP</literal></term>
1398     <listitem><para>An 8-bit, variable-length character encoding in
1399     which character code points in the range #x00-#x7f can be encoded
1400     in a single octet; characters with larger code values can be
1401     encoded in 2 bytes.</para>
1402     <para>Alias: <literal>:EUCJP</literal></para></listitem>
1403     </varlistentry>
1404   </variablelist>
1405 </sect3>
1406
1407 <sect3><title>Encoding and Decoding Strings</title>
1408 <para>&CCL; provides functions to encode and decode strings
1409to and from vectors of type (simple-array (unsigned-byte 8)).</para>
1410
1411<refentry id="count-characters-in-octet-vector">
1412  <indexterm zone="count-characters-in-octet-vector">
1413    <primary>count-characters-in-octet-vector</primary>
1414  </indexterm>
1415
1416  <refnamediv>
1417    <refname>count-characters-in-octet-vector</refname>
1418    <refpurpose></refpurpose>
1419    <refclass>Function</refclass>
1420  </refnamediv>
1421
1422  <refsynopsisdiv>
1423    <synopsis>
1424        <function>count-characters-in-octet-vector</function>
1425        <parameter>vector</parameter>
1426        <parameter>&key;</parameter>
1427        <parameter>start</parameter>
1428        <parameter>end</parameter>
1429        <parameter>external-format</parameter>
1430    </synopsis>
1431  </refsynopsisdiv>
1432
1433  <refsect1><title>Description</title>
1434  <para>
1435    Returns the number of characters that would be produced by
1436    decoding <varname>vector</varname> (or the subsequence thereof
1437    delimited by <varname>start</varname> and <varname>end</varname>)
1438    according to <varname>external-format</varname>.
1439  </para>
1440  </refsect1>
1441</refentry>
1442
1443<refentry id="decode-string-from-octets">
1444  <indexterm zone="decode-string-from-octets">
1445    <primary>"decode-string-from-octets</primary>
1446  </indexterm>
1447
1448  <refnamediv>
1449    <refname>decode-string-from-octets</refname>
1450    <refpurpose></refpurpose>
1451    <refclass>Function</refclass>
1452  </refnamediv>
1453
1454  <refsynopsisdiv>
1455    <synopsis>
1456        <function>decode-string-from-octets</function>
1457        <parameter>vector</parameter>
1458        <parameter>&key;</parameter>
1459        <parameter>start</parameter>
1460        <parameter>end</parameter>
1461        <parameter>external-format</parameter>
1462        <parameter>string</parameter>
1463    </synopsis>
1464  </refsynopsisdiv>
1465
1466
1467  <refsect1><title>Description</title>
1468  <para>
1469    Decodes the octets in <varname>vector</varname> (or the subsequence
1470    of it delimited by <varname>start</varname> and
1471    <varname>end</varname>) into a string according
1472    to <varname>external-format</varname>.
1473  </para>
1474  <para>
1475    If <varname>string</varname> is supplied, output will be written into it.
1476    It must be large enough to hold the decoded characters.  If <varname>
1477    string</varname> is not supplied, a new string will be allocated to
1478    hold the decoded characters.
1479  </para>
1480  <para>
1481    Returns, as multiple values, the decoded string and the position in
1482    <varname>vector</varname> where the decoding ended.
1483  </para>
1484  <para>
1485    Sequences of octets in <varname>vector</varname> that cannot be
1486    decoded into characters according to
1487    <varname>external-format</varname> will be decoded as
1488    #\Replacement_Character.
1489  </para>
1490  </refsect1>
1491</refentry>
1492
1493<refentry id="encode-string-to-octets">
1494  <indexterm zone="encode-string-to-octets">
1495    <primary>encode-string-to-octets</primary>
1496  </indexterm>
1497
1498  <refnamediv>
1499    <refname>encode-string-to-octets</refname>
1500    <refpurpose></refpurpose>
1501    <refclass>Function</refclass>
1502  </refnamediv>
1503
1504  <refsynopsisdiv>
1505    <synopsis>
1506        <function>encode-string-to-octets</function>
1507        <parameter>string</parameter>
1508        <parameter>&key;</parameter>
1509        <parameter>start</parameter>
1510        <parameter>end</parameter>
1511        <parameter>external-format</parameter>
1512        <parameter>use-byte-order-mark</parameter>
1513        <parameter>vector</parameter>
1514        <parameter>vector-offset</parameter>
1515    </synopsis>
1516  </refsynopsisdiv>
1517
1518
1519  <refsect1><title>Description</title>
1520  <para>
1521    Encodes <varname>string</varname> (or the substring delimited by
1522    <varname>start</varname> and <varname>end</varname>)
1523    into <varname>external-format</varname> and returns, as multiple
1524    values, a vector of octets containing the encoded data and an integer
1525    that specifies the offset into the vector where the encoded data ends.
1526  </para>
1527  <para>
1528    When <varname>use-byte-order-mark</varname> is true, a byte-order mark
1529    will be included in the encoded data.
1530  </para>
1531  <para>
1532    If <varname>vector</varname> is supplied, output will be written
1533    to it.  It must be of type (simple-array (unsigned-byte 8)) and be
1534    large enough to hold the encoded data.  If it is not supplied, the function
1535    will allocate a new vector.
1536  </para>
1537  <para>
1538    If <varname>vector-offset</varname> is supplied, data will be written
1539    into the output vector starting at that offset.
1540  </para>
1541  <para>
1542    Characters in <varname>string</varname> that cannot be encoded
1543    into <varname>external-format</varname> will be replaced with an
1544    encoding-dependent replacement character
1545    (#\Replacement_Character or #\Sub) before being encoded and written
1546    into the output vector.
1547  </para>
1548  </refsect1>
1549</refentry>
1550
1551<refentry id="string-size-in-octets">
1552  <indexterm zone="string-size-in-octets">
1553    <primary>string-size-in-octets</primary>
1554  </indexterm>
1555
1556  <refnamediv>
1557    <refname>string-size-in-octets</refname>
1558    <refpurpose></refpurpose>
1559    <refclass>Function</refclass>
1560  </refnamediv>
1561
1562  <refsynopsisdiv>
1563    <synopsis>
1564        <function>string-size-in-octets</function>
1565        <parameter>string</parameter>
1566        <parameter>&key;</parameter>
1567        <parameter>start</parameter>
1568        <parameter>end</parameter>
1569        <parameter>external-format</parameter>
1570        <parameter>use-byte-order-mark</parameter>
1571    </synopsis>
1572  </refsynopsisdiv>
1573
1574
1575  <refsect1><title>Description</title>
1576  <para>
1577    Returns the number of octets required to encode
1578    <varname>string</varname> (or the substring delimited by
1579    <varname>start</varname> and <varname>end</varname>) into
1580    <varname>external-format</varname>.
1581  </para>
1582  <para>
1583    When <varname>use-byte-order-mark</varname> is true, the returned
1584    size will include space for a byte-order marker.
1585  </para>
1586  </refsect1>
1587</refentry>
1588
1589 </sect3>
1590
1591
1592  </sect2>
1593
1594  </sect1>
1595
1596  <sect1 id="Pathanmes"><title>Pathnames</title>
1597
1598    <sect2 id="pathname-tilde-expansion">
1599      <title>Pathname Expansion</title>
1600      <para>Leading tilde (~) characters in physical pathname namestrings
1601        are expanded in the way that most shells do:</para>
1602     
1603      <para><literal>"~user/..."</literal> can be used to refer to an absolute pathname rooted
1604        at the home directory of the user named "user".</para>
1605     
1606      <para><literal>"~/..."</literal> can be used to refer to an absolute pathname rooted at
1607        the home directory of the current user.</para>
1608    </sect2>
1609
1610    <sect2 id="Predefined-Logical-Hosts"><title>Predefined Logical Hosts</title>
1611
1612      <para>&CCL; sets up logical pathname translations for logical hosts:  <literal>ccl</literal> and <literal>home</literal></para>
1613
1614      <indexterm><primary>CCL Logical Host</primary></indexterm>
1615      <para>The <literal>CCL</literal> logical host should point to the
1616        <literal>ccl</literal> directory.  It is used for a variety of
1617        purposes by &CCL; including: locating &CCL; source code,
1618        <literal>require</literal> and <literal>provide</literal>, accessing
1619        foreign function information, and the &CCL; build process. It
1620        is set to the value of the environment variable
1621        <varname>CCL_DEFAULT_DIRECTORY</varname>, which is set by the
1622        openmcl shell script <xref linkend="The-ccl-Shell-Script"/>.  If
1623        <varname>CCL_DEFAULT_DIRECTORY</varname> is not set, then it is set
1624        to the directory containing the current heap image.</para>
1625    </sect2>
1626    <sect2 id="pathname-namestrings">
1627      <title>Pathname Namestrings</title>
1628      <para>
1629        The syntax of namestrings is implementation-defined in Common Lisp.
1630        Portable programs cannot assume much of anything about them.  (See
1631        section 19.1.1 of the Common Lisp standard for more information.)
1632      </para>
1633      <para>
1634        When translating a namestring into a pathname object, most
1635        implementations seem to follow the convention that a dot
1636        character in the namestring separates the
1637        <literal>pathname-name</literal> and
1638        the <literal>pathname-type</literal>.  When there is more
1639        than one dot in involved, or when dots appear at the beginning
1640        or end of the namestrings, what to do is less clear: does
1641        ".emacs" describe a pathname whose name is
1642        <literal>nil</literal> and whose type is <literal>emacs</literal>
1643        or something else?  Similarly, given "a.b.c", the question
1644        is which parts are parsed as the pathname name, and which are
1645        parsed as the pathname type?
1646      </para>
1647      <para>
1648        When generating a namestring from a pathname object (as happens,
1649        for example, when printing a pathname), &CCL;
1650        tries to avoid some potential ambiguity by escaping characters
1651        that might otherwise be used to separate pathname components.
1652        The character used to quote or escape the separators is a
1653        backlash on Unix systems, and a #\&gt; character on Windows.
1654        So, for example, "a\\.b.c"
1655        has name "a.b" and type "c", whereas "a.b\\.c" has name
1656        "a" and type "b.c".
1657      </para>
1658      <para>
1659        To get a native namestring suitable for passing to an
1660        operating system command, use the function
1661        <literal>ccl:native-translated-namestring</literal>.
1662      </para>
1663
1664    <sect3>
1665      <title>Working with native namestrings</title>
1666      <refentry id="f_native-translated-namestring">
1667        <indexterm zone="f_native-translated-namestring">
1668          <primary>native-translated-namestring</primary>
1669        </indexterm>
1670       
1671        <refnamediv>
1672          <refname>native-translated-namestring</refname>
1673          <refpurpose>
1674            Return a namestring that uses the conventions of the
1675            native operating system.
1676          </refpurpose>
1677          <refclass>Function</refclass>
1678        </refnamediv>
1679       
1680        <refsynopsisdiv>
1681          <synopsis><function>native-translated-namestring</function> pathname-designator</synopsis>
1682        </refsynopsisdiv>
1683       
1684        <refsect1><title>Description</title>
1685        <para>
1686          This function returns a namestring that represents a pathname
1687          using the native conventions of the operating system.
1688          Any quoting or escaping of special characters will be removed.
1689        </para>
1690        <para>
1691          For example, suppose that <varname>p</varname> is a pathname made
1692          by <literal>(make-pathname :name "a.b" :type "c")</literal>.
1693          Then, <literal>(native-translated-namestring p)</literal> evaluates
1694          to "a.b.c".  By contrast, <literal>(namestring p)</literal> evaluates
1695          to "a\\.b.c".
1696        </para>
1697        </refsect1>
1698      </refentry>
1699
1700      <refentry id="m_with-filename-cstrs">
1701        <indexterm zone="m_with-filename-cstrs">
1702          <primary>with-filename-cstrs</primary>
1703        </indexterm>
1704       
1705        <refnamediv>
1706          <refname>with-filename-cstrs</refname>
1707          <refpurpose>
1708            Suitably encode strings to be used as filenames for foreign code.
1709          </refpurpose>
1710          <refclass>Macro</refclass>
1711        </refnamediv>
1712       
1713        <refsynopsisdiv>
1714          <synopsis><function>with-filename-cstrs</function> ( {(var value)}* ) {form}*</synopsis>
1715        </refsynopsisdiv>
1716       
1717        <refsect1><title>Description</title>
1718        <para>
1719          Executes <varname>forms</varname> in an environemt in which each
1720          <varname>var</varname> is bound to a stack-allocated foreign
1721          pointer which refers to a C-style string suitable for passing
1722          to foreign code which expects a filename argument.
1723        </para>
1724        <para>
1725          For example, one might use this macro in the following way:
1726  <programlisting>
1727(with-filename-cstrs ((s (native-translated-namestring pathname)))
1728  (#_unlink s))
1729  </programlisting>
1730        </para>
1731        <para>
1732          Various operating systems have different conventions for how
1733          they expect native pathname strings to be encoded.  Darwin
1734          expects then to be decomposed UTF-8.  The Unicode variants
1735          to Windows file-handling functions expect UTF-16.  Other
1736          systems just treat them as opaque byte sequences.  This macro
1737          ensures that the correct encoding is used, whatever
1738          the host operating system.
1739        </para>
1740        </refsect1>
1741      </refentry>
1742    </sect3>
1743  </sect2>
1744    <sect2 id="pathnames-on-darwin">
1745      <title>OS X (Darwin)</title>
1746     
1747      <para>&CCL; assumes that pathname strings are decomposed UTF-8.</para>
1748    </sect2>
1749    <sect2 id="pathnames-on-linux">
1750      <title>Linux</title>
1751     
1752      <para>Pathname strings are treated as null-terminated strings
1753        coded in the encoding named by the value returned by the function
1754      <varname>CCL:PATHNAME-ENCODING-NAME</varname>.  This value may be changed
1755      with <varname>SETF</varname>.</para>
1756    </sect2>
1757    <sect2 id="pathnames-on-freebsd">
1758      <title>FreeBSD</title>
1759     
1760      <para>Pathname strings are treated as null-terminated strings
1761        encoded according to the current locale; a future release may
1762        change this convention to use UTF-8.</para>
1763    </sect2>
1764  </sect1>
1765
1766  <sect1 id="Memory-Mapped-Files">
1767    <title>Memory-mapped Files</title>
1768    <para>In release 1.2 and later, &CCL;
1769      supports <glossterm linkend="memory_mapped_file">memory-mapped
1770        files</glossterm>. On operating systems that support memory-mapped
1771      files (including Mac OS X, Linux, and FreeBSD), the operating
1772      system can arrange for a range of virtual memory addresses to
1773      refer to the contents of an open file. As long as the file remains
1774      open, programs can read values from the file by reading addresses
1775      in the mapped range.</para>
1776
1777    <para>Using memory-mapped files may in some cases be more
1778      efficient than reading the contents of a file into a data
1779      structure in memory.</para>
1780
1781    <para>&CCL; provides the
1782      functions <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
1783      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> to support
1784      memory-mapping. These functions return vectors whose contents are
1785      the contents of memory-mapped files. Reading an element of such a
1786      vector returns data from the corresponding position in the
1787      file.</para>
1788
1789    <para>Without memory-mapped files, a common idiom for reading the
1790      contents of files might be something like this:</para>
1791
1792    <programlisting>
1793(let* ((stream (open pathname :direction :input :element-type '(unsigned-byte 8)))
1794       (vector (make-array (file-size-to-vector-size stream)
1795                           :element-type '(unsigned-byte 8))))
1796  (read-sequence vector stream))
1797    </programlisting>
1798
1799    <para>Using a memory-mapped files has a result that is the same in
1800      that, like the above example, it returns a vector whose contents are
1801      the same as the contents of the file. It differs in that the above
1802      example creates a new vector in memory and copies the file's
1803      contents into it; using a memory-mapped file instead arranges for
1804      the vector's elements to point to the file's contents on disk
1805      directly, without copying them into memory first.</para>
1806
1807    <para>The vectors returned by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
1808      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> are read-only; any
1809      attempt to change an element of a vector returned by these
1810      functions results in a memory-access error. &CCL; does not
1811      currently support writing data to memory-mapped files.</para>
1812
1813    <para>Vectors created by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
1814      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> are required to
1815      respect &CCL;'s limit on the total size of an array. That means
1816      that you cannot use these functions to create a vector longer
1817      than <varname>ARRAY-TOTAL-SIZE-LIMIT</varname>, even if the filesystem
1818      supports file sizes that are larger. The value
1819      of <varname>ARRAY-TOTAL-SIZE-LIMIT</varname> is <varname>(EXPT 2 24)</varname>
1820      on 32-but platforms; and <varname>(EXPT 2 56)</varname> on 64-bit
1821      platforms.</para>
1822
1823    <para>
1824      <indexterm zone="map-file-to-ivector"/>
1825      <command><varname id="map-file-to-ivector">CCL:MAP-FILE-TO-IVECTOR</varname>
1826        <parameter>pathname</parameter>
1827        <parameter>element-type</parameter>
1828        [Function]</command>
1829    </para>
1830
1831    <variablelist>
1832      <varlistentry>
1833        <term><varname>pathname</varname></term>
1834        <listitem>
1835          <para>The pathname of the file to be memory-mapped.</para>
1836        </listitem>
1837      </varlistentry>
1838     
1839      <varlistentry>
1840        <term><varname>element-type</varname></term>
1841        <listitem>
1842          <para>The element-type of the vector to be
1843            created. Specified as
1844            a <glossterm linkend="type-specifier">type-specifier</glossterm>
1845            that names a subtype of either <varname>SIGNED-BYTE</varname>
1846            or <varname>UNSIGNED-BYTE</varname>.</para>
1847        </listitem>
1848      </varlistentry>
1849    </variablelist>
1850
1851
1852    <para>
1853      The <varname>map-file-to-ivector</varname> function tries to
1854      open the file at <parameter>pathname</parameter> for reading. If
1855      successful, the function maps the file's contents to a range of
1856      virtual addresses. If successful, it returns a read-only vector
1857      whose element-type is given
1858      by <parameter>element-type</parameter>, and whose contents are
1859      the contents of the memory-mapped file.
1860    </para>
1861
1862    <para>The returned vector is
1863      a <glossterm linkend="displaced-array">displaced-array</glossterm>
1864      whose element-type is <varname>(UPGRADED-ARRAY-ELEMENT-TYPE
1865        element-type)</varname>. The target of the displaced array is a
1866      vector of type <varname>(SIMPLE-ARRAY element-type (*))</varname> whose
1867      elements are the contents of the memory-mapped file.</para>
1868
1869    <para>Because of alignment issues, the mapped file's contents
1870      start a few bytes (4 bytes on 32-bit platforms, 8 bytes on
1871      64-bit platforms) into the vector. The displaced array returned
1872      by <varname>CCL:MAP-FILE-TO-IVECTOR</varname> hides this overhead, but
1873      it's usually more efficient to operate on the underlying simple
1874      1-dimensional array.  Given a displaced array (like the value
1875      returned by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>), the function
1876      <varname>ARRAY-DISPLACEMENT</varname> returns the underlying array and
1877      the displacement index in elements.
1878    </para>
1879
1880    <para>Currently, &CCL; supports only read operations on
1881      memory-mapped files. If you try to change the contents of an array
1882      returned by <varname>map-file-to-ivector</varname>, &CCL; signals
1883      a memory error.</para>
1884
1885    <para>
1886      <indexterm zone="unmap-ivector"/>
1887      <command><varname id="unmap-ivector">CCL:UNMAP-IVECTOR</varname>
1888        <parameter>displaced-array</parameter>
1889        [Function]</command>
1890    </para>
1891
1892    <para>If the argument is a displaced-array returned
1893      by <varname>map-file-to-ivector</varname>, and if it has not yet
1894      been unmapped by this function,
1895      then <varname>unmap-ivector</varname> undoes the memory mapping,
1896      closes the mapped file, and changes the displaced-array so that its
1897      target is an empty vector (of length zero).</para>
1898
1899    <para>
1900      <indexterm zone="map-file-to-octet-vector"/>
1901      <command><varname id="map-file-to-octet-vector">CCL:MAP-FILE-TO-OCTET-VECTOR</varname>
1902        <parameter>pathname</parameter>
1903        [Function]</command>
1904    </para>
1905
1906    <para>This function is a synonym for <varname>(CCL:MAP-FILE-TO-IVECTOR
1907        pathname '(UNSIGNED-BYTE 8))</varname> It is provided as a convenience
1908      for the common case of memory-mapping a file as a vector of
1909      bytes.</para>
1910
1911    <para>
1912      <indexterm zone="unmap-octet-vector"/>
1913      <command><varname id="unmap-octet-vector">CCL:UNMAP-OCTET-VECTOR</varname>
1914        <parameter>displaced-array</parameter>
1915        [Function]</command>
1916    </para>
1917
1918    <para>This function is a synonym
1919      for <varname>(CCL:UNMAP-IVECTOR)</varname></para>
1920  </sect1>
1921
1922  <!-- ============================================================ -->
1923  <sect1 id="Static_Variables">
1924    <title>Static Variables</title>
1925
1926    <para>&CCL; supports the definition
1927      of <glossterm linkend="static_variable">static
1928        variables</glossterm>, whose values are the same across threads,
1929      and which may not be dynamically bound. The value of a static
1930      variable is thus the same across all threads; changing the value
1931      in one thread changes it for all threads.</para> 
1932
1933    <para>Attempting to dynamically rebind a static variable (for
1934      instance, by using <varname>LET</varname>, or using the variable name as
1935      a parameter in a <varname>LAMBDA</varname> form) signals an
1936      error. Static variables are shared global resources; a dynamic
1937      binding is private to a single thread.</para>
1938
1939    <para>Static variables therefore provide a simple way to share
1940      mutable state across threads. They also provide a simple way to
1941      introduce race conditions and obscure bugs into your code, since
1942      every thread reads and writes the same instance of a given static
1943      variable. You must take care, therefore, in how you change the
1944      values of static variables, and use normal multithreaded
1945      programming techniques, such as locks or semaphores, to protect
1946      against race conditions.</para>
1947
1948    <para>In &CCL;, access to a static variable is usually faster than
1949      access to a special variable that has not been declared
1950      static.</para>
1951
1952    <para>
1953      <indexterm zone="defstatic"/>
1954      <command><varname id="defstatic">DEFSTATIC</varname>
1955        <parameter>var</parameter>
1956        <parameter>value</parameter>
1957        &key;
1958        <parameter>doc-string</parameter>
1959        [Macro]</command>
1960    </para>
1961   
1962    <variablelist>
1963      <varlistentry>
1964        <term><varname>var</varname></term>
1965        <listitem>
1966          <para>The name of the new static variable.</para>
1967        </listitem>
1968      </varlistentry>
1969     
1970      <varlistentry>
1971        <term><varname>value</varname></term>
1972        <listitem>
1973          <para>The initial value of the new static variable.</para>
1974        </listitem>
1975      </varlistentry>
1976     
1977      <varlistentry>
1978        <term><varname>doc-string</varname></term>
1979        <listitem>
1980          <para>A documentation string that is assigned to the new
1981            variable.</para>
1982        </listitem>
1983      </varlistentry>
1984    </variablelist>
1985
1986    <para>Proclaims the
1987      variable <glossterm linkend="special_variable">special</glossterm>,
1988      assigns the variable the supplied value, and assigns
1989      the <varname>doc-string</varname> to the
1990      variable's <varname>VARIABLE</varname> documentation. Marks the
1991      variable static, preventing any attempt to dynamically rebind
1992      it. Any attempt to dynamically rebind <varname>var</varname>
1993      signals an error.</para>
1994  </sect1>
1995
1996  <!-- ============================================================ -->
1997  <sect1 id="Saving-Applications">
1998    <title>Saving Applications</title>
1999    <indexterm zone="Saving-Applications">
2000      <primary>save-application</primary>
2001    </indexterm>
2002
2003    <para>&CCL; provides the
2004      function <literal>CCL:SAVE-APPLICATION</literal>, which creates a file
2005      containing an archived Lisp memory image.</para>
2006
2007    <para>&CCL; consists of a small executable called the
2008      Lisp <glossterm linkend="lisp_image">kernel</glossterm>, which
2009      implements the very lowest level features of the Lisp system, and
2010      an <glossterm linkend="lisp_image">image</glossterm>, which
2011      contains the in-memory representation of most of the Lisp system,
2012      including functions, data structures, variables, and so on. When
2013      you start &CCL;, you are launching the kernel, which then locates
2014      and reads an image file, restoring the archived image in
2015      memory. Once the image is fully restored, the Lisp system is
2016      running.</para>
2017
2018    <para>Using <literal>CCL:SAVE-APPLICATION</literal>, you can create a
2019      file that contains a modified image, one that includes any changes
2020      you've made to the running Lisp system. If you later pass your
2021      image file to the &CCL; kernel as a command-line parameter, it
2022      then loads your image file instead of its default one, and &CCL;
2023      starts up with your modifications.</para>
2024
2025    <para>If this scenario seems to you like a convenient way to
2026      create an application, that's just as intended. You can create an
2027      application by modifying the running Lisp until it does what you
2028      want, then use <literal>CCL:SAVE-APPLICATION</literal> to preserve your
2029      changes and later load them for use.</para>
2030
2031    <para>In fact, you can go further than that. You can replace
2032      &CCL;'s <glossterm linkend="toplevel_function">toplevel
2033        function</glossterm> with your own, and then, when the image is
2034      loaded, the Lisp system immediately performs your tasks rather
2035      than the default tasks that make it a Lisp development system. If
2036      you save an image in which you have done this, the resulting Lisp
2037      system is your tool rather than a Lisp development system.</para>
2038
2039    <para>You can go a step further still. You can
2040      tell <literal>CCL:SAVE-APPLICATION</literal> to prepend the Lisp kernel
2041      to the image file. Doing this makes the resulting image into a
2042      self-contained executable binary. When you run the resulting file,
2043      the Lisp kernel immediately loads the attached image file and runs
2044      your saved system. The Lisp system that starts up can have any
2045      behavior you choose. It can be a Lisp development system, but with
2046      your customizations; or it can immediately perform some task of
2047      your design, making it a specialized tool rather than a general
2048      development system.</para>
2049
2050    <para>In other words, you can develop any application you like by
2051      interactively modifying &CCL; until it does what you want, then
2052      using <literal>CCL:SAVE-APPLICATION</literal> to preserve your changes
2053      in an executable image.</para>
2054
2055    <para>On Mac OS X,
2056      the <link linkend="application_builder">application builder</link>
2057      uses <literal>CCL:SAVE-APPLICATION</literal> to create the executable
2058      portion of the <glossterm linkend="application_bundle">application
2059        bundle</glossterm>. Double-clicking the application bundle runs
2060      the executable image created
2061      by <literal>CCL:SAVE-APPLICATION</literal>.</para>
2062
2063    <para>Also on Mac OS X, &CCL; supports an object type
2064      called <literal>MACPTR</literal>, which is the type of pointers into the
2065      foreign (Mac OS) heap. Examples of
2066      commonly-user <literal>MACPTR</literal> objects are Cocoa windows and
2067      other dynamically-allocated Mac OS system objects.</para>
2068
2069    <para>Because a <literal>MACPTR</literal> object is a pointer into a
2070      foreign heap that exists for the lifetime of the running Lisp
2071      process, and because a saved image is used by loading it into a
2072      brand new Lisp process, saved <literal>MACPTR</literal> objects cannot
2073      be relied on to point to the same things when reconstituted from a
2074      saved image. In fact, a restored <literal>MACPTR</literal> object might
2075      point to anything at all&mdash;for example an arbitrary location
2076      in the middle of a block of code, or a completely nonexistent
2077      virtual address.</para> 
2078
2079    <para>For that reason, <literal>CCL:SAVE-APPLICATION</literal> converts
2080      all <literal>MACPTR</literal> objects to <literal>DEAD-MACPTR</literal>
2081      objects when writing them to an image
2082      file. A <literal>DEAD-MACPTR</literal> is functionally identical to
2083      a <literal>MACPTR</literal>, except that code that operates
2084      on <literal>MACPTR</literal> objects distinguishes them
2085      from <literal>DEAD-MACPTR</literal> objects and can handle them
2086      appropriately&mdash;signaling errors, for example.</para>
2087
2088    <para>As of &CCL; 1.2, there is one exception to the conversion
2089      of <literal>MACPTR</literal> to <literal>DEAD-MACPTR</literal> objects:
2090      a <literal>MACPTR</literal> object that points to the address 0 is not
2091      converted, because address 0 can always be relied upon to refer to
2092      the same thing.</para>
2093
2094        <indexterm zone="Saving-Applications">
2095          <primary>+NULL-PTR+</primary>
2096        </indexterm>
2097    <para>As of &CCL; 1.2, the constant <literal>CCL:+NULL-PTR+</literal>
2098      refers to a <literal>MACPTR</literal> object that points to address 0.</para>
2099
2100    <para>On all supported platforms, you can
2101      use <literal>CCL:SAVE-APPLICATION</literal> to create a command-line
2102      tool that runs the same way any command-line program
2103      does. Alternatively, if you choose not to prepend the kernel, you
2104      can save an image and then later run it by passing it as a
2105      command-line parameter to the <literal>ccl</literal>
2106      or <literal>ccl64</literal> script.</para>
2107
2108    <para>
2109      <indexterm zone="save-application"/>
2110      <command><varname id="save-application">SAVE-APPLICATION</varname>
2111        <parameter>filename</parameter>
2112        &key;
2113        <parameter>toplevel-function</parameter>
2114        <parameter>init-file</parameter>
2115        <parameter>error-handler</parameter>
2116        <parameter>application-class</parameter>
2117        <parameter>clear-clos-caches</parameter>
2118        <parameter>(purify t)</parameter>
2119        <parameter>impurify</parameter>
2120        <parameter>(mode #o644)</parameter>
2121        <parameter>prepend-kernel</parameter>
2122        <parameter>native</parameter>
2123        [Function]</command>
2124    </para>
2125   
2126    <variablelist>
2127      <varlistentry>
2128        <term><varname>filename</varname></term>
2129        <listitem>
2130          <para>The pathname of the file to be created when &CCL;
2131            saves the application.</para>
2132        </listitem>
2133      </varlistentry>
2134     
2135      <varlistentry>
2136        <term><varname>toplevel-function</varname></term>
2137        <listitem>
2138          <para>The function to be executed after startup is
2139            complete. The toplevel is a function of no arguments that
2140            performs whatever actions the lisp system should perform
2141            when launched with this image.</para>
2142          <para>If this parameter is not supplied, &CCL; uses its
2143            default toplevel. The default toplevel runs
2144            the <glossterm linkend="REPL">read-eval-print
2145              loop</glossterm>.</para>
2146        </listitem>
2147      </varlistentry>
2148
2149      <varlistentry>
2150        <term><varname>init-file</varname></term>
2151        <listitem>
2152          <para>The pathname of a Lisp file to be loaded when the
2153            image starts up. You can place initialization expressions in
2154            this file, and use it to customize the behavior of the Lisp
2155            system when it starts up.</para>
2156        </listitem>
2157      </varlistentry>
2158     
2159      <varlistentry>
2160        <term><varname>error-handler</varname></term>
2161        <listitem>
2162          <para>The error-handling mode for the saved image. The
2163            supplied value determines what happens when an error is not
2164            handled by the saved image. Valid values
2165            are <literal>:quit</literal> (Lisp exits with an error
2166            message); <literal>:quit-quietly</literal> (Lisp exits without an
2167            error message); or <literal>:listener</literal> (Lisp enters a
2168            break loop, enabling you to debug the problem by interacting
2169            in a listener). If you don't supply this parameter, the
2170            saved image uses the default error handler
2171            (<literal>:listener</literal>).</para>
2172        </listitem>
2173      </varlistentry>
2174
2175      <varlistentry>
2176        <term><varname>application-class</varname></term>
2177        <listitem>
2178          <para>The CLOS class that represents the saved Lisp
2179            application. Normally you don't need to supply this
2180            parameter; <literal>CCL:SAVE-APPLICATION</literal> uses the
2181            class <literal>CCL:LISP-DEVELOPMENT-SYSTEM</literal>. In some
2182            cases you may choose to create a custom application class;
2183            in that case, pass the name of the class as the value for
2184            this parameter.</para>
2185        </listitem>
2186      </varlistentry>
2187     
2188      <varlistentry>
2189        <term><varname>clear-clos-caches</varname></term>
2190        <listitem>
2191          <para>If true, ensures that CLOS caches are emptied before
2192            saving the image. Normally you don't need to supply this
2193            parameter, but if for some reason you want to ensure the
2194            CLOS caches are clear when the image starts up, you can pass
2195            any true value.</para>
2196        </listitem>
2197     </varlistentry>
2198     <varlistentry>
2199        <term><varname>purify</varname></term>
2200        <listitem>
2201          <para>
2202            When true, calls (in effect) <code>purify</code> before
2203            saving the heap image.  This moves certain objects that
2204            are unlikely to become garbage to a special memory area
2205            that is not scanned by the GC (since it is expected that
2206            the GC wouldn't find anything to collect).
2207         </para>
2208      </listitem>
2209      </varlistentry>
2210
2211     <varlistentry>
2212        <term><varname>impurify</varname></term>
2213        <listitem>
2214          <para>
2215            If true, calls (in effect) <code>impurify</code> before
2216            saving the heap image.  (If both <literal>:impurify</literal>
2217            and <literal>:purify</literal> are true, first
2218            <code>impurify</code> is done, and then <code>purify</code>.)
2219         </para>
2220         <para>
2221           <code>impurify</code> moves objects in certain special memory
2222           areas into the regular dynamic heap, where they will be scanned
2223           by the GC.
2224         </para>
2225      </listitem>
2226      </varlistentry>
2227
2228     <varlistentry>
2229        <term><varname>mode</varname></term>
2230        <listitem>
2231          <para>
2232            A number specifying the mode (permission bits) of the output file.
2233          </para>
2234      </listitem>
2235      </varlistentry>
2236
2237     <varlistentry>
2238        <term><varname>prepend-kernel</varname></term>
2239        <listitem>
2240          <para>Specifies the file to prepend to the saved heap
2241          image.  A value of <literal>t</literal> means to prepend
2242          the lisp kernel binary that the lisp started with.
2243          Otherwise, the value of <literal>:prepend-kernel</literal>
2244          should be a pathname designator for the file to be
2245          prepended.
2246         </para>
2247         <para>
2248           If the prepended file is execuatable, its execute
2249           mode bits will be copied to the output file.
2250         </para>
2251         <para>
2252           This argument can be used to prepend any kind of file to
2253           the saved heap image.  This can be useful in some special
2254           cases.
2255         </para>           
2256      </listitem>
2257      </varlistentry>
2258     <varlistentry>
2259        <term><varname>native</varname></term>
2260        <listitem>
2261          <para>If true, saves the image as a native (ELF, Mach-O, PE)
2262          shared library.  (On platforms where this isn't yet supported,
2263          a warning is issued and the option is ignored.)
2264         </para>
2265      </listitem>
2266      </varlistentry>
2267     
2268     
2269    </variablelist>
2270
2271    <para></para>
2272  </sect1>
2273
2274  <sect1 id="concatenating-fasl-files">
2275    <title>Concatenating FASL Files</title>
2276    <para>
2277      Multiple fasl files can be concatenated into a single file.
2278    </para>
2279  <refentry id="f_fasl-concatenate">
2280    <indexterm zone="f_fasl-concatenate">
2281      <primary>fasl-concatenate</primary>
2282    </indexterm>
2283
2284    <refnamediv>
2285      <refname>FASL-CONCATENATE</refname>
2286      <refpurpose>
2287        Concatenate several fasl files, producing a single output file.
2288      </refpurpose>
2289      <refclass>Function</refclass>
2290    </refnamediv>
2291   
2292    <refsynopsisdiv>
2293      <synopsis><function>fasl-concatenate</function> out-file fasl-files &key; (:if-exists :error)</synopsis>
2294    </refsynopsisdiv>
2295
2296    <refsect1>
2297      <title>Arguments and Values</title>
2298      <variablelist>
2299        <varlistentry>
2300          <term>out-file</term>
2301          <listitem>
2302            <para>
2303              Name of the file in which to store the concatenation.
2304            </para>
2305          </listitem>
2306        </varlistentry>
2307        <varlistentry>
2308          <term>fasl-files</term>
2309          <listitem>
2310            <para>
2311              List of names of fasl files to concatenate.
2312            </para>
2313          </listitem>
2314        </varlistentry>
2315        <varlistentry>
2316          <term>:if-exists</term>
2317          <listitem>
2318            <para>
2319              As for <function>OPEN</function>, defaults to <literal>
2320              :error</literal>
2321            </para>
2322          </listitem>
2323        </varlistentry>
2324      </variablelist>
2325    </refsect1>
2326   
2327    <refsect1>
2328      <title>Description</title>
2329      <para>
2330        Creates a fasl file which, when loaded, will have the same
2331        effect as loading the individual input fasl files in the
2332        specified order.  The single file might be easier to
2333        distribute or install, and loading it may be at least a little
2334        faster than loading the individual files (since it avoids the
2335        overhead of opening and closing each file in succession.)
2336      </para>
2337      <para>
2338        The PATHNAME-TYPE of the output file and of each input file
2339        defaults to the current platform's fasl file type (.dx64fsl or
2340        whatever.)  If any of the input files has a different
2341        type/extension an error will be signaled, but it doesn't
2342        otherwise try too hard to verify that the input files are real
2343        fasl files for the current platform.
2344      </para>
2345    </refsect1>
2346  </refentry>
2347  </sect1>
2348  <sect1 id="floating-point">
2349    <title>Floating Point Numbers</title>
2350
2351    <para>
2352      In &CCL;, the Common Lisp types short-float and single-float are
2353      implemented as IEEE single precision values; double-float and
2354      long-float are IEEE double precision values.  On 64-bit
2355      platforms, single-floats are immediate values (like fixnums and
2356      characters).
2357    </para>
2358
2359  <para>
2360    Floating-point exceptions are generally enabled and detected.  By
2361    default, threads start up with overflow, division-by-zero, and
2362    invalid enabled, and the rounding mode is set to nearest. The
2363    functions <varname>SET-FPU-MODE</varname> and
2364    <varname>GET-FPU-MODE</varname> provide user control over
2365    floating-point behavior.
2366  </para>
2367
2368  <refentry id="f_get-fpu-mode">
2369    <indexterm zone="f_get-fpu-mode">
2370      <primary>get-fpu-mode</primary>
2371    </indexterm>
2372
2373    <refnamediv>
2374      <refname>GET-FPU-MODE</refname>
2375      <refpurpose>
2376        Return the state of exception-enable and rounding-mode control
2377        flags for the current thread.
2378      </refpurpose>
2379      <refclass>Function</refclass>
2380    </refnamediv>
2381   
2382    <refsynopsisdiv>
2383      <synopsis><function>get-fpu-mode</function> &optional; mode</synopsis>
2384    </refsynopsisdiv>
2385
2386    <refsect1>
2387      <title>Arguments and Values</title>
2388      <variablelist>
2389        <varlistentry>
2390          <term>mode</term>
2391          <listitem>
2392            <para>
2393              One of the keywords :rounding-mode, :overflow,
2394              :underflow, :division-by-zero, :invalid, :inexact.
2395            </para>
2396          </listitem>
2397        </varlistentry>
2398      </variablelist>
2399    </refsect1>
2400   
2401    <refsect1>
2402      <title>Description</title>
2403      <para>
2404        If <varname>mode</varname> is supplied, returns the value of
2405        the corresponding control flag for the current thread.
2406      </para>
2407      <para>
2408        Otherwise, returns a list of keyword/value pairs which
2409        describe the floating-point exception-enable and rounding-mode
2410        control flags for the current thread.
2411      </para>
2412      <variablelist>
2413        <varlistentry>
2414          <term>rounding-mode</term>
2415          <listitem>
2416            <para>
2417              One of :nearest, :zero, :positive, :negative
2418            </para>
2419          </listitem>
2420        </varlistentry>
2421        <varlistentry>
2422          <term>overflow, underflow, division-by-zero, invalid, inexact
2423          </term>
2424          <listitem>
2425            <para>
2426              If true, the floating-point exception is signaled.
2427              If NIL, it is masked.
2428            </para>
2429          </listitem>
2430        </varlistentry>
2431      </variablelist>
2432    </refsect1>
2433  </refentry>
2434
2435  <refentry id="f_set-fpu-mode">
2436    <indexterm zone="f_set-fpu-mode">
2437      <primary>set-fpu-mode</primary>
2438    </indexterm>
2439
2440    <refnamediv>
2441      <refname>SET-FPU-MODE</refname>
2442      <refpurpose>
2443        Set the state of exception-enable and rounding-mode control
2444        flags for the current thread.
2445      </refpurpose>
2446      <refclass>Function</refclass>
2447    </refnamediv>
2448   
2449    <refsynopsisdiv>
2450      <synopsis><function>set-fpu-mode</function> &key;
2451      rounding-mode overflow underflow division-by-zero
2452      invalid inexact</synopsis>
2453    </refsynopsisdiv>
2454
2455    <refsect1>
2456      <title>Arguments and Values</title>
2457      <variablelist>
2458        <varlistentry>
2459          <term>rounding-mode</term>
2460          <listitem>
2461            <para>
2462              If supplied, must be one of :nearest, :zero, :positive, or
2463              :negative.
2464            </para>
2465          </listitem>
2466        </varlistentry>
2467        <varlistentry>
2468          <term>overflow, underflow, division-by-zero, invalid, inexact</term>
2469          <listitem>
2470            <para>NIL to mask the exception, T to signal it.</para>
2471          </listitem>
2472        </varlistentry>
2473      </variablelist>
2474    </refsect1>
2475   
2476    <refsect1>
2477      <title>Description</title>
2478      <para>
2479        Sets the current thread's exception-enable and rounding-mode
2480        control flags to the indicated values for arguments that are
2481        supplied, and preserves the values assoicated with those
2482        that aren't supplied.
2483      </para>
2484    </refsect1>
2485  </refentry>
2486  </sect1>
2487
2488  <sect1 id="watched-objects"><title>Watched Objects</title>
2489  <para>
2490    As of release 1.4, Clozure CL provides a way for lisp objects to
2491    be watched so that a condition will be signaled when a thread
2492    attempts to write to the watched object. For a certain class of
2493    bugs (someone is changing this value, but I don't know who), this
2494    can be extremely helpful.
2495  </para>
2496  <sect2 id="watched-watch"><title>WATCH</title>
2497  <refentry id="f_watch">
2498    <indexterm zone="f_watch">
2499      <primary>watch</primary>
2500    </indexterm>
2501   
2502    <refnamediv>
2503      <refname>WATCH</refname>
2504      <refpurpose>
2505        Monitor a lisp object for writes.
2506      </refpurpose>
2507      <refclass>Function</refclass>
2508    </refnamediv>
2509   
2510    <refsynopsisdiv>
2511      <synopsis><function>watch</function> &optional; object</synopsis>
2512    </refsynopsisdiv>
2513   
2514    <refsect1>
2515      <title>Arguments and Values</title>
2516      <variablelist>
2517        <varlistentry>
2518          <term>object</term>
2519          <listitem>
2520            <para>
2521              Any memory-allocated lisp object.
2522            </para>
2523          </listitem>
2524        </varlistentry>
2525      </variablelist>
2526    </refsect1>
2527
2528    <refsect1>
2529      <title>Description</title>
2530      <para>
2531        The WATCH function arranges for the specified object to be
2532        monitored for writes. This is accomplished by copying the
2533        object to its own set of virtual memory pages, which are then
2534        write-protected. This protection is enforced by the computer's
2535        memory-management hardware; the write-protection does not slow
2536        down reads at all.
2537      </para>
2538      <para>
2539        When any write to the object is attempted, a
2540        WRITE-TO-WATCHED-OBJECT condition will be signaled.
2541      </para>
2542      <para>
2543        When called with no arguments, WATCH returns a freshly-consed
2544        list of the objects currently being watched.
2545      </para>
2546      <para>
2547        WATCH returns NIL if the object cannot be watched (typically
2548        because the object is in a static or pure memory area).
2549      </para>
2550    </refsect1>
2551    <refsect1 id="watch-dwim"><title>DWIM</title>
2552    <para>
2553      WATCH operates at a fairly low level; it is not possible to
2554      avoid the details of the internal representation of objects.
2555      Nevertheless, as a convenience, WATCHing a standard-instance,
2556      a hash-table, or a multi-dimensional or non-simple CL array
2557      will watch the underlying slot-vector, hash-table-vector, or
2558      data-vector, respectively.
2559      </para>
2560    </refsect1>
2561    <refsect1 id="watch-discuss"><title>Discussion</title>
2562    <para>
2563      WATCH can monitor any memory-allocated lisp object.
2564    </para>
2565    <para>
2566      In Clozure CL, a memory-allocated object is either a cons cell
2567      or a uvector.
2568    </para>
2569    <para>
2570      WATCH operates on cons cells, not lists. In order to watch a
2571      chain of cons cells, each cons cell must be watched
2572      individually. Because each watched cons cell takes up its own
2573      own virtual memory page (4 Kbytes), it's only feasible to watch
2574      relatively short lists.
2575    </para>
2576    <para>
2577      If a memory-allocated object isn't a cons cell, then it is a
2578      vector-like object called a uvector. A uvector is a
2579      memory-allocated lisp object whose first word is a header that
2580      describes the object's type and the number of elements that it
2581      contains.
2582    </para>
2583    <para>
2584      So, a hash table is a uvector, as is a string, a standard
2585      instance, a double-float, a CL array or vector, and so forth.
2586    </para>
2587    <para>
2588      Some CL objects, like strings and other simple vectors, map in a
2589      straightforward way onto the uvector representation. It is easy
2590      to understand what happens in such cases. The uvector index
2591      corresponds directly to the vector index:
2592    </para>
2593    <programlisting>
2594<![CDATA[
2595? (defvar *s* "xxxxx")
2596*S*
2597? (watch *s*)
2598"xxxxx"
2599? (setf (char *s* 3) #\o)
2600> Error: Write to watched uvector "xxxxx" at index 3
2601>        Faulting instruction: (movl (% eax) (@ -5 (% r15) (% rcx)))
2602> While executing: SET-CHAR, in process listener(1).
2603> Type :POP to abort, :R for a list of available restarts.
2604> Type :? for other options.
2605]]>
2606    </programlisting>
2607    <para>
2608      In the case of more complicated objects (e.g., a hash-table, a
2609      standard-instance, a package, etc.), the elements of the uvector
2610      are like slots in a structure. It's necessary to know which one
2611      of those "slots" contains the data that will be changed when the
2612      object is written to.
2613    </para>
2614    <para>
2615      As mentioned above, watch knows about arrays, hash-tables, and
2616      standard-instances, and will automatically watch the appropriate
2617      data-containing element.
2618    </para>
2619    <para>
2620      An example might make this clearer.
2621    </para>
2622    <programlisting>
2623<![CDATA[
2624? (defclass foo ()
2625    (slot-a slot-b slot-c))
2626#<STANDARD-CLASS FOO>
2627? (defvar *a-foo* (make-instance 'foo))
2628*A-FOO*
2629? (watch *a-foo*)
2630#<SLOT-VECTOR #xDB00D>
2631;;; Note that WATCH has watched the internal slot-vector object
2632? (setf (slot-value *a-foo* 'slot-a) 'foo)
2633> Error: Write to watched uvector #<SLOT-VECTOR #xDB00D> at index 1
2634>        Faulting instruction: (movq (% rsi) (@ -5 (% r8) (% rdi)))
2635> While executing: %MAYBE-STD-SETF-SLOT-VALUE-USING-CLASS, in process listener(1).
2636> Type :POP to abort, :R for a list of available restarts.
2637> Type :? for other options.
2638]]>
2639    </programlisting>
2640    <para>
2641      Looking at a backtrace would presumably show what object and
2642      slot name were written.
2643    </para>
2644    <para>
2645      Note that even though the write was to slot-a, the uvector index
2646      was 1 (not 0). This is because the first element of a
2647      slot-vector is a pointer to the instance that owns the slots. We
2648      can retrieve that to look at the object that was modified:
2649    </para>
2650    <programlisting>
2651<![CDATA[
26521 > (uvref (write-to-watched-object-object *break-condition*) 0)
2653#<FOO #x30004113502D>
26541 > (describe *)
2655#<FOO #x30004113502D>
2656Class: #<STANDARD-CLASS FOO>
2657Wrapper: #<CLASS-WRAPPER FOO #x300041135EBD>
2658Instance slots
2659SLOT-A: #<Unbound>
2660SLOT-B: #<Unbound>
2661SLOT-C: #<Unbound>
26621 >
2663]]> 
2664    </programlisting>
2665    </refsect1>
2666  </refentry>
2667</sect2>
2668<sect2 id="watched-unwatch"><title>UNWATCH</title>
2669<refentry id="f_unwatch">
2670  <indexterm zone="f_unwatch">
2671    <primary>unwatch</primary>
2672  </indexterm>
2673 
2674  <refnamediv>
2675    <refname>UNWATCH</refname>
2676      <refpurpose>
2677        Stop monitoring a lisp object for writes.
2678      </refpurpose>
2679      <refclass>Function</refclass>
2680  </refnamediv>
2681 
2682  <refsynopsisdiv>
2683    <synopsis><function>unwatch</function> object</synopsis>
2684  </refsynopsisdiv>
2685 
2686  <refsect1><title>Description</title>
2687  <para>
2688    The UNWATCH function ensures that the specified object is in
2689    normal, non-monitored memory. If the object is not currently
2690    being watched, UNWATCH does nothing and returns NIL. Otherwise,
2691    the newly unwatched object is returned.
2692  </para>
2693  </refsect1>
2694</refentry>
2695</sect2>
2696<sect2 id="watched-write-to-watched-object">
2697  <title>WRITE-TO-WATCHED-OBJECT</title>
2698  <refentry id="c_write-to-watched-object">
2699    <indexterm zone="c_write-to-watched-object">
2700      <primary>write-to-watched-object</primary>
2701    </indexterm>
2702   
2703    <refnamediv>
2704      <refname>WRITE-TO-WATCHED-OBJECT</refname>
2705      <refpurpose>
2706        Condition signaled when a write to a watched object is attempted.
2707      </refpurpose>
2708      <refclass>Condition</refclass>
2709    </refnamediv>
2710
2711    <refsect1><title>Discussion</title>
2712    <para>
2713      This condition is signaled when a watched object is written
2714      to. There are three slots of interest:
2715    </para>
2716    <variablelist>
2717      <varlistentry>
2718        <term>object</term>
2719        <listitem>
2720          <para>
2721            The actual object that was the destination of the write.
2722          </para>
2723        </listitem>
2724      </varlistentry>
2725      <varlistentry>
2726        <term>offset</term>
2727        <listitem>
2728          <para>
2729            The byte offset from the tagged object pointer to the
2730            address of the write.
2731          </para>
2732        </listitem>
2733      </varlistentry>
2734      <varlistentry>
2735        <term>instruction</term>
2736        <listitem>
2737          <para>
2738            The disassembled machine instruction that attempted the write.
2739          </para>
2740        </listitem>
2741      </varlistentry>
2742    </variablelist>
2743    </refsect1>
2744
2745    <refsect1><title>Restarts</title>
2746    <para>
2747      A few restarts are provided: one will skip over the faulting
2748      write instruction and proceed; another offers to unwatch the
2749      object and continue.
2750    </para>
2751    <para>
2752      There is also an emulate restart. In some common cases, the
2753      faulting write instruction can be emulated, enabling the write
2754      to be performed without having to unwatch the object (and
2755      therefore let other threads potentially write to it). If the
2756      faulting instruction isn't recognized, the emulate restart will
2757      not be offered.
2758    </para>
2759    </refsect1>
2760  </refentry>
2761</sect2>
2762<sect2 id="watch-notes"><title>Notes</title>
2763<para>
2764  Although some care has been taken to minimize potential problems
2765  arising from watching and unwatching objects from multiple
2766  threads, there may well be subtle race conditions present that
2767  could cause bad behavior.
2768</para>
2769<para>
2770  For example, suppose that a thread attempts to write to a watched
2771  object. This causes the operating system to generate an
2772  exception. The lisp kernel figures out what the exception is, and
2773  calls back into lisp to signal the write-to-watched-object
2774  condition and perhaps handle the error.
2775</para>
2776<para>
2777  Now, as soon lisp code starts running again (for the callback),
2778  it's possible that some other thread could unwatch the very
2779  watched object that caused the exception, perhaps before we even
2780  have a chance to signal the condition, much less respond to it.
2781</para>
2782<para>
2783  Having the object unwatched out from underneath a handler may at
2784  least confuse it, if not cause deeper trouble. Use caution with
2785  unwatch.
2786</para>
2787</sect2>
2788<sect2 id="watch-examples"><title>Examples</title>
2789<para>
2790  Here are a couple more examples in addition to the above examples
2791  of watching a string and a standard-instance.
2792</para>
2793<sect3><title>Fancy arrays</title>
2794<programlisting>
2795?  (defvar *f* (make-array '(2 3) :element-type 'double-float))
2796*F*
2797? (watch *f*)
2798#(0.0D0 0.0D0 0.0D0 0.0D0 0.0D0 0.0D0)
2799;;; Note that the above vector is the underlying data-vector for the array
2800? (setf (aref *f* 1 2) pi)
2801> Error: Write to watched uvector #&lt;VECTOR 6 type DOUBLE-FLOAT, simple> at index 5
2802>        Faulting instruction: (movq (% rax) (@ -5 (% r8) (% rdi)))
2803> While executing: ASET, in process listener(1).
2804> Type :POP to abort, :R for a list of available restarts.
2805> Type :? for other options.
28061 >
2807  </programlisting>
2808  <para>
2809    In this case, uvector index in the report is the row-major index
2810    of the element that was written to.
2811  </para>
2812  </sect3>
2813  <sect3><title>Hash tables</title>
2814  <para>
2815    Hash tables are surprisingly complicated. The representation of a
2816    hash table includes an element called a hash-table-vector. The
2817    keys and values of the elements are stored pairwise in this
2818    vector.
2819  </para>
2820  <para>
2821    One problem with trying to monitor hash tables for writes is that
2822    the underlying hash-table-vector is replaced with an entirely new
2823    one when the hash table is rehashed. A previously-watched
2824    hash-table-vector will not be the used by the hash table after
2825    rehashing, and writes to the new vector will not be caught.
2826  </para>
2827  <programlisting>
2828? (defvar *h* (make-hash-table))
2829*H*
2830? (setf (gethash 'noise *h*) 'feep)
2831FEEP
2832? (watch *h*)
2833#&lt;HASH-TABLE-VECTOR #xDD00D>
2834;;; underlying hash-table-vector
2835? (setf (gethash 'noise *h*) 'ding)
2836> Error: Write to watched uvector #&lt;HASH-TABLE-VECTOR #xDD00D> at index 35
2837>        Faulting instruction: (lock)
2838>          (cmpxchgq (% rsi) (@ (% r8) (% rdx)))
2839> While executing: %STORE-NODE-CONDITIONAL, in process listener(1).
2840> Type :POP to abort, :R for a list of available restarts.
2841> Type :? for other options.
2842;;; see what value is being replaced...
28431 > (uvref (write-to-watched-object-object *break-condition*) 35)
2844FEEP
2845;;; backtrace shows useful context
28461 > :b
2847*(1A109F8) : 0 (%STORE-NODE-CONDITIONAL ???) NIL
2848 (1A10A50) : 1 (LOCK-FREE-PUTHASH NOISE #&lt;HASH-TABLE :TEST EQL size 1/60 #x30004117D47D> DING) 653
2849 (1A10AC8) : 2 (CALL-CHECK-REGS PUTHASH NOISE #&lt;HASH-TABLE :TEST EQL size 1/60 #x30004117D47D> DING) 229
2850 (1A10B00) : 3 (TOPLEVEL-EVAL (SETF (GETHASH # *H*) 'DING) NIL) 709
2851 ...
2852  </programlisting>
2853  </sect3>
2854  <sect3><title>Lists</title>
2855  <para>
2856    As previously mentioned, WATCH only watches individual cons cells.
2857  </para>
2858  <programlisting>
2859? (defun watch-list (list)
2860    (maplist #'watch list))
2861WATCH-LIST
2862? (defvar *l* (list 1 2 3))
2863*L*
2864? (watch-list *l*)
2865((1 2 3) (2 3) (3))
2866? (setf (nth 2 *l*) 'foo)
2867> Error: Write to the CAR of watched cons cell (3)
2868>        Faulting instruction: (movq (% rsi) (@ 5 (% rdi)))
2869> While executing: %SETNTH, in process listener(1).
2870> Type :POP to abort, :R for a list of available restarts.
2871> Type :? for other options.
2872  </programlisting>
2873  </sect3>
2874  </sect2>
2875</sect1>
2876
2877<sect1 id="code-coverage"><title>Code Coverage</title>
2878<sect2 id="code-coverage-overview"><title>Overview</title>
2879<para>
2880  In Clozure CL 1.4 and later, code coverage provides information
2881  about which paths through generated code have been executed and
2882  which haven't. For each source form, it can report one of three
2883  possible outcomes:
2884</para>
2885<itemizedlist>
2886  <listitem>
2887    <para>
2888      Not covered: this form was never entered.
2889    </para>
2890  </listitem>
2891  <listitem>
2892    <para>
2893      Partly covered: This form was entered, and some parts were
2894      executed and some weren't.
2895    </para>
2896  </listitem>
2897  <listitem>
2898    <para>
2899      Fully covered: Every bit of code generated from this form was
2900      executed.
2901    </para>
2902  </listitem>
2903</itemizedlist>
2904</sect2>
2905
2906<sect2 id="code-coverage-limitations"><title>Limitations</title>
2907<para>
2908  While the information gathered for coverage of generated code is
2909  complete and precise, the mapping back to source forms is of
2910  necessity heuristic, and depends a great deal on the behavior of
2911  macros and the path of the source forms through compiler
2912  transforms. Source information is not recorded for variables, which
2913  further limits the source mapping. In practice, there is often
2914  enough information scattered about a partially covered function to
2915  figure out which logical path through the code was taken and which
2916  wasn't. If that doesn't work, you can try disassembling to see which
2917  parts of the compiled code were not executed: in the disassembled
2918  code there will be references to #&lt;CODE-NOTE [xxx] ...> where xxx
2919  is NIL if the code that follows was never executed and non-NIL if it
2920  was.
2921</para>
2922<para>
2923  Sometimes the situation can be improved by modifying macros to try
2924  to preserve more of the input forms, rather than destructuring and
2925  rebuilding them.
2926</para>
2927<para>
2928  Because the code coverage information is associated with compiled
2929  functions, code coverage information is not available for load-time toplevel
2930  expressions.  You can work around this by creating a function and calling
2931  it. I.e. instead of
2932  <programlisting>
2933(progn
2934  (do-this)
2935  (setq that ...) ...))</programlisting>
2936  do:
2937  <programlisting>
2938(defun init-this-and-that ()
2939  (do-this)
2940  (setq that ...)  ...)
2941(init-this-and-that)</programlisting>
2942
2943Then you can see the coverage information in the definition of
2944<literal>init-this-and-that</literal>.
2945</para>
2946</sect2>
2947
2948<sect2 id="code-coverage-usage"><title>Usage</title>
2949<para>
2950  In order to gather code coverage information, you first have to
2951  recompile all your code to include code coverage
2952  instrumentation. Compiling files will generate code coverage
2953  instrumentation if <literal>CCL:*COMPILE-CODE-COVERAGE*</literal>
2954  is true:
2955  <programlisting>
2956(setq ccl:*compile-code-coverage* t)
2957(recompile-all-your-files)</programlisting>
2958</para>
2959<para>
2960  The compilation process will be many times slower than normal, and
2961  the fasl files will be many times bigger.
2962</para>
2963<para>
2964  When you execute functions loaded from instrumented fasl files, they
2965  will record coverage information every time they are executed.
2966  You can examine that information by calling <literal>ccl:report-coverage</literal>
2967  or <literal>ccl:coverage-statistics</literal>.
2968</para>
2969 <para>
2970   While recording coverage, you can collect incremental coverage deltas between any two points
2971   in time.  You might do this while running a test suite, to record the coverage for
2972   each test, for example:
2973  <programlisting>
2974(ccl:reset-incremental-coverage)
2975(loop with coverage = (make-hash-table)
2976      for test in (tests-to-run)
2977      do (run-test test)
2978      do (setf (gethash test coverage) (ccl:get-incremental-coverage))
2979      finally (return coverage))</programlisting>creates a hash table mapping a test to a representation of all coverage recorded while running the
2980   test.  This hash table can then be passed to <literal>ccl:incremental-coverage-svn-matches</literal>
2981   or <literal>ccl:incremental-coverage-source-matches</literal>.
2982</para>
2983</sect2>
2984
2985<sect2 id="code-coverage-functions-and-variables"><title>Functions and Variables</title>
2986<para>
2987  The following functions can be used to manage the coverage data:
2988</para>
2989
2990<refentry id="f_report-coverage">
2991  <indexterm zone="f_report-coverage">
2992    <primary>report-coverage</primary>
2993  </indexterm>
2994 
2995  <refnamediv>
2996    <refname>REPORT-COVERAGE</refname>
2997    <refpurpose>Generate a code coverage report</refpurpose>
2998    <refclass>Function</refclass>
2999  </refnamediv>
3000
3001  <refsynopsisdiv>
3002    <synopsis><function>report-coverage</function> output-file &key;
3003    (external-format :default) (statistics t) (html t)
3004    </synopsis>
3005  </refsynopsisdiv>
3006
3007  <refsect1><title>Arguments and Values</title>
3008  <variablelist>
3009    <varlistentry>
3010      <term>output-file</term>
3011      <listitem>
3012        <para>
3013          Pathname for the output index file.
3014        </para>
3015      </listitem>
3016    </varlistentry>
3017   
3018    <varlistentry>
3019      <term>html</term>
3020      <listitem>
3021        <para>
3022          If non-nil (the default), this will generate an HTML report, consisting of
3023          an index file in <varname>output-file</varname> and, in the same directory,
3024          one html file for each instrumented source file that has been loaded in the
3025          current session.
3026        </para>
3027      </listitem>
3028    </varlistentry>
3029    <varlistentry>
3030      <term>external-format</term>
3031      <listitem>
3032        <para>
3033          Controls the external format of the html files.
3034        </para>
3035      </listitem>
3036    </varlistentry>
3037    <varlistentry>
3038      <term>statistics</term>
3039      <listitem>
3040        <para>
3041          If non-nil (the default), a comma-separated file is
3042          generated with the summary of statistics. You can specify a
3043          filename for the statistics argument, otherwise
3044          "statistics.csv" is created in the directory of <varname>output-file</varname>.
3045          See documentation of coverage-statistics below for a
3046          description of the values in the statistics file.
3047        </para>
3048      </listitem>
3049    </varlistentry>
3050  </variablelist>
3051  </refsect1>
3052  <refsect1><title>Example</title>
3053    <para>
3054      If you've loaded <filename>foo.lx64fsl</filename> and
3055      <filename>bar.lx64fsl</filename>, and have run some tests, you could
3056      do
3057    <programlisting>
3058(REPORT-COVERAGE "/my/dir/coverage/report.html")
3059    </programlisting>
3060    and this would generate <filename>report.html</filename>,
3061    <filename>foo_lisp.html</filename> and
3062    <filename>bar_lisp.html</filename>, and
3063    <filename>statistics.csv</filename> all in
3064    <filename>/my/dir/coverage/</filename>.
3065    </para>
3066  </refsect1>
3067</refentry>
3068
3069<refentry id="f_reset-coverage">
3070  <indexterm zone="f_reset-coverage">
3071    <primary>reset-coverage</primary>
3072  </indexterm>
3073 
3074  <refnamediv>
3075    <refname>RESET-COVERAGE</refname>
3076    <refpurpose>
3077      Resets all coverage data back to the "Not Executed" state
3078    </refpurpose>
3079    <refclass>Function</refclass>
3080  </refnamediv>
3081
3082  <refsect1><title>Description</title>
3083    <para>
3084      Resets all coverage data back to the "Not Executed" state
3085    </para>
3086  </refsect1>
3087</refentry>
3088
3089<refentry id="f_clear-coverage">
3090  <indexterm zone="f_clear-coverage">
3091    <primary>clear-coverage</primary>
3092  </indexterm>
3093 
3094  <refnamediv>
3095    <refname>CLEAR-COVERAGE</refname>
3096    <refpurpose>
3097      Forget about all instrumented files that have been loaded.
3098    </refpurpose>
3099    <refclass>Function</refclass>
3100  </refnamediv>
3101
3102  <refsect1><title>Description</title>
3103    <para>
3104      Gets rid of the information about which instrumented files have
3105      been loaded, so <literal>ccl:report-coverage</literal> will not report any files,
3106      and <literal>ccl:save-coverage-in-file</literal> will not save any info, until more
3107      instrumented files are loaded.
3108    </para>
3109  </refsect1>
3110</refentry>
3111
3112<refentry id="f_save-coverage-in-file">
3113  <indexterm zone="f_save-coverage-in-file">
3114    <primary>save-coverage-in-file</primary>
3115  </indexterm>
3116 
3117  <refnamediv>
3118    <refname>SAVE-COVERAGE-IN-FILE</refname>
3119    <refpurpose>
3120      Save all coverage into to a file so you can restore it later.
3121    </refpurpose>
3122    <refclass>Function</refclass>
3123  </refnamediv>
3124
3125  <refsynopsisdiv>
3126    <synopsis><function>save-coverage-in-file</function> pathname
3127    </synopsis>
3128  </refsynopsisdiv>
3129
3130  <refsect1><title>Description</title>
3131    <para>
3132      Saves all coverage info in a file, so you can restore the
3133      coverage state later. This allows you to combine multiple runs
3134      or continue in a later session. Equivalent to
3135      <literal>(ccl:write-coverage-to-file (ccl:get-coverage) pathname)</literal>.
3136    </para>
3137  </refsect1>
3138</refentry>
3139
3140<refentry id="f_restore-coverage-from-file">
3141  <indexterm zone="f_restore-coverage-from-file">
3142    <primary>restore-coverage-from-file</primary>
3143  </indexterm>
3144 
3145  <refnamediv>
3146    <refname>RESTORE-COVERAGE-FROM-FILE</refname>
3147    <refpurpose>
3148      Load coverage state from a file.
3149    </refpurpose>
3150    <refclass>Function</refclass>
3151  </refnamediv>
3152
3153  <refsynopsisdiv>
3154    <synopsis><function>restore-coverage-from-file</function> pathname
3155    </synopsis>
3156  </refsynopsisdiv>
3157
3158  <refsect1><title>Description</title>
3159    <para>
3160      Restores the coverage data previously saved with
3161      ccl:save-coverage-in-file, for the set of instrumented fasls
3162      that were loaded both at save and restore time. I.e. coverage
3163      info is only restored for files that have been loaded in this
3164      session. For example if in a previous session you had loaded
3165      <filename>"foo.lx86fsl"</filename> and then saved the coverage info, in this session
3166      you must load the same <filename>"foo.lx86fsl"</filename> before calling
3167      <literal>restore-coverage-from-file</literal> in order to retrieve the stored
3168      coverage info for "foo".  Equivalent to <literal>(ccl:restore-coverage
3169      (ccl:read-coverage-from-file pathname))</literal>.
3170    </para>
3171  </refsect1>
3172</refentry>
3173
3174<refentry id="f_get-coverage">
3175  <indexterm zone="f_get-coverage">
3176    <primary>get-coverage</primary>
3177  </indexterm>
3178 
3179  <refnamediv>
3180    <refname>GET-COVERAGE</refname>
3181    <refpurpose>
3182      Returns a snapshot of the current coverage data.
3183    </refpurpose>
3184    <refclass>Function</refclass>
3185  </refnamediv>
3186
3187  <refsect1><title>Description</title>
3188    <para>
3189      Returns a snapshot of the current coverage data. A snapshot is a
3190      copy of the current coverage state. It can be saved in a file
3191      with <literal>ccl:write-coverage-to-file</literal>, reinstated back as the current
3192      state with <literal>ccl:restore-coverage</literal>, or combined with other
3193      snapshots with <literal>ccl:combine-coverage</literal>.
3194    </para>
3195  </refsect1>
3196</refentry>
3197
3198<refentry id="f_restore-coverage">
3199  <indexterm zone="f_restore-coverage">
3200    <primary>restore-coverage</primary>
3201  </indexterm>
3202 
3203  <refnamediv>
3204    <refname>RESTORE-COVERAGE</refname>
3205    <refpurpose>
3206      Reinstalls a coverage snapshot as the current coverage state.
3207    </refpurpose>
3208    <refclass>Function</refclass>
3209  </refnamediv>
3210
3211  <refsynopsisdiv>
3212    <synopsis><function>restore-coverage</function> snapshot
3213    </synopsis>
3214  </refsynopsisdiv>
3215
3216  <refsect1><title>Description</title>
3217    <para>
3218      Reinstalls a coverage snapshot as the current coverage state.
3219    </para>
3220  </refsect1>
3221</refentry>
3222
3223<refentry id="f_combine-coverage">
3224  <indexterm zone="f_combine-coverage">
3225    <primary>combine-coverage</primary>
3226  </indexterm>
3227 
3228  <refnamediv>
3229    <refname>COMBINE-COVERAGE</refname>
3230    <refpurpose>
3231      Combines multiple coverage snapshots into one.
3232    </refpurpose>
3233    <refclass>Function</refclass>
3234  </refnamediv>
3235
3236   <refsynopsisdiv>
3237     <synopsis><function>combine-coverage</function> snapshots
3238     </synopsis>
3239   </refsynopsisdiv>
3240
3241  <refsect1><title>Description</title>
3242    <para>
3243      Takes a list of coverage snapshots and returns a new coverage snapshot
3244      representing a union of all the coverage data.
3245    </para>
3246  </refsect1>
3247</refentry>
3248
3249
3250<refentry id="f_write-coverage-to-file">
3251  <indexterm zone="f_write-coverage-to-file">
3252    <primary>write-coverage-to-file</primary>
3253  </indexterm>
3254 
3255  <refnamediv>
3256    <refname>WRITE-COVERAGE-TO-FILE</refname>
3257    <refpurpose>
3258      Save a coverage snapshot in a file.
3259    </refpurpose>
3260    <refclass>Function</refclass>
3261  </refnamediv>
3262
3263  <refsynopsisdiv>
3264    <synopsis><function>write-coverage-to-file</function> snapshot pathname
3265    </synopsis>
3266  </refsynopsisdiv>
3267
3268  <refsect1><title>Description</title>
3269    <para>
3270      Saves the coverage snapshot in a file. The snapshot can be
3271      loaded back with <literal>ccl:read-coverage-from-file</literal> or loaded and
3272      restored with <literal>ccl:restore-coverage-from-file</literal>. Note that the file
3273      created is actually a lisp source file and can be compiled for
3274      faster loading.
3275    </para>
3276  </refsect1>
3277</refentry>
3278
3279<refentry id="f_read-coverage-from-file">
3280  <indexterm zone="f_read-coverage-from-file">
3281    <primary>read-coverage-from-file</primary>
3282  </indexterm>
3283 
3284  <refnamediv>
3285    <refname>READ-COVERAGE-FROM-FILE</refname>
3286    <refpurpose>
3287      Return the coverage snapshot saved in a file.
3288    </refpurpose>
3289    <refclass>Function</refclass>
3290  </refnamediv>
3291
3292  <refsynopsisdiv>
3293    <synopsis><function>read-coverage-from-file</function> pathname
3294    </synopsis>
3295  </refsynopsisdiv>
3296
3297  <refsect1><title>Description</title>
3298    <para>
3299      Returns the snapshot saved in pathname. Doesn't affect the
3300      current coverage state. pathname can be the file previously
3301      created with <literal>ccl:write-coverage-to-file</literal> or
3302      <literal>ccl:save-coverage-in-file</literal>, or it can be the name of the fasl
3303      created from compiling such a file.
3304    </para>
3305  </refsect1>
3306</refentry>
3307
3308<refentry id="f_coverage-statistics">
3309  <indexterm zone="f_coverage-statistics">
3310    <primary>coverage-statistics</primary>
3311  </indexterm>
3312 
3313  <refnamediv>
3314    <refname>COVERAGE-STATISTICS</refname>
3315    <refpurpose>
3316      Returns a sequence of <literal>ccl:coverage-statistics</literal> objects, one per source file.
3317    </refpurpose>
3318    <refclass>Function</refclass>
3319  </refnamediv>
3320
3321  <refsynopsisdiv>
3322    <synopsis><function>coverage-statistics</function>
3323    </synopsis>
3324  </refsynopsisdiv>
3325
3326  <refsect1><title>Description</title>
3327    <para>
3328      Returns a sequence of <literal>ccl:coverage-statistics</literal> objects, one for each
3329      source file, containing the same information as that written to
3330      the statistics file by <literal>ccl:report-coverage</literal>. The following
3331      accessors are defined for <literal>ccl:coverage-statistics</literal> objects:
3332      <variablelist>
3333      <varlistentry>
3334        <term><function>coverage-source-file</function></term>
3335        <listitem>
3336          <para>
3337            the name of the source file corresponding to this information
3338          </para>
3339        </listitem>
3340      </varlistentry>
3341      <varlistentry>
3342        <term><function>coverage-expressions-total</function></term>
3343        <listitem>
3344          <para>
3345            the total number of expressions
3346          </para>
3347        </listitem>
3348      </varlistentry>
3349      <varlistentry>
3350        <term><function>coverage-expressions-entered</function></term>
3351        <listitem>
3352          <para>
3353            the number of source expressions that have been entered
3354            (i.e. at least partially covered)
3355          </para>
3356        </listitem>
3357      </varlistentry>
3358      <varlistentry>
3359        <term><function>coverage-expressions-covered</function></term>
3360        <listitem>
3361          <para>
3362            the number of source expressions that were fully covered
3363          </para>
3364        </listitem>
3365      </varlistentry>
3366      <varlistentry>
3367        <term><function>coverage-unreached-branches</function></term>
3368        <listitem>
3369          <para>
3370            the number of conditionals with one branch taken and one not taken
3371          </para>
3372        </listitem>
3373      </varlistentry>
3374      <varlistentry>
3375        <term><function>coverage-code-forms-total</function></term>
3376        <listitem>
3377          <para>
3378            the total number of code forms. A code form is an
3379            expression in the final stage of compilation, after all
3380            macroexpansion and compiler transforms and simplification
3381          </para>
3382        </listitem>
3383      </varlistentry>
3384      <varlistentry>
3385        <term><function>coverage-code-forms-covered</function></term>
3386        <listitem>
3387          <para>
3388            the number of code forms that have been entered
3389          </para>
3390        </listitem>
3391      </varlistentry>
3392      <varlistentry>
3393        <term><function>coverage-functions-total</function></term>
3394        <listitem>
3395          <para>
3396            the total number of functions
3397          </para>
3398        </listitem>
3399      </varlistentry>
3400      <varlistentry>
3401        <term><function>coverage-functions-fully-covered</function></term>
3402        <listitem>
3403          <para>
3404            the number of functions that were fully covered
3405          </para>
3406        </listitem>
3407      </varlistentry>
3408      <varlistentry>
3409        <term><function>coverage-functions-partly-covered</function></term>
3410        <listitem>
3411          <para>
3412            the number of functions that were partly covered
3413          </para>
3414        </listitem>
3415      </varlistentry>
3416      <varlistentry>
3417        <term><function>coverage-functions-not-entered</function></term>
3418        <listitem>
3419          <para>
3420            the number of functions never entered
3421          </para>
3422        </listitem>
3423      </varlistentry>
3424      </variablelist>
3425    </para>
3426  </refsect1>
3427</refentry>
3428
3429<refentry id="f_reset-incremental-coverage">
3430  <indexterm zone="f_reset-incremental-coverage">
3431    <primary>reset-incremental-coverage</primary>
3432  </indexterm>
3433 
3434  <refnamediv>
3435    <refname>RESET-INCREMENTAL-COVERAGE</refname>
3436    <refpurpose>
3437      Reset incremental coverage.
3438    </refpurpose>
3439    <refclass>Function</refclass>
3440  </refnamediv>
3441
3442  <refsynopsisdiv>
3443    <synopsis><function>reset-incremental-coverage</function>
3444    </synopsis>
3445  </refsynopsisdiv>
3446
3447  <refsect1><title>Description</title>
3448    <para>
3449      Marks a starting point for recording incremental coverage.
3450      Note that calling
3451      this function does not affect regular coverage data (whereas calling
3452      <literal>ccl:reset-coverage</literal> resets incremental coverage as well).
3453    </para>
3454  </refsect1>
3455</refentry>
3456
3457
3458<refentry id="f_get-incremental-coverage">
3459  <indexterm zone="f_get-incremental-coverage">
3460    <primary>get-incremental-coverage</primary>
3461  </indexterm>
3462 
3463  <refnamediv>
3464    <refname>GET-INCREMENTAL-COVERAGE</refname>
3465    <refpurpose>
3466      Returns the delta of coverage since the last incremental reset.
3467    </refpurpose>
3468    <refclass>Function</refclass>
3469  </refnamediv>
3470
3471  <refsynopsisdiv>
3472    <synopsis><function>get-incremental-coverage</function> &key; (reset t)
3473    </synopsis>
3474  </refsynopsisdiv>
3475
3476  <refsect1><title>Description</title>
3477    <para>
3478      Returns the delta of coverage since the last reset of incremental coverage.
3479     If <literal>reset</literal> is true (the default), it also resets incremental coverage
3480     now, so that the next call to <literal>get-incremental-coverage</literal> will return
3481     the delta from this point.
3482     </para>
3483     <para>
3484      Incremental coverage deltas are represented differently than the full coverage snapshots
3485      returned by functions such as <literal>ccl:get-coverage</literal>.  Incremental
3486      coverage uses an abbreviated format
3487      and is missing some of the information in a full snapshot, and therefore cannot be passed to
3488      functions documented to accept a <variable>snapshot</variable>, only to functions
3489      specifically documented to accept incremental coverage deltas.
3490     </para>
3491  </refsect1>
3492</refentry>
3493
3494<refentry id="f_incremental-coverage-source-matches">
3495  <indexterm zone="f_incremental-coverage-source-matches">
3496    <primary>incremental-coverage-source-matches</primary>
3497  </indexterm>
3498 
3499  <refnamediv>
3500    <refname>INCREMENTAL-COVERAGE-SOURCE-MATCHES</refname>
3501    <refpurpose>
3502      Find incremental coverage deltas intersecting source regions.
3503    </refpurpose>
3504    <refclass>Function</refclass>
3505  </refnamediv>
3506
3507  <refsynopsisdiv>
3508    <synopsis><function>incremental-coverage-source-matches</function> collection sources
3509    </synopsis>
3510  </refsynopsisdiv>
3511
3512  <refsect1><title>Arguments and Values</title>
3513  <variablelist>
3514    <varlistentry>
3515      <term>collection</term>
3516       <listitem>
3517         <para>
3518          A hash table mapping arbitrary keys to incremental coverage deltas, or a sequence of
3519          incremental coverage deltas.
3520         </para>
3521        </listitem>
3522    </varlistentry>
3523    <varlistentry>
3524      <term>sources</term>
3525       <listitem>
3526         <para>
3527          A list of pathnames and/or source-notes, the latter representing a range within a file.
3528         </para>
3529        </listitem>
3530    </varlistentry>
3531   </variablelist>
3532   </refsect1>
3533
3534  <refsect1><title>Description</title>
3535    <para>
3536     Given a hash table <literal>collection</literal> whose values are incremental coverage
3537     deltas, return a list of all keys corresponding to those deltas that intersect any region
3538     in <literal>sources</literal>.
3539     </para>
3540     <para>
3541     For example if the deltas represent tests, then the returned value is a list of all tests
3542     that cover some part of the source regions.
3543     </para>
3544     <para>
3545     <literal>collection</literal> can also be a sequence of deltas, in which case a subsequence
3546      of matching deltas is returned.  In particular you can test whether any particular delta
3547      intersects the sources by passing it in as a single-element list.
3548     </para>
3549  </refsect1>
3550</refentry>
3551
3552<refentry id="f_incremental-coverage-svn-matches">
3553  <indexterm zone="f_incremental-coverage-svn-matches">
3554    <primary>incremental-coverage-svn-matches</primary>
3555  </indexterm>
3556 
3557  <refnamediv>
3558    <refname>INCREMENTAL-COVERAGE-SVN-MATCHES</refname>
3559    <refpurpose>
3560      Find incremental coverage deltas matching changes from a particular subversion revision.
3561    </refpurpose>
3562    <refclass>Function</refclass>
3563  </refnamediv>
3564
3565  <refsynopsisdiv>
3566    <synopsis><function>incremental-coverage-svn-matches</function> collection &key; (directory (current-directory)) (revision :base)
3567    </synopsis>
3568  </refsynopsisdiv>
3569
3570  <refsect1><title>Arguments and Values</title>
3571  <variablelist>
3572    <varlistentry>
3573      <term>collection</term>
3574       <listitem>
3575         <para>
3576          A hash table mapping arbitrary keys to incremental coverage deltas, or a sequence of
3577          incremental coverage deltas.
3578         </para>
3579        </listitem>
3580    </varlistentry>
3581    <varlistentry>
3582      <term>directory</term>
3583       <listitem>
3584         <para>
3585          The pathname of a subversion working directory.
3586         </para>
3587        </listitem>
3588    </varlistentry>
3589    <varlistentry>
3590      <term>revision</term>
3591       <listitem>
3592         <para>
3593          The revision to compare to the working directory, an integer or another
3594          value whose printed representation is suitable for passing as the
3595          <literal>--revision</literal> argument
3596          to <filename>svn</filename>.
3597         </para>
3598        </listitem>
3599    </varlistentry>
3600   </variablelist>
3601   </refsect1>
3602
3603  <refsect1><title>Description</title>
3604    <para>
3605     Given a hash table <literal>collection</literal> whose values are incremental coverage
3606     deltas, return a list of all keys corresponding to those deltas that intersect any changed
3607     source in <literal>directory</literal> since revision <literal>revision</literal> in subversion.
3608     </para>
3609     <para>
3610     For example if the deltas represent tests, then the returned value is a list of all tests
3611     that might be affected by the changes.
3612     </para>
3613     <para>
3614     <literal>collection</literal> can also be a sequence of deltas, in which case a subsequence
3615      of matching deltas is returned.  In particular you can test whether any particular delta
3616      is affected by the changes by passing it in as a single-element list.
3617     </para>
3618  </refsect1>
3619</refentry>
3620
3621
3622
3623<refentry id="v_compile-code-coverage">
3624  <indexterm zone="v_compile-code-coverage">
3625    <primary>*COMPILE-CODE-COVERAGE*</primary>
3626  </indexterm>
3627 
3628  <refnamediv>
3629    <refname>*COMPILE-CODE-COVERAGE*</refname>
3630    <refpurpose>
3631      When true, instrument functions being compiled to collect code coverage information.
3632    </refpurpose>
3633    <refclass>Variable</refclass>
3634  </refnamediv>
3635
3636  <refsynopsisdiv>
3637    <synopsis><varname>*compile-code-coverage*</varname>
3638    </synopsis>
3639  </refsynopsisdiv>
3640
3641  <refsect1><title>Description</title>
3642    <para>
3643      This variable controls whether functions are instrumented for
3644      code coverage. Files compiled while this variable is true will
3645      contain code coverage instrumentation.
3646    </para>
3647  </refsect1>
3648</refentry>
3649
3650<refentry id="v_without-compiling-code-coverage">
3651  <indexterm zone="v_without-compiling-code-coverage">
3652    <primary>without-compiling-code-coverage</primary>
3653  </indexterm>
3654 
3655  <refnamediv>
3656    <refname>WITHOUT-COMPILING-CODE-COVERAGE</refname>
3657    <refpurpose>
3658      Don't record code coverage for forms within the body.
3659    </refpurpose>
3660    <refclass>Macro</refclass>
3661  </refnamediv>
3662
3663  <refsynopsisdiv>
3664    <synopsis><function>without-compiling-code-coverage</function>
3665    </synopsis>
3666  </refsynopsisdiv>
3667
3668  <refsect1><title>Description</title>
3669    <para>
3670      This macro arranges so that body doesn't record internal details
3671      of code coverage. It will be considered totally covered if it's
3672      entered at all. The Common Lisp macros <literal>ASSERT</literal> and <literal>CHECK-TYPE</literal> use
3673      this macro.
3674    </para>
3675  </refsect1>
3676</refentry>
3677
3678</sect2>
3679
3680<sect2 id="code-coverage-interpreting-code-coloring"><title>Interpreting Code Coloring</title>
3681<para>
3682
3683 The output of ccl:report-coverage consists of formatted source code, with coverage indicated by
3684 coloring.  Four colors are used: dark green for forms that compiled to code in which every single
3685 instruction was executed, light green for forms that have been entered but weren't totally covered, red
3686 for forms that were never entered, and the page background color for toplevel forms that weren't
3687 instrumented.
3688
3689</para>
3690<para>
3691 The source coloring is applied from outside in.  So for example if you have
3692
3693  <programlisting>
3694(outer-form ... (inner-form ...) ...)
3695  </programlisting>
3696
3697 first the whole outer form is painted with whatever color expresses the outer form coverage, and then the
3698 inner form color is replaced with whatever color expresses the inner form coverage.  One consequence of
3699 this approach is that every part of the outer form that is not specifically inside some executable inner
3700 form will have the outer form's coverage color. If the syntax of outer form involves some non-executable
3701 forms, or forms that do not have coverage info of their own for whatever reason, then they will just
3702 inherit the color of the outer form, because they don't get repainted with a color of their own.
3703</para>
3704
3705<para>
3706 One case in which this approach can be confusing is in the case of symbols.  As noted in the Limitations
3707 section, coverage information is not recorded for variables; hence the coloring of a variable does not
3708 convey information about whether the variable was evaluated or not -- that information is not available,
3709 and the variable just inherits the color of the form that contains it.
3710</para>
3711
3712
3713</sect2>
3714</sect1>
3715
3716<sect1 id="other-extensions"><title>Other Extensions</title>
3717<refentry id="v_quit">
3718  <indexterm zone="v_quit">
3719    <primary>quit</primary>
3720  </indexterm>
3721 
3722  <refnamediv>
3723    <refname>QUIT</refname>
3724    <refpurpose>
3725      Cleanly exit the lisp.
3726    </refpurpose>
3727    <refclass>Function</refclass>
3728  </refnamediv>
3729
3730  <refsynopsisdiv>
3731    <synopsis><function>quit</function> &optional; (exit 0) &key; error-handler
3732    </synopsis>
3733  </refsynopsisdiv>
3734
3735  <refsect1><title>Summary</title>
3736    <para>
3737      Cleanly exit from lisp.  If the exit argument is a value of type
3738      (signed-byte 32), that value will be passed to the C library
3739      function _exit() as the status code.  (A value of nil is treated
3740      as a zero.)
3741    </para>
3742    <para>
3743      Alternatively, exit may be a function of no arguments;  this function
3744      will be called instead of _exit() to exit the lisp.
3745    </para>
3746    <para>
3747      The error-handler argument, if supplied, must be a function of one
3748      argument, the condition, that will be called if an error occurs when
3749      preparing to quit.  The error-handler function should exit the lisp.
3750    </para>
3751  </refsect1>
3752</refentry>
3753
3754<refentry id="v_wait-for-signal">
3755  <indexterm zone="v_wait-for-signal">
3756    <primary>wait-for-signal</primary>
3757  </indexterm>
3758 
3759  <refnamediv>
3760    <refname>WAIT-FOR-SIGNAL</refname>
3761    <refpurpose>
3762      Wait for a particular signal to be received.
3763    </refpurpose>
3764    <refclass>Function</refclass>
3765  </refnamediv>
3766
3767  <refsynopsisdiv>
3768    <synopsis><function>wait-for-signal</function> s duration
3769    </synopsis>
3770  </refsynopsisdiv>
3771
3772  <refsect1><title>Summary</title>
3773    <para>
3774      Wait for the signal with signal number s to be received, or until
3775      duration seconds have elapsed.  If duration is nil, wait for an
3776      indeterminate "very long time" (many years).
3777    </para>
3778    <para>
3779      If signal number s is outside the range of valid signals, or is
3780      reserved by the lisp for its own use, an error is signaled.
3781      (An error is always signaled on Windows systems.)
3782    </para>
3783  </refsect1>
3784</refentry>
3785
3786<refentry id="v_unwind-protect">
3787  <indexterm zone="v_unwind-protect">
3788    <primary>unwind-protect</primary>
3789  </indexterm>
3790 
3791  <refnamediv>
3792    <refname>UNWIND-PROTECT</refname>
3793    <refpurpose>
3794      Ensure cleanup-forms are executed.
3795    </refpurpose>
3796    <refclass>Special operator</refclass>
3797  </refnamediv>
3798
3799  <refsynopsisdiv>
3800    <synopsis>
3801      <function>unwind-protect</function> protected-form {cleanup-form}*
3802    </synopsis>
3803  </refsynopsisdiv>
3804
3805  <refsect1><title>Summary</title>
3806    <para>
3807      In &CCL;, the cleanup forms are always executed as if they were
3808      wrapped with <xref linkend="m_without-interrupts"/>.
3809      To allow interrupts, use
3810      <xref linkend="m_with-interrupts-enabled"/>.
3811    </para>
3812  </refsect1>
3813</refentry>
3814
3815</sect1>
3816</chapter>
Note: See TracBrowser for help on using the repository browser.