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

Last change on this file since 8981 was 8981, checked in by mikel, 11 years ago

additions to ObjC and ffi docs; many mechanical edits; some standardization of XML elements and formatting

File size: 61.8 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><title>Using &CCL;</title>
13 
14  <!-- ============================================================ -->
15  <sect1><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, and the default entry and exit messages will print a | instead of space every this many levels of indentation.</para>
480
481
482  </sect1>
483
484  <sect1 id="Unicode"><title>Unicode</title>
485
486    <para>All characters and strings in &CCL; fully support Unicode
487      by using UTF-32. There is only one <literal>CHARACTER</literal> type
488      and one <literal>STRING</literal> in &CCL;.  There has been a
489      lot of discussion about this decision which can be found by
490      searching the openmcl-devel archives at <ulink
491                                                 url="http://clozure.com/pipermail/openmcl-devel/"/>.  Suffice it to
492      say that we decided that the simplicity and speed advantages of
493      UTF-32 outweigh the space disadvantage.</para>
494
495    <sect2><title>Characters</title>
496      <para>There is one <literal>CHARACTER</literal> type in &CCL;.
497        All <literal>CHARACTER</literal>s are <literal>BASE-CHAR</literal>s.
498        <varname>CHAR-CODE-LIMIT</varname> is now
499        <literal>#x110000</literal>, which means that all Unicode characters
500        can be directly represented.  As of Unicode 5.0, only about 100,000
501        of 1,114,112 possible <literal>CHAR-CODE</literal>s are actually
502        defined. The function <function>CODE-CHAR</function> knows that
503        certain ranges of code values (notably
504        <literal>#xd800</literal>-<literal>#xddff</literal>) will never be
505        valid character codes and will return <literal>NIL</literal> for
506        arguments in that range, but may return a non-<literal>NIL</literal>
507        value (an undefined/non-standard <literal>CHARACTER</literal>
508        object) for other unassigned code values.</para>
509      <para>&CCL; supports character names of the form
510        <literal>u+xxxx</literal> - where <literal>x</literal> is a sequence
511        of one or more hex digits.  The value of the hex digits denotes the
512        code of the character.  The <literal>+</literal> character is
513        optional, so <literal>#\u+0020</literal>,
514        <literal>#\U0020</literal>, and <literal>#\U+20</literal> all refer
515        to the <literal>#\Space</literal> character.</para>
516      <para>Characters with codes in the range
517        <literal>#xa0</literal>-<literal>#x7ff</literal> also have symbolic
518        names These are the names from the Unicode standard with spaces
519        replaced by underscores.  So
520        <literal>#\Greek_Capital_Letter_Epsilon</literal> can be used to
521        refer to the character whose <function>CHAR-CODE</function> is
522        <literal>#x395</literal>.</para>
523    </sect2>
524
525    <sect2 id="External-Formats"><title>External Formats</title>
526      <para><function>OPEN</function>, <function>LOAD</function>, and
527        <function>COMPILE-FILE</function> all take an
528        <literal>:EXTERNAL-FORMAT</literal> keyword argument.  The value of
529        <literal>:EXTERNAL-FORMAT</literal> can be
530        <literal>:DEFAULT</literal> (the default value), a line termination
531        keyword <xref linkend="Line-Termination-Keywords"/><xref
532                                                              linkend="k_external-format"/>, a character encoding keyword <xref
533                                                                                                                             linkend="Character-Encodings"/>, a plist with keys:
534        <literal>:CHARACTER-ENCODING</literal> and
535        <literal>:LINE-TERMINATION</literal>, or an external-format object
536        created using <function>CCL::MAKE-EXTERNAL-FORMAT</function>.  If
537        <literal>:DEFAULT</literal> is specified, then the value of
538        <varname>CCL:*DEFAULT-EXTERNAL-FORMAT*</varname> is used.  If no
539        line-termination is specified, then the value of
540        <varname>CCL:*DEFAULT-LINE-TERMINATION*</varname> is used.  If no
541        character encoding is specified, then
542        <varname>CCL:*DEFAULT-FILE-CHARACTER-ENCODING*</varname> is used for
543        file streams and
544        <varname>CCL:*DEFAULT-SOCKET-CHARACTER-ENCODING*</varname> is used
545        for socket streams.  The default, default character encoding is
546        <literal>NIL</literal> which is a synonym for <literal>:ISO-8859-1</literal>
547      </para>
548    </sect2>
549
550    <sect2 id="Line-Termination-Keywords"><title>Line Termination Keywords</title>
551      <para>Line termination keywords indicate which characters are used
552        to indicate the end of a line.  On input, the external line
553        termination characters are replaced by <literal>#\Newline</literal>
554        and on output, <literal>#\Newline</literal>s are converted to the
555        external line termination characters.</para>
556      <table id="Line-Termination-Table" frame='all'><title>Line Termination Keywords</title>
557        <tgroup cols='2' align='left' colsep='1' rowsep='1'>
558          <thead>
559            <row>
560                  <entry>keyword</entry>
561                  <entry>character(s)</entry>
562            </row>
563          </thead>
564          <tbody>
565            <row>
566                  <entry><literal>:UNIX</literal></entry>
567                  <entry><literal>#\Linefeed</literal></entry>
568            </row>
569            <row>
570                  <entry><literal>:MACOS</literal></entry>
571                  <entry><literal>#\Return</literal></entry>
572            </row>
573            <row>
574                  <entry><literal>:CR</literal></entry>
575                  <entry><literal>#\Return</literal></entry>
576            </row>
577            <row>
578                  <entry><literal>:CRLF</literal></entry>
579                  <entry><literal>#\Return #\Linefeed</literal></entry>
580            </row>
581            <row>
582                  <entry><literal>:CP/M</literal></entry>
583                  <entry><literal>#\Return #\Linefeed</literal></entry>
584            </row>
585            <row>
586                  <entry><literal>:MSDOS</literal></entry>
587                  <entry><literal>#\Return #\Linefeed</literal></entry>
588            </row>
589            <row>
590                  <entry><literal>:DOS</literal></entry>
591                  <entry><literal>#\Return #\Linefeed</literal></entry>
592            </row>
593            <row>
594                  <entry><literal>:WINDOWS</literal></entry>
595                  <entry><literal>#\Return #\Linefeed</literal></entry>
596            </row>
597            <row>
598                  <entry><literal>:INFERRED</literal></entry>
599                  <entry>see below</entry>
600            </row>
601            <row>
602                  <entry><literal>:UNICODE</literal></entry>
603                  <entry><literal>#\Line_Separator</literal></entry>
604            </row>
605          </tbody>
606        </tgroup>
607      </table>
608      <para><literal>:INFERRED</literal> means try to guess a stream's
609        line-termination conventions.  It is only useful for
610        <literal>FILE-STREAM</literal>s that are open for <literal>:INPUT</literal> or <literal>:IO</literal>.  The first buffer full of data is examined, and if a <literal>#\Return</literal> character occurs before any <literal>#\Linefeed</literal> character, then the line termination type is set to <literal>:MACOS</literal>, otherwise it is set to <literal>:UNIX</literal>.</para>
611    </sect2>
612   
613
614    <sect2 id="Character-Encodings"><title>Character Encodings</title>
615      <para>Internally, all characters and strings in &CCL; are in
616        UTF-32.  Externally, files or socket streams may encode characters
617        in a wide variety of ways.  The International Organization for
618        Standardization, widely known as ISO defines a number of these
619        character encodings.  &CCL; implements a number of these
620        encodings as detailed below.  These encodings are part of the
621        specification of external formats (see <xref
622                                                  linkend="External-Formats"/>.  When reading from a stream,
623        characters are converted from the specified external character
624        encoding to UTF-32.  When writing to a stream, characters are
625        converted from UTF-32 to the specified character encoding.  Here is
626        a list of character encoding keywords used to specify a standard
627        character encoding.</para>
628      <variablelist>
629        <varlistentry><term><literal>:ISO-8859-1</literal></term>
630          <listitem><para>An 8-bit, fixed-width character encoding in
631              which all character codes map to their Unicode
632              equivalents. Intended to support most characters used in most
633              Western European languages.</para></listitem>
634        </varlistentry>
635        <varlistentry><term><literal>:ISO-8859-2</literal></term>
636          <listitem><para>An 8-bit, fixed-width character encoding in
637              which codes #x00-#x9f map to their Unicode equivalents and
638              other codes map to other Unicode character values.  Intended to
639              provide most characters found in most languages used in
640              Central/Eastern Europe.</para></listitem>
641        </varlistentry>
642        <varlistentry><term><literal>:ISO-8859-3</literal></term>
643          <listitem><para>An 8-bit, fixed-width character encoding in
644              which codes #x00-#x9f map to their Unicode equivalents and
645              other codes map to other Unicode character values.  Intended to
646              provide most characters found in most languages used in
647              Southern Europe.</para></listitem>
648        </varlistentry>
649        <varlistentry><term><literal>:ISO-8859-4</literal></term>
650          <listitem><para>An 8-bit, fixed-width character encoding in
651              which codes #x00-#x9f map to their Unicode equivalents and
652              other codes map to other Unicode character values.  Intended to
653              provide most characters found in most languages used in
654              Northern Europe.</para></listitem>
655        </varlistentry>
656        <varlistentry><term><literal>:ISO-8859-5</literal></term>
657          <listitem><para>An 8-bit, fixed-width character encoding in
658              which codes #x00-#x9f map to their Unicode equivalents and
659              other codes map to other Unicode character values.  Intended to
660              provide most characters found in the Cyrillic
661              alphabet.</para></listitem>
662        </varlistentry>
663        <varlistentry><term><literal>:ISO-8859-6</literal></term>
664          <listitem><para>An 8-bit, fixed-width character encoding in
665              which codes #x00-#x9f map to their Unicode equivalents and
666              other codes map to other Unicode character values.  Intended to
667              provide most characters found in the Arabic
668              alphabet.</para></listitem>
669        </varlistentry>
670        <varlistentry><term><literal>:ISO-8859-7</literal></term>
671          <listitem><para>An 8-bit, fixed-width character encoding in
672              which codes #x00-#x9f map to their Unicode equivalents and
673              other codes map to other Unicode character values.  Intended to
674              provide most characters found in the Greek
675              alphabet.</para></listitem>
676        </varlistentry>
677        <varlistentry><term><literal>:ISO-8859-8</literal></term>
678          <listitem><para>An 8-bit, fixed-width character encoding in
679              which codes #x00-#x9f map to their Unicode equivalents and
680              other codes map to other Unicode character values.  Intended to
681              provide most characters found in the Hebrew
682              alphabet.</para></listitem>
683        </varlistentry>
684        <varlistentry><term><literal>:ISO-8859-9</literal></term>
685          <listitem><para>An 8-bit, fixed-width character encoding in
686              which codes #x00-#xcf map to their Unicode equivalents and
687              other codes map to other Unicode character values.  Intended to
688              provide most characters found in the Turkish
689              alphabet.</para></listitem>
690        </varlistentry>
691        <varlistentry><term><literal>:ISO-8859-10</literal></term>
692          <listitem><para>An 8-bit, fixed-width character encoding in
693              which codes #x00-#x9f map to their Unicode equivalents and
694              other codes map to other Unicode character values.  Intended to
695              provide most characters found in Nordic
696              alphabets.</para></listitem>
697        </varlistentry>
698        <varlistentry><term><literal>:ISO-8859-11</literal></term>
699          <listitem><para>An 8-bit, fixed-width character encoding in
700              which codes #x00-#x9f map to their Unicode equivalents and
701              other codes map to other Unicode character values.  Intended to
702              provide most characters found the Thai
703              alphabet.</para></listitem>
704        </varlistentry>
705        <varlistentry><term><literal>:ISO-8859-13</literal></term>
706          <listitem><para>An 8-bit, fixed-width character encoding in
707              which codes #x00-#x9f map to their Unicode equivalents and
708              other codes map to other Unicode character values.  Intended to
709              provide most characters found in Baltic
710              alphabets.</para></listitem>
711        </varlistentry>
712        <varlistentry><term><literal>:ISO-8859-14</literal></term>
713          <listitem><para>An 8-bit, fixed-width character encoding in
714              which codes #x00-#x9f map to their Unicode equivalents and
715              other codes map to other Unicode character values.  Intended to
716              provide most characters found in Celtic
717              languages.</para></listitem>
718        </varlistentry>
719        <varlistentry><term><literal>:ISO-8859-15</literal></term>
720          <listitem><para>An 8-bit, fixed-width character encoding in
721              which codes #x00-#x9f map to their Unicode equivalents and
722              other codes map to other Unicode character values.  Intended to
723              provide most characters found in Western European languages
724              (including the Euro sign and some other characters missing from
725              ISO-8859-1.</para></listitem>
726        </varlistentry>
727        <varlistentry><term><literal>:ISO-8859-16</literal></term>
728          <listitem><para>An 8-bit, fixed-width character encoding in
729              which codes #x00-#x9f map to their Unicode equivalents and
730              other codes map to other Unicode character values.  Intended to
731              provide most characters found in Southeast European
732              languages.</para></listitem>
733        </varlistentry>
734        <varlistentry><term><literal>:MACINTOSH</literal></term>
735          <listitem><para>An 8-bit, fixed-width character encoding in
736              which codes #x00-#x7f map to their Unicode equivalents and
737              other codes map to other Unicode character values.
738              Traditionally used on Classic MacOS to encode characters used
739              in western languages.</para></listitem>
740        </varlistentry>
741        <varlistentry><term><literal>:UCS-2</literal></term>
742          <listitem><para>A 16-bit, fixed-length encoding in which
743              characters with CHAR-CODEs less than #x10000 can be encoded in
744              a single 16-bit word.  The endianness of the encoded data is
745              indicated by the endianness of a byte-order-mark character
746              (#u+feff) prepended to the data; in the absence of such a
747              character on input, the data is assumed to be in big-endian
748              order.</para></listitem>
749        </varlistentry>
750        <varlistentry><term><literal>:UCS-2BE</literal></term>
751          <listitem><para>A 16-bit, fixed-length encoding in which
752              characters with CHAR-CODEs less than #x10000 can be encoded in
753              a single 16-bit big-endian word. The encoded data is implicitly
754              big-endian; byte-order-mark characters are not interpreted on
755              input or prepended to output.</para></listitem>
756        </varlistentry>
757        <varlistentry><term><literal>:UCS-2LE</literal></term>
758          <listitem><para>A 16-bit, fixed-length encoding in which
759              characters with CHAR-CODEs less than #x10000 can be encoded in
760              a single 16-bit little-endian word. The encoded data is
761              implicitly little-endian; byte-order-mark characters are not
762              interpreted on input or prepended to output.</para></listitem>
763        </varlistentry>
764        <varlistentry><term><literal>:US-ASCII</literal></term>
765          <listitem><para>An 7-bit, fixed-width character encoding in
766              which all character codes map to their Unicode
767              equivalents. </para></listitem>
768        </varlistentry>
769        <varlistentry><term><literal>:UTF-16</literal></term>
770          <listitem><para>A 16-bit, variable-length encoding in which
771              characters with CHAR-CODEs less than #x10000 can be encoded in
772              a single 16-bit word and characters with larger codes can be
773              encoded in a pair of 16-bit words.  The endianness of the
774              encoded data is indicated by the endianness of a
775              byte-order-mark character (#u+feff) prepended to the data; in
776              the absence of such a character on input, the data is assumed
777              to be in big-endian order. Output is written in native
778              byte-order with a leading byte-order mark.</para></listitem>
779        </varlistentry>
780        <varlistentry><term><literal>:UTF-16BE</literal></term>
781          <listitem><para>A 16-bit, variable-length encoding in which
782              characters with CHAR-CODEs less than #x10000 can be encoded in
783              a single 16-bit big-endian word and characters with larger
784              codes can be encoded in a pair of 16-bit big-endian words.  The
785              endianness of the encoded data is implicit in the encoding;
786              byte-order-mark characters are not interpreted on input or
787              prepended to output.</para></listitem>
788        </varlistentry>
789        <varlistentry><term><literal>:UTF-16LE</literal></term>
790          <listitem><para>A 16-bit, variable-length encoding in which
791              characters with CHAR-CODEs less than #x10000 can be encoded in
792              a single 16-bit little-endian word and characters with larger
793              codes can be encoded in a pair of 16-bit little-endian words.
794              The endianness of the encoded data is implicit in the encoding;
795              byte-order-mark characters are not interpreted on input or
796              prepended to output.</para></listitem>
797        </varlistentry>
798        <varlistentry><term><literal>:UTF-32</literal></term>
799          <listitem><para>A 32-bit, fixed-length encoding in which all
800              Unicode characters can be encoded in a single 32-bit word.  The
801              endianness of the encoded data is indicated by the endianness
802              of a byte-order-mark character (#u+feff) prepended to the data;
803              in the absence of such a character on input, input data is
804              assumed to be in big-endian order.  Output is written in native
805              byte order with a leading byte-order mark.</para></listitem>
806        </varlistentry>
807        <varlistentry><term><literal>:UTF-32BE</literal></term>
808          <listitem><para>A 32-bit, fixed-length encoding in which all
809              Unicode characters encoded in a single 32-bit word. The encoded
810              data is implicitly big-endian; byte-order-mark characters are
811              not interpreted on input or prepended to
812              output.</para></listitem>
813        </varlistentry>
814        <varlistentry><term><literal>:UTF-8</literal></term>
815          <listitem><para>An 8-bit, variable-length character encoding in
816              which characters with CHAR-CODEs in the range #x00-#x7f can be
817              encoded in a single octet; characters with larger code values
818              can be encoded in 2 to 4 bytes.</para></listitem>
819        </varlistentry>
820        <varlistentry><term><literal>:UTF32LE</literal></term>
821          <listitem><para>A 32-bit, fixed-length encoding in which all
822              Unicode characters can encoded in a single 32-bit word. The
823              encoded data is implicitly little-endian; byte-order-mark
824              characters are not interpreted on input or prepended to
825              output.</para></listitem>
826        </varlistentry>
827      </variablelist>
828    </sect2>
829  </sect1>
830
831  <sect1 id="Pathanmes"><title>Pathnames</title>
832
833    <sect2>
834      <title>Pathname Expansion</title>
835      <para>Leading tilde (~) characters in physical pathname namestrings
836        are expanded in the way that most shells do:</para>
837     
838      <para><literal>"~user/..."</literal> can be used to refer to an absolute pathname rooted
839        at the home directory of the user named "user".</para>
840     
841      <para><literal>"~/..."</literal> can be used to refer to an absolute pathname rooted at
842        the home directory of the current user.</para>
843    </sect2>
844
845    <sect2 id="Predefined-Logical-Hosts"><title>Predefined Logical Hosts</title>
846
847      <para>&CCL; sets up logical pathname translations for logical hosts:  <literal>ccl</literal> and <literal>home</literal></para>
848
849      <indexterm><primary>CCL Logical Host</primary></indexterm>
850      <para>The <literal>CCL</literal> logical host should point to the
851        <literal>ccl</literal> directory.  It is used for a variety of
852        purposes by &CCL; including: locating &CCL; source code,
853        <literal>require</literal> and <literal>provide</literal>, accessing
854        foreign function information, and the &CCL; build process. It
855        is set to the value of the environment variable
856        <varname>CCL_DEFAULT_DIRECTORY</varname>, which is set by the
857        openmcl shell script <xref linkend="The-openmcl-Shell-Script"/>.  If
858        <varname>CCL_DEFAULT_DIRECTORY</varname> is not set, then it is set
859        to the directory containing the current heap image.</para>
860    </sect2>
861   
862   
863    <sect2>
864      <title>OS X (Darwin)</title>
865     
866      <para>&CCL; assumes that pathname strings are decomposed UTF-8.</para>
867    </sect2>
868    <sect2>
869      <title>Linux</title>
870     
871      <para>Pathname strings are treated as null-terminated strings
872        encoded according to the current locale.</para>
873    </sect2>
874    <sect2>
875      <title>FreeBSD</title>
876     
877      <para>Pathname strings are treated as null-terminated strings
878        encoded according to the current locale; a future release may
879        change this convention to use UTF-8.</para>
880    </sect2>
881  </sect1>
882
883  <sect1 id="Memory-Mapped-Files">
884    <title>Memory-mapped Files</title>
885    <para>In release 1.2 and later, &CCL;
886      supports <glossterm linkend="memory_mapped_file">memory-mapped
887        files</glossterm>. On operating systems that support memory-mapped
888      files (including Mac OS X, Linux, and FreeBSD), the operating
889      system can arrange for a range of virtual memory addresses to
890      refer to the contents of an open file. As long as the file remains
891      open, programs can read values from the file by reading addresses
892      in the mapped range.</para>
893
894    <para>Using memory-mapped files may in some cases be more
895      efficient than reading the contents of a file into a data
896      structure in memory.</para>
897
898    <para>&CCL; provides the
899      functions <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
900      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> to support
901      memory-mapping. These functions return vectors whose contents are
902      the contents of memory-mapped files. Reading an element of such a
903      vector returns data from the corresponding position in the
904      file.</para>
905
906    <para>Without memory-mapped files, a common idiom for reading the
907      contents of files might be something like this:</para>
908
909    <programlisting>
910(let* ((stream (open pathname :direction :input :element-type '(unsigned-byte 8)))
911       (vector (make-array (file-size-to-vector-size stream)
912                           :element-type '(unsigned-byte 8))))
913  (read-sequence vector stream))
914    </programlisting>
915
916    <para>Using a memory-mapped files has a result that is the same in
917      that, like the above example, it returns a vector whose contents are
918      the same as the contents of the file. It differs in that the above
919      example creates a new vector in memory and copies the file's
920      contents into it; using a memory-mapped file instead arranges for
921      the vector's elements to point to the file's contents on disk
922      directly, without copying them into memory first.</para>
923
924    <para>The vectors returned by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
925      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> are read-only; any
926      attempt to change an element of a vector returned by these
927      functions results in a memory-access error. &CCL; does not
928      currently support writing data to memory-mapped files.</para>
929
930    <para>Vectors created by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
931      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> are required to
932      respect &CCL;'s limit on the total size of an array. That means
933      that you cannot use these functions to create a vector longer
934      than <varname>ARRAY-TOTAL-SIZE-LIMIT</varname>, even if the filesystem
935      supports file sizes that are larger. The value
936      of <varname>ARRAY-TOTAL-SIZE-LIMIT</varname> is <varname>(EXPT 2 24)</varname>
937      on 32-but platforms; and <varname>(EXPT 2 56)</varname> on 64-bit
938      platforms.</para>
939
940    <para>
941      <indexterm zone="map-file-to-ivector"/>
942      <command><varname id="map-file-to-ivector">CCL:MAP-FILE-TO-IVECTOR</varname>
943        <parameter>pathname</parameter>
944        <parameter>element-type</parameter>
945        [Function]</command>
946    </para>
947
948    <variablelist>
949      <varlistentry>
950        <term><varname>pathname</varname></term>
951        <listitem>
952          <para>The pathname of the file to be memory-mapped.</para>
953        </listitem>
954      </varlistentry>
955     
956      <varlistentry>
957        <term><varname>element-type</varname></term>
958        <listitem>
959          <para>The element-type of the vector to be
960            created. Specified as
961            a <glossterm linkend="type-specifier">type-specifier</glossterm>
962            that names a subtype of either <varname>SIGNED-BYTE</varname>
963            or <varname>UNSIGNED-BYTE</varname>.</para>
964        </listitem>
965      </varlistentry>
966    </variablelist>
967
968
969    <para>
970      The <varname>map-file-to-ivector</varname> function tries to
971      open the file at <parameter>pathname</parameter> for reading. If
972      successful, the function maps the file's contents to a range of
973      virtual addresses. If successful, it returns a read-only vector
974      whose element-type is given
975      by <parameter>element-type</parameter>, and whose contents are
976      the contents of the memory-mapped file.
977    </para>
978
979    <para>The returned vector is
980      a <glossterm linkend="displaced-array">displaced-array</glossterm>
981      whose element-type is <varname>(UPGRADED-ARRAY-ELEMENT-TYPE
982        element-type)</varname>. The target of the displaced array is a
983      vector of type <varname>(SIMPLE-ARRAY element-type (*))</varname> whose
984      elements are the contents of the memory-mapped file.</para>
985
986    <para>Because of alignment issues, the mapped file's contents
987      start a few bytes (4 bytes on 32-bit platforms, 8 bytes on
988      64-bit platforms) into the vector. The displaced array returned
989      by <varname>CCL:MAP-FILE-TO-IVECTOR</varname> hides this overhead, but
990      it's usually more efficient to operate on the underlying simple
991      1-dimensional array.  Given a displaced array (like the value
992      returned by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>), the function
993      <varname>ARRAY-DISPLACEMENT</varname> returns the underlying array and
994      the displacement index in elements.
995    </para>
996
997    <para>Currently, &CCL; supports only read operations on
998      memory-mapped files. If you try to change the contents of an array
999      returned by <varname>map-file-to-ivector</varname>, &CCL; signals
1000      a memory error.</para>
1001
1002    <para>
1003      <indexterm zone="unmap-ivector"/>
1004      <command><varname id="unmap-ivector">CCL:UNMAP-IVECTOR</varname>
1005        <parameter>displaced-array</parameter>
1006        [Function]</command>
1007    </para>
1008
1009    <para>If the argument is a displaced-array returned
1010      by <varname>map-file-to-ivector</varname>, and if it has not yet
1011      been unmapped by this function,
1012      then <varname>unmap-ivector</varname> undoes the memory mapping,
1013      closes the mapped file, and changes the displaced-array so that its
1014      target is an empty vector (of length zero).</para>
1015
1016    <para>
1017      <indexterm zone="map-file-to-octet-vector"/>
1018      <command><varname id="map-file-to-octet-vector">CCL:MAP-FILE-TO-OCTET-VECTOR</varname>
1019        <parameter>pathname</parameter>
1020        [Function]</command>
1021    </para>
1022
1023    <para>This function is a synonym for <varname>(CCL:MAP-FILE-TO-IVECTOR
1024        pathname '(UNSIGNED-BYTE 8))</varname> It is provided as a convenience
1025      for the common case of memory-mapping a file as a vector of
1026      bytes.</para>
1027
1028    <para>
1029      <indexterm zone="unmap-octet-vector"/>
1030      <command><varname id="unmap-octet-vector">CCL:UNMAP-OCTET-VECTOR</varname>
1031        <parameter>displaced-array</parameter>
1032        [Function]</command>
1033    </para>
1034
1035    <para>This function is a synonym
1036      for <varname>(CCL:UNMAP-IVECTOR)</varname></para>
1037  </sect1>
1038
1039  <!-- ============================================================ -->
1040  <sect1 id="Static_Variables">
1041    <title>Static Variables</title>
1042
1043    <para>&CCL; supports the definition
1044      of <glossterm linkend="static_variable">static
1045        variables</glossterm>, whose values are the same across threads,
1046      and which may not be dynamically bound. The value of a static
1047      variable is thus the same across all threads; changing the value
1048      in one thread changes it for all threads.</para> 
1049
1050    <para>Attempting to dynamically rebind a static variable (for
1051      instance, by using <varname>LET</varname>, or using the variable name as
1052      a parameter in a <varname>LAMBDA</varname> form) signals an
1053      error. Static variables are shared global resources; a dynamic
1054      binding is private to a single thread.</para>
1055
1056    <para>Static variables therefore provide a simple way to share
1057      mutable state across threads. They also provide a simple way to
1058      introduce race conditions and obscure bugs into your code, since
1059      every thread reads and writes the same instance of a given static
1060      variable. You must take care, therefore, in how you change the
1061      values of static variables, and use normal multithreaded
1062      programming techniques, such as locks or semaphores, to protect
1063      against race conditions.</para>
1064
1065    <para>In &CCL;, access to a static variable is usually faster than
1066      access to a special variable that has not been declared
1067      static.</para>
1068
1069    <para>
1070      <indexterm zone="defstatic"/>
1071      <command><varname id="defstatic">DEFSTATIC</varname>
1072        <parameter>var</parameter>
1073        <parameter>value</parameter>
1074        &key;
1075        <parameter>doc-string</parameter>
1076        [Macro]</command>
1077    </para>
1078   
1079    <variablelist>
1080      <varlistentry>
1081        <term><varname>var</varname></term>
1082        <listitem>
1083          <para>The name of the new static variable.</para>
1084        </listitem>
1085      </varlistentry>
1086     
1087      <varlistentry>
1088        <term><varname>value</varname></term>
1089        <listitem>
1090          <para>The initial value of the new static variable.</para>
1091        </listitem>
1092      </varlistentry>
1093     
1094      <varlistentry>
1095        <term><varname>doc-string</varname></term>
1096        <listitem>
1097          <para>A documentation string that is assigned to the new
1098            variable.</para>
1099        </listitem>
1100      </varlistentry>
1101    </variablelist>
1102
1103    <para>Proclaims the
1104      variable <glossterm linkend="special_variable">special</glossterm>,
1105      assigns the variable the supplied value, and assigns
1106      the <varname>doc-string</varname> to the
1107      variable's <varname>VARIABLE</varname> documentation. Marks the
1108      variable static, preventing any attempt to dynamically rebind
1109      it. Any attempt to dynamically rebind <varname>var</varname>
1110      signals an error.</para>
1111  </sect1>
1112
1113  <!-- ============================================================ -->
1114  <sect1 id="Saving-Applications">
1115        <indexterm zone="Saving-Applications">
1116          <primary>save-application</primary>
1117        </indexterm>
1118    <title>Saving Applications</title>
1119
1120    <para>&CCL; provides the
1121      function <literal>CCL:SAVE-APPLICATION</literal>, which creates a file
1122      containing an archived Lisp memory image.</para>
1123
1124    <para>&CCL; consists of a small executable called the
1125      Lisp <glossterm linkend="lisp_image">kernel</glossterm>, which
1126      implements the very lowest level features of the Lisp system, and
1127      an <glossterm linkend="lisp_image">image</glossterm>, which
1128      contains the in-memory representation of most of the Lisp system,
1129      including functions, data structures, variables, and so on. When
1130      you start &CCL;, you are launching the kernel, which then locates
1131      and reads an image file, restoring the archived image in
1132      memory. Once the image is fully restored, the Lisp system is
1133      running.</para>
1134
1135    <para>Using <literal>CCL:SAVE-APPLICATION</literal>, you can create a
1136      file that contains a modified image, one that includes any changes
1137      you've made to the running Lisp system. If you later pass your
1138      image file to the &CCL; kernel as a command-line parameter, it
1139      then loads your image file instead of its default one, and &CCL;
1140      starts up with your modifications.</para>
1141
1142    <para>If this scenario seems to you like a convenient way to
1143      create an application, that's just as intended. You can create an
1144      application by modifying the running Lisp until it does what you
1145      want, then use <literal>CCL:SAVE-APPLICATION</literal> to preserve your
1146      changes and later load them for use.</para>
1147
1148    <para>In fact, you can go further than that. You can replace
1149      &CCL;'s <glossterm linkend="toplevel_function">toplevel
1150        function</glossterm> with your own, and then, when the image is
1151      loaded, the Lisp system immediately performs your tasks rather
1152      than the default tasks that make it a Lisp development system. If
1153      you save an image in which you have done this, the resulting Lisp
1154      system is your tool rather than a Lisp development system.</para>
1155
1156    <para>You can go a step further still. You can
1157      tell <literal>CCL:SAVE-APPLICATION</literal> to prepend the Lisp kernel
1158      to the image file. Doing this makes the resulting image into a
1159      self-contained executable binary. When you run the resulting file,
1160      the Lisp kernel immediately loads the attached image file and runs
1161      your saved system. The Lisp system that starts up can have any
1162      behavior you choose. It can be a Lisp development system, but with
1163      your customizations; or it can immediately perform some task of
1164      your design, making it a specialized tool rather than a general
1165      development system.</para>
1166
1167    <para>In other words, you can develop any application you like by
1168      interactively modifying &CCL; until it does what you want, then
1169      using <literal>CCL:SAVE-APPLICATION</literal> to preserve your changes
1170      in an executable image.</para>
1171
1172    <para>On Mac OS X,
1173      the <link linkend="application_builder">application builder</link>
1174      uses <literal>CCL:SAVE-APPLICATION</literal> to create the executable
1175      portion of the <glossterm linkend="application_bundle">application
1176        bundle</glossterm>. Double-clicking the application bundle runs
1177      the executable image created
1178      by <literal>CCL:SAVE-APPLICATION</literal>.</para>
1179
1180    <para>Also on Mac OS X, &CCL; supports an object type
1181      called <literal>MACPTR</literal>, which is the type of pointers into the
1182      foreign (Mac OS) heap. Examples of
1183      commonly-user <literal>MACPTR</literal> objects are Cocoa windows and
1184      other dynamically-allocated Mac OS system objects.</para>
1185
1186    <para>Because a <literal>MACPTR</literal> object is a pointer into a
1187      foreign heap that exists for the lifetime of the running Lisp
1188      process, and because a saved image is used by loading it into a
1189      brand new Lisp process, saved <literal>MACPTR</literal> objects cannot
1190      be relied on to point to the same things when reconstituted from a
1191      saved image. In fact, a restored <literal>MACPTR</literal> object might
1192      point to anything at all&mdash;for example an arbitrary location
1193      in the middle of a block of code, or a completely nonexistent
1194      virtual address.</para> 
1195
1196    <para>For that reason, <literal>CCL:SAVE-APPLICATION</literal> converts
1197      all <literal>MACPTR</literal> objects to <literal>DEAD-MACPTR</literal>
1198      objects when writing them to an image
1199      file. A <literal>DEAD-MACPTR</literal> is functionally identical to
1200      a <literal>MACPTR</literal>, except that code that operates
1201      on <literal>MACPTR</literal> objects distinguishes them
1202      from <literal>DEAD-MACPTR</literal> objects and can handle them
1203      appropriately&mdash;signaling errors, for example.</para>
1204
1205    <para>As of &CCL; 1.2, there is one exception to the conversion
1206      of <literal>MACPTR</literal> to <literal>DEAD-MACPTR</literal> objects:
1207      a <literal>MACPTR</literal> object that points to the address 0 is not
1208      converted, because address 0 can always be relied upon to refer to
1209      the same thing.</para>
1210
1211        <indexterm zone="Saving-Applications">
1212          <primary>+NULL-PTR+</primary>
1213        </indexterm>
1214    <para>As of &CCL; 1.2, the constant <literal>CCL:+NULL-PTR+</literal>
1215      refers to a <literal>MACPTR</literal> object that points to address 0.</para>
1216
1217    <para>On all supported platforms, you can
1218      use <literal>CCL:SAVE-APPLICATION</literal> to create a command-line
1219      tool that runs the same way any command-line program
1220      does. Alternatively, if you choose not to prepend the kernel, you
1221      can save an image and then later run it by passing it as a
1222      command-line parameter to the <literal>opencml</literal>
1223      or <literal>opencml64</literal> script.</para>
1224
1225    <para>
1226      <indexterm zone="save-application"/>
1227      <command><varname id="save-application">SAVE-APPLICATION</varname>
1228        <parameter>filename</parameter>
1229        &key;
1230        <parameter>toplevel-function</parameter>
1231        <parameter>init-file</parameter>
1232        <parameter>error-handler</parameter>
1233        <parameter>application-class</parameter>
1234        <parameter>clear-clos-caches</parameter>
1235        <parameter>(purify t)</parameter>
1236        <parameter>impurify</parameter>
1237        <parameter>(mode #o644)</parameter>
1238        <parameter>prepend-kernel</parameter>
1239        [Function]</command>
1240    </para>
1241   
1242    <variablelist>
1243      <varlistentry>
1244        <term><varname>filename</varname></term>
1245        <listitem>
1246          <para>The pathname of the file to be created when &CCL;
1247            saves the application.</para>
1248        </listitem>
1249      </varlistentry>
1250     
1251      <varlistentry>
1252        <term><varname>toplevel-function</varname></term>
1253        <listitem>
1254          <para>The function to be executed after startup is
1255            complete. The toplevel is a function of no arguments that
1256            performs whatever actions the lisp system should perform
1257            when launched with this image.</para>
1258          <para>If this parameter is not supplied, &CCL; uses its
1259            default toplevel. The default toplevel runs
1260            the <glossterm linkend="REPL">read-eval-print
1261              loop</glossterm>.</para>
1262        </listitem>
1263      </varlistentry>
1264
1265      <varlistentry>
1266        <term><varname>init-file</varname></term>
1267        <listitem>
1268          <para>The pathname of a Lisp file to be loaded when the
1269            image starts up. You can place initialization expressions in
1270            this file, and use it to customize the behavior of the Lisp
1271            system when it starts up.</para>
1272        </listitem>
1273      </varlistentry>
1274     
1275      <varlistentry>
1276        <term><varname>error-handler</varname></term>
1277        <listitem>
1278          <para>The error-handling mode for the saved image. The
1279            supplied value determines what happens when an error is not
1280            handled by the saved image. Valid values
1281            are <literal>:quit</literal> (Lisp exits with an error
1282            message); <literal>:quit-quietly</literal> (Lisp exits without an
1283            error message); or <literal>:listener</literal> (Lisp enters a
1284            break loop, enabling you to debug the problem by interacting
1285            in a listener). If you don't supply this parameter, the
1286            saved image uses the default error handler
1287            (<literal>:listener</literal>).</para>
1288        </listitem>
1289      </varlistentry>
1290
1291      <varlistentry>
1292        <term><varname>application-class</varname></term>
1293        <listitem>
1294          <para>The CLOS class that represents the saved Lisp
1295            application. Normally you don't need to supply this
1296            parameter; <literal>CCL:SAVE-APPLICATION</literal> uses the
1297            class <literal>CCL:LISP-DEVELOPMENT-SYSTEM</literal>. In some
1298            cases you may choose to create a custom application class;
1299            in that case, pass the name of the class as the value for
1300            this parameter.</para>
1301        </listitem>
1302      </varlistentry>
1303     
1304      <varlistentry>
1305        <term><varname>clear-clos-caches</varname></term>
1306        <listitem>
1307          <para>If true, ensures that CLOS caches are emptied before
1308            saving the image. Normally you don't need to supply this
1309            parameter, but if for some reason you want to ensure the
1310            CLOS caches are clear when the image starts up, you can pass
1311            any true value.</para>
1312        </listitem>
1313      </varlistentry>
1314     
1315     
1316    </variablelist>
1317
1318    <para></para>
1319  </sect1>
1320
1321</chapter>
Note: See TracBrowser for help on using the repository browser.