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

Last change on this file since 13172 was 13172, checked in by rme, 10 years ago

Document FASL-CONCATENATE. (Description lifted from
http://clozure.com/pipermail/openmcl-devel/2009-May/009649.html)

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