<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
          <!ENTITY rest "<varname>&amp;rest</varname>">
          <!ENTITY key "<varname>&amp;key</varname>">
          <!ENTITY optional "<varname>&amp;optional</varname>">
          <!ENTITY body "<varname>&amp;body</varname>">
          <!ENTITY aux "<varname>&amp;aux</varname>">
          <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
          <!ENTITY CCL "Clozure CL">
          ]>

<chapter id="using-ccl"><title>Using &CCL;</title>
  
  <!-- ============================================================ -->
  <sect1 id="using-ccl-introduction"><title>Introduction</title>
    
    <para>The Common Lisp standard allows considerable latitude in the
      details of an implementation, and each particular Common Lisp
      system has some idiosyncrasies. This chapter describes ordinary
      user-level features of &CCL;, including features that may be
      part of the Common Lisp standard, but which may have quirks or
      details in the &CCL; implementation that are not described by
      the standard. It also describes extensions to the standard; that
      is, features of &CCL; that are not part of the Common Lisp
      standard at all.</para>

  </sect1>

  <!-- ============================================================ -->
  <sect1 id="Trace"><title>Trace</title>

    <para>
      &CCL;'s tracing facility is invoked by an extended version of the Common Lisp
      <varname>trace</varname> macro.  Extensions allow tracing of methods, as well as finer control
      over tracing actions.
    </para>

    <para>
      <indexterm zone="trace"/>
      <command><varname id="trace">TRACE</varname> {<replaceable>keyword</replaceable>
        <replaceable>global-value</replaceable>}* {<replaceable>spec</replaceable> |
        (<replaceable>spec</replaceable> {<replaceable>keyword</replaceable>
        <replaceable>local-value</replaceable>}*)}* [Macro]</command>
    </para>

    <para>
      The <varname>trace</varname> macro encapsulates the functions named by
      <replaceable>spec</replaceable>s, causing trace actions to take place on entry and
      exit from each function.  The default actions print a message on function entry and
      exit. <replaceable>Keyword</replaceable>/<replaceable>value</replaceable> options
      can be used to specify changes in the default behavior.
    </para>

    <para>
      Invoking <varname>(trace)</varname> without arguments returns a list of functions being traced.
    </para>
    
    <para>
      A <replaceable>spec</replaceable> is either a symbol that is the name of a function, or an
      expression of the form <varname>(setf <replaceable>symbol</replaceable>)</varname>, or a
      specific method of a generic function in the form <varname>(:method
        <replaceable>gf-name</replaceable> {<replaceable>qualifier</replaceable>}*
        ({<replaceable>specializer</replaceable>}*))</varname>, where a
      <replaceable>specializer</replaceable> can be the name of a class or an <varname>EQL</varname>
      specializer.
    </para>

    <para>
      A <replaceable>spec</replaceable> can also be a string naming a package, or equivalently a
      list <varname>(:package <replaceable>package-name</replaceable>)</varname>, in order to
      request that all functions in the package to be traced.
    </para>

    <para>
      By default, whenever a traced function is entered or exited, a short message is
      printed on <varname>*trace-output*</varname> showing the arguments on entry and
      values on exit.  Options specified as key/value pairs can be used to modify this
      behavior.  Options preceding the function <replaceable>spec</replaceable>s apply to
      all the functions being traced.  Options specified along with a
      <replaceable>spec</replaceable> apply to that spec only and override any
      global options. The following options are supported:
    </para>

    <variablelist>

      <varlistentry>
	    <term><varname>:methods {T | nil}</varname></term>
	    <listitem>
	      <para> If true, and if applied to a <replaceable>spec</replaceable> naming a generic
	        function, arranges to trace all the methods of the generic function in addition to the
	        generic function itself.
	      </para>
	    </listitem>
      </varlistentry>

      <varlistentry>
	    <term><varname>:inside <replaceable>outside-spec</replaceable>
	        | ({<replaceable>outside-spec</replaceable>}*)</varname></term>
	    <listitem>
	      <para>Inhibits all trace actions unless the current
	        invocation of the function being traced is inside one of the
	        <replaceable>outside-spec</replaceable>'s, i.e. unless a function named by one of the
	        <replaceable>outside-spec</replaceable>'s is currently on the stack.
	        <replaceable>outside-spec</replaceable> can name a function, a
	        method, or a package, as above.
	      </para>
	    </listitem>
      </varlistentry>

      <varlistentry>
	    <term><varname>:if <replaceable>form</replaceable></varname></term>
	    <term><varname>:condition <replaceable>form</replaceable></varname></term>
	    <listitem>
	      <para> Evaluates <replaceable>form</replaceable> whenever the function being traced is
	        about to be entered, and inhibits all trace actions if <replaceable>form</replaceable>
	        returns nil. The form may reference the lexical variable <varname>ccl::args</varname>,
	        which is a list of the arguments in this call. <varname>:condition</varname> is just a
	        synonym for <varname>:if</varname>, though if both are specified, both must return non-nil.
	      </para>
	    </listitem>
      </varlistentry>

      <varlistentry>
	    <term><varname>:before-if <replaceable>form</replaceable></varname></term>
	    <listitem>
	      <para> Evaluates <replaceable>form</replaceable> whenever the function being traced is
	        about to be entered, and inhibits the entry trace actions if
	        <replaceable>form</replaceable> returns nil.  The form may reference the lexical variable
	        <varname>ccl::args</varname>, which is a list of the arguments in this call. If both
	        <varname>:if</varname> and <varname>:before-if</varname> are specified, both must return
	        non-nil in order for the before entry actions to happen.
	      </para>
	    </listitem>
      </varlistentry>

      <varlistentry>
	    <term><varname>:after-if <replaceable>form</replaceable></varname></term>
	    <listitem>
	      <para> Evaluates <replaceable>form</replaceable> whenever the function being traced has
	        just exited, and inhibits the exit trace actions if <replaceable>form</replaceable>
	        returns nil.  The form may reference the lexical variable <varname>ccl::vals</varname>,
	        which is a list of values returned by this call. If both <varname>:if</varname> and
	        <varname>:after-if</varname> are specified, both must return non-nil in order for the
	        after exit actions to happen.
	      </para>
	    </listitem>
      </varlistentry>

      <varlistentry>
	    <term><varname>:print-before <replaceable>form</replaceable></varname></term>
	    <listitem>
	      <para> Evaluates <replaceable>form</replaceable> whenever the function being traced is
	        about to be entered, and prints the result before printing the standard entry message.
	        The form may reference the lexical variable <varname>ccl::args</varname>, which is a list
	        of the arguments in this call.  To see multiple forms, use <varname>values</varname>:
	        <varname>:print-before (values (one-thing) (another-thing))</varname>.
	      </para>
	    </listitem>
      </varlistentry>

      <varlistentry>
	    <term><varname>:print-after <replaceable>form</replaceable></varname></term>
	    <listitem>
	      <para> Evaluates <replaceable>form</replaceable> whenever the function being traced has
	        just exited, and prints the result after printing the standard exit message.  The form may
	        reference the lexical variable <varname>ccl::vals</varname>, which is a list of values
	        returned by this call. To see multiple forms, use <varname>values</varname>:
	        <varname>:print-after (values (one-thing) (another-thing))</varname>.
	      </para>
	    </listitem>
      </varlistentry>

      <varlistentry>
	    <term><varname>:print <replaceable>form</replaceable></varname></term>
	    <listitem>
	      <para>Equivalent to <varname>:print-before <replaceable>form</replaceable> :print-after <replaceable>form</replaceable></varname>.
	      </para>
	    </listitem>
      </varlistentry>

      <varlistentry>
	    <term><varname>:eval-before <replaceable>form</replaceable></varname></term>
	    <listitem>
	      <para>Evaluates <replaceable>form</replaceable> whenever the function being traced is
	        about to be entered.  The form may reference the lexical variable
	        <varname>ccl::args</varname>, which is a list of the arguments in this call.
	      </para>
	    </listitem>
      </varlistentry>

      <varlistentry>
	    <term><varname>:eval-after <replaceable>form</replaceable></varname></term>
	    <listitem>
	      <para>Evaluates <replaceable>form</replaceable> whenever the function being has just
	        exited.  The form may reference the lexical variable <varname>ccl::vals</varname>, which
	        is a list of values returned by this call.
	      </para>
	    </listitem>
      </varlistentry>

      <varlistentry>
	    <term><varname>:eval <replaceable>form</replaceable></varname></term>
	    <listitem>
	      <para>Equivalent to <varname>:eval-before <replaceable>form</replaceable>
	          :eval-after <replaceable>form</replaceable></varname>.
	      </para>
	    </listitem>
      </varlistentry>

      <varlistentry>
	    <term><varname>:break-before <replaceable>form</replaceable></varname></term>
	    <listitem>
	      <para>Evaluates <replaceable>form</replaceable> whenever the function being traced is
	        about to be entered, and if the result is non-nil, enters a debugger break loop.  The form
	        may reference the lexical variable <varname>ccl::args</varname>, which is a list of the
	        arguments in this call.
	      </para>
	    </listitem>
      </varlistentry>

      <varlistentry>
	    <term><varname>:break-after <replaceable>form</replaceable></varname></term>
	    <listitem>
	      <para>Evaluates <replaceable>form</replaceable> whenever the function being traced has
	        just exited, and if the result is non-nil, enters a debugger break loop. The form may
	        reference the lexical variable <varname>ccl::vals</varname>, which is a list of values
	        returned by this call.
	      </para>
	    </listitem>
      </varlistentry>

      <varlistentry>
	    <term><varname>:break <replaceable>form</replaceable></varname></term>
	    <listitem>
	      <para>Equivalent to <varname>:break-before <replaceable>form</replaceable> :break-after <replaceable>form</replaceable></varname>.
	      </para>
	    </listitem>
      </varlistentry>

      <varlistentry>
	    <term><varname>:backtrace-before <replaceable>form</replaceable></varname></term>
	    <term><varname>:backtrace <replaceable>form</replaceable></varname></term>
	    <listitem>
	      <para>Evaluates <replaceable>form</replaceable> whenever the function being traced is
	        about to be entered.  The form may reference the lexical variable
	        <varname>ccl::args</varname>, which is a list of the arguments in this call. The value
	        returned by <replaceable>form</replaceable> is intepreted as follows:
	      </para>

	      <variablelist>

	        <varlistentry>
	          <term><varname>nil</varname></term>
	          <listitem><para>does nothing</para></listitem>
	        </varlistentry>

	        <varlistentry>
	          <term><varname>:detailed</varname></term>
	          <listitem><para>prints a detailed backtrace to
	              <varname>*trace-output*</varname>.</para></listitem>
	        </varlistentry>

	        <varlistentry>
	          <term><varname>(:detailed <replaceable>integer</replaceable>)</varname></term>
	          <listitem><para>prints the top <replaceable>integer</replaceable> frames of detailed
	              backtrace to <varname>*trace-output*</varname>.
	          </para></listitem>
	        </varlistentry>

	        <varlistentry>
	          <term><replaceable>integer</replaceable></term>
	          <listitem><para>prints top <replaceable>integer</replaceable> frames of a terse
	              backtrace to <varname>*trace-output*</varname>.
	          </para></listitem>
	        </varlistentry>

	        <varlistentry>
	          <term>anything else</term>
	          <listitem><para>prints a terse backtrace to <varname>*trace-output*</varname>.
	          </para></listitem>
	        </varlistentry>
	      </variablelist>
	      <para>
	        Note that unlike with the other options, <varname>:backtrace</varname> is equivalent to
	        <varname>:backtrace-before</varname> only, not both before and after, since it's usually
	        not helpful to print the same backtrace both before and after the function call.
	      </para>
	    </listitem>
      </varlistentry>

      <varlistentry>
	    <term><varname>:backtrace-after <replaceable>form</replaceable></varname></term>
	    <listitem>
	      <para>Evaluates <replaceable>form</replaceable> whenever the function being traced has
	        just exited.  The form may reference the lexical variable <varname>ccl::vals</varname>,
	        which is a list of values returned by this call. The value returned by
	        <replaceable>form</replaceable> is intepreted as follows:
	      </para>

	      <variablelist>

	        <varlistentry>
	          <term><varname>nil</varname></term>
	          <listitem><para>does nothing</para></listitem>
	        </varlistentry>

	        <varlistentry>
	          <term><varname>:detailed</varname></term>
	          <listitem><para>prints a detailed backtrace to
	              <varname>*trace-output*</varname>.</para></listitem>
	        </varlistentry>

	        <varlistentry>
	          <term><varname>(:detailed <replaceable>integer</replaceable>)</varname></term>
	          <listitem><para>prints the top <replaceable>integer</replaceable> frames of detailed
	              backtrace to <varname>*trace-output*</varname>.
	          </para></listitem>
	        </varlistentry>

	        <varlistentry>
	          <term><replaceable>integer</replaceable></term>
	          <listitem><para>prints top <replaceable>integer</replaceable> frames of a terse
	              backtrace to <varname>*trace-output*</varname>.
	          </para></listitem>
	        </varlistentry>

	        <varlistentry>
	          <term>anything else</term>
	          <listitem><para>prints a terse backtrace to <varname>*trace-output*</varname>.
	          </para></listitem>
	        </varlistentry>
	      </variablelist>
	    </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>:before</varname> <replaceable>action</replaceable></term>
        <listitem>
	      <para>specifies the action to be taken just before the traced function is entered.  <replaceable>action</replaceable> is one of:</para>

	      <variablelist>
	        <varlistentry>
	          <term><varname>:print</varname></term>
	          <listitem>
		        <para>The default, prints a short indented message showing the function name and the invocation arguments</para>
	          </listitem>
	        </varlistentry>

	        <varlistentry>
	          <term><varname>:break</varname></term>
	          <listitem>
		        <para>Equivalent to <varname>:before :print :break-before t</varname></para>
	          </listitem>
	        </varlistentry>

	        <varlistentry>
	          <term><varname>:backtrace</varname></term>
	          <listitem>
		        <para>Equivalent to <varname>:before :print :backtrace-before t</varname></para>
	          </listitem>
	        </varlistentry>


	        <varlistentry>
	          <term><replaceable>function</replaceable></term>
	          <listitem>
		        <para>
                  Any other value is interpreted as a function to call on entry instead of
                  printing the standard entry message.  It is called with its first
                  argument being the name of the function being traced, the remaining
                  arguments being all the arguments to the function being traced, and
                  <varname>ccl:*trace-level*</varname> bound to the current nesting level
                  of trace actions. </para>
	          </listitem>
	        </varlistentry>
	      </variablelist>
	    </listitem>
      </varlistentry>

      <varlistentry>

        <term><varname>:after</varname> <replaceable>action</replaceable></term>
        <listitem>

	      <para>specifies the action to be taken just after the traced function exits.  <replaceable>action</replaceable> is one of:</para>

	      <variablelist>
	        <varlistentry>
	          <term><varname>:print</varname></term>
	          <listitem>
	            <para>The default, prints a short indented message showing the function name and the
	              returned values </para>
	          </listitem>
	        </varlistentry>

	        <varlistentry>
	          <term><varname>:break</varname></term>
	          <listitem>
	            <para>Equivalent to <varname>:after :print :break-after t</varname></para>
	          </listitem>
	        </varlistentry>

		    <varlistentry>
		      <term><varname>:backtrace</varname></term>
		      <listitem>
		        <para>Equivalent to <varname>:after :print :backtrace-after t</varname></para>
		      </listitem>
		    </varlistentry>

	        <varlistentry>
	          <term><replaceable>function</replaceable></term>
	          <listitem>
	            <para>Any other value is interpreted as a function to
	              call on exit instead of printing the standard exit
	              message.  It is called with its first argument being
	              the name of the function being traced, the
	              remaining arguments being all the values returned by the function
	              being traced, and ccl:*trace-level* bound to the current
	              nesting level of trace actions.
	            </para>
	          </listitem>
	        </varlistentry>
	      </variablelist>
        </listitem>
      </varlistentry>

    </variablelist>


    <para>
      <indexterm zone="trace-level"/>
      <command><varname id="trace-level">CCL:*TRACE-LEVEL*</varname>    [Variable]</command>
    </para>

    <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>

    <para>
      <indexterm zone="trace-max-indent"/>
      <command><varname id="trace-max-indent">CCL:*TRACE-MAX-INDENT*</varname>    [Variable]</command>
    </para>

    <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>

    <para>
      <indexterm zone="trace-function"/>
      <command><varname id="trace-function">CCL:TRACE-FUNCTION</varname> <replaceable>spec</replaceable> &key; {<replaceable>keyword</replaceable> <replaceable>value</replaceable>}*    [Function]</command>
    </para>
    
    <para>
      This is a functional version of the TRACE macro.  <replaceable>spec</replaceable> and
      <replaceable>keyword</replaceable>s are as for TRACE, except that all arguments are evaluated.
    </para>

    <para>
      <indexterm zone="trace-print-level"/>
      <command><varname id="trace-print-level">CCL:*TRACE-PRINT-LEVEL*</varname>   [Variable]</command>
    </para>

    <para>The default print actions bind <varname>CL:*PRINT-LEVEL*</varname> to this value while
      printing. Note that this rebinding is only in effect during the default entry and exit messages.
      It does not apply to printing of <varname>:print-before/:print-after</varname> forms or any
      explicit printing done by user code.</para>

    <para>
      <indexterm zone="trace-print-length"/>
      <command><varname id="trace-print-length">CCL:*TRACE-PRINT-LENGTH*</varname>    [Variable]</command>
    </para>
    
    <para>The default print actions bind <varname>CL:*PRINT-LENGTH*</varname> to this value while
      printing. Note that this rebinding is only in effect during the default entry and exit messages.
      It does not apply to printing of <varname>:print-before/:print-after</varname> forms or any
      explicit printing done by user code.</para>

    <para>
      <indexterm zone="trace-bar-frequency"/>
      <command><varname id="trace-bar-frequency">CCL:*TRACE-BAR-FREQUENCY*</varname>    [Variable]</command>
    </para>

    <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>


  </sect1>

  <sect1 id="Advising"><title>Advising</title>
  <para>
    The <literal>advise</literal> macro can be thought of as a more
    general version of <literal>trace</literal>. It allows code that
    you specify to run before, after, or around a given function, for
    the purpose of changing the behavior of the function. Each piece
    of added code is called a piece of advice. Each piece of advice
    has a unique name, so that you can have multiple pieces of advice
    on the same function, including multiple
    <literal>:before</literal>, <literal>:after</literal>, and
    <literal>:around</literal> pieces of advice.
  </para>
  <para>
    The <literal>:name</literal> and <literal>:when</literal>
    keywords serve to identify the piece of advice.  A later call to
    <literal>advise</literal> with the same values of
    <literal>:name</literal> and <literal>:when</literal> will replace
    the existing piece of advice; a call with different values will not.
  </para>

  <refentry id="m_advise">
    <indexterm zone="m_advise">
      <primary>advise</primary>
    </indexterm>

    <refnamediv>
      <refname>ADVISE</refname>
      <refpurpose>
	Add a piece of advice to the function or method specified by
	<varname>spec</varname> according to
	<varname>form</varname>.
      </refpurpose>
      <refclass>Macro</refclass>
    </refnamediv>
    
    <refsynopsisdiv>
      <synopsis><function>advise</function> spec form &key; when name</synopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Arguments and Values</title>
      <variablelist>
	<varlistentry>
	  <term>spec</term>
	  <listitem>
	    <para>
	      A specification of the function on which to put the
	      advice.  This is either a symbol that is the name of a
	      function or generic function, or an expression of the
	      form (setf <replaceable>symbol</replaceable>), or a
	      specific method of a generic function in the form
	      (:method symbol {qualifiers} (specializer {specializer})).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>form</term>
	  <listitem>
	    <para>
	      A form to execute before, after, or around the advised
	      function. The form can refer to the variable arglist
	      that is bound to the arguments with which the advised
	      function was called. You can exit from form with
	      (return).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>name</term>
	  <listitem>
	    <para>
	      A name that identifies the piece of advice.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>when</term>
	  <listitem>
	    <para>
	      An argument that specifies when the piece of advice is
	      run. There are three allowable values. The default is
	      <literal>:before</literal>, which specifies that form is
	      executed before the advised function is called. Other
	      possible values are <literal>:after</literal>, which
	      specifies that form is executed after the advised
	      function is called, and <literal>:around</literal>,
	      which specifies that form is executed around the call to
	      the advised function. Use <literal>(:do-it)</literal>
	      within form to indicate invocation of the original
	      definition.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </refsect1>
    
    <refsect1>
      <title>Examples</title>
      <para>
	The function <literal>foo</literal>, already defined, does
	something with a list of numbers. The following code uses a
	piece of advice to make foo return zero if any of its
	arguments is not a number. Using :around advice, you can do
	the following:
	<programlisting>
(advise foo (if (some #'(lambda (n) (not (numberp n))) arglist)
	      0
	      (:do-it))
	:when :around :name :zero-if-not-nums)
	</programlisting>
      </para>
      <para>
	To do the same thing using a :before piece of advice:
	<programlisting>
(advise foo (if (some #'(lambda (n) (not (numberp n))) arglist)
	      (return 0))
	:when :before :name :zero-if-not-nums)
	</programlisting>
      </para>
    </refsect1>
  </refentry>

  <refentry id="m_unadvise">
    <indexterm zone="m_unadvise">
      <primary>unadvise</primary>
    </indexterm>

    <refnamediv>
      <refname>UNADVISE</refname>
      <refpurpose>
	Remove the piece or pieces of advice matching <varname>spec</varname>,
	<varname>when</varname>, and <varname>name</varname>.
      </refpurpose>
      <refclass>Macro</refclass>
    </refnamediv>
    
    <refsynopsisdiv>
      <synopsis><function>unadvise</function> spec &key; when name</synopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>
      <para>
	The unadvise macro removes the piece or pieces of advice
	matching <literal>spec</literal>, <literal>when</literal>,
	and <literal>name</literal>. When the value of
	<literal>spec</literal> is t and the values of <literal>when</literal>
	and <literal>name</literal> are nil, unadvise
	removes every piece of advice; when <literal>spec</literal> is
	t, the argument <literal>when</literal> is nil, and
	<literal>name</literal> is non-nil, unadvise removes all
	pieces of advice with the given name.
      </para>
    </refsect1>
    <refsect1>
      <title>Arguments and Values</title>
      <para>
	The arguments have the same meaning as in
	<xref linkend="m_advise"/>.
      </para>
    </refsect1>
  </refentry>

  <refentry id="m_advisedp">
    <indexterm zone="m_advisedp">
      <primary>advisedp</primary>
    </indexterm>

    <refnamediv>
      <refname>ADVISEDP</refname>
      <refpurpose>
	Return a list of the pieces of advice matching <varname>spec</varname>,
	<varname>when</varname>, and <varname>name</varname>.
      </refpurpose>
      <refclass>Macro</refclass>
    </refnamediv>
    
    <refsynopsisdiv>
      <synopsis><function>advisedp</function> spec &key; when name</synopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Description</title>
      <para>
	The advisedp macro returns a list of existing pieces of advice
	that match <literal>spec</literal>, <literal>when</literal>,
	and <literal>name</literal>. When the value of
	<literal>spec</literal> is t and the values of
	<literal>when</literal> and <literal>name</literal> are nil,
	advisedp returns all existing pieces of advice.
      </para>
    </refsect1>
    <refsect1>
      <title>Arguments and Values</title>
      <para>
	The arguments have the same meaning as in
	<xref linkend="m_advise"/>.
      </para>
    </refsect1>
  </refentry>

  </sect1>

  <sect1 id="Directory"><title>Directory</title>
  <para>&CCL;'s <varname>DIRECTORY</varname> function accepts the following
implementation-dependent keyword arguments:</para>
  <variablelist>
  <varlistentry>
     <term><varname>:files</varname> <replaceable>boolean</replaceable></term>
     <listitem>
       <para> If true, includes regular (non-directory) files in DIRECTORY's output.  Defaults to T.</para>
     </listitem>
  </varlistentry>
  <varlistentry>
     <term><varname>:directories</varname> <replaceable>boolean</replaceable></term>
     <listitem>
       <para> If true, includes directories in DIRECTORY's output.  Defaults to NIL.</para>
     </listitem>
  </varlistentry>
  <varlistentry>
     <term><varname>:all</varname> <replaceable>boolean</replaceable></term>
     <listitem>
       <para> If true, includes files and directories whose names start with a dot character in DIRECTORY's output.  (Entries whose name is "." or ".." are never included.) Defaults to T.</para>
     </listitem>
  </varlistentry>
  <varlistentry>
     <term><varname>:follow-links</varname> <replaceable>boolean</replaceable></term>
     <listitem>
       <para> If true, includes the TRUENAMEs of symbolic or hard links in DIRECTORY's output; if false, includes the link filenames without attempting to resolve them. Defaults to T.</para>
       <para>Note that legacy HFS alias files are treated as plain files.</para>
     </listitem>
  </varlistentry>
  </variablelist>
  </sect1>
  <sect1 id="Unicode"><title>Unicode</title>

    <para>All characters and strings in &CCL; fully support Unicode by
    using UTF-32. There is only one <literal>CHARACTER</literal> type
    and one <literal>STRING</literal> type in &CCL;.  There has been a
    lot of discussion about this decision which can be found by
    searching the openmcl-devel archives at <ulink
    url="http://clozure.com/pipermail/openmcl-devel/"/>.  Suffice it
    to say that we decided that the simplicity and speed advantages of
    only supporting UTF-32 outweigh the space disadvantage.</para>



  <sect2 id="unicode-characters"><title>Characters</title>
    <para>There is one <literal>CHARACTER</literal> type in &CCL;.
    All <literal>CHARACTER</literal>s are
    <literal>BASE-CHAR</literal>s.  <varname>CHAR-CODE-LIMIT</varname>
    is now <literal>#x110000</literal>, which means that all Unicode
    characters can be directly represented.  As of Unicode 5.0, only
    about 100,000 of 1,114,112 possible <literal>CHAR-CODE</literal>s
    are actually defined. The function <function>CODE-CHAR</function>
    knows that certain ranges of code values (notably
    <literal>#xd800</literal>-<literal>#xddff</literal>) will never be
    valid character codes and will return <literal>NIL</literal> for
    arguments in that range, but may return a
    non-<literal>NIL</literal> value (an undefined/non-standard
    <literal>CHARACTER</literal> object) for other unassigned code
    values.</para>

    <para>&CCL; supports character names of the form
    <literal>u+xxxx</literal>&mdash;where <literal>x</literal> is a
    sequence of one or more hex digits.  The value of the hex digits
    denotes the code of the character.  The <literal>+</literal>
    character is optional, so <literal>#\u+0020</literal>,
    <literal>#\U0020</literal>, and <literal>#\U+20</literal> all
    refer to the <literal>#\Space</literal> character.</para>

    <para>Characters with codes in the range
    <literal>#xa0</literal>-<literal>#x7ff</literal> also have
    symbolic names These are the names from the Unicode standard with
    spaces replaced by underscores.  So
    <literal>#\Greek_Capital_Letter_Epsilon</literal> can be used to
    refer to the character whose <function>CHAR-CODE</function> is
    <literal>#x395</literal>.  To see the complete list of supported
    character names, look just below the definition for
    <function>register-character-name</function> in
    <literal>ccl:level-1;l1-reader.lisp</literal>.</para>
  </sect2>


  <sect2 id="External-Formats"><title>External Formats</title>
    <para><function>OPEN</function>, <function>LOAD</function>, and
    <function>COMPILE-FILE</function> all take an
    <literal>:EXTERNAL-FORMAT</literal> keyword argument.  The value
    of <literal>:EXTERNAL-FORMAT</literal> can be
    <literal>:DEFAULT</literal> (the default value), a line
    termination keyword (see <xref
    linkend="Line-Termination-Keywords"/>), a character encoding
    keyword (see <xref linkend="Character-Encodings"/>), an
    external-format object created using
    <function>CCL::MAKE-EXTERNAL-FORMAT</function> (see <xref
    linkend="f_make-external-format"/>), or a plist with keys:
    <literal>:DOMAIN</literal>, <literal>:CHARACTER-ENCODING</literal>
    and <literal>:LINE-TERMINATION</literal>.  If
    <parameter>argument</parameter> is a plist, the result of
    <literal>(APPLY #'MAKE-EXTERNAL-FORMAT
    <parameter>argument</parameter>)</literal> will be used.</para>

    <para>If <literal>:DEFAULT</literal> is specified, then the value
    of <varname>CCL:*DEFAULT-EXTERNAL-FORMAT*</varname> is used.  If
    no line-termination is specified, then the value of
    <varname>CCL:*DEFAULT-LINE-TERMINATION*</varname> is used, which
    defaults to <literal>:UNIX</literal>.  If no character encoding is
    specified, then
    <varname>CCL:*DEFAULT-FILE-CHARACTER-ENCODING*</varname> is used
    for file streams and
    <varname>CCL:*DEFAULT-SOCKET-CHARACTER-ENCODING*</varname> is used
    for socket streams.  The default, default character encoding is
    <literal>NIL</literal> which is a synonym for
    <literal>:ISO-8859-1</literal>.</para>

    <para>Note that the set of keywords used to denote
    CHARACTER-ENCODINGs and the set of keywords used to denote
    line-termination conventions is disjoint: a keyword denotes at
    most a character encoding or a line termination convention, but
    never both.</para>

    <para>EXTERNAL-FORMATs are objects (structures) with two
    read-only fields that can be accessed via the functions:
    <function>EXTERNAL-FORMAT-LINE-TERMINATION</function> and
    <function>EXTERNAL-FORMAT-CHARACTER-ENCODING</function>.</para>

  
    <refentry id="v_default-external-format">
	<indexterm zone="v_default-external-format">
	  <primary>*default-external-format*</primary>
	</indexterm>
	    
	<refnamediv>
	  <refname>CCL:*DEFAULT-EXTERNAL-FORMAT*</refname>
	  <refpurpose></refpurpose>
	  <refclass>Variable</refclass>
	</refnamediv>

	<refsect1>
	  <title>Description</title>

	  <para>The value of this variable is used when :EXTERNAL-FORMAT is
	        unspecified or specified as :DEFAULT. It can
	        meaningfully be given any value that can be used as an
                external-format (except for the value :DEFAULT.)
	      </para>
	  <para>The initial value of this variable
	        in &CCL; is <literal>:UNIX</literal>, which is equivalent to
                <literal>(:LINE-TERMINATION :UNIX)</literal>, among other
                things.  </para>
	</refsect1>
    </refentry>

    <refentry id="v_default-line-termination">
	<indexterm zone="v_default-line-termination">
	  <primary>*default-line-termination*</primary>
	</indexterm>
	    
	<refnamediv>
	  <refname>CCL:*DEFAULT-LINE-TERMINATION*</refname>
	  <refpurpose></refpurpose>
	  <refclass>Variable</refclass>
	</refnamediv>

	<refsect1>
	  <title>Description</title>

	  <para>The value of this variable is used when an external-format
                doesn't specify a line-termination convention (or specifies
                it as :DEFAULT.) It can meaningfully be given any value 
                that can be used as a line termination keyword 
                (see <xref linkend="Line-Termination-Keywords"/>).
	      </para>
	  <para>The initial value of this variable
	        in &CCL; is <literal>:UNIX</literal>.
          </para>
	</refsect1>
    </refentry>

    <refentry id="f_make-external-format">
      <indexterm zone="f_make-external-format">
	<primary>make-external-format</primary>
      </indexterm>
      
      <refnamediv>
	<refname>MAKE-EXTERNAL-FORMAT</refname>
	<refpurpose>Either creates a new external format object, or
	return an existing one with the same specified slot
	values.</refpurpose>
	<refclass>Function</refclass>
      </refnamediv>

      <refsynopsisdiv>
	<synopsis>
	  <function>make-external-format</function>
	  &key; domain character-encoding line-termination
	  => external-format
	</synopsis>
      </refsynopsisdiv>

      <refsect1>
	<title>Arguments and Values</title>
	
	<variablelist>
	  <varlistentry>
	    <term>domain</term>
	    <listitem>
	      <para>This is used to indicate where the external
	      format is to be used.  Its value can be almost
	      anything.  It defaults to <literal>NIL</literal>.
	      There are two domains that have a pre-defined meaning in
	      &CCL;: <literal>:FILE</literal> indicates
	      encoding for a file in the file system and
	      <literal>:SOCKET</literal> indicates i/o to/from a
	      socket.  The value of <parameter>domain</parameter>
	      affects the default values for
	      <parameter>character-encoding</parameter> and
	      <parameter>line-termination</parameter>.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>character-encoding</term>
	    <listitem>
	      <para>A keyword that specifies the character encoding
	      for the external format. <xref
	      linkend="Character-Encodings"/>.  Defaults to
	      <literal>:DEFAULT</literal> which means if
	      <parameter>domain</parameter> is
	      <literal>:FILE</literal> use the value of the variable
	      <varname>CCL:*DEFAULT-FILE-CHARACTER-ENCODING*</varname>
	      and if <parameter>domain</parameter> is
	      <literal>:SOCKET</literal>, use the value of the
	      variable
	      <varname>CCL:*DEFAULT-SOCKET-CHARACTER-ENCODING*</varname>.
	      The initial value of both of these variables is
	      <literal>NIL</literal>, which means the
	      <literal>:ISO-8859-1</literal> encoding.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>line-termination</term>
	    <listitem>
	      <para>A keyword that indicates a line termination
	      keyword <xref linkend="Line-Termination-Keywords"/>.
	      Defaults to <literal>:DEFAULT</literal> which means
	      use the value of the variable
	      <varname>CCL:*DEFAULT-LINE-TERMINATION*</varname>.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>external-format</term>
	    <listitem>
	      <para>An external-format object as described above.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </refsect1>
      
      <refsect1>
	<title>Description</title>
	
	<para>Despite the function's name, it doesn't necessarily create a
	new, unique EXTERNAL-FORMAT object: two calls to
	MAKE-EXTERNAL-FORMAT with the same arguments made in the same
	dynamic environment return the same (eq) object.
	</para>
      </refsect1>
    </refentry>

  </sect2>

  <sect2 id="Line-Termination-Keywords"><title>Line Termination Keywords</title>
  <para>Line termination keywords indicate which characters are used
  to indicate the end of a line.  On input, the external line
  termination characters are replaced by <literal>#\Newline</literal>
  and on output, <literal>#\Newline</literal>s are converted to the
  external line termination characters.</para>
  <table id="Line-Termination-Table" frame='all'><title>Line Termination Keywords</title>
  <tgroup cols='2' align='left' colsep='1' rowsep='1'>
    <thead>
      <row>
	<entry>keyword</entry>
	<entry>character(s)</entry>
      </row>
    </thead>
    <tbody>
      <row>
	<entry><literal>:UNIX</literal></entry>
	<entry><literal>#\Linefeed</literal></entry>
      </row>
      <row>
	<entry><literal>:MACOS</literal></entry>
	<entry><literal>#\Return</literal></entry>
      </row>
      <row>
	<entry><literal>:CR</literal></entry>
	<entry><literal>#\Return</literal></entry>
      </row>
      <row>
	<entry><literal>:CRLF</literal></entry>
	<entry><literal>#\Return #\Linefeed</literal></entry>
      </row>
      <row>
	<entry><literal>:CP/M</literal></entry>
	<entry><literal>#\Return #\Linefeed</literal></entry>
      </row>
      <row>
	<entry><literal>:MSDOS</literal></entry>
	<entry><literal>#\Return #\Linefeed</literal></entry>
      </row>
      <row>
	<entry><literal>:DOS</literal></entry>
	<entry><literal>#\Return #\Linefeed</literal></entry>
      </row>
      <row>
	<entry><literal>:WINDOWS</literal></entry>
	<entry><literal>#\Return #\Linefeed</literal></entry>
      </row>
      <row>
	<entry><literal>:INFERRED</literal></entry>
	<entry>see below</entry>
      </row>
      <row>
	<entry><literal>:UNICODE</literal></entry>
	<entry><literal>#\Line_Separator</literal></entry>
      </row>
    </tbody>
  </tgroup>
  </table>
  <para><literal>:INFERRED</literal> means that a stream's
  line-termination convention is determined by looking at the contents
  of a file.  It is only useful for <literal>FILE-STREAM</literal>s
  that're 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>:WINDOWS</literal> if that
  <literal>#\Return</literal> character is immediately followed by a
  <literal>#\Linefeed</literal> character and to <literal>:MACOS</literal>
  otherwise.  If a <literal>#\Return</literal> character isn't found in
  the buffer or if <literal>#\Return</literal> is preceded by
  <literal>#\Linefeed</literal>, the file's line terminationt type
  is set to <literal>:UNIX</literal>.</para>
  </sect2>
  


  <sect2 id="Character-Encodings"><title>Character Encodings</title>
    <para>Internally, all characters and strings in &CCL; are in
    UTF-32.  Externally, files or socket streams may encode characters
    in a wide variety of ways.  The International Organization for
    Standardization, widely known as ISO, defines many of these
    character encodings.  &CCL; implements some of these encodings as
    detailed below.  These encodings are part of the specification of
    external formats <xref linkend="External-Formats"/>.  When reading
    from a stream, characters are converted from the specified
    external character encoding to UTF-32.  When writing to a stream,
    characters are converted from UTF-32 to the specified character
    encoding.</para>

    <para>Internally, CHARACTER-ENCODINGs are objects (structures)
    that are named by character encoding keywords (:ISO-8859-1,
    :UTF-8, etc.).  The structures contain attributes of the encoding
    and functions used to encode/decode external data, but unless
    you're trying to define or debug an encoding there's little reason
    to know much about the CHARACTER-ENCODING objects and it's usually
    preferable to refer to a character encoding by its name.
    </para>

    <para>
    </para>

    <sect3><title>Encoding Problems</title>
      <para>On output to streams with character encodings that can
      encode the full range of Unicode&mdash;and on input from any
      stream&mdash;"unencodable characters" are represented using the
      Unicode #\Replacement_Character (= #\U+fffd); the presence of
      such a character usually indicates that something got lost in
      translation.  Either data wasn't encoded properly or there was a
      bug in the decoding process.</para>
    </sect3>

    <sect3><title>Byte Order Marks</title>
      <para>The endianness of a character encoding is sometimes
      explicit, and sometimes not.  For example,
      <literal>:UTF-16BE</literal> indicates big-endian, but
      <literal>:UTF-16</literal> does not specify endianness.  A byte
      order mark is a special character that may appear at the
      beginning of a stream of encoded characters to specify the
      endianness of a multi-byte character encoding.  (It may also be
      used with UTF-8 character encodings, where it is simply used to
      indicate that the encoding is UTF-8.)</para>

      <para>&CCL; writes a byte order mark as the first character
      of a file or socket stream when the endianness of the character
      encoding is not explicit.  &CCL; also expects a byte order
      mark on input from streams where the endianness is not
      explicit. If a byte order mark is missing from input data, that
      data is assumed to be in big-endian order.</para>

      <para>A byte order mark from a UTF-8 encoded input stream is not
      treated specially and just appears as a normal character from
      the input stream.  It is probably a good idea to skip over this
      character.</para>
    </sect3>

  <sect3><title><function>DESCRIBE-CHARACTER-ENCODINGS</function></title>
    <para>The set of character encodings supported by &CCL; can be
    retrieved by calling
    <function>CCL:DESCRIBE-CHARACTER-ENCODINGS</function>.</para>


      <refentry id="f_describe-character-encodings">
	<indexterm zone="f_describe-character-encodings">
	  <primary>[fn-name]</primary>
	</indexterm>

	<refnamediv>
	  <refname>DESCRIBE-CHARACTER-ENCODINGS</refname>
	  <refpurpose>Writes descriptions of defined character
	  encodings to <varname>*terminal-io*</varname>.</refpurpose>
	  <refclass>Function</refclass>
	</refnamediv>

	<refsynopsisdiv>
	  <synopsis>
	    <function>describe-character-encodings</function>
	  </synopsis>
	</refsynopsisdiv>

	<refsect1>
	  <title>Description</title>

	  <para>Writes descriptions of all defined character encodings
	  to <varname>*terminal-io*</varname>.  These descriptions
	  include the names of the encoding's aliases and a doc string
	  which briefly describes each encoding's properties and
	  intended use.</para>
	</refsect1>

	<refsect1>
	  <title>See Also</title>
	 
	  <simplelist type="inline">
	    <member><xref linkend="Character-Encodings"/></member>
	    <member><xref linkend="External-Formats"/></member>
	    <member><xref linkend="Supported-Character-Encodings"/></member>
	  </simplelist>
	</refsect1>
      </refentry>
  </sect3>

  <sect3 id="Supported-Character-Encodings"><title>Supported Character Encodings</title>
     <para>The list of supported encodings is reproduced here.  Most
     encodings have aliases, e.g. the encoding named
     <literal>:ISO-8859-1</literal> can also be referred to by the
     names <literal>:LATIN1</literal> and <literal>:IBM819</literal>,
     among others.  Where possible, the keywordized name of an
     encoding is equivalent to the preferred MIME charset name (and
     the aliases are all registered IANA charset names.)</para>

  <variablelist>
    <varlistentry><term><literal>:ISO-8859-1</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which all character codes map to their Unicode
       equivalents. Intended to support most characters used in most
       Western European languages.</para>
       <para>&CCL; uses ISO-8859-1 encoding for
       <varname>*TERMINAL-IO*</varname> and for all streams whose
       EXTERNAL-FORMAT isn't explicitly specified.  The default for
       <varname>*TERMINAL-IO*</varname> can be set via the
       <literal>-K</literal> command-line argument (see <xref
       linkend="Command-Line-Options"/>).
       </para>
       <para>ISO-8859-1 just covers the first 256 Unicode code
       points, where the first 128 code points are equivalent to
       US-ASCII.  That should be pretty much equivalent to what
       earliers versions of &CCL; did that only supported 8-bit characters,
       but it may not be optimal for users working in a particular
       locale.</para>
       <para>Aliases: <literal>:ISO_8859-1, :LATIN1, :L1,
       :IBM819, :CP819, :CSISOLATIN1</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:ISO-8859-2</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which codes #x00-#x9f map to their Unicode equivalents and
       other codes map to other Unicode character values.  Intended to
       provide most characters found in most languages used in
       Central/Eastern Europe.</para>
       <para>Aliases: <literal>:ISO_8859-2, :LATIN2, :L2,
       :CSISOLATIN2</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:ISO-8859-3</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which codes #x00-#x9f map to their Unicode equivalents and
       other codes map to other Unicode character values.  Intended to
       provide most characters found in most languages used in
       Southern Europe.</para>
       <para>Aliases: <literal>:ISO_8859-3, :LATIN3 :L3,
       :CSISOLATIN3</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:ISO-8859-4</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which codes #x00-#x9f map to their Unicode equivalents and
       other codes map to other Unicode character values.  Intended to
       provide most characters found in most languages used in
       Northern Europe.</para>
       <para>Aliases: <literal>:ISO_8859-4, :LATIN4, :L4, :CSISOLATIN4</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:ISO-8859-5</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which codes #x00-#x9f map to their Unicode equivalents and
       other codes map to other Unicode character values.  Intended to
       provide most characters found in the Cyrillic
       alphabet.</para>
       <para>Aliases: <literal>:ISO_8859-5, :CYRILLIC, :CSISOLATINCYRILLIC,
       :ISO-IR-144</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:ISO-8859-6</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which codes #x00-#x9f map to their Unicode equivalents and
       other codes map to other Unicode character values.  Intended to
       provide most characters found in the Arabic
       alphabet.</para>
       <para>Aliases: <literal>:ISO_8859-6, :ARABIC, :CSISOLATINARABIC,
       :ISO-IR-127</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:ISO-8859-7</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which codes #x00-#x9f map to their Unicode equivalents and
       other codes map to other Unicode character values.  Intended to
       provide most characters found in the Greek
       alphabet.</para>
       <para>Aliases: <literal>:ISO_8859-7, :GREEK, :GREEK8, :CSISOLATINGREEK,
       :ISO-IR-126, :ELOT_928, :ECMA-118</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:ISO-8859-8</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which codes #x00-#x9f map to their Unicode equivalents and
       other codes map to other Unicode character values.  Intended to
       provide most characters found in the Hebrew
       alphabet.</para>
       <para>Aliases: <literal>:ISO_8859-8, :HEBREW, :CSISOLATINHEBREW,
       :ISO-IR-138</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:ISO-8859-9</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which codes #x00-#xcf map to their Unicode equivalents and
       other codes map to other Unicode character values.  Intended to
       provide most characters found in the Turkish
       alphabet.</para>
       <para>Aliases: <literal>:ISO_8859-9, :LATIN5, :CSISOLATIN5,
       :ISO-IR-148</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:ISO-8859-10</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which codes #x00-#x9f map to their Unicode equivalents and
       other codes map to other Unicode character values.  Intended to
       provide most characters found in Nordic
       alphabets.</para>
       <para>Aliases: <literal>:ISO_8859-10, :LATIN6, :CSISOLATIN6,
       :ISO-IR-157</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:ISO-8859-11</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which codes #x00-#x9f map to their Unicode equivalents and
       other codes map to other Unicode character values.  Intended to
       provide most characters found the Thai
       alphabet.</para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:ISO-8859-13</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which codes #x00-#x9f map to their Unicode equivalents and
       other codes map to other Unicode character values.  Intended to
       provide most characters found in Baltic
       alphabets.</para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:ISO-8859-14</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which codes #x00-#x9f map to their Unicode equivalents and
       other codes map to other Unicode character values.  Intended to
       provide most characters found in Celtic
       languages.</para>
       <para>Aliases: <literal>:ISO_8859-14, :ISO-IR-199, :LATIN8, :L8,
       :ISO-CELTIC</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:ISO-8859-15</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which codes #x00-#x9f map to their Unicode equivalents and
       other codes map to other Unicode character values.  Intended to
       provide most characters found in Western European languages
       (including the Euro sign and some other characters missing from
       ISO-8859-1.</para>
       <para>Aliases: <literal>:ISO_8859-15, :LATIN9</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:ISO-8859-16</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which codes #x00-#x9f map to their Unicode equivalents and
       other codes map to other Unicode character values.  Intended to
       provide most characters found in Southeast European
       languages.</para>
       <para>Aliases: <literal>:ISO_8859-16, :ISO-IR-199, :LATIN8, :L8,
       :ISO-CELTIC</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:MACINTOSH</literal></term>
       <listitem><para>An 8-bit, fixed-width character encoding in
       which codes #x00-#x7f map to their Unicode equivalents and
       other codes map to other Unicode character values.
       Traditionally used on Classic MacOS to encode characters used
       in western languages.</para>
       <para>Aliases: <literal>:MACOS-ROMAN, :MACOSROMAN, :MAC-ROMAN,
       :MACROMAN</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:UCS-2</literal></term>
       <listitem><para>A 16-bit, fixed-length encoding in which
       characters with CHAR-CODEs less than #x10000 can be encoded in
       a single 16-bit word.  The endianness of the encoded data is
       indicated by the endianness of a byte-order-mark character
       (#u+feff) prepended to the data; in the absence of such a
       character on input, the data is assumed to be in big-endian
       order.</para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:UCS-2BE</literal></term>
       <listitem><para>A 16-bit, fixed-length encoding in which
       characters with CHAR-CODEs less than #x10000 can be encoded in
       a single 16-bit big-endian word. The encoded data is implicitly
       big-endian; byte-order-mark characters are not interpreted on
       input or prepended to output.</para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:UCS-2LE</literal></term>
       <listitem><para>A 16-bit, fixed-length encoding in which
       characters with CHAR-CODEs less than #x10000 can be encoded in
       a single 16-bit little-endian word. The encoded data is
       implicitly little-endian; byte-order-mark characters are not
       interpreted on input or prepended to output.</para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:US-ASCII</literal></term>
       <listitem><para>An 7-bit, fixed-width character encoding in
       which all character codes map to their Unicode
       equivalents. </para>
       <para>Aliases: <literal>:CSASCII, :CP637, :IBM637, :US,
       :ISO646-US, :ASCII, :ISO-IR-6</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:UTF-16</literal></term>
       <listitem><para>A 16-bit, variable-length encoding in which
       characters with CHAR-CODEs less than #x10000 can be encoded in
       a single 16-bit word and characters with larger codes can be
       encoded in a pair of 16-bit words.  The endianness of the
       encoded data is indicated by the endianness of a
       byte-order-mark character (#u+feff) prepended to the data; in
       the absence of such a character on input, the data is assumed
       to be in big-endian order. Output is written in native
       byte-order with a leading byte-order mark.</para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:UTF-16BE</literal></term>
       <listitem><para>A 16-bit, variable-length encoding in which
       characters with CHAR-CODEs less than #x10000 can be encoded in
       a single 16-bit big-endian word and characters with larger
       codes can be encoded in a pair of 16-bit big-endian words.  The
       endianness of the encoded data is implicit in the encoding;
       byte-order-mark characters are not interpreted on input or
       prepended to output.</para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:UTF-16LE</literal></term>
       <listitem><para>A 16-bit, variable-length encoding in which
       characters with CHAR-CODEs less than #x10000 can be encoded in
       a single 16-bit little-endian word and characters with larger
       codes can be encoded in a pair of 16-bit little-endian words.
       The endianness of the encoded data is implicit in the encoding;
       byte-order-mark characters are not interpreted on input or
       prepended to output.</para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:UTF-32</literal></term>
       <listitem><para>A 32-bit, fixed-length encoding in which all
       Unicode characters can be encoded in a single 32-bit word.  The
       endianness of the encoded data is indicated by the endianness
       of a byte-order-mark character (#u+feff) prepended to the data;
       in the absence of such a character on input, input data is
       assumed to be in big-endian order.  Output is written in native
       byte order with a leading byte-order mark.</para>
       <para>Alias: <literal>:UTF-4</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:UTF-32BE</literal></term>
       <listitem><para>A 32-bit, fixed-length encoding in which all
       Unicode characters encoded in a single 32-bit word. The encoded
       data is implicitly big-endian; byte-order-mark characters are
       not interpreted on input or prepended to
       output.</para>
       <para>Alias: <literal>:UCS-4BE</literal></para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:UTF-8</literal></term>
       <listitem><para>An 8-bit, variable-length character encoding in
       which characters with CHAR-CODEs in the range #x00-#x7f can be
       encoded in a single octet; characters with larger code values
       can be encoded in 2 to 4 bytes.</para></listitem>
     </varlistentry>
    <varlistentry><term><literal>:UTF-32LE</literal></term>
       <listitem><para>A 32-bit, fixed-length encoding in which all
       Unicode characters can encoded in a single 32-bit word. The
       encoded data is implicitly little-endian; byte-order-mark
       characters are not interpreted on input or prepended to
       output.</para>
       <para>Alias: <literal>:UCS-4LE</literal></para></listitem>
     </varlistentry>
     <varlistentry><term><literal>:Windows-31j</literal></term>
     <listitem><para>An 8-bit, variable-length character encoding in
     which character code points in the range #x00-#x7f can be encoded
     in a single octet; characters with larger code values can be
     encoded in 2 bytes.</para>
     <para>Aliases: <literal>:CP932, :CSWINDOWS31J</literal></para></listitem>
     </varlistentry>
     <varlistentry><term><literal>:EUC-JP</literal></term>
     <listitem><para>An 8-bit, variable-length character encoding in
     which character code points in the range #x00-#x7f can be encoded
     in a single octet; characters with larger code values can be
     encoded in 2 bytes.</para>
     <para>Alias: <literal>:EUCJP</literal></para></listitem>
     </varlistentry>
     <varlistentry><term><literal>:GB2312</literal></term>
     <listitem><para>An 8-bit, variable-length character encoding in which
     character code points in the range #x00-#x80 can be encoded in a
     single octet; characters with larger code values can be encoded
     in 2 bytes.</para>
     <para>Alias: <literal>:GB2312-80 :GB2312-1980 :EUC-CN :EUCCN</literal></para></listitem>
     </varlistentry>
     <varlistentry><term><literal>:CP936</literal></term>
     <listitem><para>An 8-bit, variable-length character encoding in which
     character code points in the range #x00-#x80 can be encoded in a
     single octet; characters with larger code values can be encoded
     in 2 bytes.</para>
     <para>Alias: <literal>:GBK :MS936 :WINDOWS-936</literal></para></listitem>
     </varlistentry>
   </variablelist>
 </sect3>

 <sect3><title>Encoding and Decoding Strings</title>
 <para>&CCL; provides functions to encode and decode strings
to and from vectors of type (simple-array (unsigned-byte 8)).</para>

<refentry id="count-characters-in-octet-vector">
  <indexterm zone="count-characters-in-octet-vector">
    <primary>count-characters-in-octet-vector</primary>
  </indexterm>

  <refnamediv>
    <refname>count-characters-in-octet-vector</refname>
    <refpurpose></refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis>
	<function>count-characters-in-octet-vector</function>
	<parameter>vector</parameter>
	<parameter>&key;</parameter>
	<parameter>start</parameter>
	<parameter>end</parameter>
	<parameter>external-format</parameter>
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Description</title>
  <para>
    Returns the number of characters that would be produced by
    decoding <varname>vector</varname> (or the subsequence thereof
    delimited by <varname>start</varname> and <varname>end</varname>)
    according to <varname>external-format</varname>.
  </para>
  </refsect1>
</refentry>

<refentry id="decode-string-from-octets">
  <indexterm zone="decode-string-from-octets">
    <primary>"decode-string-from-octets</primary>
  </indexterm>

  <refnamediv>
    <refname>decode-string-from-octets</refname>
    <refpurpose></refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis>
	<function>decode-string-from-octets</function>
	<parameter>vector</parameter>
	<parameter>&key;</parameter>
	<parameter>start</parameter>
	<parameter>end</parameter>
	<parameter>external-format</parameter>
	<parameter>string</parameter>
    </synopsis>
  </refsynopsisdiv>


  <refsect1><title>Description</title>
  <para>
    Decodes the octets in <varname>vector</varname> (or the subsequence
    of it delimited by <varname>start</varname> and
    <varname>end</varname>) into a string according
    to <varname>external-format</varname>.
  </para>
  <para>
    If <varname>string</varname> is supplied, output will be written into it.
    It must be large enough to hold the decoded characters.  If <varname>
    string</varname> is not supplied, a new string will be allocated to
    hold the decoded characters.
  </para>
  <para>
    Returns, as multiple values, the decoded string and the position in
    <varname>vector</varname> where the decoding ended.
  </para>
  <para>
    Sequences of octets in <varname>vector</varname> that cannot be
    decoded into characters according to
    <varname>external-format</varname> will be decoded as
    #\Replacement_Character.
  </para>
  </refsect1>
</refentry>

<refentry id="encode-string-to-octets">
  <indexterm zone="encode-string-to-octets">
    <primary>encode-string-to-octets</primary>
  </indexterm>

  <refnamediv>
    <refname>encode-string-to-octets</refname>
    <refpurpose></refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis>
	<function>encode-string-to-octets</function>
	<parameter>string</parameter>
	<parameter>&key;</parameter>
	<parameter>start</parameter>
	<parameter>end</parameter>
	<parameter>external-format</parameter>
	<parameter>use-byte-order-mark</parameter>
	<parameter>vector</parameter>
	<parameter>vector-offset</parameter>
    </synopsis>
  </refsynopsisdiv>


  <refsect1><title>Description</title>
  <para>
    Encodes <varname>string</varname> (or the substring delimited by
    <varname>start</varname> and <varname>end</varname>)
    into <varname>external-format</varname> and returns, as multiple
    values, a vector of octets containing the encoded data and an integer
    that specifies the offset into the vector where the encoded data ends.
  </para>
  <para>
    When <varname>use-byte-order-mark</varname> is true, a byte-order mark
    will be included in the encoded data.
  </para>
  <para>
    If <varname>vector</varname> is supplied, output will be written
    to it.  It must be of type (simple-array (unsigned-byte 8)) and be
    large enough to hold the encoded data.  If it is not supplied, the function
    will allocate a new vector.
  </para>
  <para>
    If <varname>vector-offset</varname> is supplied, data will be written
    into the output vector starting at that offset.
  </para>
  <para>
    Characters in <varname>string</varname> that cannot be encoded
    into <varname>external-format</varname> will be replaced with an
    encoding-dependent replacement character
    (#\Replacement_Character or #\Sub) before being encoded and written
    into the output vector.
  </para>
  </refsect1>
</refentry>

<refentry id="string-size-in-octets">
  <indexterm zone="string-size-in-octets">
    <primary>string-size-in-octets</primary>
  </indexterm>

  <refnamediv>
    <refname>string-size-in-octets</refname>
    <refpurpose></refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis>
	<function>string-size-in-octets</function>
	<parameter>string</parameter>
	<parameter>&key;</parameter>
	<parameter>start</parameter>
	<parameter>end</parameter>
	<parameter>external-format</parameter>
	<parameter>use-byte-order-mark</parameter>
    </synopsis>
  </refsynopsisdiv>


  <refsect1><title>Description</title>
  <para>
    Returns the number of octets required to encode
    <varname>string</varname> (or the substring delimited by
    <varname>start</varname> and <varname>end</varname>) into
    <varname>external-format</varname>.
  </para>
  <para>
    When <varname>use-byte-order-mark</varname> is true, the returned
    size will include space for a byte-order marker.
  </para>
  </refsect1>
</refentry>

 </sect3>


  </sect2>

  </sect1>

  <sect1 id="Pathanmes"><title>Pathnames</title>

    <sect2 id="pathname-tilde-expansion">
      <title>Pathname Expansion</title>
      <para>Leading tilde (~) characters in physical pathname namestrings
        are expanded in the way that most shells do:</para>
      
      <para><literal>"~user/..."</literal> can be used to refer to an absolute pathname rooted
        at the home directory of the user named "user".</para>
      
      <para><literal>"~/..."</literal> can be used to refer to an absolute pathname rooted at
        the home directory of the current user.</para>
    </sect2>

    <sect2 id="Predefined-Logical-Hosts"><title>Predefined Logical Hosts</title>

      <para>&CCL; sets up logical pathname translations for logical hosts:  <literal>ccl</literal> and <literal>home</literal></para>

      <indexterm><primary>CCL Logical Host</primary></indexterm>
      <para>The <literal>CCL</literal> logical host should point to the
        <literal>ccl</literal> directory.  It is used for a variety of
        purposes by &CCL; including: locating &CCL; source code,
        <literal>require</literal> and <literal>provide</literal>, accessing
        foreign function information, and the &CCL; build process. It
        is set to the value of the environment variable
        <varname>CCL_DEFAULT_DIRECTORY</varname>, which is set by the
        openmcl shell script <xref linkend="The-ccl-Shell-Script"/>.  If
        <varname>CCL_DEFAULT_DIRECTORY</varname> is not set, then it is set
        to the directory containing the current heap image.</para>
    </sect2>
    <sect2 id="pathname-namestrings">
      <title>Pathname Namestrings</title>
      <para>
	The syntax of namestrings is implementation-defined in Common Lisp.
	Portable programs cannot assume much of anything about them.  (See
	section 19.1.1 of the Common Lisp standard for more information.)
      </para>
      <para>
	When translating a namestring into a pathname object, most
	implementations seem to follow the convention that a dot
	character in the namestring separates the
	<literal>pathname-name</literal> and
	the <literal>pathname-type</literal>.  When there is more
	than one dot in involved, or when dots appear at the beginning
	or end of the namestrings, what to do is less clear: does
	".emacs" describe a pathname whose name is
	<literal>nil</literal> and whose type is <literal>emacs</literal>
	or something else?  Similarly, given "a.b.c", the question
	is which parts are parsed as the pathname name, and which are
	parsed as the pathname type?
      </para>
      <para>
	When generating a namestring from a pathname object (as happens,
	for example, when printing a pathname), &CCL;
	tries to avoid some potential ambiguity by escaping characters
	that might otherwise be used to separate pathname components.
	The character used to quote or escape the separators is a
	backlash on Unix systems, and a #\&gt; character on Windows.
	So, for example, "a\\.b.c"
	has name "a.b" and type "c", whereas "a.b\\.c" has name
	"a" and type "b.c".
      </para>
      <para>
	To get a native namestring suitable for passing to an
	operating system command, use the function
	<literal>ccl:native-translated-namestring</literal>.
      </para>

    <sect3>
      <title>Working with native namestrings</title>
      <refentry id="f_native-translated-namestring">
	<indexterm zone="f_native-translated-namestring">
	  <primary>native-translated-namestring</primary>
	</indexterm>
	
	<refnamediv>
	  <refname>native-translated-namestring</refname>
	  <refpurpose>
	    Return a namestring that uses the conventions of the
	    native operating system.
	  </refpurpose>
	  <refclass>Function</refclass>
	</refnamediv>
	
	<refsynopsisdiv>
	  <synopsis><function>native-translated-namestring</function> pathname-designator</synopsis>
	</refsynopsisdiv>
	
	<refsect1><title>Description</title>
	<para>
	  This function returns a namestring that represents a pathname
	  using the native conventions of the operating system.
	  Any quoting or escaping of special characters will be removed.
	</para>
	<para>
	  For example, suppose that <varname>p</varname> is a pathname made
	  by <literal>(make-pathname :name "a.b" :type "c")</literal>.
	  Then, <literal>(native-translated-namestring p)</literal> evaluates
	  to "a.b.c".  By contrast, <literal>(namestring p)</literal> evaluates
	  to "a\\.b.c".
	</para>
	</refsect1>
      </refentry>

      <refentry id="m_with-filename-cstrs">
	<indexterm zone="m_with-filename-cstrs">
	  <primary>with-filename-cstrs</primary>
	</indexterm>
	
	<refnamediv>
	  <refname>with-filename-cstrs</refname>
	  <refpurpose>
	    Suitably encode strings to be used as filenames for foreign code.
	  </refpurpose>
	  <refclass>Macro</refclass>
	</refnamediv>
	
	<refsynopsisdiv>
	  <synopsis><function>with-filename-cstrs</function> ( {(var value)}* ) {form}*</synopsis>
	</refsynopsisdiv>
	
	<refsect1><title>Description</title>
	<para>
	  Executes <varname>forms</varname> in an environemt in which each
	  <varname>var</varname> is bound to a stack-allocated foreign
	  pointer which refers to a C-style string suitable for passing
	  to foreign code which expects a filename argument.
	</para>
	<para>
	  For example, one might use this macro in the following way:
  <programlisting>
(with-filename-cstrs ((s (native-translated-namestring pathname)))
  (#_unlink s))
  </programlisting>
	</para>
	<para>
	  Various operating systems have different conventions for how
	  they expect native pathname strings to be encoded.  Darwin
	  expects then to be decomposed UTF-8.  The Unicode variants
	  to Windows file-handling functions expect UTF-16.  Other
	  systems just treat them as opaque byte sequences.  This macro
	  ensures that the correct encoding is used, whatever
	  the host operating system.
	</para>
	</refsect1>
      </refentry>
    </sect3>
  </sect2>
    <sect2 id="pathnames-on-darwin">
      <title>OS X (Darwin)</title>
      
      <para>&CCL; assumes that pathname strings are decomposed UTF-8.</para>
    </sect2>
    <sect2 id="pathnames-on-linux">
      <title>Linux</title>
      
      <para>Pathname strings are treated as null-terminated strings
        coded in the encoding named by the value returned by the function
      <varname>CCL:PATHNAME-ENCODING-NAME</varname>.  This value may be changed
      with <varname>SETF</varname>.</para>
    </sect2>
    <sect2 id="pathnames-on-freebsd">
      <title>FreeBSD</title>
      
      <para>Pathname strings are treated as null-terminated strings
        encoded according to the current locale; a future release may
        change this convention to use UTF-8.</para>
    </sect2>
  </sect1>

  <sect1 id="Memory-Mapped-Files">
    <title>Memory-mapped Files</title>
    <para>In release 1.2 and later, &CCL;
      supports <glossterm linkend="memory_mapped_file">memory-mapped
        files</glossterm>. On operating systems that support memory-mapped
      files (including Mac OS X, Linux, and FreeBSD), the operating
      system can arrange for a range of virtual memory addresses to
      refer to the contents of an open file. As long as the file remains
      open, programs can read values from the file by reading addresses
      in the mapped range.</para>

    <para>Using memory-mapped files may in some cases be more
      efficient than reading the contents of a file into a data
      structure in memory.</para>

    <para>&CCL; provides the
      functions <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> to support
      memory-mapping. These functions return vectors whose contents are
      the contents of memory-mapped files. Reading an element of such a
      vector returns data from the corresponding position in the
      file.</para>

    <para>Without memory-mapped files, a common idiom for reading the
      contents of files might be something like this:</para>

    <programlisting>
(let* ((stream (open pathname :direction :input :element-type '(unsigned-byte 8)))
       (vector (make-array (file-size-to-vector-size stream)
                           :element-type '(unsigned-byte 8))))
  (read-sequence vector stream))
    </programlisting>

    <para>Using a memory-mapped files has a result that is the same in
      that, like the above example, it returns a vector whose contents are
      the same as the contents of the file. It differs in that the above
      example creates a new vector in memory and copies the file's
      contents into it; using a memory-mapped file instead arranges for
      the vector's elements to point to the file's contents on disk
      directly, without copying them into memory first.</para>

    <para>The vectors returned by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> are read-only; any
      attempt to change an element of a vector returned by these
      functions results in a memory-access error. &CCL; does not
      currently support writing data to memory-mapped files.</para>

    <para>Vectors created by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>
      and <varname>CCL:MAP-FILE-TO-OCTET-VECTOR</varname> are required to
      respect &CCL;'s limit on the total size of an array. That means
      that you cannot use these functions to create a vector longer
      than <varname>ARRAY-TOTAL-SIZE-LIMIT</varname>, even if the filesystem
      supports file sizes that are larger. The value
      of <varname>ARRAY-TOTAL-SIZE-LIMIT</varname> is <varname>(EXPT 2 24)</varname>
      on 32-but platforms; and <varname>(EXPT 2 56)</varname> on 64-bit
      platforms.</para>

    <para>
      <indexterm zone="map-file-to-ivector"/>
      <command><varname id="map-file-to-ivector">CCL:MAP-FILE-TO-IVECTOR</varname>
        <parameter>pathname</parameter>
        <parameter>element-type</parameter>
        [Function]</command>
    </para>

    <variablelist>
      <varlistentry>
        <term><varname>pathname</varname></term>
        <listitem>
          <para>The pathname of the file to be memory-mapped.</para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><varname>element-type</varname></term>
        <listitem>
          <para>The element-type of the vector to be
            created. Specified as
            a <glossterm linkend="type-specifier">type-specifier</glossterm>
            that names a subtype of either <varname>SIGNED-BYTE</varname>
            or <varname>UNSIGNED-BYTE</varname>.</para>
        </listitem>
      </varlistentry>
    </variablelist>


    <para>
      The <varname>map-file-to-ivector</varname> function tries to
      open the file at <parameter>pathname</parameter> for reading. If
      successful, the function maps the file's contents to a range of
      virtual addresses. If successful, it returns a read-only vector
      whose element-type is given
      by <parameter>element-type</parameter>, and whose contents are
      the contents of the memory-mapped file.
    </para>

    <para>The returned vector is
      a <glossterm linkend="displaced-array">displaced-array</glossterm>
      whose element-type is <varname>(UPGRADED-ARRAY-ELEMENT-TYPE
        element-type)</varname>. The target of the displaced array is a
      vector of type <varname>(SIMPLE-ARRAY element-type (*))</varname> whose
      elements are the contents of the memory-mapped file.</para>

    <para>Because of alignment issues, the mapped file's contents
      start a few bytes (4 bytes on 32-bit platforms, 8 bytes on
      64-bit platforms) into the vector. The displaced array returned
      by <varname>CCL:MAP-FILE-TO-IVECTOR</varname> hides this overhead, but
      it's usually more efficient to operate on the underlying simple
      1-dimensional array.  Given a displaced array (like the value
      returned by <varname>CCL:MAP-FILE-TO-IVECTOR</varname>), the function
      <varname>ARRAY-DISPLACEMENT</varname> returns the underlying array and
      the displacement index in elements.
    </para>

    <para>Currently, &CCL; supports only read operations on
      memory-mapped files. If you try to change the contents of an array
      returned by <varname>map-file-to-ivector</varname>, &CCL; signals
      a memory error.</para>

    <para>
      <indexterm zone="unmap-ivector"/>
      <command><varname id="unmap-ivector">CCL:UNMAP-IVECTOR</varname>
        <parameter>displaced-array</parameter>
        [Function]</command>
    </para>

    <para>If the argument is a displaced-array returned
      by <varname>map-file-to-ivector</varname>, and if it has not yet
      been unmapped by this function,
      then <varname>unmap-ivector</varname> undoes the memory mapping,
      closes the mapped file, and changes the displaced-array so that its
      target is an empty vector (of length zero).</para>

    <para>
      <indexterm zone="map-file-to-octet-vector"/>
      <command><varname id="map-file-to-octet-vector">CCL:MAP-FILE-TO-OCTET-VECTOR</varname>
        <parameter>pathname</parameter>
        [Function]</command>
    </para>

    <para>This function is a synonym for <varname>(CCL:MAP-FILE-TO-IVECTOR
        pathname '(UNSIGNED-BYTE 8))</varname> It is provided as a convenience
      for the common case of memory-mapping a file as a vector of
      bytes.</para>

    <para>
      <indexterm zone="unmap-octet-vector"/>
      <command><varname id="unmap-octet-vector">CCL:UNMAP-OCTET-VECTOR</varname>
        <parameter>displaced-array</parameter>
        [Function]</command>
    </para>

    <para>This function is a synonym
      for <varname>(CCL:UNMAP-IVECTOR)</varname></para>
  </sect1>

  <!-- ============================================================ -->
  <sect1 id="Static_Variables">
    <title>Static Variables</title>

    <para>&CCL; supports the definition
      of <glossterm linkend="static_variable">static
        variables</glossterm>, whose values are the same across threads,
      and which may not be dynamically bound. The value of a static
      variable is thus the same across all threads; changing the value
      in one thread changes it for all threads.</para> 

    <para>Attempting to dynamically rebind a static variable (for
      instance, by using <varname>LET</varname>, or using the variable name as
      a parameter in a <varname>LAMBDA</varname> form) signals an
      error. Static variables are shared global resources; a dynamic
      binding is private to a single thread.</para>

    <para>Static variables therefore provide a simple way to share
      mutable state across threads. They also provide a simple way to
      introduce race conditions and obscure bugs into your code, since
      every thread reads and writes the same instance of a given static
      variable. You must take care, therefore, in how you change the
      values of static variables, and use normal multithreaded
      programming techniques, such as locks or semaphores, to protect
      against race conditions.</para>

    <para>In &CCL;, access to a static variable is usually faster than
      access to a special variable that has not been declared
      static.</para>

    <para>
      <indexterm zone="defstatic"/>
      <command><varname id="defstatic">DEFSTATIC</varname>
        <parameter>var</parameter>
        <parameter>value</parameter>
        &key;
        <parameter>doc-string</parameter>
        [Macro]</command>
    </para>
    
    <variablelist>
      <varlistentry>
        <term><varname>var</varname></term>
        <listitem>
          <para>The name of the new static variable.</para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><varname>value</varname></term>
        <listitem>
          <para>The initial value of the new static variable.</para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><varname>doc-string</varname></term>
        <listitem>
          <para>A documentation string that is assigned to the new
            variable.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Proclaims the
      variable <glossterm linkend="special_variable">special</glossterm>,
      assigns the variable the supplied value, and assigns
      the <varname>doc-string</varname> to the
      variable's <varname>VARIABLE</varname> documentation. Marks the
      variable static, preventing any attempt to dynamically rebind
      it. Any attempt to dynamically rebind <varname>var</varname>
      signals an error.</para>
  </sect1>

  <!-- ============================================================ -->
  <sect1 id="Saving-Applications">
    <title>Saving Applications</title>
    <indexterm zone="Saving-Applications">
      <primary>save-application</primary>
    </indexterm>

    <para>&CCL; provides the
      function <literal>CCL:SAVE-APPLICATION</literal>, which creates a file
      containing an archived Lisp memory image.</para>

    <para>&CCL; consists of a small executable called the
      Lisp <glossterm linkend="lisp_image">kernel</glossterm>, which
      implements the very lowest level features of the Lisp system, and
      an <glossterm linkend="lisp_image">image</glossterm>, which
      contains the in-memory representation of most of the Lisp system,
      including functions, data structures, variables, and so on. When
      you start &CCL;, you are launching the kernel, which then locates
      and reads an image file, restoring the archived image in
      memory. Once the image is fully restored, the Lisp system is
      running.</para>

    <para>Using <literal>CCL:SAVE-APPLICATION</literal>, you can create a
      file that contains a modified image, one that includes any changes
      you've made to the running Lisp system. If you later pass your
      image file to the &CCL; kernel as a command-line parameter, it
      then loads your image file instead of its default one, and &CCL;
      starts up with your modifications.</para>

    <para>If this scenario seems to you like a convenient way to
      create an application, that's just as intended. You can create an
      application by modifying the running Lisp until it does what you
      want, then use <literal>CCL:SAVE-APPLICATION</literal> to preserve your
      changes and later load them for use.</para>

    <para>In fact, you can go further than that. You can replace
      &CCL;'s <glossterm linkend="toplevel_function">toplevel
        function</glossterm> with your own, and then, when the image is
      loaded, the Lisp system immediately performs your tasks rather
      than the default tasks that make it a Lisp development system. If
      you save an image in which you have done this, the resulting Lisp
      system is your tool rather than a Lisp development system.</para>

    <para>You can go a step further still. You can
      tell <literal>CCL:SAVE-APPLICATION</literal> to prepend the Lisp kernel
      to the image file. Doing this makes the resulting image into a
      self-contained executable binary. When you run the resulting file,
      the Lisp kernel immediately loads the attached image file and runs
      your saved system. The Lisp system that starts up can have any
      behavior you choose. It can be a Lisp development system, but with
      your customizations; or it can immediately perform some task of
      your design, making it a specialized tool rather than a general
      development system.</para>

    <para>In other words, you can develop any application you like by
      interactively modifying &CCL; until it does what you want, then
      using <literal>CCL:SAVE-APPLICATION</literal> to preserve your changes
      in an executable image.</para>

    <para>On Mac OS X,
      the <link linkend="application_builder">application builder</link>
      uses <literal>CCL:SAVE-APPLICATION</literal> to create the executable
      portion of the <glossterm linkend="application_bundle">application
        bundle</glossterm>. Double-clicking the application bundle runs
      the executable image created
      by <literal>CCL:SAVE-APPLICATION</literal>.</para>

    <para>Also on Mac OS X, &CCL; supports an object type
      called <literal>MACPTR</literal>, which is the type of pointers into the
      foreign (Mac OS) heap. Examples of
      commonly-user <literal>MACPTR</literal> objects are Cocoa windows and
      other dynamically-allocated Mac OS system objects.</para>

    <para>Because a <literal>MACPTR</literal> object is a pointer into a
      foreign heap that exists for the lifetime of the running Lisp
      process, and because a saved image is used by loading it into a
      brand new Lisp process, saved <literal>MACPTR</literal> objects cannot
      be relied on to point to the same things when reconstituted from a
      saved image. In fact, a restored <literal>MACPTR</literal> object might
      point to anything at all&mdash;for example an arbitrary location
      in the middle of a block of code, or a completely nonexistent
      virtual address.</para> 

    <para>For that reason, <literal>CCL:SAVE-APPLICATION</literal> converts
      all <literal>MACPTR</literal> objects to <literal>DEAD-MACPTR</literal>
      objects when writing them to an image
      file. A <literal>DEAD-MACPTR</literal> is functionally identical to
      a <literal>MACPTR</literal>, except that code that operates
      on <literal>MACPTR</literal> objects distinguishes them
      from <literal>DEAD-MACPTR</literal> objects and can handle them
      appropriately&mdash;signaling errors, for example.</para>

    <para>As of &CCL; 1.2, there is one exception to the conversion
      of <literal>MACPTR</literal> to <literal>DEAD-MACPTR</literal> objects:
      a <literal>MACPTR</literal> object that points to the address 0 is not
      converted, because address 0 can always be relied upon to refer to
      the same thing.</para>

	<indexterm zone="Saving-Applications">
	  <primary>+NULL-PTR+</primary>
	</indexterm>
    <para>As of &CCL; 1.2, the constant <literal>CCL:+NULL-PTR+</literal>
      refers to a <literal>MACPTR</literal> object that points to address 0.</para>

    <para>On all supported platforms, you can
      use <literal>CCL:SAVE-APPLICATION</literal> to create a command-line
      tool that runs the same way any command-line program
      does. Alternatively, if you choose not to prepend the kernel, you
      can save an image and then later run it by passing it as a
      command-line parameter to the <literal>ccl</literal>
      or <literal>ccl64</literal> script.</para>

    <para>
      <indexterm zone="save-application"/>
      <command><varname id="save-application">SAVE-APPLICATION</varname>
        <parameter>filename</parameter>
        &key;
        <parameter>toplevel-function</parameter>
        <parameter>init-file</parameter>
        <parameter>error-handler</parameter>
        <parameter>application-class</parameter>
        <parameter>clear-clos-caches</parameter>
        <parameter>(purify t)</parameter>
        <parameter>impurify</parameter>
        <parameter>(mode #o644)</parameter>
        <parameter>prepend-kernel</parameter>
        <parameter>native</parameter>
        [Function]</command>
    </para>
    
    <variablelist>
      <varlistentry>
        <term><varname>filename</varname></term>
        <listitem>
          <para>The pathname of the file to be created when &CCL;
            saves the application.</para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><varname>toplevel-function</varname></term>
        <listitem>
          <para>The function to be executed after startup is
            complete. The toplevel is a function of no arguments that
            performs whatever actions the lisp system should perform
            when launched with this image.</para>
          <para>If this parameter is not supplied, &CCL; uses its
            default toplevel. The default toplevel runs
            the <glossterm linkend="REPL">read-eval-print
              loop</glossterm>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>init-file</varname></term>
        <listitem>
          <para>The pathname of a Lisp file to be loaded when the
            image starts up. You can place initialization expressions in
            this file, and use it to customize the behavior of the Lisp
            system when it starts up.</para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><varname>error-handler</varname></term>
        <listitem>
          <para>The error-handling mode for the saved image. The
            supplied value determines what happens when an error is not
            handled by the saved image. Valid values
            are <literal>:quit</literal> (Lisp exits with an error
            message); <literal>:quit-quietly</literal> (Lisp exits without an
            error message); or <literal>:listener</literal> (Lisp enters a
            break loop, enabling you to debug the problem by interacting
            in a listener). If you don't supply this parameter, the
            saved image uses the default error handler
            (<literal>:listener</literal>).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>application-class</varname></term>
        <listitem>
          <para>The CLOS class that represents the saved Lisp
            application. Normally you don't need to supply this
            parameter; <literal>CCL:SAVE-APPLICATION</literal> uses the
            class <literal>CCL:LISP-DEVELOPMENT-SYSTEM</literal>. In some
            cases you may choose to create a custom application class;
            in that case, pass the name of the class as the value for
            this parameter.</para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><varname>clear-clos-caches</varname></term>
        <listitem>
          <para>If true, ensures that CLOS caches are emptied before
            saving the image. Normally you don't need to supply this
            parameter, but if for some reason you want to ensure the
            CLOS caches are clear when the image starts up, you can pass
            any true value.</para>
        </listitem>
     </varlistentry>
     <varlistentry>
        <term><varname>purify</varname></term>
        <listitem>
          <para>
	    When true, calls (in effect) <code>purify</code> before
	    saving the heap image.  This moves certain objects that
	    are unlikely to become garbage to a special memory area
	    that is not scanned by the GC (since it is expected that
	    the GC wouldn't find anything to collect).
         </para>
      </listitem>
      </varlistentry>

     <varlistentry>
        <term><varname>impurify</varname></term>
        <listitem>
          <para>
	    If true, calls (in effect) <code>impurify</code> before
	    saving the heap image.  (If both <literal>:impurify</literal>
	    and <literal>:purify</literal> are true, first
	    <code>impurify</code> is done, and then <code>purify</code>.)
         </para>
	 <para>
	   <code>impurify</code> moves objects in certain special memory
	   areas into the regular dynamic heap, where they will be scanned
	   by the GC.
	 </para>
      </listitem>
      </varlistentry>

     <varlistentry>
        <term><varname>mode</varname></term>
        <listitem>
          <para>
	    A number specifying the mode (permission bits) of the output file.
	  </para>
      </listitem>
      </varlistentry>

     <varlistentry>
        <term><varname>prepend-kernel</varname></term>
        <listitem>
          <para>Specifies the file to prepend to the saved heap
	  image.  A value of <literal>t</literal> means to prepend
	  the lisp kernel binary that the lisp started with.
	  Otherwise, the value of <literal>:prepend-kernel</literal>
	  should be a pathname designator for the file to be
	  prepended.
         </para>
	 <para>
	   If the prepended file is execuatable, its execute
	   mode bits will be copied to the output file.
	 </para>
	 <para>
	   This argument can be used to prepend any kind of file to
	   the saved heap image.  This can be useful in some special
	   cases.
	 </para>	   
      </listitem>
      </varlistentry>
     <varlistentry>
        <term><varname>native</varname></term>
        <listitem>
          <para>If true, saves the image as a native (ELF, Mach-O, PE)
          shared library.  (On platforms where this isn't yet supported,
          a warning is issued and the option is ignored.)
         </para>
      </listitem>
      </varlistentry>
      
      
    </variablelist>

    <para></para>
  </sect1>

  <sect1 id="concatenating-fasl-files">
    <title>Concatenating FASL Files</title>
    <para>
      Multiple fasl files can be concatenated into a single file.
    </para>
  <refentry id="f_fasl-concatenate">
    <indexterm zone="f_fasl-concatenate">
      <primary>fasl-concatenate</primary>
    </indexterm>

    <refnamediv>
      <refname>FASL-CONCATENATE</refname>
      <refpurpose>
	Concatenate several fasl files, producing a single output file.
      </refpurpose>
      <refclass>Function</refclass>
    </refnamediv>
    
    <refsynopsisdiv>
      <synopsis><function>fasl-concatenate</function> out-file fasl-files &key; (:if-exists :error)</synopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Arguments and Values</title>
      <variablelist>
	<varlistentry>
	  <term>out-file</term>
	  <listitem>
	    <para>
	      Name of the file in which to store the concatenation.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>fasl-files</term>
	  <listitem>
	    <para>
	      List of names of fasl files to concatenate.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>:if-exists</term>
	  <listitem>
	    <para>
	      As for <function>OPEN</function>, defaults to <literal>
	      :error</literal>
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </refsect1>
    
    <refsect1>
      <title>Description</title>
      <para>
	Creates a fasl file which, when loaded, will have the same
	effect as loading the individual input fasl files in the
	specified order.  The single file might be easier to
	distribute or install, and loading it may be at least a little
	faster than loading the individual files (since it avoids the
	overhead of opening and closing each file in succession.)
      </para>
      <para>
	The PATHNAME-TYPE of the output file and of each input file
	defaults to the current platform's fasl file type (.dx64fsl or
	whatever.)  If any of the input files has a different
	type/extension an error will be signaled, but it doesn't
	otherwise try too hard to verify that the input files are real
	fasl files for the current platform.
      </para>
    </refsect1>
  </refentry>
  </sect1>
  <sect1 id="floating-point">
    <title>Floating Point Numbers</title>

    <para>
      In &CCL;, the Common Lisp types short-float and single-float are
      implemented as IEEE single precision values; double-float and
      long-float are IEEE double precision values.  On 64-bit
      platforms, single-floats are immediate values (like fixnums and
      characters).
    </para>

  <para>
    Floating-point exceptions are generally enabled and detected.  By
    default, threads start up with overflow, division-by-zero, and
    invalid enabled, and the rounding mode is set to nearest. The
    functions <varname>SET-FPU-MODE</varname> and
    <varname>GET-FPU-MODE</varname> provide user control over
    floating-point behavior.
  </para>

  <refentry id="f_get-fpu-mode">
    <indexterm zone="f_get-fpu-mode">
      <primary>get-fpu-mode</primary>
    </indexterm>

    <refnamediv>
      <refname>GET-FPU-MODE</refname>
      <refpurpose>
	Return the state of exception-enable and rounding-mode control
	flags for the current thread.
      </refpurpose>
      <refclass>Function</refclass>
    </refnamediv>
    
    <refsynopsisdiv>
      <synopsis><function>get-fpu-mode</function> &optional; mode</synopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Arguments and Values</title>
      <variablelist>
	<varlistentry>
	  <term>mode</term>
	  <listitem>
	    <para>
	      One of the keywords :rounding-mode, :overflow,
	      :underflow, :division-by-zero, :invalid, :inexact.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </refsect1>
    
    <refsect1>
      <title>Description</title>
      <para>
	If <varname>mode</varname> is supplied, returns the value of
	the corresponding control flag for the current thread.
      </para>
      <para>
	Otherwise, returns a list of keyword/value pairs which
	describe the floating-point exception-enable and rounding-mode
	control flags for the current thread.
      </para>
      <variablelist>
	<varlistentry>
	  <term>rounding-mode</term>
	  <listitem>
	    <para>
	      One of :nearest, :zero, :positive, :negative
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>overflow, underflow, division-by-zero, invalid, inexact
	  </term>
	  <listitem>
	    <para>
	      If true, the floating-point exception is signaled.
	      If NIL, it is masked.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </refsect1>
  </refentry>

  <refentry id="f_set-fpu-mode">
    <indexterm zone="f_set-fpu-mode">
      <primary>set-fpu-mode</primary>
    </indexterm>

    <refnamediv>
      <refname>SET-FPU-MODE</refname>
      <refpurpose>
	Set the state of exception-enable and rounding-mode control
	flags for the current thread.
      </refpurpose>
      <refclass>Function</refclass>
    </refnamediv>
    
    <refsynopsisdiv>
      <synopsis><function>set-fpu-mode</function> &key;
      rounding-mode overflow underflow division-by-zero
      invalid inexact</synopsis>
    </refsynopsisdiv>

    <refsect1>
      <title>Arguments and Values</title>
      <variablelist>
	<varlistentry>
	  <term>rounding-mode</term>
	  <listitem>
	    <para>
	      If supplied, must be one of :nearest, :zero, :positive, or
	      :negative.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>overflow, underflow, division-by-zero, invalid, inexact</term>
	  <listitem>
	    <para>NIL to mask the exception, T to signal it.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </refsect1>
    
    <refsect1>
      <title>Description</title>
      <para>
	Sets the current thread's exception-enable and rounding-mode
	control flags to the indicated values for arguments that are
	supplied, and preserves the values assoicated with those
	that aren't supplied.
      </para>
    </refsect1>
  </refentry>
  </sect1>

  <sect1 id="watched-objects"><title>Watched Objects</title>
  <para>
    As of release 1.4, Clozure CL provides a way for lisp objects to
    be watched so that a condition will be signaled when a thread
    attempts to write to the watched object. For a certain class of
    bugs (someone is changing this value, but I don't know who), this
    can be extremely helpful.
  </para>
  <sect2 id="watched-watch"><title>WATCH</title>
  <refentry id="f_watch">
    <indexterm zone="f_watch">
      <primary>watch</primary>
    </indexterm>
    
    <refnamediv>
      <refname>WATCH</refname>
      <refpurpose>
	Monitor a lisp object for writes.
      </refpurpose>
      <refclass>Function</refclass>
    </refnamediv>
    
    <refsynopsisdiv>
      <synopsis><function>watch</function> &optional; object</synopsis>
    </refsynopsisdiv>
    
    <refsect1>
      <title>Arguments and Values</title>
      <variablelist>
	<varlistentry>
	  <term>object</term>
	  <listitem>
	    <para>
	      Any memory-allocated lisp object.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </refsect1>

    <refsect1>
      <title>Description</title>
      <para>
	The WATCH function arranges for the specified object to be
	monitored for writes. This is accomplished by copying the
	object to its own set of virtual memory pages, which are then
	write-protected. This protection is enforced by the computer's
	memory-management hardware; the write-protection does not slow
	down reads at all.
      </para>
      <para>
	When any write to the object is attempted, a
	WRITE-TO-WATCHED-OBJECT condition will be signaled.
      </para>
      <para>
	When called with no arguments, WATCH returns a freshly-consed
	list of the objects currently being watched.
      </para>
      <para>
	WATCH returns NIL if the object cannot be watched (typically
	because the object is in a static or pure memory area).
      </para>
    </refsect1>
    <refsect1 id="watch-dwim"><title>DWIM</title>
    <para>
      WATCH operates at a fairly low level; it is not possible to
      avoid the details of the internal representation of objects.
      Nevertheless, as a convenience, WATCHing a standard-instance,
      a hash-table, or a multi-dimensional or non-simple CL array
      will watch the underlying slot-vector, hash-table-vector, or
      data-vector, respectively.
      </para>
    </refsect1>
    <refsect1 id="watch-discuss"><title>Discussion</title>
    <para>
      WATCH can monitor any memory-allocated lisp object.
    </para>
    <para>
      In Clozure CL, a memory-allocated object is either a cons cell
      or a uvector.
    </para>
    <para>
      WATCH operates on cons cells, not lists. In order to watch a
      chain of cons cells, each cons cell must be watched
      individually. Because each watched cons cell takes up its own
      own virtual memory page (4 Kbytes), it's only feasible to watch
      relatively short lists.
    </para>
    <para>
      If a memory-allocated object isn't a cons cell, then it is a
      vector-like object called a uvector. A uvector is a
      memory-allocated lisp object whose first word is a header that
      describes the object's type and the number of elements that it
      contains.
    </para>
    <para>
      So, a hash table is a uvector, as is a string, a standard
      instance, a double-float, a CL array or vector, and so forth.
    </para>
    <para>
      Some CL objects, like strings and other simple vectors, map in a
      straightforward way onto the uvector representation. It is easy
      to understand what happens in such cases. The uvector index
      corresponds directly to the vector index:
    </para>
    <programlisting>
<![CDATA[
? (defvar *s* "xxxxx")
*S*
? (watch *s*)
"xxxxx"
? (setf (char *s* 3) #\o)
> Error: Write to watched uvector "xxxxx" at index 3
>        Faulting instruction: (movl (% eax) (@ -5 (% r15) (% rcx)))
> While executing: SET-CHAR, in process listener(1).
> Type :POP to abort, :R for a list of available restarts.
> Type :? for other options.
]]>
    </programlisting>
    <para>
      In the case of more complicated objects (e.g., a hash-table, a
      standard-instance, a package, etc.), the elements of the uvector
      are like slots in a structure. It's necessary to know which one
      of those "slots" contains the data that will be changed when the
      object is written to.
    </para>
    <para>
      As mentioned above, watch knows about arrays, hash-tables, and
      standard-instances, and will automatically watch the appropriate
      data-containing element.
    </para>
    <para>
      An example might make this clearer.
    </para>
    <programlisting>
<![CDATA[
? (defclass foo ()
    (slot-a slot-b slot-c))
#<STANDARD-CLASS FOO>
? (defvar *a-foo* (make-instance 'foo))
*A-FOO*
? (watch *a-foo*)
#<SLOT-VECTOR #xDB00D>
;;; Note that WATCH has watched the internal slot-vector object
? (setf (slot-value *a-foo* 'slot-a) 'foo)
> Error: Write to watched uvector #<SLOT-VECTOR #xDB00D> at index 1
>        Faulting instruction: (movq (% rsi) (@ -5 (% r8) (% rdi)))
> While executing: %MAYBE-STD-SETF-SLOT-VALUE-USING-CLASS, in process listener(1).
> Type :POP to abort, :R for a list of available restarts.
> Type :? for other options.
]]>
    </programlisting>
    <para>
      Looking at a backtrace would presumably show what object and
      slot name were written.
    </para>
    <para>
      Note that even though the write was to slot-a, the uvector index
      was 1 (not 0). This is because the first element of a
      slot-vector is a pointer to the instance that owns the slots. We
      can retrieve that to look at the object that was modified:
    </para>
    <programlisting>
<![CDATA[
1 > (uvref (write-to-watched-object-object *break-condition*) 0)
#<FOO #x30004113502D>
1 > (describe *)
#<FOO #x30004113502D>
Class: #<STANDARD-CLASS FOO>
Wrapper: #<CLASS-WRAPPER FOO #x300041135EBD>
Instance slots
SLOT-A: #<Unbound>
SLOT-B: #<Unbound>
SLOT-C: #<Unbound>
1 >
]]> 
    </programlisting>
    </refsect1>
  </refentry>
</sect2>
<sect2 id="watched-unwatch"><title>UNWATCH</title>
<refentry id="f_unwatch">
  <indexterm zone="f_unwatch">
    <primary>unwatch</primary>
  </indexterm>
  
  <refnamediv>
    <refname>UNWATCH</refname>
      <refpurpose>
	Stop monitoring a lisp object for writes.
      </refpurpose>
      <refclass>Function</refclass>
  </refnamediv>
  
  <refsynopsisdiv>
    <synopsis><function>unwatch</function> object</synopsis>
  </refsynopsisdiv>
  
  <refsect1><title>Description</title>
  <para>
    The UNWATCH function ensures that the specified object is in
    normal, non-monitored memory. If the object is not currently
    being watched, UNWATCH does nothing and returns NIL. Otherwise,
    the newly unwatched object is returned.
  </para>
  </refsect1>
</refentry>
</sect2>
<sect2 id="watched-write-to-watched-object">
  <title>WRITE-TO-WATCHED-OBJECT</title>
  <refentry id="c_write-to-watched-object">
    <indexterm zone="c_write-to-watched-object">
      <primary>write-to-watched-object</primary>
    </indexterm>
    
    <refnamediv>
      <refname>WRITE-TO-WATCHED-OBJECT</refname>
      <refpurpose>
	Condition signaled when a write to a watched object is attempted.
      </refpurpose>
      <refclass>Condition</refclass>
    </refnamediv>

    <refsect1><title>Discussion</title>
    <para>
      This condition is signaled when a watched object is written
      to. There are three slots of interest:
    </para>
    <variablelist>
      <varlistentry>
	<term>object</term>
	<listitem>
	  <para>
	    The actual object that was the destination of the write.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>offset</term>
	<listitem>
	  <para>
	    The byte offset from the tagged object pointer to the
	    address of the write.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>instruction</term>
	<listitem>
	  <para>
	    The disassembled machine instruction that attempted the write.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
    </refsect1>

    <refsect1><title>Restarts</title>
    <para>
      A few restarts are provided: one will skip over the faulting
      write instruction and proceed; another offers to unwatch the
      object and continue.
    </para>
    <para>
      There is also an emulate restart. In some common cases, the
      faulting write instruction can be emulated, enabling the write
      to be performed without having to unwatch the object (and
      therefore let other threads potentially write to it). If the
      faulting instruction isn't recognized, the emulate restart will
      not be offered.
    </para>
    </refsect1>
  </refentry>
</sect2>
<sect2 id="watch-notes"><title>Notes</title>
<para>
  Although some care has been taken to minimize potential problems
  arising from watching and unwatching objects from multiple
  threads, there may well be subtle race conditions present that
  could cause bad behavior.
</para>
<para>
  For example, suppose that a thread attempts to write to a watched
  object. This causes the operating system to generate an
  exception. The lisp kernel figures out what the exception is, and
  calls back into lisp to signal the write-to-watched-object
  condition and perhaps handle the error.
</para>
<para>
  Now, as soon lisp code starts running again (for the callback),
  it's possible that some other thread could unwatch the very
  watched object that caused the exception, perhaps before we even
  have a chance to signal the condition, much less respond to it.
</para>
<para>
  Having the object unwatched out from underneath a handler may at
  least confuse it, if not cause deeper trouble. Use caution with
  unwatch.
</para>
</sect2>
<sect2 id="watch-examples"><title>Examples</title>
<para>
  Here are a couple more examples in addition to the above examples
  of watching a string and a standard-instance.
</para>
<sect3><title>Fancy arrays</title>
<programlisting>
?  (defvar *f* (make-array '(2 3) :element-type 'double-float))
*F*
? (watch *f*)
#(0.0D0 0.0D0 0.0D0 0.0D0 0.0D0 0.0D0)
;;; Note that the above vector is the underlying data-vector for the array
? (setf (aref *f* 1 2) pi)
> Error: Write to watched uvector #&lt;VECTOR 6 type DOUBLE-FLOAT, simple> at index 5
>        Faulting instruction: (movq (% rax) (@ -5 (% r8) (% rdi)))
> While executing: ASET, in process listener(1).
> Type :POP to abort, :R for a list of available restarts.
> Type :? for other options.
1 > 
  </programlisting>
  <para>
    In this case, uvector index in the report is the row-major index
    of the element that was written to.
  </para>
  </sect3>
  <sect3><title>Hash tables</title>
  <para>
    Hash tables are surprisingly complicated. The representation of a
    hash table includes an element called a hash-table-vector. The
    keys and values of the elements are stored pairwise in this
    vector.
  </para>
  <para>
    One problem with trying to monitor hash tables for writes is that
    the underlying hash-table-vector is replaced with an entirely new
    one when the hash table is rehashed. A previously-watched
    hash-table-vector will not be the used by the hash table after
    rehashing, and writes to the new vector will not be caught.
  </para>
  <programlisting>
? (defvar *h* (make-hash-table))
*H*
? (setf (gethash 'noise *h*) 'feep)
FEEP
? (watch *h*)
#&lt;HASH-TABLE-VECTOR #xDD00D>
;;; underlying hash-table-vector
? (setf (gethash 'noise *h*) 'ding)
> Error: Write to watched uvector #&lt;HASH-TABLE-VECTOR #xDD00D> at index 35
>        Faulting instruction: (lock)
>          (cmpxchgq (% rsi) (@ (% r8) (% rdx)))
> While executing: %STORE-NODE-CONDITIONAL, in process listener(1).
> Type :POP to abort, :R for a list of available restarts.
> Type :? for other options.
;;; see what value is being replaced...
1 > (uvref (write-to-watched-object-object *break-condition*) 35)
FEEP
;;; backtrace shows useful context
1 > :b
*(1A109F8) : 0 (%STORE-NODE-CONDITIONAL ???) NIL
 (1A10A50) : 1 (LOCK-FREE-PUTHASH NOISE #&lt;HASH-TABLE :TEST EQL size 1/60 #x30004117D47D> DING) 653
 (1A10AC8) : 2 (CALL-CHECK-REGS PUTHASH NOISE #&lt;HASH-TABLE :TEST EQL size 1/60 #x30004117D47D> DING) 229
 (1A10B00) : 3 (TOPLEVEL-EVAL (SETF (GETHASH # *H*) 'DING) NIL) 709
 ...
  </programlisting>
  </sect3>
  <sect3><title>Lists</title>
  <para>
    As previously mentioned, WATCH only watches individual cons cells.
  </para>
  <programlisting>
? (defun watch-list (list)
    (maplist #'watch list))
WATCH-LIST
? (defvar *l* (list 1 2 3))
*L*
? (watch-list *l*)
((1 2 3) (2 3) (3))
? (setf (nth 2 *l*) 'foo)
> Error: Write to the CAR of watched cons cell (3)
>        Faulting instruction: (movq (% rsi) (@ 5 (% rdi)))
> While executing: %SETNTH, in process listener(1).
> Type :POP to abort, :R for a list of available restarts.
> Type :? for other options.
  </programlisting>
  </sect3>
  </sect2>
</sect1>

<sect1 id="code-coverage"><title>Code Coverage</title>
<sect2 id="code-coverage-overview"><title>Overview</title>
<para>
  In Clozure CL 1.4 and later, code coverage provides information
  about which paths through generated code have been executed and
  which haven't. For each source form, it can report one of three
  possible outcomes:
</para>
<itemizedlist>
  <listitem>
    <para>
      Not covered: this form was never entered.
    </para>
  </listitem>
  <listitem>
    <para>
      Partly covered: This form was entered, and some parts were
      executed and some weren't.
    </para>
  </listitem>
  <listitem>
    <para>
      Fully covered: Every bit of code generated from this form was
      executed.
    </para>
  </listitem>
</itemizedlist>
</sect2>

<sect2 id="code-coverage-limitations"><title>Limitations</title>
<para>
  While the information gathered for coverage of generated code is
  complete and precise, the mapping back to source forms is of
  necessity heuristic, and depends a great deal on the behavior of
  macros and the path of the source forms through compiler
  transforms. Source information is not recorded for variables, which
  further limits the source mapping. In practice, there is often
  enough information scattered about a partially covered function to
  figure out which logical path through the code was taken and which
  wasn't. If that doesn't work, you can try disassembling to see which
  parts of the compiled code were not executed: in the disassembled
  code there will be references to #&lt;CODE-NOTE [xxx] ...> where xxx
  is NIL if the code that follows was never executed and non-NIL if it
  was.
</para>
<para>
  Sometimes the situation can be improved by modifying macros to try
  to preserve more of the input forms, rather than destructuring and
  rebuilding them.
</para>
<para>
  Because the code coverage information is associated with compiled
  functions, code coverage information is not available for load-time toplevel
  expressions.  You can work around this by creating a function and calling
  it. I.e. instead of
  <programlisting>
(progn
  (do-this)
  (setq that ...) ...))</programlisting>
  do:
  <programlisting>
(defun init-this-and-that ()
  (do-this)
  (setq that ...)  ...)
(init-this-and-that)</programlisting>

Then you can see the coverage information in the definition of
<literal>init-this-and-that</literal>.
</para>
</sect2>

<sect2 id="code-coverage-usage"><title>Usage</title>
<para>
  In order to gather code coverage information, you first have to
  recompile all your code to include code coverage
  instrumentation. Compiling files will generate code coverage
  instrumentation if <literal>CCL:*COMPILE-CODE-COVERAGE*</literal>
  is true:
  <programlisting>
(setq ccl:*compile-code-coverage* t) 
(recompile-all-your-files)</programlisting>
</para>
<para>
  The compilation process will be many times slower than normal, and
  the fasl files will be many times bigger.
</para>
<para>
  When you execute functions loaded from instrumented fasl files, they
  will record coverage information every time they are executed. 
  You can examine that information by calling <literal>ccl:report-coverage</literal>
  or <literal>ccl:coverage-statistics</literal>.
</para>
 <para>
   While recording coverage, you can collect incremental coverage deltas between any two points
   in time.  You might do this while running a test suite, to record the coverage for
   each test, for example:
  <programlisting>
(ccl:reset-incremental-coverage)
(loop with coverage = (make-hash-table)
      for test in (tests-to-run)
      do (run-test test)
      do (setf (gethash test coverage) (ccl:get-incremental-coverage))
      finally (return coverage))</programlisting>creates a hash table mapping a test to a representation of all coverage recorded while running the
   test.  This hash table can then be passed to <literal>ccl:report-coverage</literal>, <literal>ccl:incremental-coverage-svn-matches</literal>
   or <literal>ccl:incremental-coverage-source-matches</literal>.
</para>
</sect2>

<sect2 id="code-coverage-functions-and-variables"><title>Functions and Variables</title>
<para>
  The following functions can be used to manage the coverage data:
</para>

<refentry id="f_report-coverage">
  <indexterm zone="f_report-coverage">
    <primary>report-coverage</primary>
  </indexterm>
  
  <refnamediv>
    <refname>REPORT-COVERAGE</refname>
    <refpurpose>Generate a code coverage report</refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><function>report-coverage</function> output-file &key;
    (tags nil) (external-format :default) (statistics t) (html t)
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Arguments and Values</title>
  <variablelist>
    <varlistentry>
      <term>output-file</term>
      <listitem>
	<para>
          Pathname for the output index file.
	</para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term>html</term>
      <listitem>
	<para>
	  If non-nil (the default), this will generate an HTML report, consisting of
	  an index file in <varname>output-file</varname> and, in the same directory,
          one html file for each instrumented source file that has been loaded in the
          current session.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>tags</term>
      <listitem>
	<para>
	  If non-nil, this should be a hash table mapping arbitrary keys (tags) to incremental coverage deltas.  The
          HTML report will show a list of tags, and allow selection of an arbitrary subset of them to show the
          coloring and statistics for coverage by that subset.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>external-format</term>
      <listitem>
	<para>
	  Controls the external format of the html files.
	</para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>statistics</term>
      <listitem>
	<para>
	  If non-nil (the default), a comma-separated file is 
	  generated with the summary of statistics. You can specify a
	  filename for the statistics argument, otherwise
	  "statistics.csv" is created in the directory of <varname>output-file</varname>.
          See documentation of coverage-statistics below for a
	  description of the values in the statistics file.
	</para>
      </listitem>
    </varlistentry>
  </variablelist>
  </refsect1>
  <refsect1><title>Example</title>
    <para>
      If you've loaded <filename>foo.lx64fsl</filename> and
      <filename>bar.lx64fsl</filename>, and have run some tests, you could
      do
    <programlisting>
(REPORT-COVERAGE "/my/dir/coverage/report.html")
    </programlisting>
    and this would generate <filename>report.html</filename>,
    <filename>foo_lisp.html</filename> and
    <filename>bar_lisp.html</filename>, and
    <filename>statistics.csv</filename> all in
    <filename>/my/dir/coverage/</filename>.
    </para>
  </refsect1>
</refentry>

<refentry id="f_reset-coverage">
  <indexterm zone="f_reset-coverage">
    <primary>reset-coverage</primary>
  </indexterm>
  
  <refnamediv>
    <refname>RESET-COVERAGE</refname>
    <refpurpose>
      Resets all coverage data back to the "Not Executed" state
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsect1><title>Description</title>
    <para>
      Resets all coverage data back to the "Not Executed" state
    </para>
  </refsect1>
</refentry>

<refentry id="f_clear-coverage">
  <indexterm zone="f_clear-coverage">
    <primary>clear-coverage</primary>
  </indexterm>
  
  <refnamediv>
    <refname>CLEAR-COVERAGE</refname>
    <refpurpose>
      Forget about all instrumented files that have been loaded.
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsect1><title>Description</title>
    <para>
      Gets rid of the information about which instrumented files have
      been loaded, so <literal>ccl:report-coverage</literal> will not report any files,
      and <literal>ccl:save-coverage-in-file</literal> will not save any info, until more
      instrumented files are loaded.
    </para>
  </refsect1>
</refentry>

<refentry id="f_save-coverage-in-file">
  <indexterm zone="f_save-coverage-in-file">
    <primary>save-coverage-in-file</primary>
  </indexterm>
  
  <refnamediv>
    <refname>SAVE-COVERAGE-IN-FILE</refname>
    <refpurpose>
      Save all coverage into to a file so you can restore it later.
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><function>save-coverage-in-file</function> pathname
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Description</title>
    <para>
      Saves all coverage info in a file, so you can restore the
      coverage state later. This allows you to combine multiple runs
      or continue in a later session. Equivalent to
      <literal>(ccl:write-coverage-to-file (ccl:get-coverage) pathname)</literal>.
    </para>
  </refsect1>
</refentry>

<refentry id="f_restore-coverage-from-file">
  <indexterm zone="f_restore-coverage-from-file">
    <primary>restore-coverage-from-file</primary>
  </indexterm>
  
  <refnamediv>
    <refname>RESTORE-COVERAGE-FROM-FILE</refname>
    <refpurpose>
      Load coverage state from a file.
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><function>restore-coverage-from-file</function> pathname
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Description</title>
    <para>
      Restores the coverage data previously saved with
      ccl:save-coverage-in-file, for the set of instrumented fasls
      that were loaded both at save and restore time. I.e. coverage
      info is only restored for files that have been loaded in this
      session. For example if in a previous session you had loaded
      <filename>"foo.lx86fsl"</filename> and then saved the coverage info, in this session
      you must load the same <filename>"foo.lx86fsl"</filename> before calling
      <literal>restore-coverage-from-file</literal> in order to retrieve the stored
      coverage info for "foo".  Equivalent to <literal>(ccl:restore-coverage
      (ccl:read-coverage-from-file pathname))</literal>.
    </para>
  </refsect1>
</refentry>

<refentry id="f_get-coverage">
  <indexterm zone="f_get-coverage">
    <primary>get-coverage</primary>
  </indexterm>
  
  <refnamediv>
    <refname>GET-COVERAGE</refname>
    <refpurpose>
      Returns a snapshot of the current coverage data.
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsect1><title>Description</title>
    <para>
      Returns a snapshot of the current coverage data. A snapshot is a
      copy of the current coverage state. It can be saved in a file
      with <literal>ccl:write-coverage-to-file</literal>, reinstated back as the current
      state with <literal>ccl:restore-coverage</literal>, or combined with other
      snapshots with <literal>ccl:combine-coverage</literal>.
    </para>
  </refsect1>
</refentry>

<refentry id="f_restore-coverage">
  <indexterm zone="f_restore-coverage">
    <primary>restore-coverage</primary>
  </indexterm>
  
  <refnamediv>
    <refname>RESTORE-COVERAGE</refname>
    <refpurpose>
      Reinstalls a coverage snapshot as the current coverage state.
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><function>restore-coverage</function> snapshot
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Description</title>
    <para>
      Reinstalls a coverage snapshot as the current coverage state.
    </para>
  </refsect1>
</refentry>

<refentry id="f_combine-coverage">
  <indexterm zone="f_combine-coverage">
    <primary>combine-coverage</primary>
  </indexterm>
  
  <refnamediv>
    <refname>COMBINE-COVERAGE</refname>
    <refpurpose>
      Combines multiple coverage snapshots into one.
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

   <refsynopsisdiv>
     <synopsis><function>combine-coverage</function> snapshots
     </synopsis>
   </refsynopsisdiv>

  <refsect1><title>Description</title>
    <para>
      Takes a list of coverage snapshots and returns a new coverage snapshot
      representing a union of all the coverage data.
    </para>
  </refsect1>
</refentry>


<refentry id="f_write-coverage-to-file">
  <indexterm zone="f_write-coverage-to-file">
    <primary>write-coverage-to-file</primary>
  </indexterm>
  
  <refnamediv>
    <refname>WRITE-COVERAGE-TO-FILE</refname>
    <refpurpose>
      Save a coverage snapshot in a file.
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><function>write-coverage-to-file</function> snapshot pathname
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Description</title>
    <para>
      Saves the coverage snapshot in a file. The snapshot can be
      loaded back with <literal>ccl:read-coverage-from-file</literal> or loaded and
      restored with <literal>ccl:restore-coverage-from-file</literal>. Note that the file
      created is actually a lisp source file and can be compiled for
      faster loading.
    </para>
  </refsect1>
</refentry>

<refentry id="f_read-coverage-from-file">
  <indexterm zone="f_read-coverage-from-file">
    <primary>read-coverage-from-file</primary>
  </indexterm>
  
  <refnamediv>
    <refname>READ-COVERAGE-FROM-FILE</refname>
    <refpurpose>
      Return the coverage snapshot saved in a file.
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><function>read-coverage-from-file</function> pathname
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Description</title>
    <para>
      Returns the snapshot saved in pathname. Doesn't affect the
      current coverage state. pathname can be the file previously
      created with <literal>ccl:write-coverage-to-file</literal> or
      <literal>ccl:save-coverage-in-file</literal>, or it can be the name of the fasl
      created from compiling such a file.
    </para>
  </refsect1>
</refentry>

<refentry id="f_coverage-statistics">
  <indexterm zone="f_coverage-statistics">
    <primary>coverage-statistics</primary>
  </indexterm>
  
  <refnamediv>
    <refname>COVERAGE-STATISTICS</refname>
    <refpurpose>
      Returns a sequence of <literal>ccl:coverage-statistics</literal> objects, one per source file.
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><function>coverage-statistics</function>
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Description</title>
    <para>
      Returns a sequence of <literal>ccl:coverage-statistics</literal> objects, one for each
      source file, containing the same information as that written to
      the statistics file by <literal>ccl:report-coverage</literal>. The following
      accessors are defined for <literal>ccl:coverage-statistics</literal> objects:
      <variablelist>
      <varlistentry>
	<term><function>coverage-source-file</function></term>
	<listitem>
	  <para>
	    the name of the source file corresponding to this information
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><function>coverage-expressions-total</function></term>
	<listitem>
	  <para>
	    the total number of expressions
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><function>coverage-expressions-entered</function></term>
	<listitem>
	  <para>
	    the number of source expressions that have been entered
	    (i.e. at least partially covered)
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><function>coverage-expressions-covered</function></term>
	<listitem>
	  <para>
	    the number of source expressions that were fully covered
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><function>coverage-unreached-branches</function></term>
	<listitem>
	  <para>
	    the number of conditionals with one branch taken and one not taken
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><function>coverage-code-forms-total</function></term>
	<listitem>
	  <para>
	    the total number of code forms. A code form is an
	    expression in the final stage of compilation, after all
	    macroexpansion and compiler transforms and simplification
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><function>coverage-code-forms-covered</function></term>
	<listitem>
	  <para>
	    the number of code forms that have been entered
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><function>coverage-functions-total</function></term>
	<listitem>
	  <para>
	    the total number of functions
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><function>coverage-functions-fully-covered</function></term>
	<listitem>
	  <para>
	    the number of functions that were fully covered
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><function>coverage-functions-partly-covered</function></term>
	<listitem>
	  <para>
	    the number of functions that were partly covered
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><function>coverage-functions-not-entered</function></term>
	<listitem>
	  <para>
	    the number of functions never entered
	  </para>
	</listitem>
      </varlistentry>
      </variablelist>
    </para>
  </refsect1>
</refentry>

<refentry id="f_reset-incremental-coverage">
  <indexterm zone="f_reset-incremental-coverage">
    <primary>reset-incremental-coverage</primary>
  </indexterm>
  
  <refnamediv>
    <refname>RESET-INCREMENTAL-COVERAGE</refname>
    <refpurpose>
      Reset incremental coverage.
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><function>reset-incremental-coverage</function>
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Description</title>
    <para>
      Marks a starting point for recording incremental coverage.
      Note that calling
      this function does not affect regular coverage data (whereas calling
      <literal>ccl:reset-coverage</literal> resets incremental coverage as well).
    </para>
  </refsect1>
</refentry>


<refentry id="f_get-incremental-coverage">
  <indexterm zone="f_get-incremental-coverage">
    <primary>get-incremental-coverage</primary>
  </indexterm>
  
  <refnamediv>
    <refname>GET-INCREMENTAL-COVERAGE</refname>
    <refpurpose>
      Returns the delta of coverage since the last incremental reset.
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><function>get-incremental-coverage</function> &key; (reset t)
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Description</title>
    <para>
      Returns the delta of coverage since the last reset of incremental coverage.
     If <literal>reset</literal> is true (the default), it also resets incremental coverage
     now, so that the next call to <literal>get-incremental-coverage</literal> will return
     the delta from this point.
     </para>
     <para>
      Incremental coverage deltas are represented differently than the full coverage snapshots
      returned by functions such as <literal>ccl:get-coverage</literal>.  Incremental
      coverage uses an abbreviated format
      and is missing some of the information in a full snapshot, and therefore cannot be passed to
      functions documented to accept a <varname>snapshot</varname>, only to functions
      specifically documented to accept incremental coverage deltas.
     </para>
  </refsect1>
</refentry>

<refentry id="f_incremental-coverage-source-matches">
  <indexterm zone="f_incremental-coverage-source-matches">
    <primary>incremental-coverage-source-matches</primary>
  </indexterm>
  
  <refnamediv>
    <refname>INCREMENTAL-COVERAGE-SOURCE-MATCHES</refname>
    <refpurpose>
      Find incremental coverage deltas intersecting source regions.
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><function>incremental-coverage-source-matches</function> collection sources
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Arguments and Values</title>
  <variablelist>
    <varlistentry>
      <term>collection</term>
       <listitem>
         <para>
          A hash table mapping arbitrary keys to incremental coverage deltas, or a sequence of
          incremental coverage deltas.
         </para>
        </listitem>
    </varlistentry>
    <varlistentry>
      <term>sources</term>
       <listitem>
         <para>
          A list of pathnames and/or source-notes, the latter representing a range within a file.
         </para>
        </listitem>
    </varlistentry>
   </variablelist>
   </refsect1>

  <refsect1><title>Description</title>
    <para>
     Given a hash table <literal>collection</literal> whose values are incremental coverage
     deltas, return a list of all keys corresponding to those deltas that intersect any region
     in <literal>sources</literal>.
     </para>
     <para>
     For example if the deltas represent tests, then the returned value is a list of all tests
     that cover some part of the source regions.
     </para>
     <para>
     <literal>collection</literal> can also be a sequence of deltas, in which case a subsequence
      of matching deltas is returned.  In particular you can test whether any particular delta
      intersects the sources by passing it in as a single-element list.
     </para>
  </refsect1>
</refentry>

<refentry id="f_incremental-coverage-svn-matches">
  <indexterm zone="f_incremental-coverage-svn-matches">
    <primary>incremental-coverage-svn-matches</primary>
  </indexterm>
  
  <refnamediv>
    <refname>INCREMENTAL-COVERAGE-SVN-MATCHES</refname>
    <refpurpose>
      Find incremental coverage deltas matching changes from a particular subversion revision.
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><function>incremental-coverage-svn-matches</function> collection &key; (directory (current-directory)) (revision :base)
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Arguments and Values</title>
  <variablelist>
    <varlistentry>
      <term>collection</term>
       <listitem>
         <para>
          A hash table mapping arbitrary keys to incremental coverage deltas, or a sequence of
          incremental coverage deltas.
         </para>
        </listitem>
    </varlistentry>
    <varlistentry>
      <term>directory</term>
       <listitem>
         <para>
          The pathname of a subversion working directory.
         </para>
        </listitem>
    </varlistentry>
    <varlistentry>
      <term>revision</term>
       <listitem>
         <para>
          The revision to compare to the working directory, an integer or another
          value whose printed representation is suitable for passing as the
          <literal>--revision</literal> argument
          to <filename>svn</filename>.
         </para>
        </listitem>
    </varlistentry>
   </variablelist>
   </refsect1>

  <refsect1><title>Description</title>
    <para>
     Given a hash table <literal>collection</literal> whose values are incremental coverage
     deltas, return a list of all keys corresponding to those deltas that intersect any changed
     source in <literal>directory</literal> since revision <literal>revision</literal> in subversion.
     </para>
     <para>
     For example if the deltas represent tests, then the returned value is a list of all tests
     that might be affected by the changes.
     </para>
     <para>
     <literal>collection</literal> can also be a sequence of deltas, in which case a subsequence
      of matching deltas is returned.  In particular you can test whether any particular delta
      is affected by the changes by passing it in as a single-element list.
     </para>
  </refsect1>
</refentry>



<refentry id="v_compile-code-coverage">
  <indexterm zone="v_compile-code-coverage">
    <primary>*COMPILE-CODE-COVERAGE*</primary>
  </indexterm>
  
  <refnamediv>
    <refname>*COMPILE-CODE-COVERAGE*</refname>
    <refpurpose>
      When true, instrument functions being compiled to collect code coverage information.
    </refpurpose>
    <refclass>Variable</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><varname>*compile-code-coverage*</varname>
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Description</title>
    <para>
      This variable controls whether functions are instrumented for
      code coverage. Files compiled while this variable is true will
      contain code coverage instrumentation.
    </para>
  </refsect1>
</refentry>

<refentry id="v_without-compiling-code-coverage">
  <indexterm zone="v_without-compiling-code-coverage">
    <primary>without-compiling-code-coverage</primary>
  </indexterm>
  
  <refnamediv>
    <refname>WITHOUT-COMPILING-CODE-COVERAGE</refname>
    <refpurpose>
      Don't record code coverage for forms within the body.
    </refpurpose>
    <refclass>Macro</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><function>without-compiling-code-coverage</function>
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Description</title>
    <para>
      This macro arranges so that body doesn't record internal details
      of code coverage. It will be considered totally covered if it's
      entered at all. The Common Lisp macros <literal>ASSERT</literal> and <literal>CHECK-TYPE</literal> use
      this macro.
    </para>
  </refsect1>
</refentry>

</sect2>

<sect2 id="code-coverage-interpreting-code-coloring"><title>Interpreting Code Coloring</title>
<para>

 The output of ccl:report-coverage consists of formatted source code, with coverage indicated by
 coloring.  Four colors are used: dark green for forms that compiled to code in which every single
 instruction was executed, light green for forms that have been entered but weren't totally covered, red
 for forms that were never entered, and the page background color for toplevel forms that weren't
 instrumented.

</para>
<para>
 The source coloring is applied from outside in.  So for example if you have

  <programlisting>
(outer-form ... (inner-form ...) ...)
  </programlisting>

 first the whole outer form is painted with whatever color expresses the outer form coverage, and then the
 inner form color is replaced with whatever color expresses the inner form coverage.  One consequence of
 this approach is that every part of the outer form that is not specifically inside some executable inner
 form will have the outer form's coverage color. If the syntax of outer form involves some non-executable
 forms, or forms that do not have coverage info of their own for whatever reason, then they will just
 inherit the color of the outer form, because they don't get repainted with a color of their own.
</para>

<para>
 One case in which this approach can be confusing is in the case of symbols.  As noted in the Limitations
 section, coverage information is not recorded for variables; hence the coloring of a variable does not
 convey information about whether the variable was evaluated or not -- that information is not available,
 and the variable just inherits the color of the form that contains it.
</para>


</sect2>
</sect1>

<sect1 id="other-extensions"><title>Other Extensions</title>
<refentry id="v_quit">
  <indexterm zone="v_quit">
    <primary>quit</primary>
  </indexterm>
  
  <refnamediv>
    <refname>QUIT</refname>
    <refpurpose>
      Cleanly exit the lisp.
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><function>quit</function> &optional; (exit 0) &key; error-handler
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Summary</title>
    <para>
      Cleanly exit from lisp.  If the exit argument is a value of type
      (signed-byte 32), that value will be passed to the C library
      function _exit() as the status code.  (A value of nil is treated
      as a zero.)
    </para>
    <para>
      Alternatively, exit may be a function of no arguments;  this function
      will be called instead of _exit() to exit the lisp.
    </para>
    <para>
      The error-handler argument, if supplied, must be a function of one
      argument, the condition, that will be called if an error occurs when
      preparing to quit.  The error-handler function should exit the lisp.
    </para>
  </refsect1>
</refentry>

<refentry id="v_wait-for-signal">
  <indexterm zone="v_wait-for-signal">
    <primary>wait-for-signal</primary>
  </indexterm>
  
  <refnamediv>
    <refname>WAIT-FOR-SIGNAL</refname>
    <refpurpose>
      Wait for a particular signal to be received.
    </refpurpose>
    <refclass>Function</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis><function>wait-for-signal</function> s duration
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Summary</title>
    <para>
      Wait for the signal with signal number s to be received, or until
      duration seconds have elapsed.  If duration is nil, wait for an
      indeterminate "very long time" (many years).
    </para>
    <para>
      If signal number s is outside the range of valid signals, or is
      reserved by the lisp for its own use, an error is signaled.
      (An error is always signaled on Windows systems.)
    </para>
  </refsect1>
</refentry>

<refentry id="v_unwind-protect">
  <indexterm zone="v_unwind-protect">
    <primary>unwind-protect</primary>
  </indexterm>
  
  <refnamediv>
    <refname>UNWIND-PROTECT</refname>
    <refpurpose>
      Ensure cleanup-forms are executed.
    </refpurpose>
    <refclass>Special operator</refclass>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis>
      <function>unwind-protect</function> protected-form {cleanup-form}*
    </synopsis>
  </refsynopsisdiv>

  <refsect1><title>Summary</title>
    <para>
      In &CCL;, the cleanup forms are always executed as if they were
      wrapped with <xref linkend="m_without-interrupts"/>.
      To allow interrupts, use
      <xref linkend="m_with-interrupts-enabled"/>.
    </para>
  </refsect1>
</refentry>

<refentry id="v_disassemble-verbose">
  <indexterm zone="v_disassemble-verbose">
    <primary>*disassemble-verbose*</primary>
  </indexterm>
  
  <refnamediv>
    <refname>*disassemble-verbose*</refname>
    <refpurpose>
      When true, display verbose disassembly output.
    </refpurpose>
    <refclass>Variable</refclass>
  </refnamediv>

  <refsect1><title>Description</title>
    <para>
      When true, the output of <literal>disassemble</literal> may
      include platform-dependent additional information.  For
      instance, on the x86 ports, the output will include the x86
      opcode bytes.
    </para>
    <para>
      The default value is <literal>nil</literal>.
    </para>
  </refsect1>
</refentry>

</sect1>
</chapter>
