<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl"
  href="http://docbook.sf.net/release/xsl/current/manpages/docbook.xsl"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V@DTDVER@//EN"
          "@DTD@" [
  <!-- allow alt in acronym -->
  <!ENTITY % local.word.char.mix "|alt">
  <!ENTITY % cl-entities SYSTEM "cl-ent.xml">
  %cl-entities;
  <!ENTITY % imp-entities SYSTEM "impent.xml">
  %imp-entities;
  <!ENTITY % unix-entities SYSTEM "unix-ent.xml">
  %unix-entities;
  <!ENTITY ld "<replaceable>locale-dir</replaceable>">
  <!ENTITY lf "<replaceable>lisp-file</replaceable>">
  <!ENTITY lld "<replaceable>lisp-lib-dir</replaceable>">
  <!ENTITY exprs "<replaceable>expressions</replaceable>">
  <!ENTITY opt-lf '<option><link linkend="opt-exec-file">&lf;</link></option>'>
]>

<refentry id="clisp">

<refentryinfo>
 <title>&clisp; version @VERSION@</title>
 <subtitle>Platform: @PLATFORM@</subtitle>
 <date>Last modified: @TODAY@</date>
 <productnumber>@VERSION@</productnumber>
 <productname>CLISP</productname>
 &clisp-authors; &clisp-doc-copyright; &clisp-abstract;
</refentryinfo>

<refmeta>
<refentrytitle>clisp</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source-name">ANSI Common Lisp</refmiscinfo>
<refmiscinfo class="manual">Platform: @PLATFORM@</refmiscinfo>
</refmeta>

<refnamediv id="summary">
<refname>clisp</refname>
<refpurpose>&the-ansi; &cl; compiler, interpreter and debugger.</refpurpose>
</refnamediv>

<refsynopsisdiv id="synopsis"><cmdsynopsis>&clisp-cmd;
<group><arg><option><link linkend="opt-help">-h</link></option></arg>
 <arg><option><link linkend="opt-help">--help</link></option></arg></group>
<arg><option><link linkend="opt-version">--version</link></option></arg>
<arg><option><link linkend="opt-license">--license</link></option></arg>
<arg><option><link linkend="opt-help-image">-help-image</link></option></arg>
<arg><option><link linkend="opt-libdir">-B &lld;</link></option></arg>
<arg><option><link linkend="opt-printlibdir">-b</link></option></arg>
<arg><option><link linkend="opt-link-set">-K
   <replaceable>linking-set</replaceable></link></option></arg>
<arg><option><link linkend="opt-memfile">-M
   <replaceable>mem-file</replaceable></link></option></arg>
<arg><option><link linkend="opt-memsize">-m &mems-r;</link></option></arg>
<arg><option><link linkend="opt-lang">-L &lang-r;</link></option></arg>
<arg><option><link linkend="opt-locale">-N &ld;</link></option></arg>
<arg><option><link linkend="opt-enc">-E&dom-r; &encoding-r;</link></option></arg>
<group><arg>&opt-q;</arg>
 <arg><option><link linkend="opt-verbose">--quiet</link></option></arg>
 <arg><option><link linkend="opt-verbose">--silent</link></option></arg>
 <arg>&opt-v;</arg>
 <arg><option><link linkend="opt-verbose">--verbose</link></option></arg></group>
<arg><option><link linkend="opt-on-error">-on-error
   <replaceable>action</replaceable></link></option></arg>
<arg><option><link linkend="opt-repl">-repl</link></option></arg>
<arg><option><link linkend="opt-wait">-w</link></option></arg>
<arg><option><link linkend="opt-ilisp">-I</link></option></arg>
<arg>&opt-norl;</arg>
<group><arg>&opt-ansi;</arg><arg>&opt-traditional;</arg></group>
<arg>&opt-modern;</arg>
<arg><option><link linkend="opt-pack">-p &pack-r;</link></option></arg>
<arg>&opt-C;</arg>
<arg>&opt-norc;</arg>
<arg rep="repeat"><option><link linkend="opt-load-paths">-lp
   &dir-r;</link></option></arg>
<arg rep="repeat"><option><link linkend="opt-init">-i
   <replaceable>init-file</replaceable></link></option></arg>
<arg rep="repeat"><option><link linkend="opt-compile">-c</link></option>
 <arg><option><link linkend="opt-list">-l</link></option></arg> &lf;
 <arg><option><link linkend="opt-out">-o</link>
   <replaceable>output-file</replaceable></option></arg></arg>
<arg rep="repeat"><option><link linkend="opt-exec-expr">-x
   &exprs;</link></option></arg>
<arg>&opt-lf; <arg rep="repeat"><option>&arg-r;</option></arg></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsection id="description"><title>Description</title>

<para>Invokes the &cl; interpreter and compiler.</para>

<refsection id="interactive-mode"><title>Interactive Mode</title>

<para>When called without <link linkend="batch-mode">batch</link> arguments,
 executes the &repl;, in which expressions are in turn <itemizedlist>
<listitem><simpara>&read; from the standard input,</simpara></listitem>
<listitem><simpara>&eval;uated by the lisp interpreter,</simpara></listitem>
<listitem><simpara>and their results are &print;ed to the standard output.
</simpara></listitem></itemizedlist></para>
</refsection>

<refsection id="batch-mode"><title>Non-Interactive (Batch) Mode</title>

<para>Invoked with &opt-c;, compiles the specified lisp files to a
platform-independent &bytecode; which can be executed more efficiently.</para>
<para>Invoked with &opt-x;, executes the specified lisp expressions.</para>
<para>Invoked with &opt-lf;, runs the specified lisp file.</para>
<para>Batch mode activates the &opt-q; option.</para>
</refsection>

</refsection>

<refsection id="options"><title>Options</title>

<variablelist>
<varlistentry id="opt-help"><term><option>-h</option></term>
 <term><option>--help</option></term>
 <listitem><simpara>Displays a help message on how to invoke &clisp;.
</simpara></listitem></varlistentry>

<varlistentry id="opt-version"><term><option>--version</option></term>
 <listitem><simpara>Displays the &clisp; version number,
   as given by the function &lisp-implementation-version;,
   the value of the variable &features-my;,
   as well some other information.</simpara></listitem></varlistentry>

<varlistentry id="opt-license"><term><option>--license</option></term>
 <listitem><simpara>Displays a summary of the licensing information,
   the &gnu; &gpl;.</simpara></listitem></varlistentry>

<varlistentry id="opt-help-image"><term><option>-help-image</option></term>
 <listitem><simpara>Displays information about the &mem-image; being invoked:
   whether is it suitable for scripting as well as the &documentation-k;
   supplied to &savemem;.</simpara></listitem></varlistentry>

<varlistentry id="opt-libdir"><term><option>-B</option> &lld;</term>
 <listitem><simpara>Specifies the installation directory.
   This is the directory containing the linking sets and other data files.
   This option is normally not necessary, because the installation directory
   is already built-in into the &clisp-cmd; executable.
   Directory &lld; can be changed dynamically using the &symbol-macro; &libdir;.
</simpara></listitem></varlistentry>

<varlistentry id="opt-printlibdir"><term><option>-b</option></term>
 <listitem><simpara>Print the installation directory and exit immediately.
   The namestring of &libdir; is printed without any quotes.
   This is mostly useful in module Makefiles, see,
   e.g., <filename role="clisp-cvs">modules/syscalls/Makefile.in</filename>.
</simpara></listitem></varlistentry>

<varlistentry id="opt-link-set"><term><option>-K</option>
  <replaceable>linking-set</replaceable></term>
 <listitem><para>Specifies the &linkset; to be run.
   This is a directory (relative to the <link linkend="opt-libdir">&lld;</link>)
   containing at least a main executable (&rt;) and an initial &mem-image;.
   Possible values are
   <variablelist>&varlist-table;<varlistentry><term>&base;</term>
     <listitem><simpara>the core &clisp;</simpara></listitem></varlistentry>
    <varlistentry><term>&full;</term>
     <listitem><simpara>core plus all the modules with which this
       installation was built, see
       <olink targetdoc="impnotes" targetptr="modules"/>.
   </simpara></listitem></varlistentry></variablelist>
   The <olink targetdoc="impnotes" targetptr="faq-modules">default</olink>
   is &base;.</para></listitem></varlistentry>

<varlistentry id="opt-memfile"><term><option>-M</option>
  <replaceable>mem-file</replaceable></term>
 <listitem><simpara>Specifies the initial &mem-image;.  This must be a
   memory dump produced by the &savemem; function by this &clisp-cmd; &rt;.
<!-- #ifdef UNIX -->
   It may have been compressed using &gnu; &gzip;.
<!-- #endif -->
</simpara></listitem></varlistentry>

<varlistentry id="opt-memsize"><term><option>-m</option> &mems-r;</term>
 <listitem><para>Sets the amount of memory &clisp;
   tries to grab on startup. The amount may be given as
   <variablelist>
    <varlistentry><term>&n-r;</term><term>&n-r;<command>B</command></term>
     <listitem><simpara>measured in bytes
    </simpara></listitem></varlistentry>
    <varlistentry><term>&n-r;</term><term>&n-r;<command>W</command></term>
     <listitem><simpara>measured in machine words (4&times;&n-r; on
       32-bit platforms, 8&times;&n-r; on 64-bit platforms)
    </simpara></listitem></varlistentry>
    <varlistentry>
     <term>&n-r;<command>K</command></term>
     <term>&n-r;<command>KB</command></term>
     <listitem><simpara>measured in kilobytes
    </simpara></listitem></varlistentry>
     <varlistentry><term>&n-r;<command>KW</command></term>
     <listitem><simpara>measured in kilowords
    </simpara></listitem></varlistentry>
    <varlistentry>
     <term>&n-r;<command>M</command></term>
     <term>&n-r;<command>MB</command></term>
     <listitem><simpara>measured in megabytes
   </simpara></listitem></varlistentry>
    <varlistentry><term>&n-r;<command>MW</command></term>
     <listitem><simpara>measured in megawords
   </simpara></listitem></varlistentry></variablelist>
   The default is 3 megabytes.
<!-- #if (oint_addr_len+addr_shift==24) -->
   The argument is constrained between 100 KB and 16 MB.
<!-- #elif (oint_addr_len+addr_shift==26) -->
   The argument is constrained between 100 KB and 64 MB.
<!-- #elif (oint_addr_len+addr_shift==28) -->
   The argument is constrained between 100 KB and 256 MB.
<!-- #else -->
   The argument is constrained above 100 KB.
<!-- #endif -->
   </para><simpara>This version of &clisp;
<!-- #if defined(SPVW_MIXED) && defined(SPVW_BLOCKS) -->
<!-- #ifdef GENERATIONAL_GC -->
   is not likely to actually use the entire &mems-r; since &gc;ion will
   periodically reduce the amount of used memory.
   It is therefore common to specify 10 MB even if only 2 MB are going
   to be used.
<!-- #else -->
   eventually uses the entire &mems-r;.
<!-- #endif -->
<!-- #else -->
   allocates memory dynamically. &mems-r; is essentially ignored
   (except that it determines the Lisp &STACK; size).
<!-- #endif -->
</simpara></listitem></varlistentry>

<varlistentry id="opt-lang"><term><option>-L</option> &lang-r;</term>
 <listitem><para>Specifies the
   <olink targetdoc="impnotes" targetptr="language">language</olink>
   &clisp; uses to communicate with the user. This may be
<!-- #ifndef GNU_GETTEXT -->
   only <command>english</command>.
<!-- #else -->
   one of <simplelist type="inline">
    <member><command>english</command></member>
    <member><command>german</command></member>
    <member><command>french</command></member>
    <member><command>spanish</command></member>
    <member><command>dutch</command></member>
    <member><command>russian</command></member>
    <member><command>danish</command></member></simplelist>.
   Other languages may be specified through the &env-var; <envar>LANG</envar>,
   provided the corresponding message catalog is installed.
<!-- #endif -->
   The language may be changed dynamically using the &symbol-macro;
   &curr-lang;.</para></listitem></varlistentry>

<varlistentry id="opt-locale"><term><option>-N</option> &ld;</term>
<listitem><simpara>Specifies the base directory of locale files.
  &clisp; will search its message catalogs in
  <filename>&ld;/&lang-r;/LC_MESSAGES/clisp.mo</filename>.
  This directory may be changed dynamically using the &symbol-macro;
  &curr-lang;.</simpara></listitem></varlistentry>

<varlistentry id="opt-enc">
 <term><option>-E&dom-r; &encoding-r;</option></term>
 <listitem><para>Specifies the encoding used for the given domain,
   overriding the default which depends on the &env-var;s
   <envar>LC_ALL</envar>, <envar>LC_CTYPE</envar>, <envar>LANG</envar>.
   &dom-r; can be
   <variablelist>&varlist-table;
    <varlistentry><term><constant>file</constant></term>
     <listitem><simpara>affecting &def-file-enc;
    </simpara></listitem></varlistentry>
    <varlistentry><term><constant>pathname</constant></term>
     <listitem><simpara>affecting &path-enc;
    </simpara></listitem></varlistentry>
    <varlistentry><term><constant>terminal</constant></term>
     <listitem><simpara>affecting &term-enc;
    </simpara></listitem></varlistentry>
    <varlistentry><term><constant>foreign</constant></term>
     <listitem><simpara>affecting &foreign-enc;
    </simpara></listitem></varlistentry>
    <varlistentry><term><constant>misc</constant></term>
     <listitem><simpara>affecting &misc-enc;
    </simpara></listitem></varlistentry>
    <varlistentry><term><replaceable>blank</replaceable></term>
     <listitem><simpara>affecting all of the above.
   </simpara></listitem></varlistentry></variablelist></para>
   <warning><para>Note that the values of these &symbol-macro;s that have
     been saved in a &mem-image; are ignored: these &symbol-macro;s are
     reset based on the OS environment &after-e; the &mem-image; is loaded.
     You have to use the &RC-file;, &init-hooks; or &init-function; to
     set them on startup, but it is best to set the aforementioned
     &env-var;s appropriately for consistency with other programs.
     See <olink targetdoc="impnotes" targetptr="custom-init-fini"/>.
</para></warning></listitem></varlistentry>

<varlistentry id="opt-verbose"><term><option>-q</option></term>
 <term><option>--quiet</option></term>
 <term><option>--silent</option></term>
 <term><option>-v</option></term>
 <term><option>--verbose</option></term>
 <listitem><simpara>Change verbosity level: by default, &clisp; displays a
   banner at startup and a good-bye message when quitting, and initializes
   &load-verbose-var; and &compile-verbose-var; to &t;, and
   &load-print-var; and &compile-print-var; to &nil;, as per &ansi-cl;.
   The first &opt-q; removes the banner and the good-bye message, the
   second sets variables &load-verbose-var;, &compile-verbose-var; and
   &savemem-verbose; to &nil;.
   The first &opt-v; sets variables &err-pr-bt;, &load-print-var; and
   &compile-print-var; to &t;, the second sets &load-echo; to &t;.
   These settings affect the output produced by &opt-i; and &opt-c; options.
   Note that these settings persist into the &repl;.
   Repeated <option>-q</option> and <option>-v</option> cancel each other,
   e.g., <option>-q -q -v -v -v</option> is equivalent to <option>-v</option>.
</simpara></listitem></varlistentry>

<varlistentry id="opt-on-error">
 <term><option>-on-error</option> <replaceable>action</replaceable></term>
 <listitem><para>Establish global error handlers,
   depending on <replaceable>action</replaceable>:<variablelist>
    <varlistentry><term>appease</term>
     <listitem><simpara>&cont-err;s are turned into &warning-t;s (with
       &appease-cerrors;) other &error-t;s are handled in the default way
    </simpara></listitem></varlistentry>
    <varlistentry><term>debug</term>
     <listitem><simpara>&error-t;s &invoke-debugger; (the normal &repl;
       behavior), disables &batch-mode; imposed by &opt-c;, &opt-x;,
       and &opt-lf;,</simpara></listitem></varlistentry>
    <varlistentry><term>abort</term>
     <listitem><simpara>&cont-err;s are appeased, other &error-t;s
       are &abort;ed with &abort-on-error;</simpara></listitem></varlistentry>
    <varlistentry><term>exit</term>
     <listitem><simpara>&cont-err;s are appeased, other &error-t;s terminate
       &clisp; with &exit-on-error; (the normal &batch-mode; behavior).
     </simpara></listitem></varlistentry></variablelist>
   See also &set-global-handler;.</para></listitem></varlistentry>

<varlistentry id="opt-repl"><term><option>-repl</option></term>
 <listitem><simpara>Start an interactive &repl; after processing the
   &opt-c;, &opt-x;, and &opt-lf; options and on any &error-t; &signal;ed
   during that processing.</simpara>
<simpara>Disables &batch-mode;.</simpara></listitem></varlistentry>

<varlistentry id="opt-wait"><term><option>-w</option></term>
 <listitem><simpara>Wait for a keypress after program termination.
</simpara></listitem></varlistentry>

<varlistentry id="opt-ilisp"><term><option>-I</option></term>
 <listitem><para>Interact better with &emacs;
   (useful when running &clisp; under &emacs; using &slime;, &ilisp; et al).
   With this option, &clisp; interacts in a way that &emacs; can deal with:
   <itemizedlist><listitem><simpara>unnecessary prompts are not suppressed.
    </simpara></listitem>
<!-- #ifdef GNU_READLINE -->
    <listitem><simpara>The &readline; library treats &tab-c;
      (see <xref linkend="completion"/>) as a normal self-inserting
      character (see <olink targetdoc="impnotes" targetptr="faq-rl-tab"/>).
    </simpara></listitem>
<!-- #endif -->
</itemizedlist></para></listitem></varlistentry>

<varlistentry id="opt-norl"><term><option>-disable-readline</option></term>
 <listitem><simpara>Do not use &readline; even when it has been linked against.
   This can be used if one wants to paste non-&ascii; characters, or
   when &readline; misbehaves due to installation (different versions on
   the build and install machines) or setup (bad <envar>TERM</envar>
   &env-var; value) issues.</simpara></listitem></varlistentry>

<varlistentry id="opt-ansi"><term><option>-ansi</option></term>
 <listitem><simpara>Comply with the &ansi-cl; specification even where
   &clisp; has been traditionally different by setting the
   &symbol-macro; &ansi; to &t;.</simpara></listitem></varlistentry>

<varlistentry id="opt-traditional"><term><option>-traditional</option></term>
 <listitem><simpara>Traditional: reverses the residual effects of
   &opt-ansi; in the saved &mem-image;.</simpara></listitem></varlistentry>

<varlistentry id="opt-modern"><term><option>-modern</option></term>
 <listitem><simpara>Provides a modern view of symbols: at startup the
  &package-var; variable will be set to the &cs-clu; package, and the
  &print-case-var; will be set to <constant>:DOWNCASE</constant>.
  This has the effect that symbol lookup is case-sensitive (except for
  keywords and old-style packages) and that keywords and uninterned symbols
  are printed with lower-case preferrence.
   See <olink targetdoc="impnotes" targetptr="package-case"/>.
</simpara></listitem></varlistentry>

<varlistentry id="opt-pack"><term><option>-p</option> &pack-r;</term>
 <listitem><simpara>At startup the value of the variable &package-var;
   will be set to the package named &pack-r;.
   The default is the value of &package-var; when the image was
   <olink targetdoc="impnotes" targetptr="image">saved</olink>,
   normally &clu-pac;.</simpara></listitem></varlistentry>

<varlistentry id="opt-load-comp"><term><option>-C</option></term>
 <listitem><simpara>Compile when loading: at startup the value of the
   variable &load-comp; will be set to &t;.
   Code being &load;ed will then be &compile;d on the fly.
   This results in slower loading, but faster execution.
</simpara></listitem></varlistentry>

<varlistentry id="opt-norc"><term><option>-norc</option></term>
 <listitem><simpara>Normally &clisp; loads the user
   <ulink url="http://www.faqs.org/docs/artu/ch10s03.html"><quote>run
     control</quote> (RC)</ulink> file on startup (this happens
   &after-e; the &opt-C; option is processed).
   The file loaded is <filename>.clisprc.lisp</filename>
   or <filename>.clisprc.fas</filename>
   in the home directory &user-homedir-pathname;, whichever is newer.
   This option, &opt-norc;, prevents loading of the &RC-file;.
</simpara></listitem></varlistentry>

<varlistentry id="opt-load-paths"><term><option>-lp</option> &dir-r;</term>
 <listitem><simpara>Specifies directories to be added to &load-paths;
   at startup.  This is done &after-e; loading the &RC-file; (so that
   it does not override the command-line option) but &before-e; loading
   the init-files specified by the <option>-i</option> options (so that
   the init-files will be searched for in the specified directories).
   Several <option>-lp</option> options can be given; all the specified
   directories will be added.</simpara></listitem></varlistentry>

<varlistentry id="opt-init"><term><option>-i</option>
  <replaceable>init-file</replaceable></term>
 <listitem><simpara>Specifies initialization files to be &load;ed
   at startup.  These should be lisp files (source or compiled).
   Several <option>-i</option> options can be given; all the specified
   files will be loaded in order.</simpara></listitem></varlistentry>

<varlistentry id="opt-compile"><term><option>-c</option> &lf;</term>
 <listitem><simpara>Compiles the specified &lf;s to &bytecode;
   (<filename>*.fas</filename>).  The compiled files can then be
   &load;ed instead of the sources to gain efficiency.</simpara>
<simpara>Imposes &batch-mode;.</simpara></listitem></varlistentry>

<varlistentry id="opt-out"><term><option>-o</option>
  <replaceable>outputfile</replaceable></term>
 <listitem><simpara>Specifies the output file or directory for the
   compilation of the last specified <link linkend="opt-compile">&lf;</link>.
</simpara></listitem></varlistentry>

<varlistentry id="opt-list"><term><option>-l</option></term>
 <listitem><simpara>Produce a &bytecode; &disassemble; listing
   (<filename>*.lis</filename>) of the files being compiled.
   Useful only for debugging.
   See <olink targetdoc="impnotes" targetptr="compilefile"/> for details.
</simpara></listitem></varlistentry>

<varlistentry id="opt-exec-expr"><term><option>-x</option> &exprs;</term>
 <listitem><simpara>Executes a series of arbitrary expressions instead
   of a &repl;.
   The values of the expressions will be output to &standard-output-var;.
   Due to the argument processing done by the shell, the &exprs; must be
   enclosed in double quotes, and double quotes and backslashes must be
   escaped with backslashes.</simpara>
<simpara>Imposes &batch-mode;.</simpara></listitem></varlistentry>

<varlistentry id="opt-exec-file"><term>&lf; [ &arg-r; ... ]</term>
 <listitem><simpara>Loads and executes a &lf;, as described in
   <olink targetdoc="impnotes" targetptr="quickstart-unix"/>.
   There will be no &repl;.
   Before &lf; is loaded, the variable &args; will be bound to a list of
   strings, representing the &arg-r;s.
<!-- #ifdef UNIX -->
   The first line of &lf; may start with <command>#!</command>,
   thus permitting &clisp; to be used as a script interpreter.
<!-- #endif -->
   If &lf; is <command>-</command>,
   the &standard-input-var; is used instead of a file.</simpara>
<simpara>This option is <emphasis>disabled</emphasis> if the &mem-image;
 was created by &savemem; with &nil; &script-k; argument.
 In that case the &list-t; &args; starts with &lf;.</simpara>
<simpara>This option must be the last one.</simpara>
<simpara>No &RC-file; will be executed.</simpara>
<simpara>Imposes &batch-mode;.</simpara>
</listitem></varlistentry>

</variablelist>

<para>As usual, <option>--</option> stops option processing and places
 all remaining command line arguments into &args;.</para>

</refsection>

<refsection id="reference"><title>Language Reference</title>

<para>The language implemented is &the-ansi; &cl;.
 The implementation mostly conforms to the <olink targetdoc="impnotes"
 targetptr="ref-ansi">ANSI Common Lisp standard</olink>,
 see <olink targetdoc="impnotes" targetptr="ansi"/>.</para>

<bibliolist>&ansi-cl-bib;</bibliolist>

</refsection>

<refsection id="clue"><title>Command Line User Environment</title>

<variablelist>
<varlistentry><term>&help;</term>
 <listitem><simpara>get context-sensitive on-line help, see
   <olink targetdoc="impnotes" targetptr="environment"/>.
</simpara></listitem></varlistentry>

<varlistentry><term>(&apropos-my; &name-r;)</term>
 <listitem><simpara>list the &symbol-t;s matching &name-r;.
</simpara></listitem></varlistentry>

<varlistentry><term>(&describe-my; &symbol-r;)</term>
 <listitem><simpara>describe the &symbol-r;.
</simpara></listitem></varlistentry>

<varlistentry><term>(exit)</term><term>(quit)</term><term>(bye)</term>
 <listitem><simpara><olink targetdoc="impnotes" targetptr="quit">quit</olink>
 &clisp;.</simpara></listitem></varlistentry>

<varlistentry><term>EOF
<!-- #if defined(UNIX) -->
 (<keycombo>&ctrl;<keysym>D</keysym></keycombo> on &unix;)
<!-- #endif -->
<!-- #if defined(WIN32_NATIVE) -->
 (<keycombo>&ctrl;<keysym>Z</keysym></keycombo> on &win32;)
<!-- #endif -->
</term><listitem><simpara>leave the current level of the &repl;
 (see also <olink targetdoc="impnotes" targetptr="spec-symb"/>).
</simpara></listitem></varlistentry>

<!-- #ifdef GNU_READLINE -->
<varlistentry><term>arrow keys</term>
 <listitem><simpara>for editing and viewing the input history, using the
   &readline; library.</simpara></listitem></varlistentry>

<varlistentry id="completion"><term>&tab-c; key</term>
 <listitem><para>Context sensitive:
  <itemizedlist><listitem><simpara>If you are in the <quote>function
     position</quote> (in the first symbol after an opening paren or in
     the first symbol after a &sharp-prime;), the completion is
     limited to the symbols that name functions.</simpara></listitem>
   <listitem><simpara>If you are in the "filename position" (inside a
     string after &sharp-P;), the completion is done across file names,
     &bash;-style.</simpara></listitem>
   <listitem><simpara>If you have not typed anything yet, you will get
     a help message, as if by the &help; command.</simpara></listitem>
   <listitem><simpara>If you have not started typing the next symbol
     (i.e., you are at a whitespace), the current function or macro is
     &describe-my;d.</simpara></listitem>
   <listitem><simpara>Otherwise, the symbol you are currently typing is
     completed.</simpara></listitem></itemizedlist>
</para></listitem></varlistentry>
<!-- #endif -->
</variablelist>
</refsection>

<refsection id="using"><title>Using and Extending &clisp;</title>

<epigraph><attribution><ulink url="http://www.franz.com/~jkf/">John
  Foderaro</ulink></attribution>
 <para>&cl; is a <emphasis>programmable</emphasis>
  programming language.</para></epigraph>

<para>When &clisp; is invoked, the &rt; loads
 the <link linkend="init-mem">initial memory image</link> and outputs
 the <olink targetdoc="impnotes" targetptr="prompt">prompt</olink>;
 at which one can start typing &defvar;s, &defun;s and &defmacro;s.</para>

<para>To avoid having to re-enter the same definitions by hand in every
 session, one can create a lisp file with all the variables, functions,
 macros, etc.; (optionally) compile it with &compile-file;; and &load;
 it either by hand or from the &RC-file;; or save a &mem-image; to
 avoid the &load; overhead.</para>

<para>However, sometimes one needs to use some functionality implemented in
 another language, e.g., call a &c-lang; library function.
 For that one uses the <olink targetdoc="impnotes" targetptr="dffi">Foreign
  Function Interface</olink> and/or
 the <olink targetdoc="impnotes" targetptr="modules">External
  Modules</olink> facility.
 Finally, the truly adventurous ones might delve
 into <olink targetdoc="impnotes" targetptr="extend">Extending the
  Core</olink>.</para>

</refsection>

<refsection id="files"><title>Files</title>

<variablelist>
<varlistentry id="driver">
<!-- #if defined(UNIX) && !defined(UNIX_CYGWIN) -->
<term>&clisp-cmd;</term>
<!-- #endif -->
<!-- #if defined(WIN32_NATIVE) || defined(UNIX_CYGWIN) -->
<term><command>clisp.exe</command></term>
<!-- #endif -->
<listitem><simpara>startup driver (an executable or, rarely, a shell script)
  which remembers the location of the &rt;
  and starts it with the appropriate arguments
</simpara></listitem></varlistentry>

<varlistentry id="runtime">
<!-- #if defined(UNIX) && !defined(UNIX_CYGWIN) -->
<term>&lisp-run;</term>
<!-- #endif -->
<!-- #if defined(WIN32_NATIVE) || defined(UNIX_CYGWIN) -->
<term><filename>lisp.exe</filename></term>
<!-- #endif -->
<listitem><simpara>main executable (runtime) - the part of &clisp;
  implemented in &c-lang;.</simpara></listitem></varlistentry>

<varlistentry id="init-mem"><term><filename>lispinit.mem</filename></term>
<listitem><simpara>initial &mem-image; (the part of &clisp; implemented
  in lisp)</simpara></listitem></varlistentry>

<varlistentry id="config-lisp"><term><filename>config.lisp</filename></term>
<listitem><simpara>site-dependent configuration (should have been
  customized before &clisp; was built); see
  <olink targetdoc="impnotes" targetptr="customize"/>
</simpara></listitem></varlistentry>

<varlistentry><term><filename>*.lisp</filename></term>
<listitem><simpara>lisp source</simpara></listitem></varlistentry>

<varlistentry><term><filename>*.fas</filename></term>
<listitem><simpara>lisp code, compiled by &clisp;
</simpara></listitem></varlistentry>

<varlistentry><term><filename>*.lib</filename></term>
<listitem><simpara>lisp source library information,
  generated by &compile-file-my;, see
  <olink targetdoc="impnotes" targetptr="require"/>.
</simpara></listitem></varlistentry>

<varlistentry><term><filename>*.c</filename></term>
<listitem><simpara>C code, compiled from lisp source by &clisp;
 (see <olink targetdoc="impnotes" targetptr="dffi"/>)
</simpara></listitem></varlistentry>
</variablelist>
<para>For the &clisp; source files,
 see <olink targetdoc="impnotes" targetptr="source-files"/>.</para>
</refsection>

<refsection id="environment"><title>Environment</title>

<para>All &env-var;s that &clisp; uses are read at most once.</para>

<variablelist>
<varlistentry><term><envar>CLISP_LANGUAGE</envar></term>
 <listitem><simpara>specifies the language &clisp; uses to communicate
   with the user.  The legal values are identical to those of the &opt-L;
   option which can be used to override this &env-var;.
</simpara></listitem></varlistentry>

<!-- #ifdef ENABLE_UNICODE -->
<varlistentry><term><envar>LC_CTYPE</envar></term>
 <listitem><simpara>specifies the locale which determines the character
   set in use.  The value can be of the form
   <command>&lang-r;</command> or
   <command>&lang-r;_<replaceable>country</replaceable></command> or
   <command>&lang-r;_<replaceable>country</replaceable>.<replaceable>charset</replaceable></command>,
   where &lang-r; is a two-letter ISO 639
   language code (lower case), <replaceable>country</replaceable> is a
   two-letter ISO 3166 country code (upper case).
   <replaceable>charset</replaceable> is an optional character set
   specification, and needs normally not be given because the character
   set can be inferred from the language and country.
   This &env-var; can be overridden with the &opt-E; option.
</simpara></listitem></varlistentry>
<!-- #endif -->

<varlistentry><term><envar>LANG</envar></term>
 <listitem><simpara>specifies the language &clisp;
   uses to communicate with the user, unless it is already specified
   through the &env-var; <envar>CLISP_LANGUAGE</envar> or the
   &opt-L; option.
<!-- #ifdef ENABLE_UNICODE -->
   It also specifies the locale determining the character set in use, unless
   already specified through the &env-var; <envar>LC_CTYPE</envar>.
<!-- #endif -->
   The value may begin with a two-letter ISO 639 language code, for example
   <command>en</command>, <command>de</command>, <command>fr</command>.
</simpara></listitem></varlistentry>

<!-- #ifdef UNIX -->
<varlistentry><term><envar>HOME</envar></term><term><envar>USER</envar></term>
 <listitem><simpara>used for determining the value of the function
   &user-homedir-pathname;.</simpara></listitem></varlistentry>
<!-- #endif -->

<varlistentry>
<!-- #ifdef UNIX -->
<term><envar>SHELL</envar></term>
<!-- #endif -->
<!-- #ifdef WIN32_NATIVE -->
<term><envar>COMSPEC</envar></term>
<!-- #endif -->
<listitem><simpara>is used to find the interactive command interpreter
  called by &shell;.</simpara></listitem></varlistentry>

<!-- #ifdef UNIX -->
<varlistentry><term><envar>TERM</envar></term>
 <listitem><simpara>determines the screen size recognized by the pretty
   printer.</simpara></listitem></varlistentry>
<!-- #endif -->

<varlistentry><term><envar>ORGANIZATION</envar></term>
 <listitem><simpara>for &short-site-name; and &long-site-name; in
   &config-lisp;.</simpara></listitem></varlistentry>
<varlistentry><term><envar>CLHSROOT</envar></term>
 <listitem><simpara>for &clhs-root; in &config-lisp;.
</simpara></listitem></varlistentry>
<varlistentry><term><envar>IMPNOTES</envar></term>
 <listitem><simpara>for &impnotes-root; in &config-lisp;.
</simpara></listitem></varlistentry>
<varlistentry><term><envar>EDITOR</envar></term>
 <listitem><simpara>for <function>editor-name</function> in
   &config-lisp;.</simpara></listitem></varlistentry>

<varlistentry>
 <term><envar>LOGICAL_HOST_&host-r;_FROM</envar></term>
 <term><envar>LOGICAL_HOST_&host-r;_TO</envar></term>
 <term><envar>LOGICAL_HOST_&host-r;</envar></term>
 <listitem><simpara>for &load-lpt-db;</simpara></listitem></varlistentry>

</variablelist>
</refsection>

<refsection id="input-output"><title>Input and Outut</title>

<para>See <olink targetdoc="impnotes" targetptr="stream-stdio-init"/>.</para>

</refsection>

<refsection id="see-also"><title>See also</title>

<para><simplelist>
  <member><olink targetdoc="impnotes"/></member>
  <member><olink targetdoc="clink"/></member>
  <member>&cmucl; - <command>cmucl</command>(1)</member>
  <member>&sbcl; - <command>sbcl</command>(1)</member>
  <member>&emacs; - <command>emacs</command>(1)</member>
</simplelist></para>

</refsection>

<refsection id="bugs"><title>Bugs</title>

<para>When you encounter a bug in &clisp; or in its documentation (this
 manual page or <olink targetdoc="impnotes" targetptr="impnotes-top"/>),
 please report it to the &clisp;
 <ulink url="https://sourceforge.net/p/clisp/bugs/">SourceForge bug tracker</ulink>.
Login, either to your &sf; account, or to your
<ulink url="http://openid.net/">OpenID</ulink> account.
Then click the "Create Ticket" link on the left-hand side.</para>

<para><emphasis>Before</emphasis> submitting a bug report, please take
 the following basic steps to make the report more useful:<orderedlist>
 <listitem><simpara>Unless your bug is locale-specific, please set your
   locale to <literal>en</literal>.  You <emphasis>cannot</emphasis>
   assume that &clisp; maintainers understand a language other than
   <ulink url="http://www.catb.org/esr/faqs/hacker-howto.html#skills4">English</ulink>,
   even though, historically, few &clisp; maintainers spoke English natively.
 </simpara></listitem>
 <listitem><simpara>Do a clean build (remove your build directory
   and build &clisp; with <command>./configure --cbcx build</command>
   or at least do a <command role="unix">make distclean</command>
   before &make;).</simpara></listitem>
 <listitem><simpara>If you are reporting a <quote>hard crash</quote>
   (segmentation fault, bus error, core dump etc), please do
   <command>./configure &with-debug; --cbcx build-g ; cd build-g; gdb
    lisp.run</command>, then load the appropriate &linkset; by either
   &base; or &full; &gdb; command, and report the backtrace (see also
   <olink targetdoc="impnotes" targetptr="faq-debug"/>).</simpara></listitem>
 <listitem><simpara>If you are using pre-built binaries and experience a
   hard crash, the problem is likely to be in the incompatibilities
   between the platform on which the binary was built and yours; please
   try compiling the sources and report the problem if it persists.
</simpara></listitem></orderedlist></para>

<para>When submitting a bug report, please specify the following
 information:<orderedlist>
 <listitem><simpara>What is your platform (<command role="unix">uname
    -a</command> on a &unix; system)?</simpara></listitem>
 <listitem><simpara>Please supply the full output (copy and paste) of
   all the error messages.</simpara></listitem>
 <listitem><simpara>Please provide detailed instructions on how to
   reproduce the problem.</simpara></listitem>
 <listitem><simpara>Where did you get the &clisp; sources or binaries?  When?
   (Absolute dates, e.g., <quote>2006-01-17</quote>, are preferred over
   the relative ones, e.g., <quote>2 days ago</quote>. If you are using
   &git;, please supply the output of
   <command>git rev-list --max-count=1 HEAD</command>).</simpara></listitem>
 <listitem><para>If you are reporting a build failure:<orderedlist>
  <listitem><simpara>What is your compiler version?</simpara></listitem>
  <listitem><simpara>What is your &glibc; version (on &gnu;/&linux;)?
  </simpara></listitem>
  <listitem><simpara>What is the version of each of the
   <filename role="clisp-cvs">DEPENDENCIES</filename>?</simpara></listitem>
  <listitem><para>How did you run <filename role="clisp-cvs">configure</filename>?
   We need the options you used as well as the values of the &env-var;s
   <simplelist><member><envar>CC</envar></member>
   <member><envar>CFLAGS</envar></member><member><envar>CPPFLAGS</envar></member>
   <member><envar>LDFLAFS</envar></member>
   <member><envar>LD_LIBRARY_PATH</envar></member></simplelist>.</para></listitem>
  <listitem><simpara>Please attach all build logs.</simpara></listitem>
 </orderedlist></para></listitem>
 <listitem><simpara>If you have a working &clisp;, please supply the output of
  <command><link linkend="opt-version">clisp --version</link></command>
</simpara></listitem></orderedlist></para>

</refsection>

<refsection id="projects"><title>Projects</title>

<itemizedlist>
 <listitem><simpara>Enhance the compiler so that it can inline local
   functions.</simpara></listitem>
 <listitem><simpara>Embed &clisp; in &vim;.</simpara></listitem>
</itemizedlist>
</refsection>

</refentry>