doc/index.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <?xml-stylesheet type="text/xsl" href="clixdoc.xsl" ?>
   3
   4 <clix:documentation xmlns='http://www.w3.org/1999/xhtml' xmlns:clix='http://bknr.net/clixdoc'>
   5   <clix:title>HUNCHENTOOT - The Common Lisp web server formerly known as TBNL</clix:title>
   6   <clix:short-description>
   7     A fully-featured web server written in Common Lisp offering things
   8     like HTTP/1.1 chunking, persistent connections, and SSL.  Includes
   9     a framework for building dynamic websites interactively.
  10   </clix:short-description>
  11
  12   <h2>
  13     <a href="http://www.htg1.de/hunchentoot/hunchentoot.html"
  14        title="Click here for the Hunchentoot logo"
  15        class="noborder">
  16       <img align="top" width="93" height="45" border="0" src="hunchentoot.gif" />
  17     </a>
  18     HUNCHENTOOT - The Common Lisp web server formerly known as TBNL
  19   </h2>
  20
  21   <blockquote>
  22     <clix:chapter name='abstract' title='Abstract'>
  23       <p>
  24         Hunchentoot is a web server written in Common Lisp and at the
  25         same time a toolkit for building dynamic websites.  As a
  26         stand-alone web server, Hunchentoot is capable of HTTP/1.1
  27         chunking (both directions), persistent connections
  28         (keep-alive), and SSL.
  29       </p>
  30       <p>
  31         Hunchentoot provides facilities like automatic session
  32         handling (with and without cookies), logging, customizable
  33         error handling, and easy access to GET and POST parameters
  34         sent by the client. It does <em>not</em> include functionality
  35         to programmatically generate HTML output. For this task you
  36         can use any library you like, e.g. (shameless self-plug)
  37         <a href="http://weitz.de/cl-who/">CL-WHO</a> or
  38         <a href="http://weitz.de/html-template/">HTML-TEMPLATE</a>.
  39       </p>
  40       <p>
  41         Hunchentoot talks with its front-end or with the client over
  42         TCP/IP sockets and optionally uses multiprocessing to handle
  43         several requests at the same time.  Therefore, it cannot be
  44         implemented completely in
  45         <a href="http://www.lispworks.com/documentation/HyperSpec/Front/index.htm">portable
  46         Common Lisp</a>.  It currently works "natively" with
  47         <a href="http://www.lispworks.com/">LispWorks</a> (which is the
  48         main development and testing platform), and additionally on all
  49         Lisps which are supported by the compatibility
  50         layers <a href="http://common-lisp.net/project/usocket/">usocket</a>
  51         and <a href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux
  52         Threads</a>.
  53       </p>
  54       <p>
  55         Hunchentoot comes with a
  56         <a href="http://www.opensource.org/licenses/bsd-license.php">BSD-style
  57         license</a> so you can basically do with it whatever you want.
  58       </p>
  59       <p>
  60         Hunchentoot is (or was) for example used by
  61         <a href="http://postabon.com/">Postabon</a>,
  62         <a href="http://www.city-farming.de/">City Farming</a>,
  63         <a href="http://www.thoughtcrime.us/tp/">Trip Planner</a>,
  64         <a href="http://clutu.com/">clutu</a>,
  65         <a href="http://twitterbuzz.com/">TwitterBuzz</a>,
  66         <a href="http://www.jalat.com/">Jalat</a>,
  67         <a href="http://heikestephan.de/">Heike Stephan</a>,
  68         <a href="http://www.memetrics.com/">xOs</a>, and
  69         <a href="http://syseng.nist.gov/moss">the</a>
  70         <a href="http://syseng.nist.gov/se-interop">NIST</a>.
  71       </p>
  72       <p>
  73         <font color="red">Download shortcut:</font>
  74         <a href="http://weitz.de/files/hunchentoot.tar.gz">http://weitz.de/files/hunchentoot.tar.gz</a>.
  75       </p>
  76     </clix:chapter>
  77   </blockquote>
  78
  79   <clix:chapter name='contents' title='Contents'></clix:chapter>
  80   <clix:contents></clix:contents>
  81
  82   <clix:chapter name="install" title="Download and installation">
  83     Hunchentoot depends on a couple of other Lisp libraries which you'll need
  84     to install first:
  85     <ul>
  86       <li>Pierre R. Mai's <a href="http://www.cliki.net/md5">MD5</a>,</li>
  87       <li>Kevin Rosenberg's <a href="http://www.cliki.net/cl-base64">CL-BASE64</a>,</li>
  88       <li>Janis Dzerins' <a href="http://common-lisp.net/project/rfc2388/">RFC2388</a>,</li>
  89       <li>Peter Seibel's <a href="http://weitz.de/cl-fad/">CL-FAD</a>,</li>
  90       <li>Gary King's <a href="http://common-lisp.net/project/trivial-backtrace/">trivial-backtrace</a>,</li>
  91       <li>Erik Huelsmann's <a href="http://common-lisp.net/project/usocket">usocket</a> (unless you're using LispWorks),</li>
  92       <li>Greg Pfeil's <a href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux Threads</a> (unless you're using LispWorks),
  93       </li>
  94       <li>
  95         David Lichteblau's <a href="http://common-lisp.net/project/cl-plus-ssl/">CL+SSL</a>
  96         (unless you're using LispWorks),
  97       </li>
  98       <li>
  99         and my own <a href="http://weitz.de/flexi-streams/">FLEXI-STREAMS</a> (0.12.0 or higher),
 100         <a href="http://weitz.de/chunga/">Chunga</a> (1.0.0 or
 101         higher), and <a href="http://weitz.de/cl-ppcre/">
 102         CL-PPCRE</a> (plus
 103         <a href="http://weitz.de/cl-who/">CL-WHO</a> for the <a href="#start">example code</a>
 104         and <a href="http://weitz.de/drakma/">Drakma</a> for the <a href="#testing">tests</a>).
 105       </li>
 106     </ul>
 107
 108     Make sure to use the <em>newest</em> versions of all of these
 109     libraries (which might themselves depend on other libraries) - try
 110     the repository versions if you're in doubt.  Note: You can compile
 111     Hunchentoot without SSL support - and thus without the need to
 112     have CL+SSL - if you add <code>:HUNCHENTOOT-NO-SSL</code> to
 113     <a href="http://www.lispworks.com/documentation/HyperSpec/Body/v_featur.htm">
 114       <code>*FEATURES*</code></a> <em>before</em> you compile it.
 115     <p>
 116       Hunchentoot will only work with Lisps where
 117       the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#character_code">character
 118       codes</a> of
 119       all <a href="http://en.wikipedia.org/wiki/ISO_8859-1">Latin-1</a>
 120       characters coincide with their
 121       Unicode <a href="http://en.wikipedia.org/wiki/Code_point">code
 122       points</a> (which is the case for all current implementations I
 123       know).
 124     </p>
 125     <p>
 126       Hunchentoot itself together with this documentation can be
 127       downloaded from
 128       <a href="http://weitz.de/files/hunchentoot.tar.gz">http://weitz.de/files/hunchentoot.tar.gz</a>.
 129       The current version is 1.1.1.
 130     </p>
 131     <p>
 132       The preferred method to compile and load Hunchentoot is via
 133       <a href="http://www.cliki.net/asdf">ASDF</a>.  If you think that
 134       it's too much work to find and download all the libraries
 135       mentioned above, try something like
 136       <a href="http://common-lisp.net/project/asdf-install/">ASDF-INSTALL</a>,
 137       <a href="http://common-lisp.net/project/clbuild/">clbuild</a>,
 138       or my own <a href="http://weitz.de/starter-pack/">Starter
 139         Pack</a>.  There's also a port for
 140       <a href="http://www.gentoo.org/proj/en/common-lisp/index.xml">Gentoo
 141         Linux</a> thanks to Matthew Kennedy.
 142     </p>
 143     <p>
 144       The current development version of Hunchentoot can be found
 145       at <a href="http://bknr.net/trac/browser/trunk/thirdparty">http://bknr.net/trac/browser/trunk/thirdparty</a>.
 146       This is the one to send <a href="#mail">patches</a> against.
 147       Use at your own risk.
 148     </p>
 149     <p>
 150       An
 151       unofficial <a href="http://www.selenic.com/mercurial/wiki/">Mercurial</a>
 152       repository of older versions is available at
 153       <a href="http://arcanes.fr.eu.org/~pierre/2007/02/weitz/">http://arcanes.fr.eu.org/~pierre/2007/02/weitz/</a>
 154       thanks to Pierre Thierry.
 155     </p>
 156     <p>
 157       Luís Oliveira maintains an
 158       unofficial <a href="http://darcs.net/">darcs</a> repository of
 159       Hunchentoot at
 160       <a href="http://common-lisp.net/~loliveira/ediware/">http://common-lisp.net/~loliveira/ediware/</a>.
 161     </p>
 162     <p>
 163       Andrey Moskvitin maintains an
 164       unofficial <a href="http://git-scm.com/">git</a> repository of
 165       Hunchentoot at
 166       <a href="http://github.com/archimag/hunchentoot">http://github.com/archimag/hunchentoot</a>.
 167     </p>
 168
 169     <clix:subchapter name="proxy" title="Hunchentoot behind a proxy">
 170
 171       If you're feeling unsecure about exposing Hunchentoot to the wild,
 172       wild Internet or if your Lisp web application is part of a larger
 173       website, you can hide it behind a
 174       <a href="http://en.wikipedia.org/wiki/Proxy_server">proxy server</a>.
 175       One approach that I have used several times is to employ Apache's
 176       <a href="http://httpd.apache.org/docs/2.0/mod/mod_proxy.html">mod_proxy</a>
 177       module with a configuration that looks like this:
 178
 179 <pre><a href="http://httpd.apache.org/docs/2.0/mod/mod_proxy.html#proxypass" class="noborder">ProxyPass</a> /hunchentoot http://127.0.0.1:3000/hunchentoot
 180 <a href="http://httpd.apache.org/docs/2.0/mod/mod_proxy.html#proxypassreverse" class="noborder">ProxyPassReverse</a> /hunchentoot http://127.0.0.1:3000/hunchentoot</pre>
 181
 182       This will tunnel all requests where the URI path begins with
 183       <code>"/hunchentoot"</code> to a (Hunchentoot) server listening on
 184       port 3000 on the same machine.
 185
 186       <p>
 187         Of course, there are
 188         <a href="http://www.red-bean.com/pipermail/lispweb/2006-October/001342.html">several
 189           other</a> (more lightweight) web proxies that you could use
 190         instead of Apache.
 191       </p>
 192     </clix:subchapter>
 193   </clix:chapter>
 194
 195   <clix:chapter name="mail" title="Support and mailing lists">
 196
 197     For questions, bug reports, feature requests, improvements, or
 198     patches please use the
 199     <a href="http://common-lisp.net/mailman/listinfo/tbnl-devel">tbnl-devel
 200       mailing list</a>. If you want to be notified about future
 201       releases subscribe to the
 202     <a href="http://common-lisp.net/mailman/listinfo/tbnl-announce">tbnl-announce
 203       mailing list</a>. These mailing lists were made available thanks
 204     to the services of
 205     <a href="http://common-lisp.net/">common-lisp.net</a>.  You can
 206     <b>search</b> the devel mailing list
 207     <a href="http://google.com/coop/cse?cx=002927904911724867201%3A0l5rif_cxj0">here</a>
 208     (thanks to Tiarnán Ó Corráin).
 209     <p>
 210       If you want to send patches, please
 211       <a href="http://weitz.de/patches.html">read this first</a>.
 212     </p>
 213   </clix:chapter>
 214
 215   <clix:chapter name="start" title="Your own webserver (the easy teen-age New York version)">
 216     Starting your own web server is pretty easy.  Do something like this:
 217 <pre>(hunchentoot:<a class="noborder" href="#start">start</a> (make-instance 'hunchentoot:<a class="noborder" href="#acceptor">easy-acceptor</a> :port 4242))</pre>
 218     That's it.  Now you should be able to enter the address
 219     "<a href='http://127.0.0.1:4242/'><code>http://127.0.0.1:4242/</code></a>" in
 220     your browser and see something, albeit nothing very interesting
 221     for now.
 222
 223     <p>
 224       Now be a bit more adventurous, try this
 225 <pre>(hunchentoot:<a class="noborder" href="#define-easy-handler">define-easy-handler</a> (say-yo :uri "/yo") (name)
 226   (setf (hunchentoot:<a class="noborder" href="#content-type*">content-type*</a>) "text/plain")
 227   (format nil "Hey~@[ ~A~]!" name))</pre>
 228       and see what happens at "<a href='http://127.0.0.1:4242/yo'><code>http://127.0.0.1:4242/yo</code></a>" or
 229       "<a href='http://127.0.0.1:4242/yo?name=Dude'><code>http://127.0.0.1:4242/yo?name=Dude</code></a>" .
 230     </p>
 231
 232     <p>
 233     Hunchentoot comes with a little example website which you can use
 234     to see if it works and which should also demonstrate a couple of
 235     the things you can do with Hunchentoot.  To start the example
 236     website, enter the following code into your listener:
 237
 238 <pre>(<a class="noborder" href="http://common-lisp.net/~mmommer/asdf-howto.shtml#sec11">asdf:oos</a> 'asdf:load-op :hunchentoot-test)</pre>
 239
 240     Now go to "<a href='http://127.0.0.1:4242/hunchentoot/test'><code>http://127.0.0.1:4242/hunchentoot/test</code></a>" and play a bit.
 241     </p>
 242   </clix:chapter>
 243
 244   <clix:chapter name="tutorials" title="Tutorials and add-ons">
 245     <p>
 246       Here are some Hunchentoot tutorials done by others:
 247     </p>
 248     <ul>
 249       <li>
 250         <a href="http://www.adampetersen.se/articles/lispweb.htm">"Lisp for the Web"</a> by Adam Petersen.
 251       </li>
 252       <li>
 253         Two <a href="http://myblog.rsynnott.com/2007/09/getting-started-with-hunchento.html">getting</a>
 254         <a href="http://myblog.rsynnott.com/2007/10/doing-more-with-hunchentoot-cl-server.html">started</a>
 255         articles by Robert Synnott.
 256       </li>
 257       <li>
 258         <a href="http://www.newartisans.com/blog_files/common.lisp.with.apache.php">Running Common Lisp
 259           behind Apache</a> by John Wiegley.  (And there's a
 260         <a href="http://www.newartisans.com/blog_files/hunchentoot.primer.php">second part</a>.)
 261       </li>
 262       <li>
 263         A <a href="http://www.lispcast.com/index.php/2007/10/lispcast-writing-a-simple-reddit-clone-in-common-lisp/">"LispCast"</a>
 264         by Eric Normand about writing a <a href="http://reddit.com/">Reddit</a> clone using
 265         Hunchentoot.  Apparently the first part of a
 266         <a href="http://bc.tech.coop/blog/071028.html">series</a>.
 267       </li>
 268       <li>
 269         A <a href="http://roeim.net/vetle/docs/cl-webapp-intro/">tutorial</a> about
 270         implementing a blog in Common Lisp by Vetle Roeim.
 271       </li>
 272       <li>
 273         A <a href="http://www.jalat.com/blogs/lisp?id=3">tutorial</a> for (an older version of)
 274         Hunchentoot by Asbjørn Bjørnstad.
 275       </li>
 276       <li>
 277         A <a href="http://www.frank-buss.de/lisp/tbnl.html">TBNL tutorial</a> from Frank Buss.
 278         (Hunchentoot is not <a href="http://weitz.de/tbnl/">TBNL</a>, but the two are similar enough
 279         to make the tutorial worthwhile.)
 280       </li>
 281       <li>
 282         For Win32, Bill
 283         Clementson <a href="http://bc.tech.coop/blog/041105.html">explains</a>
 284         how to set up Hunchentoot's
 285         predecessor <a href="http://weitz.de/tbnl/">TBNL</a> with
 286         Apache/mod_lisp.  See
 287         also <a href="http://bc.tech.coop/blog/061013.html">http://bc.tech.coop/blog/061013.html</a>.
 288       </li>
 289     </ul>
 290
 291     Check the dates of these tutorials!  Many of them might not be a
 292     perfect fit with the latest release of Hunchentoot as there have
 293     been several changes to its API recently, especially in 2009.
 294     Also, the fact that these tutorials are listed here doesn't
 295     necessarily mean that I endorse them or think that they show
 296     idiomatic Lisp code.  You'll have to decide yourself if they're
 297     helpful to you or not.
 298
 299     <p>
 300       Here is some software which extends Hunchentoot or is based on it:
 301     </p>
 302     <ul>
 303       <li>Tomo Matsumoto's web application
 304       framework <a href="http://web4r.org/en/">web4r</a>.
 305       </li>
 306       <li>
 307         <a href="http://common-lisp.net/project/cl-weblocks/">Weblocks</a>
 308         by Slava Akhmechet is a "continuations-based web framework" which is
 309         based on Hunchentoot.
 310       </li>
 311       <li>
 312         <a href="http://pen.two-bytes.com/misc/ht-ajax.html">HT-AJAX</a> is
 313         an <a href="http://en.wikipedia.org/wiki/Ajax_%28programming%29">Ajax</a>
 314         framework for Hunchentoot by Ury Marshak.
 315       </li>
 316       <li>
 317         Mac Chan
 318         <a href="http://common-lisp.net/pipermail/tbnl-devel/2007-May/001324.html">has
 319           ported <a href="http://lemonodor.com/">John Wiseman</a>'s
 320           <a href="http://www.lemonodor.com/archives/000128.html">Lisp
 321             Server Pages</a> to Hunchentoot.</a>
 322       </li>
 323       <li>
 324         <a href="http://site.znain.com/dl/lisp/hunchentoot-dir-lister/">hunchentoot-dir-lister</a>
 325         is a directory listing addition for Hunchentoot by Dimitre Liotev.
 326       </li>
 327       <li>
 328         Cyrus Harmon's
 329         <a href="http://cyrusharmon.org/blog/display?id=64">nuclblog</a> is a
 330         <a href="http://en.wikipedia.org/wiki/Blog">blog</a> engine which uses Hunchentoot.
 331       </li>
 332       <li>
 333         <a href="http://cyrusharmon.org/projects?project=hunchentoot-cgi">hunchentoot-cgi</a>
 334         (also by Cyrus Harmon) provides
 335         <a href="http://en.wikipedia.org/wiki/Common_Gateway_Interface">CGI</a>
 336         handlers for Hunchentoot.
 337       </li>
 338       <li>
 339         <a href="http://weitz.de/cl-webdav/">CL-WEBDAV</a> is a <a href="http://webdav.org/">WebDAV</a>
 340         server based on Hunchentoot.
 341       </li>
 342       <li>
 343         <a href="http://restas.lisper.ru/">RESTAS</a> is a web
 344         framework based on Hunchentoot.
 345       </li>
 346     </ul>
 347   </clix:chapter>
 348
 349   <clix:chapter name="reference" title="Function and variable reference">
 350
 351     <clix:subchapter name="acceptors" title="Acceptors">
 352
 353       If you want Hunchentoot to actually do something, you have to create and
 354       <a href="#start">start</a> an <a href="#acceptor">acceptor</a>.
 355       You can also run several acceptors in one image, each one
 356       listening on a different different port.
 357
 358       <clix:class name='acceptor'>
 359         <clix:description>
 360           To create a Hunchentoot webserver, you make an instance of
 361           this class and use the generic function
 362           <clix:ref>START</clix:ref> to start it (and
 363           <clix:ref>STOP</clix:ref> to stop it).  Use the
 364           <code>:port</code> initarg if you don&#039;t want to listen
 365           on the default http port 80.  There are other initargs most
 366           of which you probably won&#039;t need very often.  They are
 367           explained in detail in the docstrings of the slot
 368           definitions for this class.
 369           <p>
 370             Unless you are in a Lisp without MP capabilities, you can
 371             have several active instances of
 372             <clix:ref>ACCEPTOR</clix:ref> (listening on different
 373             ports) at the same time.
 374           </p>
 375         </clix:description>
 376       </clix:class>
 377
 378       <clix:class name='ssl-acceptor'>
 379         <clix:description>Create and <clix:ref>START</clix:ref> an instance of this class
 380         (instead of <clix:ref>ACCEPTOR</clix:ref>) if you want an https server.  There are two
 381         required initargs, <code>:SSL-CERTIFICATE-FILE</code> and <code>:SSL-PRIVATEKEY-FILE</code>, for
 382         pathname designators denoting the certificate file and the key file in
 383         PEM format.  On LispWorks, you can have both in one file in which case
 384         the second initarg is optional.  You can also use the
 385         <code>:SSL-PRIVATEKEY-PASSWORD</code> initarg to provide a password
 386         (as a string) for the key file (or <code>NIL</code>, the default, for
 387         no password).
 388         <p>
 389           The default port for <clix:ref>SSL-ACCEPTOR</clix:ref> instances is 443 instead of 80
 390         </p>
 391         </clix:description>
 392       </clix:class>
 393
 394       <clix:function generic='true' name='start'>
 395         <clix:lambda-list>acceptor
 396         </clix:lambda-list>
 397         <clix:returns>acceptor
 398         </clix:returns>
 399         <clix:description>Starts <clix:arg>acceptor</clix:arg> so that it begins accepting
 400         connections.  Returns the acceptor.
 401         </clix:description>
 402       </clix:function>
 403
 404       <clix:function generic='true' name='stop'>
 405         <clix:lambda-list>acceptor
 406         </clix:lambda-list>
 407         <clix:returns>acceptor
 408         </clix:returns>
 409         <clix:description>Stops <clix:arg>acceptor</clix:arg> so that it
 410         no longer accepts requests.
 411         </clix:description>
 412       </clix:function>
 413
 414       <clix:special-variable name='*acceptor*'>
 415         <clix:description>The current ACCEPTOR object in the context of a request.
 416         </clix:description>
 417       </clix:special-variable>
 418
 419       <clix:readers generic='true'>
 420         <clix:listed-reader generic='true' name='acceptor-address'>
 421           <clix:lambda-list>acceptor
 422           </clix:lambda-list>
 423           <clix:returns>address
 424           </clix:returns>
 425         </clix:listed-reader>
 426
 427         <clix:listed-reader generic='true' name='acceptor-port'>
 428           <clix:lambda-list>acceptor
 429           </clix:lambda-list>
 430           <clix:returns>port
 431           </clix:returns>
 432         </clix:listed-reader>
 433
 434         <clix:listed-reader generic='true' name='acceptor-read-timeout'>
 435           <clix:lambda-list>acceptor
 436           </clix:lambda-list>
 437           <clix:returns>read-timeout
 438           </clix:returns>
 439         </clix:listed-reader>
 440
 441         <clix:listed-reader generic='true' name='acceptor-ssl-certificate-file'>
 442           <clix:lambda-list>ssl-acceptor
 443           </clix:lambda-list>
 444           <clix:returns>ssl-certificate-file
 445           </clix:returns>
 446         </clix:listed-reader>
 447
 448         <clix:listed-reader generic='true' name='acceptor-ssl-privatekey-file'>
 449           <clix:lambda-list>ssl-acceptor
 450           </clix:lambda-list>
 451           <clix:returns>ssl-privatekey-file
 452           </clix:returns>
 453         </clix:listed-reader>
 454
 455         <clix:listed-reader generic='true' name='acceptor-ssl-privatekey-password'>
 456           <clix:lambda-list>ssl-acceptor
 457           </clix:lambda-list>
 458           <clix:returns>ssl-privatekey-password
 459           </clix:returns>
 460         </clix:listed-reader>
 461
 462         <clix:listed-reader generic='true' name='acceptor-ssl-certificate-file'>
 463           <clix:lambda-list>listen-backlog
 464           </clix:lambda-list>
 465           <clix:returns>number-of-pending-connections
 466           </clix:returns>
 467         </clix:listed-reader>
 468
 469         <clix:description>
 470           Number of pending connections allowed in the listen socket
 471           before the kernel rejects further incoming connections.
 472           Non-LispWorks only.
 473         </clix:description>
 474
 475         <clix:listed-reader generic='true' name='acceptor-write-timeout'>
 476           <clix:lambda-list>acceptor
 477           </clix:lambda-list>
 478           <clix:returns>write-timeout
 479           </clix:returns>
 480         </clix:listed-reader>
 481
 482         <clix:description>
 483           These are readers for various slots of <clix:ref>ACCEPTOR</clix:ref>
 484           objects (and some of them obviously only make sense
 485           for <clix:ref>SSL-ACCEPTOR</clix:ref> objects).  See the docstrings of
 486           these slots for more information and note that there are corresponding
 487           initargs for all of them.
 488         </clix:description>
 489       </clix:readers>
 490
 491       <clix:accessors generic='true'>
 492         <clix:listed-accessor generic='true' name='acceptor-access-log-destination'>
 493           <clix:lambda-list>acceptor
 494           </clix:lambda-list>
 495           <clix:returns>(or pathname null)
 496           </clix:returns>
 497         </clix:listed-accessor>
 498
 499         <clix:listed-accessor generic='true' name='acceptor-error-template-directory'>
 500           <clix:lambda-list>acceptor
 501           </clix:lambda-list>
 502           <clix:returns>(or pathname null)
 503           </clix:returns>
 504         </clix:listed-accessor>
 505
 506         <clix:listed-accessor generic='true' name='acceptor-input-chunking-p'>
 507           <clix:lambda-list>acceptor
 508           </clix:lambda-list>
 509           <clix:returns>input-chunking-p
 510           </clix:returns>
 511         </clix:listed-accessor>
 512
 513         <clix:listed-accessor generic='true' name='acceptor-message-log-destination'>
 514           <clix:lambda-list>acceptor
 515           </clix:lambda-list>
 516           <clix:returns>(or pathname null)
 517           </clix:returns>
 518         </clix:listed-accessor>
 519
 520         <clix:listed-accessor generic='true' name='acceptor-name'>
 521           <clix:lambda-list>acceptor
 522           </clix:lambda-list>
 523           <clix:returns>name
 524           </clix:returns>
 525         </clix:listed-accessor>
 526
 527         <clix:listed-accessor generic='true' name='acceptor-output-chunking-p'>
 528           <clix:lambda-list>acceptor
 529           </clix:lambda-list>
 530           <clix:returns>output-chunking-p
 531           </clix:returns>
 532         </clix:listed-accessor>
 533
 534         <clix:listed-accessor generic='true' name='acceptor-persistent-connections-p'>
 535           <clix:lambda-list>acceptor
 536           </clix:lambda-list>
 537           <clix:returns>persistent-connections-p
 538           </clix:returns>
 539         </clix:listed-accessor>
 540
 541         <clix:listed-accessor generic='true' name='acceptor-reply-class'>
 542           <clix:lambda-list>acceptor
 543           </clix:lambda-list>
 544           <clix:returns>reply-class
 545           </clix:returns>
 546         </clix:listed-accessor>
 547
 548         <clix:listed-accessor generic='true' name='acceptor-request-class'>
 549           <clix:lambda-list>acceptor
 550           </clix:lambda-list>
 551           <clix:returns>request-class
 552           </clix:returns>
 553         </clix:listed-accessor>
 554
 555         <clix:listed-accessor generic='true' name='acceptor-request-dispatcher'>
 556           <clix:lambda-list>acceptor
 557           </clix:lambda-list>
 558           <clix:returns>request-dispatcher
 559           </clix:returns>
 560         </clix:listed-accessor>
 561
 562         <clix:description>
 563           These are accessors for various slots of <clix:ref>ACCEPTOR</clix:ref>
 564           objects.  See the docstrings of these slots for more information and
 565           note that there are corresponding initargs for all of them.
 566         </clix:description>
 567       </clix:accessors>
 568
 569       <clix:function generic='true' name='acceptor-ssl-p'>
 570         <clix:lambda-list>acceptor
 571         </clix:lambda-list>
 572         <clix:returns>generalized-boolean
 573         </clix:returns>
 574         <clix:description>Returns a true value if <clix:arg>acceptor</clix:arg> uses SSL
 575         connections.  The default is to unconditionally return <code>NIL</code> and
 576         subclasses of <clix:ref>ACCEPTOR</clix:ref> must specialize this method to signal that
 577         they&#039;re using secure connections - see the <clix:ref>SSL-ACCEPTOR</clix:ref> class.
 578         </clix:description>
 579       </clix:function>
 580
 581       <clix:special-variable name='*default-connection-timeout*'>
 582         <clix:description>The default connection timeout used when an
 583         acceptor is reading from and writing to a socket stream.  Note that
 584         some Lisps allow you to set different timeouts for reading and writing
 585         and you can specify both values via initargs when you create
 586         an <a href="#acceptors">acceptor</a>.
 587         </clix:description>
 588       </clix:special-variable>
 589
 590     </clix:subchapter>
 591
 592     <clix:subchapter name="acceptor-behaviour" title="Customizing acceptor behaviour">
 593
 594       If you want to modify what acceptors do, you should subclass
 595       <clix:ref>ACCEPTOR</clix:ref> (or
 596       <clix:ref>SSL-ACCEPTOR</clix:ref>) and specialize the generic
 597       functions that constitute their behaviour.  The life of an
 598       acceptor looks like this: It is started with the function
 599       <clix:ref>START</clix:ref> which immediately calls
 600       <clix:ref>START-LISTENING</clix:ref> and then applies the
 601       function <clix:ref>EXECUTE-ACCEPTOR</clix:ref> to its <a
 602       href="#taskmasters">taskmaster</a>.  This function will
 603       eventually call <clix:ref>ACCEPT-CONNECTIONS</clix:ref> which is
 604       responsible for settings things up to wait for clients to
 605       connect.  For each connection which comes in,
 606       <clix:ref>HANDLE-INCOMING-CONNECTION</clix:ref> is applied to
 607       the taskmaster which will either call
 608       <clix:ref>PROCESS-CONNECTION</clix:ref> directly,
 609       or will create a thread to call it.
 610       <clix:ref>PROCESS-CONNECTION</clix:ref> calls
 611       <clix:ref>INITIALIZE-CONNECTION-STREAM</clix:ref> before it does
 612       anything else, then it selects and calls a function which
 613       handles the <a href="#requests">request</a>, and finally it
 614       sends the <a href="#replies">reply</a> to the client before it
 615       calls <clix:ref>RESET-CONNECTION-STREAM</clix:ref>.  If the
 616       connection is persistent, this procedure is repeated (except for
 617       the intialization step) in a loop until the connection is
 618       closed.  The acceptor is stopped with <clix:ref>STOP</clix:ref>.
 619
 620       <p>
 621         If you just want to use the standard acceptors that come with
 622         Hunchentoot, you don't need to know anything about the functions
 623         listed in this section.
 624       </p>
 625
 626       <clix:function generic='true' name='start-listening'>
 627         <clix:lambda-list>acceptor
 628         </clix:lambda-list>
 629         <clix:returns>|
 630         </clix:returns>
 631         <clix:description>Sets up a listen socket for the given acceptor and
 632         enables it to listen to incoming connections.  This function is called
 633         from the thread that starts the acceptor initially and may return
 634         errors resulting from the listening operation (like &#039;address in use&#039;
 635         or similar).
 636         </clix:description>
 637       </clix:function>
 638
 639       <clix:function generic='true' name='accept-connections'>
 640         <clix:lambda-list>acceptor
 641         </clix:lambda-list>
 642         <clix:returns>nil
 643         </clix:returns>
 644         <clix:description>In a loop, accepts a connection and hands it over
 645         to the acceptor's taskmaster for processing using
 646         <clix:ref>HANDLE-INCOMING-CONNECTION</clix:ref>. On LispWorks, this
 647         function returns immediately, on other Lisps it returns only once the
 648         acceptor has been stopped.
 649         </clix:description>
 650       </clix:function>
 651
 652       <clix:function generic='true' name='process-connection'>
 653         <clix:lambda-list>acceptor socket
 654         </clix:lambda-list>
 655         <clix:returns>nil
 656         </clix:returns>
 657         <clix:description>
 658           This function is called by the taskmaster when a new client
 659           connection has been established.  Its arguments are the
 660           <clix:ref>ACCEPTOR</clix:ref> object and a LispWorks socket
 661           handle or a usocket socket stream object in
 662           <clix:arg>socket</clix:arg>.  It reads the request headers,
 663           sets up the <a href="#requests">request</a> and <a
 664           href="#replies">reply</a> objects, and hands over to
 665           <clix:ref>PROCESS-REQUEST</clix:ref> which calls
 666           <clix:ref>HANDLE-REQUEST</clix:ref> to select and call a
 667           handler for the request and sends its reply to the client.
 668           This is done in a loop until the stream has to be closed or
 669           until a connection timeout occurs.  It is probably not a
 670           good idea to re-implement this method until you really,
 671           really know what you're doing.
 672         </clix:description>
 673       </clix:function>
 674
 675       <clix:function generic='true' name='initialize-connection-stream'>
 676         <clix:lambda-list>acceptor stream
 677         </clix:lambda-list>
 678         <clix:returns>stream
 679         </clix:returns>
 680         <clix:description>
 681           Can be used to modify the stream which is used to
 682           communicate between client and server before the request is
 683           read.  The default method of <clix:ref>ACCEPTOR</clix:ref>
 684           does nothing, but see for example the method defined for
 685           <clix:ref>SSL-ACCEPTOR</clix:ref>.  All methods of this
 686           generic function <em>must</em> return the stream to use.
 687         </clix:description>
 688       </clix:function>
 689
 690       <clix:function generic='true' name='reset-connection-stream'>
 691         <clix:lambda-list>acceptor stream
 692         </clix:lambda-list>
 693         <clix:returns>stream
 694         </clix:returns>
 695         <clix:description>
 696           Resets the stream which is used to communicate
 697           between client and server after one request has been served so that it
 698           can be used to process the next request.  This generic function is
 699           called after a request has been processed and <em>must</em> return the
 700           stream.
 701         </clix:description>
 702       </clix:function>
 703
 704       <clix:function name="acceptor-log-access" generic="true">
 705         <clix:lambda-list>acceptor &amp;key return-code content content-length</clix:lambda-list>
 706         <clix:description>
 707           Function to call to log access to the acceptor.  The <clix:arg>return-code</clix:arg>,
 708           <clix:arg>content</clix:arg> and <clix:arg>content-length</clix:arg> keyword arguments contain additional
 709           information about the request to log.  In addition, it can use the
 710           standard request accessor functions that are available to handler
 711           functions to find out more information about the request.
 712         </clix:description>
 713       </clix:function>
 714
 715       <clix:function name="acceptor-log-message" generic="true">
 716         <clix:lambda-list>acceptor log-level format-string &amp;rest format-arguments</clix:lambda-list>
 717         <clix:description>
 718           Function to call to log messages by the <clix:arg>acceptor</clix:arg>.  It must accept
 719           a severity level for the message, which will be one of :ERROR, :INFO,
 720           or :WARNING, a format string and an arbitary number of formatting
 721           arguments.
 722         </clix:description>
 723       </clix:function>
 724
 725       <clix:function name="acceptor-status-message" generic="true">
 726         <clix:lambda-list>acceptor http-return-code content</clix:lambda-list>
 727         <clix:description>
 728           This function is called after the request's handler has been
 729           invoked to convert the <clix:arg>HTTP-STATUS-CODE</clix:arg>
 730           to a HTML message to be displayed to the user.  If this
 731           function returns a string, that string is sent to the client
 732           instead of the content produced by the handler, if any.
 733
 734           If an ERROR-TEMPLATE-DIRECTORY is set in the current
 735           acceptor and the directory contains a file corresponding to
 736           HTTP-STATUS-CODE named &lt;code&gt;.html, that file is sent
 737           to the client after variable substitution.  Variables are
 738           referenced by ${&lt;variable-name&gt;}.
 739
 740           Additional keyword arguments may be provided which are made
 741           available to the templating logic as substitution variables.
 742           These variables can be interpolated into error message
 743           templates in, which contains the current URL relative to the
 744           server and without GET parameters.
 745
 746           In addition to the variables corresponding to keyword
 747           arguments, the script-name, lisp-implementation-type,
 748           lisp-implementation-version and hunchentoot-version
 749           variables are available.
 750         </clix:description>
 751       </clix:function>
 752
 753     </clix:subchapter>
 754
 755     <clix:subchapter name="taskmasters" title="Taskmasters">
 756       As a "normal" Hunchentoot user, you can completely ignore
 757       taskmasters and skip this section.  But if you're still reading,
 758       here are the dirty details: Each <a
 759       href="#acceptors">acceptor</a> has a taskmaster associated with
 760       it at creation time.  It is the taskmaster's job to distribute
 761       the work of accepting and handling incoming connections.  The
 762       acceptor calls the taskmaster if appropriate and the taskmaster
 763       calls back into the acceptor.  This is done using the generic
 764       functions described in this and the <a
 765       href="#acceptor-behaviour">previous</a> section.  Hunchentoot
 766       comes with two standard taskmaster implementations - one (which
 767       is the default used on multi-threaded Lisps) which starts a new
 768       thread for each incoming connection and one which handles all
 769       requests sequentially.  It should for example be relatively
 770       straightforward to create a taskmaster which allocates threads
 771       from a fixed pool instead of creating a new one for each
 772       connection.
 773
 774       <p>
 775         You can control the resources consumed by a threaded taskmaster via
 776         two initargs. <code>:max-thread-count</code> lets you set the maximum
 777         number of request threads that can be processes simultaneously.  If
 778         this is <code>nil</code>, the is no thread limit imposed.
 779
 780         <code>:max-accept-count</code> lets you set the maximum number of requests
 781         that can be outstanding (i.e. being processed or queued for processing).
 782
 783         If <code>:max-thread-count</code> is supplied and <code>:max-accept-count</code>
 784         is <code>NIL</code>, then a <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref>
 785         error will be generated if there are more than the max-thread-count
 786         threads processing requests.  If both <code>:max-thread-count</code>
 787         and <code>:max-accept-count</code> are supplied, then max-thread-count
 788         must be less than max-accept-count; if more than max-thread-count
 789         requests are being processed, then requests up to max-accept-count
 790         will be queued until a thread becomes available.  If more than
 791         max-accept-count requests are outstanding, then a <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref>
 792         error will be generated.
 793
 794         In a load-balanced environment with multiple Hunchentoot servers, it's
 795         reasonable to provide <code>:max-thread-count</code> but leave
 796         <code>:max-accept-count</code> null.   This will immediately result
 797         in <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref> when one server is
 798         out of resources, so the load balancer can try to find another server.
 799
 800         In an environment with a single Hunchentoot server, it's reasonable
 801         to provide both <code>:max-thread-count</code> and a somewhat larger value
 802         for <code>:max-accept-count</code>.  This will cause a server that's almost
 803         out of resources to wait a bit; if the server is completely out of resources,
 804         then the reply will be <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref>.
 805         The default for these values is 100 and 120, respectively.
 806       </p>
 807
 808       <p>
 809         If you want to implement your own taskmasters, you should subclass
 810         <clix:ref>TASKMASTER</clix:ref> or one of its subclasses,
 811         <clix:ref>SINGLE-THREADED-TASKMASTER</clix:ref> or
 812         <clix:ref>ONE-THREAD-PER-CONNECTION-TASKMASTER</clix:ref>, and
 813         specialize the generic functions in this section.
 814       </p>
 815
 816       <clix:class name='taskmaster'>
 817         <clix:description>
 818           An instance of this class is responsible for distributing
 819           the work of handling requests for its acceptor.  This is an
 820           "abstract" class in the sense that usually only instances of
 821           subclasses of <clix:ref>TASKMASTER</clix:ref> will be used.
 822         </clix:description>
 823       </clix:class>
 824
 825       <clix:class name='one-thread-per-connection-taskmaster'>
 826         <clix:description>
 827           A taskmaster that starts one thread for listening to
 828           incoming requests and one thread for each incoming
 829           connection.
 830           <p>
 831             This is the default taskmaster implementation for multi-threaded Lisp
 832             implementations.
 833           </p>
 834         </clix:description>
 835       </clix:class>
 836
 837       <clix:class name='single-threaded-taskmaster'>
 838         <clix:description>
 839           A taskmaster that runs synchronously in the
 840           thread where the <clix:ref>START</clix:ref> function was invoked (or
 841           in the case of LispWorks in the thread started
 842           by <a href="http://www.lispworks.com/documentation/lw51/LWRM/html/lwref-61.htm#marker-910861"><code>COMM:START-UP-SERVER</code></a>).
 843           This is the simplest possible taskmaster implementation in that its
 844           methods do nothing but calling their acceptor &quot;sister&quot;
 845           methods - <clix:ref>EXECUTE-ACCEPTOR</clix:ref> calls <clix:ref>ACCEPT-CONNECTIONS</clix:ref>,
 846           <clix:ref>HANDLE-INCOMING-CONNECTION</clix:ref> calls <clix:ref>PROCESS-CONNECTION</clix:ref>.
 847         </clix:description>
 848       </clix:class>
 849
 850       <clix:function generic='true' name='execute-acceptor'>
 851         <clix:lambda-list>taskmaster
 852         </clix:lambda-list>
 853         <clix:returns>result
 854         </clix:returns>
 855         <clix:description>This is a callback called by the acceptor once it
 856         has performed all initial processing to start listening for incoming
 857         connections (see <clix:ref>START-LISTENING</clix:ref>).  It usually calls the
 858         <clix:ref>ACCEPT-CONNECTIONS</clix:ref> method of the acceptor, but depending on the
 859         taskmaster instance the method might be called from a new thread.
 860         </clix:description>
 861       </clix:function>
 862
 863       <clix:function generic='true' name='handle-incoming-connection'>
 864         <clix:lambda-list>taskmaster socket
 865         </clix:lambda-list>
 866         <clix:returns>result
 867         </clix:returns>
 868         <clix:description>
 869           This function is called by the acceptor to start
 870           processing of requests on a new incoming connection.  <clix:arg>socket</clix:arg> is the
 871           usocket instance that represents the new connection (or a socket
 872           handle on LispWorks).  The taskmaster starts processing requests on
 873           the incoming connection by calling the <clix:ref>PROCESS-CONNECTION</clix:ref>
 874           method of the acceptor instance.  The <clix:arg>socket</clix:arg> argument is passed to
 875           <clix:ref>PROCESS-CONNECTION</clix:ref> as an argument.
 876
 877           If the taskmaster is a multi-threaded taskmaster, <clix:ref>HANDLE-INCOMING-THREAD</clix:ref>
 878           will call <clix:ref>CREATE-TASKMASTER-THREAD</clix:ref>, which will call
 879           <clix:ref>PROCESS-CONNECTION</clix:ref> in a new thread.
 880           <clix:ref>HANDLE-INCOMING-THREAD</clix:ref> might issue a
 881           <clix:ref>+HTTP-SERVICE-UNAVAILABLE+</clix:ref> error
 882           if there are too many request threads or it might block waiting for a
 883           request thread to finish.
 884               </clix:description>
 885             </clix:function>
 886
 887             <clix:function generic='true' name='create-taskmaster-thread'>
 888             <clix:lambda-list>taskmaster socket
 889             </clix:lambda-list>
 890             <clix:returns>thread
 891             </clix:returns>
 892               <clix:description>This function is called by <clix:ref>HANDLE-INCOMING-THREAD</clix:ref>
 893           to create a new thread which calls <clix:ref>PROCESS-CONNECTION</clix:ref>.
 894           If you specialize this function, you must be careful to have the thread
 895           call <clix:ref>DECREMENT-TASKMASTER-REQUEST-COUNT</clix:ref> before
 896           it exits.  A typical method will look like this:
 897
 898                 <pre>(defmethod create-taskmaster-thread ((taskmaster monitor-taskmaster) socket)
 899             (bt:make-thread
 900              (lambda ()
 901                (with-monitor-error-handlers
 902                  (unwind-protect
 903                       (with-monitor-variable-bindings
 904                         (process-connection (taskmaster-acceptor taskmaster) socket))
 905                    (decrement-taskmaster-request-count taskmaster))))))</pre>
 906
 907
 908
 909
 910
 911
 912
 913         </clix:description>
 914       </clix:function>
 915
 916       <clix:function generic='true' name='shutdown'>
 917         <clix:lambda-list>taskmaster
 918         </clix:lambda-list>
 919         <clix:returns>taskmaster
 920         </clix:returns>
 921         <clix:description>Shuts down the taskmaster, i.e. frees all resources
 922         that were set up by it.  For example, a multi-threaded taskmaster
 923         might terminate all threads that are currently associated with it.
 924         This function is called by the acceptor's <clix:ref>STOP</clix:ref> method.
 925         </clix:description>
 926       </clix:function>
 927
 928       <clix:accessor generic='true' name='taskmaster-acceptor'>
 929         <clix:lambda-list>taskmaster
 930         </clix:lambda-list>
 931         <clix:returns>acceptor
 932         </clix:returns>
 933         <clix:description>
 934           This is an accessor for the slot of a <clix:ref>TASKMASTER</clix:ref>
 935           object that links back to the <a href="#acceptors">acceptor</a> it is
 936           associated with.
 937         </clix:description>
 938       </clix:accessor>
 939
 940     </clix:subchapter>
 941
 942     <clix:subchapter name="request-dispatch" title="Request dispatch and handling">
 943
 944       The main job of <clix:ref>HANDLE-REQUEST</clix:ref> is to select
 945       and call a function which handles the request, i.e. which looks
 946       at the data the client has sent and prepares an appropriate
 947       reply to send back.  This is by default implemented as follows:
 948       <p>
 949         Each acceptor has a <a href="#acceptor-request-dispatcher"><em>request
 950         dispatcher</em></a> which is a unary function that accepts
 951         a <clix:ref>REQUEST</clix:ref> object.  This function is called by the
 952         default method of <clix:ref>HANDLE-REQUEST</clix:ref>.  The idea is
 953         that this function looks at the request object and depending on its
 954         contents decides to call another function which "does the work".  This
 955         "other" function is by convention called a <a class="none"
 956         name="handlers"><em>request handler</em></a>.  (Obviously, this is
 957         really only a convention as <clix:ref>HANDLE-REQUEST</clix:ref>
 958         doesn't "know" what the request dispatcher does.  You could as well
 959         say that the request dispatcher and the request handler have the same
 960         job.)
 961       </p>
 962       <p>
 963         The default behaviour, unless your acceptor has its own request
 964         dispatcher, is that Hunchentoot walks through the list
 965         <clix:ref>*DISPATCH-TABLE*</clix:ref> which consists of <em>dispatch
 966         functions</em>.  Each of these functions accepts the request object as
 967         its only argument and either returns a request handler to handle the
 968         request or <code>NIL</code> which means that the next dispatcher in
 969         the list will be tried.  If all dispatch functions
 970         return <code>NIL</code>, the return code
 971         <clix:ref>+HTTP-NOT-FOUND+</clix:ref> will be sent to the client.
 972       </p>
 973       <p>
 974         The default method of <clix:ref>HANDLE-REQUEST</clix:ref> also sets up
 975         <a href="#logging">standard error handling</a> before it calls the acceptor's request
 976         dispatcher.
 977       </p>
 978       <p>
 979         All functions and variables in this section are related to the
 980         standard request dispatch mechanism described above and are
 981         meaningless if you're using your own request dispatcher.
 982       </p>
 983       <p>
 984         Request handlers do their work by modifying
 985         the <a href="#replies">reply object</a> if necessary and by eventually
 986         returning the response body in the form of a string or a binary
 987         sequence.  As an alternative, they can also
 988         call <clix:ref>SEND-HEADERS</clix:ref> and write directly to a stream.
 989       </p>
 990
 991       <clix:special-variable name='*dispatch-table*'>
 992         <clix:description>
 993           A global list of dispatch functions.  The initial value is a
 994           list consisting of the two symbols
 995           <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref> and
 996           <clix:ref>DEFAULT-DISPATCHER</clix:ref>.
 997         </clix:description>
 998       </clix:special-variable>
 999
1000       <clix:function name='default-dispatcher'>
1001         <clix:lambda-list>request
1002         </clix:lambda-list>
1003         <clix:returns>result
1004         </clix:returns>
1005         <clix:description>
1006           Default dispatch function which handles every request with
1007           the function stored in
1008           <clix:ref>*DEFAULT-HANDLER*</clix:ref>.
1009         </clix:description>
1010       </clix:function>
1011
1012       <clix:special-variable name='*default-handler*'>
1013         <clix:description>The name of the function which is always returned by
1014         <clix:ref>DEFAULT-DISPATCHER</clix:ref>.
1015         </clix:description>
1016       </clix:special-variable>
1017
1018       <clix:function name="create-prefix-dispatcher">
1019         <clix:lambda-list>prefix handler</clix:lambda-list>
1020         <clix:returns>dispatch-fn</clix:returns>
1021         <clix:description>
1022           A convenience function which will return a dispatcher that
1023           returns <clix:arg>handler</clix:arg> whenever the path part of
1024           the request URI starts with the
1025           string <clix:arg>prefix</clix:arg>.
1026         </clix:description>
1027       </clix:function>
1028
1029       <clix:function name="create-regex-dispatcher">
1030         <clix:lambda-list>regex handler</clix:lambda-list>
1031         <clix:returns>dispatch-fn</clix:returns>
1032         <clix:description>
1033           A convenience function which will return a dispatcher that
1034           returns <clix:arg>handler</clix:arg> whenever the path part of
1035           the request URI matches
1036           the <a href="http://weitz.de/cl-ppcre/">CL-PPCRE</a> regular
1037           expression <clix:arg>regex</clix:arg> (which can be a string, an
1038           s-expression, or a scanner).
1039         </clix:description>
1040       </clix:function>
1041
1042       <clix:function name="create-folder-dispatcher-and-handler">
1043         <clix:lambda-list>uri-prefix base-path <clix:lkw>optional</clix:lkw> content-type</clix:lambda-list>
1044         <clix:returns>dispatch-fn</clix:returns>
1045         <clix:description>
1046           Creates and returns a dispatch function which will dispatch to
1047           a handler function which emits the file relative
1048           to <clix:arg>base-path</clix:arg> that is denoted by the URI of
1049           the request relative
1050           to <clix:arg>uri-prefix</clix:arg>.  <clix:arg>uri-prefix</clix:arg>
1051           must be a string ending with a
1052           slash, <clix:arg>base-path</clix:arg> must be a pathname
1053           designator for an existing directory.
1054           Uses <clix:ref>HANDLE-STATIC-FILE</clix:ref> internally.
1055           <p>
1056             If <clix:arg>content-type</clix:arg> is <em>not</em>
1057             <code>NIL</code>, it will be used as a the content type for
1058             all files in the folder.  Otherwise (which is the default)
1059             the content type of each file will be
1060             determined <a href="#handle-static-file">as usual</a>.
1061           </p>
1062         </clix:description>
1063       </clix:function>
1064
1065       <clix:function name='create-static-file-dispatcher-and-handler'>
1066         <clix:lambda-list>uri path
1067         <clix:lkw>optional
1068         </clix:lkw> content-type
1069         </clix:lambda-list>
1070         <clix:returns>result
1071         </clix:returns>
1072         <clix:description>
1073           Creates and returns a request dispatch function which will
1074           dispatch to a handler function which emits the file denoted
1075           by the pathname designator PATH with content type
1076           CONTENT-TYPE if the SCRIPT-NAME of the request matches the
1077           string URI.  If CONTENT-TYPE is NIL, tries to determine the
1078           content type via the file&#039;s suffix.
1079         </clix:description>
1080       </clix:function>
1081
1082       <clix:function macro="true" name="define-easy-handler">
1083         <clix:lambda-list>description lambda-list [[declaration* | documentation]] form*</clix:lambda-list>
1084         <clix:description>
1085           Defines a handler as if
1086           by <a href="http://www.lispworks.com/documentation/HyperSpec/Body/m_defun.htm">
1087             <code>DEFUN</code></a> and optionally registers it with a
1088           URI so that it will be found
1089           by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref>.
1090           <p>
1091             <clix:arg>description</clix:arg> is either a
1092             symbol <clix:arg>name</clix:arg> or a list matching the
1093             <a href="http://www.lispworks.com/documentation/HyperSpec/Body/03_de.htm">destructuring
1094               lambda list</a>
1095           </p>
1096           <pre>(name &amp;key uri acceptor-names default-parameter-type default-request-type).</pre>
1097           <clix:arg>lambda-list</clix:arg> is a list the elements of which
1098           are either a symbol <clix:arg>var</clix:arg> or a list matching
1099           the destructuring lambda list
1100           <pre>(var &amp;key real-name parameter-type init-form request-type).</pre>
1101           The resulting handler will be a Lisp function with the
1102           name <clix:arg>name</clix:arg> and keyword parameters named by
1103           the <clix:arg>var</clix:arg> symbols.
1104           Each <clix:arg>var</clix:arg> will be bound to the value of the
1105           GET or POST parameter called <clix:arg>real-name</clix:arg> (a
1106           string) before the body of the function is executed.
1107           If <clix:arg>real-name</clix:arg> is not provided, it will be
1108           computed
1109           by <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_stg_up.htm#string-downcase">downcasing</a>
1110           the symbol name of <clix:arg>var</clix:arg>.
1111           <p>
1112             If <clix:arg>uri</clix:arg> (which is evaluated) is provided,
1113             then it must be a string or
1114             a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_f.htm#function_designator">function
1115               designator</a> for a unary function.  In this case, the
1116             handler will be returned
1117             by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref>,
1118             if <clix:arg>uri</clix:arg> is a string and
1119             the <a href="#script-name">script name</a> of the current
1120             request is <clix:arg>uri</clix:arg>, or
1121             if <clix:arg>uri</clix:arg> designates a function and applying
1122             this function to
1123             the <a href="#*request*">current <code>REQUEST</code>
1124               object</a> returns a true value.
1125           </p>
1126           <p>
1127             <clix:arg>acceptor-names</clix:arg> (which is evaluated) can be a
1128             list of symbols which means that the handler will only be
1129             returned by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref> in
1130             acceptors which have one of these names
1131             (see <clix:ref>ACCEPTOR-NAME</clix:ref>).  <clix:arg>acceptor-names</clix:arg> can also be the
1132             symbol <code>T</code> which means that the handler will be
1133             returned by <clix:ref>DISPATCH-EASY-HANDLERS</clix:ref>
1134             in <em>every</em> acceptor.
1135           </p>
1136           <p>
1137             Whether the GET or POST parameter (or both) will be taken into
1138             consideration, depends on <clix:arg>request-type</clix:arg>
1139             which can
1140             be <code>:GET</code>, <code>:POST</code>, <code>:BOTH</code>,
1141             or <code>NIL</code>.  In the last case, the value of
1142             <clix:arg>default-request-type</clix:arg> (the default of which
1143             is <code>:BOTH</code>) will be used.
1144           </p>
1145           <p>
1146             The value of <clix:arg>var</clix:arg> will usually be a string
1147             (unless it resulted from a <a href="#upload">file upload</a>
1148             in which case it won't be converted at all), but
1149             if <clix:arg>parameter-type</clix:arg> (which is evaluated) is
1150             provided, the string will be converted to another Lisp type by
1151             the following rules:
1152           </p>
1153           <p>
1154             If the corresponding GET or POST parameter wasn't provided by
1155             the client, <clix:arg>var</clix:arg>'s value will
1156             be <code>NIL</code>.  If <clix:arg>parameter-type</clix:arg>
1157             is <code>'STRING</code>,
1158             <clix:arg>var</clix:arg>'s value remains as is.
1159             If <clix:arg>parameter-type</clix:arg> is <code>'INTEGER</code>
1160             and the parameter string consists solely of decimal
1161             digits, <clix:arg>var</clix:arg>'s value will be the
1162             corresponding integer, otherwise <code>NIL</code>.
1163             If <clix:arg>parameter-type</clix:arg> is
1164             <code>'KEYWORD</code>, <clix:arg>var</clix:arg>'s value will be
1165             the keyword obtained
1166             by <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_intern.htm">interning</a>
1167             the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/f_stg_up.htm#string-upcase">upcased</a>
1168             parameter string into
1169             the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/11_abc.htm">keyword
1170               package</a>.  If <clix:arg>parameter-type</clix:arg>
1171             is <code>'CHARACTER</code> and the parameter string is of
1172             length one, <clix:arg>var</clix:arg>'s value will be the single
1173             character of this string, otherwise <code>NIL</code>.
1174             If <clix:arg>parameter-type</clix:arg>
1175             is <code>'BOOLEAN</code>, <clix:arg>var</clix:arg>'s value will
1176             always be <code>T</code> (unless it is <code>NIL</code> by the
1177             first rule above, of course).
1178             If <clix:arg>parameter-type</clix:arg> is any other atom, it is
1179             supposed to be
1180             a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_f.htm#function_designator">function
1181               designator</a> for a unary function which will be called to
1182             convert the string to something else.
1183           </p>
1184           <p>
1185             Those were the rules for <em>simple</em> parameter types, but
1186             <clix:arg>parameter-type</clix:arg> can also be a list starting
1187             with one of the symbols
1188             <code>LIST</code>, <code>ARRAY</code>,
1189             or <code>HASH-TABLE</code>.  The second value of the list must
1190             always be a simple parameter type as in the last paragraph -
1191             we'll call it the <em>inner type</em> below.
1192           </p>
1193           <p>
1194             In the case of <code>'LIST</code>, all GET/POST parameters
1195             called <clix:arg>real-name</clix:arg> will be collected,
1196             converted to the inner type as by the rules above, and
1197             assembled into a list which will be the value of
1198             <clix:arg>var</clix:arg>.
1199           </p>
1200           <p>
1201             In the case of <code>'ARRAY</code>, all GET/POST parameters
1202             which have a name like the result of
1203           </p>
1204           <pre>(format nil "~A[~A]" real-name n)</pre>
1205           where <clix:arg>n</clix:arg> is a non-negative integer, will be
1206           assembled into an array where the <clix:arg>n</clix:arg>th element
1207           will be set accordingly, after conversion to the inner type.
1208           The array, which will become the value
1209           of <clix:arg>var</clix:arg>, will be big enough to hold all
1210           matching parameters, but not bigger.  Array elements not set as
1211           described above will be <code>NIL</code>.  Note
1212           that <code>VAR</code> will always be bound to an array, which
1213           may be empty, so it will never be <code>NIL</code>, even if no
1214           appropriate GET/POST parameters are found.
1215           <p>
1216             The full form of a <code>'HASH-TABLE</code> parameter type is
1217           </p>
1218           <pre>(hash-table inner-type key-type test-function)</pre>
1219           but <clix:arg>key-type</clix:arg>
1220           and <clix:arg>test-function</clix:arg> can be left out in which
1221           case they default to <code>'STRING</code>
1222           and <code>'EQUAL</code>, respectively.  For this parameter type,
1223           all GET/POST parameters which have a name like the result of
1224           <pre>(format nil "~A{~A}" real-name key)</pre>
1225           (where <clix:arg>key</clix:arg> is a string that doesn't contain
1226           curly brackets) will become the values (after conversion
1227           to <clix:arg>inner-type</clix:arg>) of a hash table with test
1228           function <clix:arg>test-function</clix:arg>
1229           where <clix:arg>key</clix:arg> (after conversion
1230           to <clix:arg>key-type</clix:arg>) will be the corresponding key.
1231           Note that <clix:arg>var</clix:arg> will always be bound to a hash
1232           table, which may be empty, so it will never be <code>NIL</code>,
1233           even if no appropriate GET/POST parameters are found.
1234           <p>
1235             To make matters even more complicated, the three compound
1236             parameter types also have an abbreviated form - just one of
1237             the symbols <code>LIST</code>, <code>ARRAY</code>,
1238             or <code>HASH-TABLE</code>.  In this case, the inner type will
1239             default to <code>'STRING</code>.
1240           </p>
1241           <p>
1242             If <clix:arg>parameter-type</clix:arg> is not provided
1243             or <code>NIL</code>, <clix:arg>default-parameter-type</clix:arg>
1244             (the default of which is <code>'STRING</code>) will be used
1245             instead.
1246           </p>
1247           <p>
1248             If the result of the computations above would be
1249             that <clix:arg>var</clix:arg> would be bound
1250             to <code>NIL</code>, then <clix:arg>init-form</clix:arg> (if
1251             provided) will be evaluated instead,
1252             and <clix:arg>var</clix:arg> will be bound to the result of this
1253             evaluation.
1254           </p>
1255           <p>
1256             Handlers built with this macro are constructed in such a way
1257             that the resulting Lisp function is useful even outside of
1258             Hunchentoot.  Specifically, all the parameter computations
1259             above will only happen if <clix:ref>*REQUEST*</clix:ref> is
1260             bound, i.e. if we're within a Hunchentoot request.
1261             Otherwise, <clix:arg>var</clix:arg> will always be bound to the
1262             result of evaluating <clix:arg>init-form</clix:arg> unless a
1263             corresponding keyword argument is provided.
1264           </p>
1265           <p>
1266             The <a href="#example">example code</a> that comes with
1267             Hunchentoot contains an example which demonstrates some of the
1268             features of <clix:ref>DEFINE-EASY-HANDLER</clix:ref>.
1269           </p>
1270         </clix:description>
1271       </clix:function>
1272
1273       <clix:function name='dispatch-easy-handlers'>
1274         <clix:lambda-list>request
1275         </clix:lambda-list>
1276         <clix:returns>result
1277         </clix:returns>
1278         <clix:description>This is a dispatcher which returns the appropriate handler
1279         defined with <clix:ref>DEFINE-EASY-HANDLER</clix:ref>, if there is one.
1280         </clix:description>
1281       </clix:function>
1282
1283     </clix:subchapter>
1284
1285     <clix:subchapter name="requests" title="Request objects">
1286
1287       For each incoming request, the <a href="#acceptors">acceptor</a> (in
1288       <clix:ref>PROCESS-CONNECTION</clix:ref>) creates a
1289       <clix:ref>REQUEST</clix:ref> object and makes it available to <a
1290       href="#handlers">handlers</a> via the special variable
1291       <clix:ref>*REQUEST*</clix:ref>.  This object contains all relevant
1292       information about the request and this section collects the functions
1293       which can be used to query such an object.  In all function where
1294       <clix:arg>request</clix:arg> is an optional or keyword parameter, the
1295       default is <clix:ref>*REQUEST*</clix:ref>.
1296
1297       <p>
1298         If you need more fine-grained control over the behaviour of request
1299         objects, you can subclass <clix:ref>REQUEST</clix:ref> and initialize
1300         the <a href="#acceptor-request-class"><code>REQUEST-CLASS</code></a>
1301         slot of the <clix:ref>ACCEPTOR</clix:ref> class accordingly.  The
1302         acceptor will generate request objects of the class named by this
1303         slot.
1304       </p>
1305
1306       <clix:class name='request'>
1307         <clix:description>
1308           Objects of this class hold all the information
1309           about an incoming request.  They are created automatically by
1310           acceptors and can be accessed by the
1311           corresponding <a href="#handlers">handler</a>.
1312
1313           You should not mess with the slots of these objects directly, but you
1314           can subclass <clix:ref>REQUEST</clix:ref> in order to implement your
1315           own behaviour.  See
1316           the <a href="#acceptor-request-class"><code>REQUEST-CLASS</code></a>
1317           slot of the <clix:ref>ACCEPTOR</clix:ref> class.
1318         </clix:description>
1319       </clix:class>
1320
1321       <clix:special-variable name='*request*'>
1322         <clix:description>The current REQUEST object while in the context of a request.
1323         </clix:description>
1324       </clix:special-variable>
1325
1326       <clix:function name='real-remote-addr'>
1327         <clix:lambda-list>
1328           <clix:lkw>optional
1329           </clix:lkw> request
1330         </clix:lambda-list>
1331         <clix:returns>string{, list}
1332         </clix:returns>
1333         <clix:description>
1334           Returns the &#039;<code>X-Forwarded-For</code>&#039; incoming http header as the
1335           second value in the form of a list of IP addresses and the first
1336           element of this list as the first value if this header exists.
1337           Otherwise returns the value of <clix:ref>REMOTE-ADDR</clix:ref> as the only value.
1338         </clix:description>
1339       </clix:function>
1340
1341       <clix:function name='parameter'>
1342         <clix:lambda-list>name
1343         <clix:lkw>optional
1344         </clix:lkw> request
1345         </clix:lambda-list>
1346         <clix:returns>string
1347         </clix:returns>
1348         <clix:description>
1349           Returns the GET or the POST parameter with name
1350           <clix:arg>name</clix:arg> (a string) - or <code>NIL</code>
1351           if there is none.  If both a GET and a POST parameter with
1352           the same name exist the GET parameter is returned.  Search
1353           is case-sensitive.  See also
1354           <clix:ref>GET-PARAMETER</clix:ref> and
1355           <clix:ref>POST-PARAMETER</clix:ref>.
1356         </clix:description>
1357       </clix:function>
1358
1359       <clix:function name="get-parameter">
1360         <clix:lambda-list>name <clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1361         <clix:returns>string</clix:returns>
1362         <clix:description>
1363           Returns the value of the GET parameter (as provided via the
1364           request URI) named by the string <clix:arg>name</clix:arg> as a
1365           string (or <code>NIL</code> if there ain't no GET parameter
1366           with this name). Note that only the first value will be
1367           returned if the client provided more than one GET parameter
1368           with the name <clix:arg>name</clix:arg>. See
1369           also <clix:ref>GET-PARAMETERS*</clix:ref>.
1370         </clix:description>
1371       </clix:function>
1372
1373       <clix:function name="post-parameter">
1374         <clix:lambda-list>name <clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1375         <clix:returns>string</clix:returns>
1376         <clix:description>
1377           Returns the value of the POST parameter (as provided in the
1378           request's body) named by the
1379           string <clix:arg>name</clix:arg>. Note that only the first value
1380           will be returned if the client provided more than one POST
1381           parameter with the name <clix:arg>name</clix:arg>.  This value
1382           will usually be a string (or <code>NIL</code> if there ain't
1383           no POST parameter with this name). If, however, the browser
1384           sent a <a class="none" name="upload">file</a> through
1385           a <a href="http://www.faqs.org/rfcs/rfc2388.html">
1386             <code>multipart/form-data</code>
1387           </a> form, the value of this function is a three-element list
1388           <pre>(path file-name content-type)</pre>
1389           where <clix:arg>path</clix:arg> is a pathname denoting the place
1390           were the uploaded file was
1391           stored, <clix:arg>file-name</clix:arg> (a string) is the file
1392           name sent by the browser, and <clix:arg>content-type</clix:arg>
1393           (also a string) is the content type sent by the browser. The
1394           file denoted by <clix:arg>path</clix:arg> will be deleted after
1395           the request has been handled - you have to move or copy it
1396           somewhere else if you want to keep it.
1397           <p>
1398             POST parameters will only be computed if the content type of
1399             the request body was <code>multipart/form-data</code>
1400             or <code>application/x-www-form-urlencoded</code>.  Although
1401             this function is called <code>POST-PARAMETER</code>, you can
1402             instruct Hunchentoot to compute these parameters for other
1403             request methods by
1404             setting <clix:ref>*METHODS-FOR-POST-PARAMETERS*</clix:ref>.
1405           </p>
1406           <p>
1407             See also <clix:ref>POST-PARAMETERS</clix:ref>
1408             and <clix:ref>*TMP-DIRECTORY*</clix:ref>.
1409           </p>
1410         </clix:description>
1411       </clix:function>
1412
1413       <clix:function name="get-parameters*">
1414         <clix:lambda-list><clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1415         <clix:returns>alist</clix:returns>
1416         <clix:description>
1417           Returns
1418           an <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_a.htm#alist">alist</a>
1419           of all GET parameters (as provided via the request
1420           URI). The <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#car">car</a>
1421           of each element of this list is the parameter's name while
1422           the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#cdr">cdr</a>
1423           is its value (as a string). The elements of this list are in
1424           the same order as they were within the request URI. See
1425           also <clix:ref>GET-PARAMETER</clix:ref>.
1426         </clix:description>
1427       </clix:function>
1428
1429       <clix:function name="post-parameters*">
1430         <clix:lambda-list><clix:lkw>optional</clix:lkw> request</clix:lambda-list>
1431         <clix:returns>alist</clix:returns>
1432         <clix:description>
1433           Returns
1434           an <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_a.htm#alist">alist</a>
1435           of all POST parameters (as provided via the request's
1436           body). The <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#car">car</a>
1437           of each element of this list is the parameter's name while
1438           the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_c.htm#cdr">cdr</a>
1439           is its value. The elements of this list are in the same order
1440           as they were within the request's body.
1441           <p>
1442             See also <clix:ref>POST-PARAMETER</clix:ref>.
1443           </p>
1444         </clix:description>
1445       </clix:function>
1446
1447       <clix:special-variable name='*methods-for-post-parameters*'>
1448         <clix:description>A list of the request method types (as keywords) for which
1449         Hunchentoot will try to compute <clix:arg>post-parameters</clix:arg>.
1450         </clix:description>
1451       </clix:special-variable>
1452
1453       <clix:function name='cookie-in'>
1454         <clix:lambda-list>name
1455         <clix:lkw>optional
1456         </clix:lkw> request
1457         </clix:lambda-list>
1458         <clix:returns>cookie
1459         </clix:returns>
1460         <clix:description>
1461           Returns the cookie with the name <clix:arg>name</clix:arg> (a string) as sent by the
1462           browser - or <code>NIL</code> if there is none.
1463         </clix:description>
1464       </clix:function>
1465
1466       <clix:function name='cookies-in*'>
1467         <clix:lambda-list>
1468           <clix:lkw>optional
1469           </clix:lkw> request
1470         </clix:lambda-list>
1471         <clix:returns>alist
1472         </clix:returns>
1473         <clix:description>Returns an alist of all cookies associated with the <clix:ref>REQUEST</clix:ref> object
1474         <clix:arg>request</clix:arg>.
1475         </clix:description>
1476       </clix:function>
1477
1478       <clix:function name='host'>
1479         <clix:lambda-list>
1480           <clix:lkw>optional
1481           </clix:lkw> request
1482         </clix:lambda-list>
1483         <clix:returns>host
1484         </clix:returns>
1485         <clix:description>Returns the &#039;Host&#039; incoming http header value.
1486         </clix:description>
1487       </clix:function>
1488
1489       <clix:function name='query-string*'>
1490         <clix:lambda-list>
1491           <clix:lkw>optional
1492           </clix:lkw> request
1493         </clix:lambda-list>
1494         <clix:returns>string
1495         </clix:returns>
1496         <clix:description>
1497           Returns the query string of the <clix:ref>REQUEST</clix:ref> object <clix:arg>request</clix:arg>. That&#039;s
1498           the part behind the question mark (i.e. the GET parameters).
1499         </clix:description>
1500       </clix:function>
1501
1502       <clix:function name='referer'>
1503         <clix:lambda-list>
1504           <clix:lkw>optional
1505           </clix:lkw> request
1506         </clix:lambda-list>
1507         <clix:returns>result
1508         </clix:returns>
1509         <clix:description>
1510           Returns the &#039;Referer&#039; (sic!) http header.
1511         </clix:description>
1512       </clix:function>
1513
1514       <clix:function name='request-method*'>
1515         <clix:lambda-list>
1516           <clix:lkw>optional
1517           </clix:lkw> request
1518         </clix:lambda-list>
1519         <clix:returns>keyword
1520         </clix:returns>
1521         <clix:description>
1522           Returns the request method as a Lisp keyword.
1523         </clix:description>
1524       </clix:function>
1525
1526       <clix:function name='request-uri*'>
1527         <clix:lambda-list>
1528           <clix:lkw>optional
1529           </clix:lkw> request
1530         </clix:lambda-list>
1531         <clix:returns>uri
1532         </clix:returns>
1533         <clix:description>
1534           Returns the request URI.
1535         </clix:description>
1536       </clix:function>
1537
1538       <clix:function name='server-protocol*'>
1539         <clix:lambda-list>
1540           <clix:lkw>optional
1541           </clix:lkw> request
1542         </clix:lambda-list>
1543         <clix:returns>keyword
1544         </clix:returns>
1545         <clix:description>
1546           Returns the request protocol as a Lisp keyword.
1547         </clix:description>
1548       </clix:function>
1549
1550       <clix:function name='user-agent'>
1551         <clix:lambda-list>
1552           <clix:lkw>optional
1553           </clix:lkw> request
1554         </clix:lambda-list>
1555         <clix:returns>result
1556         </clix:returns>
1557         <clix:description>
1558           Returns the &#039;User-Agent&#039; http header.
1559         </clix:description>
1560       </clix:function>
1561
1562       <clix:function name='header-in*'>
1563         <clix:lambda-list>name
1564         <clix:lkw>optional
1565         </clix:lkw> request
1566         </clix:lambda-list>
1567         <clix:returns>header
1568         </clix:returns>
1569         <clix:description>
1570           Returns the incoming header with name
1571           <clix:arg>name</clix:arg>.  <clix:arg>name</clix:arg> can be
1572           a keyword (recommended) or a string.
1573         </clix:description>
1574       </clix:function>
1575
1576       <clix:function name='headers-in*'>
1577         <clix:lambda-list>
1578           <clix:lkw>optional
1579           </clix:lkw> request
1580         </clix:lambda-list>
1581         <clix:returns>alist
1582         </clix:returns>
1583         <clix:description>
1584           Returns an alist of the incoming headers associated with the
1585           <clix:ref>REQUEST</clix:ref> object
1586           <clix:arg>request</clix:arg>.
1587         </clix:description>
1588       </clix:function>
1589
1590       <clix:function name='remote-addr*'>
1591         <clix:lambda-list>
1592           <clix:lkw>optional
1593           </clix:lkw> request
1594         </clix:lambda-list>
1595         <clix:returns>address
1596         </clix:returns>
1597         <clix:description>
1598           Returns the address the current request originated from.
1599         </clix:description>
1600       </clix:function>
1601
1602       <clix:function name='remote-port*'>
1603         <clix:lambda-list>
1604           <clix:lkw>optional
1605           </clix:lkw> request
1606         </clix:lambda-list>
1607         <clix:returns>port
1608         </clix:returns>
1609         <clix:description>
1610           Returns the port the current request originated from.
1611         </clix:description>
1612       </clix:function>
1613
1614       <clix:function name='script-name*'>
1615         <clix:lambda-list>
1616           <clix:lkw>optional
1617           </clix:lkw> request
1618         </clix:lambda-list>
1619         <clix:returns>script-name
1620         </clix:returns>
1621         <clix:description>
1622           Returns the file name of the <clix:ref>REQUEST</clix:ref>
1623           object <clix:arg>request</clix:arg>. That&#039;s the
1624           requested URI without the query string (i.e the GET
1625           parameters).
1626         </clix:description>
1627       </clix:function>
1628
1629       <clix:accessor name='aux-request-value'>
1630         <clix:lambda-list>symbol
1631         <clix:lkw>optional
1632         </clix:lkw> request
1633         </clix:lambda-list>
1634         <clix:returns>value, present-p
1635         </clix:returns>
1636         <clix:description>
1637           This accessor can be used to associate arbitrary
1638           data with the the symbol <clix:arg>symbol</clix:arg> in the <clix:ref>REQUEST</clix:ref> object
1639           <clix:arg>request</clix:arg>. <clix:arg>present-p</clix:arg> is true if such data was found, otherwise <code>NIL</code>.
1640         </clix:description>
1641       </clix:accessor>
1642
1643       <clix:function name='delete-aux-request-value'>
1644         <clix:lambda-list>symbol
1645         <clix:lkw>optional
1646         </clix:lkw> request
1647         </clix:lambda-list>
1648         <clix:returns>|
1649         </clix:returns>
1650         <clix:description>
1651           Removes the value associated with <clix:arg>symbol</clix:arg> from the <clix:ref>REQUEST</clix:ref> object
1652           <clix:arg>request</clix:arg>.
1653         </clix:description>
1654       </clix:function>
1655
1656       <clix:function name='authorization'>
1657         <clix:lambda-list>
1658           <clix:lkw>optional
1659           </clix:lkw> request
1660         </clix:lambda-list>
1661         <clix:returns>result
1662         </clix:returns>
1663         <clix:description>
1664           Returns as two values the user and password (if any) as
1665           encoded in the &#039;AUTHORIZATION&#039; header.  Returns
1666           <code>NIL</code> if there is no such header.
1667         </clix:description>
1668       </clix:function>
1669
1670       <clix:special-variable name='*hunchentoot-default-external-format*'>
1671         <clix:description>
1672           The external format used to compute the <clix:ref>REQUEST</clix:ref> object.
1673         </clix:description>
1674       </clix:special-variable>
1675
1676       <clix:special-variable name='*file-upload-hook*'>
1677         <clix:description>
1678           If this is not <code>NIL</code>, it should be a unary
1679           function which will be called with a pathname for each file
1680           which is <a href="#upload">uploaded</a> to Hunchentoot.  The
1681           pathname denotes the temporary file to which the uploaded
1682           file is written.  The hook is called directly before the
1683           file is created. At this point,
1684           <clix:ref>*REQUEST*</clix:ref> is already bound to the
1685           current <clix:ref>REQUEST</clix:ref> object, but obviously
1686           you can't access the post parameters yet.
1687         </clix:description>
1688       </clix:special-variable>
1689
1690       <clix:function name="raw-post-data">
1691         <clix:lambda-list>
1692           <clix:lkw>key</clix:lkw>
1693           request external-format force-text force-binary want-stream
1694         </clix:lambda-list>
1695         <clix:returns>raw-body-or-stream</clix:returns>
1696         <clix:description>
1697           Returns the content sent by the client in the request body if
1698           there was any (unless the content type
1699           was <code>multipart/form-data</code> in which
1700           case <code>NIL</code> is returned).  By default, the result is
1701           a string if the type of the <code>Content-Type</code>
1702           <a href="http://www.faqs.org/rfcs/rfc1590.html">media type</a>
1703           is <code>"text"</code>, and a vector of octets otherwise.  In
1704           the case of a string, the external format to be used to decode
1705           the content will be determined from the <code>charset</code>
1706           parameter sent by the client (or
1707           otherwise <clix:ref>*HUNCHENTOOT-DEFAULT-EXTERNAL-FORMAT*</clix:ref>
1708           will be used).
1709           <p>
1710             You can also provide an external format explicitly (through
1711             <clix:arg>external-format</clix:arg>) in which case the result
1712             will unconditionally be a string.  Likewise, you can provide
1713             a true value for <clix:arg>force-text</clix:arg> which will
1714             force Hunchentoot to act as if the type of the media type
1715             had been <code>"text"</code>
1716             (with <clix:arg>external-format</clix:arg> taking precedence
1717             if provided).  Or you can provide a true value
1718             for <clix:arg>force-binary</clix:arg> which means that you
1719             want a vector of octets at any rate.  (If both
1720             <clix:arg>force-text</clix:arg>
1721             and <clix:arg>force-binary</clix:arg> are true, an error will
1722             be signaled.)
1723           </p>
1724           <p>
1725             If, however, you provide a true value
1726             for <clix:arg>want-stream</clix:arg>, the other parameters are
1727             ignored and you'll get the content (flexi) stream to read
1728             from it yourself.  It is then your responsibility to read
1729             the correct amount of data, because otherwise you won't be
1730             able to return a response to the client.  The stream will
1731             have
1732             its <a href="http://weitz.de/flexi-streams/#flexi-streams">octet
1733               position</a> set to <code>0</code>.  If the client provided
1734             a <code>Content-Length</code> header, the stream will also
1735             have a
1736             corresponding <a href="http://weitz.de/flexi-streams/#flexi-streams">bound</a>,
1737             so no matter whether the client used chunked encoding or
1738             not, you can always read until EOF.
1739           </p>
1740           <p>
1741             If the content type of the request
1742             was <code>multipart/form-data</code>
1743             or <code>application/x-www-form-urlencoded</code>, the
1744             content has been read by Hunchentoot already and you can't
1745             read from the stream anymore.
1746           </p>
1747           <p>
1748             You can call <clix:ref>RAW-POST-DATA</clix:ref> more than once
1749             per request, but you can't mix calls which have different
1750             values for <clix:arg>want-stream</clix:arg>.
1751           </p>
1752           <p>
1753             Note that this function is slightly misnamed because a
1754             client can send content even if the request method is not
1755             POST.
1756           </p>
1757         </clix:description>
1758       </clix:function>
1759
1760
1761       <clix:function name='recompute-request-parameters'>
1762         <clix:lambda-list>
1763           <clix:lkw>key
1764           </clix:lkw> request external-format
1765         </clix:lambda-list>
1766         <clix:returns>|
1767         </clix:returns>
1768         <clix:description>
1769           Recomputes the GET and POST parameters for the <clix:ref>REQUEST</clix:ref> object
1770           <clix:arg>request</clix:arg>.  This only makes sense if you&#039;re switching external formats
1771           during the request.
1772         </clix:description>
1773       </clix:function>
1774
1775       <clix:function generic='true' name='process-request'>
1776         <clix:lambda-list>request
1777         </clix:lambda-list>
1778         <clix:returns>nil
1779         </clix:returns>
1780         <clix:description>
1781           This function is called by <clix:ref>PROCESS-CONNECTION</clix:ref>
1782           after the incoming headers have been read.  It
1783           calls <clix:ref>HANDLE-REQUEST</clix:ref> (and is more or less just a
1784           thin wrapper around it) to select and call a
1785           <a href="#handlers">handler</a> and send the output of this handler to
1786           the client.  Note that <clix:ref>PROCESS-CONNECTION</clix:ref> is
1787           called once per connection and loops in case of a persistent
1788           connection while <clix:ref>PROCESS-REQUEST</clix:ref> is called anew
1789           for each request.
1790           <p>
1791             The return value of this function is ignored.
1792           </p>
1793           <p>
1794             Like <clix:ref>PROCESS-CONNECTION</clix:ref>, this is another function
1795             the behaviour of which you should only modify if you really, really
1796             know what you're doing.
1797           </p>
1798         </clix:description>
1799       </clix:function>
1800
1801       <clix:function generic='true' name='handle-request'>
1802         <clix:lambda-list>acceptor request
1803         </clix:lambda-list>
1804         <clix:returns>content
1805         </clix:returns>
1806         <clix:description>
1807           This function is called by <clix:ref>PROCESS-REQUEST</clix:ref> once
1808           the request has been read and a <clix:ref>REQUEST</clix:ref> object
1809           has been created.  Its job is to actually handle the request, i.e. to
1810           return something to the client.
1811           <p>
1812             The default method calls the
1813             acceptor's <a href="#request-dispatch">request dispatcher</a>, but you
1814             can of course implement a different behaviour.  The default method
1815             also sets up <a href="#logging">standard error handling</a> for
1816             the <a href="#handlers">handler</a>.
1817           </p>
1818           <p>
1819             Might be a good place to bind or rebind special variables which can
1820             then be accessed by your <a href="#handlers">handlers</a>.
1821           </p>
1822         </clix:description>
1823       </clix:function>
1824
1825
1826       <clix:readers generic='true'>
1827         <clix:listed-reader generic='true' name='cookies-in'>
1828           <clix:lambda-list>request
1829           </clix:lambda-list>
1830           <clix:returns>cookies
1831           </clix:returns>
1832         </clix:listed-reader>
1833
1834         <clix:listed-reader generic='true' name='get-parameters'>
1835           <clix:lambda-list>request
1836           </clix:lambda-list>
1837           <clix:returns>get-parameters
1838           </clix:returns>
1839         </clix:listed-reader>
1840
1841         <clix:listed-reader generic='true' name='header-in'>
1842           <clix:lambda-list>name request
1843           </clix:lambda-list>
1844           <clix:returns>result
1845           </clix:returns>
1846           <clix:description>
1847           </clix:description>
1848         </clix:listed-reader>
1849
1850         <clix:listed-reader generic='true' name='headers-in'>
1851           <clix:lambda-list>request
1852           </clix:lambda-list>
1853           <clix:returns>headers
1854           </clix:returns>
1855         </clix:listed-reader>
1856
1857         <clix:listed-reader generic='true' name='post-parameters'>
1858           <clix:lambda-list>request
1859           </clix:lambda-list>
1860           <clix:returns>post-parameters
1861           </clix:returns>
1862         </clix:listed-reader>
1863
1864         <clix:listed-reader generic='true' name='query-string'>
1865           <clix:lambda-list>request
1866           </clix:lambda-list>
1867           <clix:returns>query-string
1868           </clix:returns>
1869         </clix:listed-reader>
1870
1871         <clix:listed-reader generic='true' name='remote-addr'>
1872           <clix:lambda-list>request
1873           </clix:lambda-list>
1874           <clix:returns>address
1875           </clix:returns>
1876         </clix:listed-reader>
1877
1878         <clix:listed-reader generic='true' name='remote-port'>
1879           <clix:lambda-list>request
1880           </clix:lambda-list>
1881           <clix:returns>port
1882           </clix:returns>
1883         </clix:listed-reader>
1884
1885         <clix:listed-reader generic='true' name='request-acceptor'>
1886           <clix:lambda-list>request
1887           </clix:lambda-list>
1888           <clix:returns>acceptor
1889           </clix:returns>
1890         </clix:listed-reader>
1891
1892         <clix:listed-reader generic='true' name='request-method'>
1893           <clix:lambda-list>request
1894           </clix:lambda-list>
1895           <clix:returns>method
1896           </clix:returns>
1897         </clix:listed-reader>
1898
1899         <clix:listed-reader generic='true' name='request-uri'>
1900           <clix:lambda-list>request
1901           </clix:lambda-list>
1902           <clix:returns>uri
1903           </clix:returns>
1904         </clix:listed-reader>
1905
1906         <clix:listed-reader generic='true' name='server-protocol'>
1907           <clix:lambda-list>request
1908           </clix:lambda-list>
1909           <clix:returns>protocol
1910           </clix:returns>
1911         </clix:listed-reader>
1912
1913         <clix:listed-reader generic='true' name='script-name'>
1914           <clix:lambda-list>request
1915           </clix:lambda-list>
1916           <clix:returns>result
1917           </clix:returns>
1918         </clix:listed-reader>
1919
1920         <clix:description>
1921           These are various generic readers which are used
1922           to read information about a <clix:ref>REQUEST</clix:ref> object.  If you are writing a
1923           <a href="#handlers">handler</a>, you should <em>not</em> use these readers but instead utilize the
1924           corresponding functions with an asterisk at the end of their name,
1925           also listed in this section.  These generic readers are only
1926           exported for users who want to create their own subclasses of
1927           <clix:ref>REQUEST</clix:ref>.
1928         </clix:description>
1929
1930       </clix:readers>
1931
1932     </clix:subchapter>
1933
1934     <clix:subchapter name="replies" title="Reply objects">
1935
1936       For each incoming request, the <a href="#acceptors">acceptor</a>
1937       (in <clix:ref>PROCESS-CONNECTION</clix:ref>) creates
1938       a <clix:ref>REPLY</clix:ref> object and makes it available
1939       to <a href="#handlers">handlers</a> via the special variable
1940       <clix:ref>*REPLY*</clix:ref>.  This object contains all relevant
1941       information (except for the content body) about the reply that will be
1942       sent to the client and this section collects the functions which can
1943       be used to query and modify such an object.  In all function
1944       where <clix:arg>reply</clix:arg> is an optional or keyword parameter,
1945       the default is <clix:ref>*REPLY*</clix:ref>.
1946
1947       <p>
1948         If you need more fine-grained control over the behaviour of reply
1949         objects, you can subclass <clix:ref>REPLY</clix:ref> and initialize
1950         the <a href="#acceptor-reply-class"><code>REPLY-CLASS</code></a>
1951         slot of the <clix:ref>ACCEPTOR</clix:ref> class accordingly.  The
1952         acceptor will generate reply objects of the class named by this
1953         slot.
1954       </p>
1955
1956       <clix:class name='reply'>
1957         <clix:description>
1958           Objects of this class hold all the information about an
1959           outgoing reply.  They are created automatically by
1960           Hunchentoot and can be accessed and modified by the
1961           corresponding <a href="#handlers">handler</a>.
1962         <p>
1963           You should not mess with the slots of these objects directly, but you
1964           can subclass <clix:ref>REPLY</clix:ref> in order to implement your own behaviour.  See the
1965           <a href="#acceptor-reply-class"><code>:reply-class</code></a> initarg
1966           of the <clix:ref>ACCEPTOR</clix:ref> class.
1967         </p>
1968         </clix:description>
1969       </clix:class>
1970
1971       <clix:special-variable name='*reply*'>
1972         <clix:description>
1973           The current <clix:ref>REPLY</clix:ref> object in the context of a request.
1974         </clix:description>
1975       </clix:special-variable>
1976
1977       <clix:accessor name='header-out'>
1978         <clix:lambda-list>name
1979         <clix:lkw>optional
1980         </clix:lkw> reply
1981         </clix:lambda-list>
1982         <clix:returns>string
1983         </clix:returns>
1984         <clix:description>
1985           <clix:ref>HEADER-OUT</clix:ref> returns the outgoing http header named by the keyword <clix:arg>name</clix:arg> if there is one, otherwise <code>NIL</code>. <code>SETF</code> of <clix:ref>HEADER-OUT</clix:ref> changes the current value of the header named <clix:arg>name</clix:arg>. If no header named <clix:arg>name</clix:arg> exists, it is created. For backwards compatibility, <clix:arg>name</clix:arg> can also be a string in which case the association between a header and its name is case-insensitive.
1986           <p>
1987             Note that the header 'Set-Cookie' cannot be queried by <clix:ref>HEADER-OUT</clix:ref> and must not be set by <code>SETF</code> of <clix:ref>HEADER-OUT</clix:ref>.
1988             See also <clix:ref>HEADERS-OUT*</clix:ref>, <clix:ref>CONTENT-TYPE*</clix:ref>, <clix:ref>CONTENT-LENGTH*</clix:ref>, <clix:ref>COOKIES-OUT*</clix:ref>, and <clix:ref>COOKIE-OUT</clix:ref>.
1989           </p>
1990         </clix:description>
1991       </clix:accessor>
1992
1993       <clix:function name='headers-out*'>
1994         <clix:lambda-list>
1995           <clix:lkw>optional
1996           </clix:lkw> reply
1997         </clix:lambda-list>
1998         <clix:returns>alist
1999         </clix:returns>
2000         <clix:description>Returns an alist of the outgoing headers associated with the
2001         <clix:ref>REPLY</clix:ref> object <clix:arg>reply</clix:arg>.  See also <clix:ref>HEADER-OUT</clix:ref>.
2002         </clix:description>
2003       </clix:function>
2004
2005       <clix:accessor name='content-length*'>
2006         <clix:lambda-list>
2007           <clix:lkw>optional
2008           </clix:lkw> reply
2009         </clix:lambda-list>
2010         <clix:returns>content-length
2011         </clix:returns>
2012         <clix:description>
2013           The outgoing &#039;Content-Length&#039; http header of <clix:arg>reply</clix:arg>.
2014         </clix:description>
2015       </clix:accessor>
2016
2017       <clix:accessor name='content-type*'>
2018         <clix:lambda-list>
2019           <clix:lkw>optional
2020           </clix:lkw> reply
2021         </clix:lambda-list>
2022         <clix:returns>content-type
2023         </clix:returns>
2024         <clix:description>
2025           The outgoing &#039;Content-Type&#039; http header of <clix:arg>reply</clix:arg>.
2026         </clix:description>
2027       </clix:accessor>
2028
2029       <clix:function name='cookie-out'>
2030         <clix:lambda-list>name
2031         <clix:lkw>optional
2032         </clix:lkw> reply
2033         </clix:lambda-list>
2034         <clix:returns>result
2035         </clix:returns>
2036         <clix:description>
2037           Returns the current value of the outgoing <a
2038           href="#cookies">cookie</a> named
2039           <clix:arg>name</clix:arg>. Search is case-sensitive.
2040         </clix:description>
2041       </clix:function>
2042
2043       <clix:accessor name='cookies-out*'>
2044         <clix:lambda-list>
2045           <clix:lkw>optional
2046           </clix:lkw> reply
2047         </clix:lambda-list>
2048         <clix:returns>alist
2049         </clix:returns>
2050         <clix:description>
2051           Returns or sets an alist of the outgoing <a
2052           href="#cookies">cookies</a> associated with the
2053           <clix:ref>REPLY</clix:ref> object
2054           <clix:arg>reply</clix:arg>.
2055         </clix:description>
2056       </clix:accessor>
2057
2058       <clix:accessor name='return-code*'>
2059         <clix:lambda-list>
2060           <clix:lkw>optional
2061           </clix:lkw> reply
2062         </clix:lambda-list>
2063         <clix:returns>return-code
2064         </clix:returns>
2065         <clix:description>
2066           Gets or sets the http return code of
2067           <clix:arg>reply</clix:arg>.  The return code of each
2068           <clix:ref>REPLY</clix:ref> object is initially set to
2069           <clix:ref>+HTTP-OK+</clix:ref>.
2070         </clix:description>
2071       </clix:accessor>
2072
2073       <clix:function name="send-headers">
2074         <clix:returns>stream</clix:returns>
2075         <clix:description>
2076           Sends the initial status line and all headers as determined
2077           by the <clix:ref>REPLY</clix:ref>
2078           object <clix:ref>*REPLY*</clix:ref>.  Returns
2079           a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_b.htm#binary">binary</a>
2080           stream to which the body of the reply can be written.  Once
2081           this function has been called, further changes
2082           to <clix:ref>*REPLY*</clix:ref> don't have any effect.
2083           Also, automatic handling of errors (i.e. sending the
2084           corresponding status code to the browser, etc.) is turned
2085           off for this request and functions
2086           like <clix:ref>REDIRECT</clix:ref> or
2087           to <clix:ref>ABORT-REQUEST-HANDLER</clix:ref> won't have the
2088           desired effect once the headers are sent.
2089           <p>
2090             If your handlers return the full body as a string or as an
2091             array of octets, you should <em>not</em> call this function.
2092             If a handler calls <clix:ref>SEND-HEADERS</clix:ref> , its
2093             return value is ignored.
2094           </p>
2095         </clix:description>
2096       </clix:function>
2097
2098       <clix:accessor name='reply-external-format*'>
2099         <clix:lambda-list>
2100           <clix:lkw>optional
2101           </clix:lkw> reply
2102         </clix:lambda-list>
2103         <clix:returns>external-format
2104         </clix:returns>
2105         <clix:description>
2106           Gets or sets the external format of <clix:arg>reply</clix:arg> which is used for character output.
2107         </clix:description>
2108       </clix:accessor>
2109
2110       <clix:special-variable name='*default-content-type*'>
2111         <clix:description>
2112           The default content-type header which is returned to the client.
2113         </clix:description>
2114       </clix:special-variable>
2115
2116       <clix:constants>
2117         <clix:listed-constant name="+http-continue+"/>
2118         <clix:listed-constant name="+http-switching-protocols+"/>
2119         <clix:listed-constant name="+http-ok+"/>
2120         <clix:listed-constant name="+http-created+"/>
2121         <clix:listed-constant name="+http-accepted+"/>
2122         <clix:listed-constant name="+http-non-authoritative-information+"/>
2123         <clix:listed-constant name="+http-no-content+"/>
2124         <clix:listed-constant name="+http-reset-content+"/>
2125         <clix:listed-constant name="+http-partial-content+"/>
2126         <clix:listed-constant name="+http-multi-status+"/>
2127         <clix:listed-constant name="+http-multiple-choices+"/>
2128         <clix:listed-constant name="+http-moved-permanently+"/>
2129         <clix:listed-constant name="+http-moved-temporarily+"/>
2130         <clix:listed-constant name="+http-see-other+"/>
2131         <clix:listed-constant name="+http-not-modified+"/>
2132         <clix:listed-constant name="+http-use-proxy+"/>
2133         <clix:listed-constant name="+http-temporary-redirect+"/>
2134         <clix:listed-constant name="+http-bad-request+"/>
2135         <clix:listed-constant name="+http-authorization-required+"/>
2136         <clix:listed-constant name="+http-payment-required+"/>
2137         <clix:listed-constant name="+http-forbidden+"/>
2138         <clix:listed-constant name="+http-not-found+"/>
2139         <clix:listed-constant name="+http-method-not-allowed+"/>
2140         <clix:listed-constant name="+http-not-acceptable+"/>
2141         <clix:listed-constant name="+http-proxy-authentication-required+"/>
2142         <clix:listed-constant name="+http-request-time-out+"/>
2143         <clix:listed-constant name="+http-conflict+"/>
2144         <clix:listed-constant name="+http-gone+"/>
2145         <clix:listed-constant name="+http-length-required+"/>
2146         <clix:listed-constant name="+http-precondition-failed+"/>
2147         <clix:listed-constant name="+http-request-entity-too-large+"/>
2148         <clix:listed-constant name="+http-request-uri-too-large+"/>
2149         <clix:listed-constant name="+http-unsupported-media-type+"/>
2150         <clix:listed-constant name="+http-requested-range-not-satisfiable+"/>
2151         <clix:listed-constant name="+http-expectation-failed+"/>
2152         <clix:listed-constant name="+http-failed-dependency+"/>
2153         <clix:listed-constant name="+http-internal-server-error+"/>
2154         <clix:listed-constant name="+http-not-implemented+"/>
2155         <clix:listed-constant name="+http-bad-gateway+"/>
2156         <clix:listed-constant name="+http-service-unavailable+"/>
2157         <clix:listed-constant name="+http-gateway-time-out+"/>
2158         <clix:listed-constant name="+http-version-not-supported+"/>
2159         <clix:description>
2160           The values of these constants are 100, 101, 200, 201, 202,
2161           203, 204, 205, 206, 207, 300, 301, 302, 303, 304, 305, 307,
2162           400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411,
2163           412, 413, 414, 415, 416, 417, 424, 500, 501, 502, 503, 504,
2164           and 505. See <clix:ref>RETURN-CODE</clix:ref>.
2165         </clix:description>
2166       </clix:constants>
2167
2168       <clix:readers generic='true'>
2169         <clix:listed-reader generic='true' name='content-length'>
2170           <clix:lambda-list>reply
2171           </clix:lambda-list>
2172           <clix:returns>content-length
2173           </clix:returns>
2174         </clix:listed-reader>
2175
2176         <clix:listed-reader generic='true' name='content-type'>
2177           <clix:lambda-list>reply
2178           </clix:lambda-list>
2179           <clix:returns>content-type
2180           </clix:returns>
2181         </clix:listed-reader>
2182
2183         <clix:listed-reader generic='true' name='headers-out'>
2184           <clix:lambda-list>reply
2185           </clix:lambda-list>
2186           <clix:returns>headers-out
2187           </clix:returns>
2188         </clix:listed-reader>
2189
2190         <clix:description>
2191           These are various generic readers which are used
2192           to read information about a <clix:ref>REPLY</clix:ref> object.  If you are writing a
2193           <a href="#handlers">handler</a>, you should <em>not</em> use these readers but instead utilize the
2194           corresponding functions with an asterisk at the end of their name,
2195           also listed in this section.  These generic readers are only
2196           exported for users who want to create their own subclasses of
2197           <clix:ref>REPLY</clix:ref>.
2198         </clix:description>
2199       </clix:readers>
2200
2201       <clix:accessors generic='true'>
2202         <clix:listed-accessor generic='true' name='cookies-out'>
2203           <clix:lambda-list>reply
2204           </clix:lambda-list>
2205           <clix:returns>result
2206           </clix:returns>
2207         </clix:listed-accessor>
2208
2209         <clix:listed-accessor generic='true' name='return-code'>
2210           <clix:lambda-list>reply
2211           </clix:lambda-list>
2212           <clix:returns>result
2213           </clix:returns>
2214         </clix:listed-accessor>
2215
2216         <clix:listed-accessor generic='true' name='reply-external-format'>
2217           <clix:lambda-list>reply
2218           </clix:lambda-list>
2219           <clix:returns>result
2220           </clix:returns>
2221         </clix:listed-accessor>
2222
2223         <clix:description>
2224           These are various generic accessors which are
2225           used to query and modify a <clix:ref>REPLY</clix:ref> objects.  If
2226           you are writing a
2227           <a href="#handlers">handler</a>, you should <em>not</em> use these
2228           accessors but instead utilize the corresponding functions with an
2229           asterisk at the end of their name, also listed in this section.
2230           These generic accessors are only exported for users who want to
2231           create their own subclasses of
2232           <clix:ref>REPLY</clix:ref>.
2233         </clix:description>
2234       </clix:accessors>
2235
2236
2237     </clix:subchapter>
2238
2239     <clix:subchapter name="sessions" title="Sessions">
2240       Hunchentoot supports <em>sessions</em>: Once a <a href="#handlers">request
2241       handler</a> has called <clix:ref>START-SESSION</clix:ref>, Hunchentoot
2242       uses either cookies or (if the client doesn't send the cookies
2243       back) <a href="#*rewrite-for-session-urls*">rewrites URLs</a> to keep
2244       track of this client, i.e. to provide a kind of 'state' for the
2245       stateless http protocol. The session associated with the client is a
2246       <a href="#session">CLOS object</a> which can be used
2247       to <a href="#session-value">store arbitrary data</a> between requests.
2248       <p>
2249         Hunchentoot makes some reasonable effort to prevent eavesdroppers from
2250         hijacking sessions (see below), but this should not be considered
2251         really secure. Don't store sensitive data in sessions and rely solely
2252         on the session mechanism as a safeguard against malicious users who
2253         want to get at this data!
2254       </p>
2255       <p>
2256         For each request there's one <clix:ref>SESSION</clix:ref> object which is accessible to the
2257         <a href="#handler">handler</a> via the special
2258         variable <clix:ref>*SESSION*</clix:ref>. This object holds all the
2259         information available about the session and can be accessed with the
2260         functions described in this chapter. Note that the internal structure
2261         of <clix:ref>SESSION</clix:ref> objects should be considered opaque
2262         and may change in future releases of Hunchentoot.
2263       </p>
2264       <p>
2265         Sessions are automatically <a href="#session-verify">verified</a> for
2266         validity and age when the <clix:ref>REQUEST</clix:ref> object is
2267         instantiated, i.e. if <clix:ref>*SESSION*</clix:ref> is not NIL then
2268         this session is valid (as far as Hunchentoot is concerned) and
2269         not <a href="#session-too-old-p">too old</a>.  Old sessions
2270         are <a href="#session-gc">automatically removed</a>.
2271       </p>
2272
2273       <clix:class name='session'>
2274         <clix:description>
2275           <clix:ref>SESSION</clix:ref> objects are
2276           automatically maintained by Hunchentoot.  They should not be created
2277           explicitly with <code>MAKE-INSTANCE</code> but implicitly
2278           with <clix:ref>START-SESSION</clix:ref> and they should be treated as
2279           opaque objects.
2280           <p>
2281             You can ignore Hunchentoot's <clix:ref>SESSION</clix:ref> objects and
2282             <a href="#session-behaviour">implement your own sessions</a> if you provide corresponding methods for
2283             <clix:ref>SESSION-COOKIE-VALUE</clix:ref>
2284             and <clix:ref>SESSION-VERIFY</clix:ref>.
2285           </p>
2286         </clix:description>
2287       </clix:class>
2288
2289       <clix:function name='start-session'>
2290         <clix:lambda-list>
2291         </clix:lambda-list>
2292         <clix:returns>session
2293         </clix:returns>
2294         <clix:description>
2295           Returns the current <clix:ref>SESSION</clix:ref>
2296           object. If there is no current session, creates one and updates the
2297           corresponding data structures. In this case the function will also
2298           send a session cookie to the browser.
2299         </clix:description>
2300       </clix:function>
2301
2302       <clix:accessor name='session-value'>
2303         <clix:lambda-list>symbol
2304         <clix:lkw>optional
2305         </clix:lkw> session
2306         </clix:lambda-list>
2307         <clix:returns>value, present-p
2308         </clix:returns>
2309         <clix:description>
2310           This accessor can be used to associate arbitrary data with the the
2311           symbol <clix:arg>symbol</clix:arg> in the <clix:ref>SESSION</clix:ref>
2312           object <clix:arg>session</clix:arg>. <clix:arg>present-p</clix:arg> is
2313           true if such data was found, otherwise <code>NIL</code>. The default
2314           value for <clix:arg>session</clix:arg> is
2315           <clix:ref>*SESSION*</clix:ref>.
2316           <p>
2317             If <code>SETF</code> of <clix:ref>SESSION-VALUE</clix:ref> is called
2318             with <clix:arg>session</clix:arg> being <code>NIL</code> then a
2319             session is automatically instantiated
2320             with <clix:ref>START-SESSION</clix:ref>.
2321           </p>
2322         </clix:description>
2323       </clix:accessor>
2324
2325       <clix:function name='delete-session-value'>
2326         <clix:lambda-list>symbol
2327         <clix:lkw>optional
2328         </clix:lkw> session
2329         </clix:lambda-list>
2330         <clix:returns>|
2331         </clix:returns>
2332         <clix:description>
2333           Removes the value associated with
2334           <clix:arg>symbol</clix:arg> from
2335           <clix:arg>session</clix:arg> if there is one.
2336         </clix:description>
2337       </clix:function>
2338
2339       <clix:special-variable name='*session*'>
2340         <clix:description>
2341           The current session while in the context of a request, or
2342           <code>NIL</code>.
2343         </clix:description>
2344       </clix:special-variable>
2345
2346       <clix:function name='remove-session'>
2347         <clix:lambda-list>session
2348         </clix:lambda-list>
2349         <clix:returns>|
2350         </clix:returns>
2351         <clix:description>
2352           Completely removes the <clix:ref>SESSION</clix:ref> object
2353           <clix:arg>session</clix:arg> from Hunchentoot&#039;s
2354           internal <a href="#session-db">session database</a>.
2355         </clix:description>
2356       </clix:function>
2357
2358       <clix:function name='reset-sessions'>
2359         <clix:lambda-list>
2360           <clix:lkw>optional
2361           </clix:lkw> acceptor
2362         </clix:lambda-list>
2363         <clix:returns>|
2364         </clix:returns>
2365         <clix:description>
2366           Removes <em>all</em> stored sessions of
2367           <clix:arg>acceptor</clix:arg>.  The default for
2368           <clix:arg>acceptor</clix:arg> is
2369           <clix:ref>*ACCEPTOR*</clix:ref>.
2370         </clix:description>
2371       </clix:function>
2372
2373       <clix:special-variable name='*rewrite-for-session-urls*'>
2374         <clix:description>
2375           Whether HTML pages should possibly be rewritten for cookie-less
2376           session-management.
2377         </clix:description>
2378       </clix:special-variable>
2379
2380       <clix:special-variable name='*content-types-for-url-rewrite*'>
2381         <clix:description>
2382           The content types for which url-rewriting is OK. See
2383           <clix:ref>*REWRITE-FOR-SESSION-URLS*</clix:ref>.
2384         </clix:description>
2385       </clix:special-variable>
2386
2387       <clix:special-variable name='*use-remote-addr-for-sessions*'>
2388         <clix:description>
2389           Whether the client&#039;s remote IP (as returned by <clix:ref>REAL-REMOTE-ADDR</clix:ref>)
2390           should be encoded into the session string.  If this value is true, a
2391           session will cease to be accessible if the client&#039;s remote IP changes.
2392           <p>
2393             This might for example be an issue if the client uses a proxy server
2394             which doesn&#039;t send correct &#039;X_FORWARDED_FOR&#039; headers.
2395           </p>
2396         </clix:description>
2397       </clix:special-variable>
2398
2399       <clix:function generic='true' name='session-remote-addr'>
2400         <clix:lambda-list>session
2401         </clix:lambda-list>
2402         <clix:returns>remote-addr
2403         </clix:returns>
2404         <clix:description>
2405           The remote IP address of the client when this session was started (as
2406           returned by <clix:ref>REAL-REMOTE-ADDR</clix:ref>).
2407         </clix:description>
2408       </clix:function>
2409
2410       <clix:special-variable name='*use-user-agent-for-sessions*'>
2411         <clix:description>Whether the &#039;User-Agent&#039; header should
2412         be encoded into the session string.  If this value is true, a session
2413         will cease to be accessible if the client sends a different
2414         &#039;User-Agent&#039; header.
2415         </clix:description>
2416       </clix:special-variable>
2417
2418       <clix:function generic='true' name='session-user-agent'>
2419         <clix:lambda-list>session
2420         </clix:lambda-list>
2421         <clix:returns>user-agent
2422         </clix:returns>
2423         <clix:description>
2424           The incoming &#039;User-Agent&#039; header that
2425           was sent when this session was created.
2426         </clix:description>
2427       </clix:function>
2428
2429       <clix:accessor generic='true' name='session-max-time'>
2430         <clix:lambda-list>session
2431         </clix:lambda-list>
2432         <clix:returns>max-time
2433         </clix:returns>
2434         <clix:description>
2435           Gets or sets the time (in seconds) after
2436           which <clix:arg>session</clix:arg> expires if it's not used.
2437         </clix:description>
2438       </clix:accessor>
2439
2440
2441       <clix:special-variable name='*session-max-time*'>
2442         <clix:description>
2443           The default time (in seconds) after which a session times out.
2444         </clix:description>
2445       </clix:special-variable>
2446
2447       <clix:special-variable name='*session-gc-frequency*'>
2448         <clix:description>
2449           A session GC (see function <clix:ref>SESSION-GC</clix:ref>) will happen every
2450           <clix:ref>*SESSION-GC-FREQUENCY*</clix:ref> requests (counting only
2451           requests which create a new session) if this variable is
2452           not <code>NIL</code>.  See <clix:ref>SESSION-CREATED</clix:ref>.
2453         </clix:description>
2454       </clix:special-variable>
2455
2456       <clix:function name='session-gc'>
2457         <clix:lambda-list>
2458         </clix:lambda-list>
2459         <clix:returns>|
2460         </clix:returns>
2461         <clix:description>
2462           Removes sessions from the current session database which are
2463           too old - see <clix:ref>SESSION-TOO-OLD-P</clix:ref>.
2464         </clix:description>
2465       </clix:function>
2466
2467       <clix:function name='session-too-old-p'>
2468         <clix:lambda-list>session
2469         </clix:lambda-list>
2470         <clix:returns>generalized-boolean
2471         </clix:returns>
2472         <clix:description>
2473           Returns true if the <clix:ref>SESSION</clix:ref> object <clix:arg>session</clix:arg> has not been active in
2474           the last <code>(session-max-time session)</code> seconds.
2475         </clix:description>
2476       </clix:function>
2477
2478       <clix:special-variable name='*session-removal-hook*'>
2479         <clix:description>
2480           A function of one argument
2481           (a <clix:ref>SESSION</clix:ref> object) which is called whenever a
2482           session is <a href="#session-gc">garbage-collected</a>.
2483         </clix:description>
2484       </clix:special-variable>
2485
2486       <clix:function generic='true' name='session-id'>
2487         <clix:lambda-list>session
2488         </clix:lambda-list>
2489         <clix:returns>session-id
2490         </clix:returns>
2491         <clix:description>
2492           The unique ID (an INTEGER) of the session.
2493         </clix:description>
2494       </clix:function>
2495
2496       <clix:function generic='true' name='session-start'>
2497         <clix:lambda-list>session
2498         </clix:lambda-list>
2499         <clix:returns>universal-time
2500         </clix:returns>
2501         <clix:description>
2502           The time this session was started.
2503         </clix:description>
2504       </clix:function>
2505
2506
2507     </clix:subchapter>
2508
2509     <clix:subchapter name="session-behaviour" title="Customizing session behaviour">
2510
2511       For everyday session usage, you will probably just
2512       use <clix:ref>START-SESSION</clix:ref>,
2513       <clix:ref>SESSION-VALUE</clix:ref>,
2514       and maybe <clix:ref>DELETE-SESSION-VALUE</clix:ref>
2515       and <clix:ref>*SESSION*</clix:ref>.  However, there are two ways to
2516       customize the way Hunchentoot maintains sessions.
2517       <p>
2518         One way is to mostly leave the session mechanism intact but to tweak
2519         it a bit:
2520         <ul>
2521           <li>The publicly visible part of a session is encoded using a
2522           <a href="#*session-secret*">secret</a> which you can set yourself.</li>
2523           <li>And it is stored using a cookie (or GET
2524           parameter) <a href="#session-cookie-name">name</a> that you can
2525           override.</li>
2526           <li>Each session receives a <a href="#next-session-id">new ID</a> when
2527           it is created and you can implement a more robust way to do that.</li>
2528           <li>You can arrange to be called whenever a session
2529           is <a href="#session-created">created</a> to trigger some action.  You
2530           might also do this to invent your own
2531           session <a href="#session-gc">garbage collection</a>.</li>
2532           <li>By default, all sessions are stored in a global alist in memory.
2533           You can't change the alist part, but you can distribute your sessions
2534           over different <a href="#session-db">"databases"</a>.</li>
2535           <li>By default, every operation which modifies sessions or one of the
2536           session databases is guarded by a global lock, but you can arrange to
2537           <a href="#session-db-lock">provide</a> different locks for this.</li>
2538         </ul>
2539       </p>
2540       <p>
2541         The other way to customize Hunchentoot's sessions is to completely
2542         replace them.  This is actually pretty easy: Create your own class to
2543         store state (which doesn't have to and probably shouldn't inherit
2544         from <clix:ref>SESSION</clix:ref>) and implement methods for
2545         <clix:ref>SESSION-VERIFY</clix:ref>
2546         and <clix:ref>SESSION-COOKIE-VALUE</clix:ref> - that's it.
2547         Hunchentoot will continue to use cookies and/or to rewrite URLs to
2548         keep track of session state and it will store "the current session"
2549         (whatever that is in your implementation)
2550         in <clix:ref>*SESSION*</clix:ref>.  Everything else (like persisting
2551         sessions, GC, getting and setting values) you'll have to take care of
2552         yourself and the other session functions
2553         (like <clix:ref>START-SESSION</clix:ref> or
2554         <clix:ref>SESSION-VALUE</clix:ref>) won't work anymore.  (Almost)
2555         total freedom, but a lot of responsibility as well... :)
2556       </p>
2557
2558       <clix:special-variable name='*session-secret*'>
2559         <clix:description>
2560           A random ASCII string that&#039;s used to encode the public
2561           session data.  This variable is initially unbound and will
2562           be set (using <clix:ref>RESET-SESSION-SECRET</clix:ref>) the
2563           first time a session is created, if necessary.  You can
2564           prevent this from happening if you set the value yourself
2565           before starting <a href="#acceptors">acceptors</a>.
2566         </clix:description>
2567       </clix:special-variable>
2568
2569       <clix:function name='reset-session-secret'>
2570         <clix:lambda-list>
2571         </clix:lambda-list>
2572         <clix:returns>secret
2573         </clix:returns>
2574         <clix:description>
2575           Sets <clix:ref>*SESSION-SECRET*</clix:ref> to a
2576           new random value. All old sessions will cease to be valid.
2577         </clix:description>
2578       </clix:function>
2579
2580       <clix:function generic='true' name='session-cookie-name'>
2581         <clix:lambda-list>acceptor
2582         </clix:lambda-list>
2583         <clix:returns>name
2584         </clix:returns>
2585         <clix:description>
2586           Returns the name (a string) of the cookie (or
2587           the GET parameter) which is used to store a session on the client
2588           side.  The default is to use the
2589           string <code>&quot;hunchentoot-session&quot;</code>, but you can
2590           specialize this function if you want another name.
2591         </clix:description>
2592       </clix:function>
2593
2594       <clix:function generic='true' name='session-created'>
2595         <clix:lambda-list>acceptor new-session
2596         </clix:lambda-list>
2597         <clix:returns>result
2598         </clix:returns>
2599         <clix:description>
2600           This function is called whenever a new session
2601           has been created.  There&#039;s a default method which might trigger
2602           a <a href="#session-gc">session GC</a> based on the value of
2603           <clix:ref>*SESSION-GC-FREQUENCY*</clix:ref>.
2604           <p>
2605             The return value is ignored.
2606           </p>
2607         </clix:description>
2608       </clix:function>
2609
2610       <clix:function generic='true' name='next-session-id'>
2611         <clix:lambda-list>acceptor
2612         </clix:lambda-list>
2613         <clix:returns>id
2614         </clix:returns>
2615         <clix:description>
2616           Returns the next sequential session ID, an
2617           integer, which should be unique per session.  The default method uses
2618           a simple global counter and isn&#039;t guarded by a lock.  For a
2619           high-performance production environment you might consider using a
2620           more robust implementation.
2621         </clix:description>
2622       </clix:function>
2623
2624       <clix:accessor generic='true' name='session-db'>
2625         <clix:lambda-list>acceptor
2626         </clix:lambda-list>
2627         <clix:returns>database
2628         </clix:returns>
2629         <clix:description>
2630           Returns the current session database which is an
2631           alist where each car is a session&#039;s ID and the cdr is the
2632           corresponding <clix:ref>SESSION</clix:ref> object itself.  The default
2633           is to use a global list for all acceptors.
2634         </clix:description>
2635       </clix:accessor>
2636
2637       <clix:function generic='true' name='session-db-lock'>
2638         <clix:lambda-list>acceptor
2639         <clix:lkw>key
2640         </clix:lkw> whole-db-p
2641         </clix:lambda-list>
2642         <clix:returns>lock
2643         </clix:returns>
2644         <clix:description>
2645           A function which returns a lock that will be
2646           used to prevent concurrent access to sessions.  The first argument
2647           will be the <a href="#acceptors">acceptor</a> that handles the
2648           current <a href="#requests">request</a>, the second argument is true
2649           if the whole (current) session database is modified.  If it
2650           is <code>NIL</code>, only one existing session in the database is
2651           modified.
2652           <p>
2653             This function can return <code>NIL</code> which means that sessions or
2654             session databases will be modified without a lock held (for example
2655             for single-threaded environments).  The default is to always return a
2656             global lock (ignoring the <clix:arg>acceptor</clix:arg> argument) for
2657             Lisps that support threads and <code>NIL</code> otherwise.
2658           </p>
2659         </clix:description>
2660       </clix:function>
2661
2662       <clix:function generic='true' name='session-verify'>
2663         <clix:lambda-list>request
2664         </clix:lambda-list>
2665         <clix:returns>session-or-nil
2666         </clix:returns>
2667         <clix:description>
2668           Tries to get a session identifier from the cookies
2669           (or alternatively from the GET parameters) sent by the client (see
2670           <clix:ref>SESSION-COOKIE-NAME</clix:ref>
2671           and <clix:ref>SESSION-COOKIE-VALUE</clix:ref>).  This identifier is
2672           then checked for validity against the <clix:ref>REQUEST</clix:ref>
2673           object
2674           <clix:arg>request</clix:arg>.  On success the corresponding session object (if not too
2675           old) is returned (and updated).  Otherwise <code>NIL</code> is returned.
2676           <p>
2677             A default method is provided and you only need to write your own one
2678             if you want to maintain your own sessions.
2679           </p>
2680         </clix:description>
2681       </clix:function>
2682
2683       <clix:function generic='true' name='session-cookie-value'>
2684         <clix:lambda-list>session
2685         </clix:lambda-list>
2686         <clix:returns>string
2687         </clix:returns>
2688         <clix:description>
2689           Returns a string which can be used to safely
2690           restore the session <clix:arg>session</clix:arg> if as session has
2691           already been established.  This is used as the value stored in the
2692           session cookie or in the corresponding GET parameter and verified
2693           by <clix:ref>SESSION-VERIFY</clix:ref>.
2694           <p>
2695             A default
2696             method is provided and there&#039;s no reason to change it unless you
2697             want to use your own session objects.
2698           </p>
2699         </clix:description>
2700       </clix:function>
2701
2702     </clix:subchapter>
2703
2704     <clix:subchapter name="cookies" title="Cookies">
2705
2706       Outgoing cookies are stored in the request's <clix:ref>REPLY</clix:ref>
2707       object (see <clix:ref>COOKIE-OUT</clix:ref>
2708       and <clix:ref>COOKIES-OUT*</clix:ref>). They are CLOS objects
2709       defined like this:
2710
2711       <pre>(defclass cookie ()
2712   ((name :initarg :name
2713          :reader <a class="noborder" name="cookie-name">cookie-name</a>
2714          :type string
2715          :documentation "The name of the cookie - a string.")
2716    (value :initarg :value
2717           :accessor <a class="noborder" name="cookie-value">cookie-value</a>
2718           :initform ""
2719           :documentation "The value of the cookie. Will be URL-encoded when sent to the browser.")
2720    (expires :initarg :expires
2721             :initform nil
2722             :accessor <a class="noborder" name="cookie-expires">cookie-expires</a>
2723             :documentation "The time (a universal time) when the cookie expires (or NIL).")
2724    (path :initarg :path
2725          :initform nil
2726          :accessor <a class="noborder" name="cookie-path">cookie-path</a>
2727          :documentation "The path this cookie is valid for (or NIL).")
2728    (domain :initarg :domain
2729            :initform nil
2730            :accessor <a class="noborder" name="cookie-domain">cookie-domain</a>
2731            :documentation "The domain this cookie is valid for (or NIL).")
2732    (secure :initarg :secure
2733            :initform nil
2734            :accessor <a class="noborder" name="cookie-secure">cookie-secure</a>
2735            :documentation "A generalized boolean denoting whether this is a secure cookie.")
2736    (http-only :initarg :http-only
2737               :initform nil
2738               :accessor <a class="noborder" name="cookie-http-only">cookie-http-only</a>
2739               :documentation "A generalized boolean denoting whether this is a <a href="http://msdn2.microsoft.com/en-us/library/ms533046.aspx">HttpOnly</a> cookie.")))
2740       </pre>
2741
2742       The <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_r.htm#reader">reader</a>
2743       <clix:ref>COOKIE-NAME</clix:ref> and
2744       the <a href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_a.htm#accessor">accessors</a>
2745       <clix:ref>COOKIE-VALUE</clix:ref>, <clix:ref>COOKIE-EXPIRES</clix:ref>,
2746       <clix:ref>COOKIE-PATH</clix:ref>, <clix:ref>COOKIE-DOMAIN</clix:ref>, <clix:ref>COOKIE-SECURE</clix:ref>,
2747       and <clix:ref>COOKIE-HTTP-ONLY</clix:ref> are all exported from
2748       the <code>HUNCHENTOOT</code> package.  For now, the class name itself is <em>not</em> exported.
2749
2750       <clix:function name="set-cookie">
2751         <clix:lambda-list>
2752           name <clix:lkw>key</clix:lkw> value expires path
2753           domain secure http-only reply
2754         </clix:lambda-list>
2755         <clix:returns>cookie</clix:returns>
2756         <clix:description>
2757           Creates a <code>COOKIE</code> object from the parameters
2758           provided to this function and adds it to the outgoing cookies
2759           of the <a href="#replies"><code>REPLY</code> object</a>
2760           <clix:arg>reply</clix:arg>. If a cookie with the same name
2761           (case-sensitive) already exists, it is replaced. The default
2762           for <clix:arg>reply</clix:arg>
2763           is <clix:ref>*REPLY*</clix:ref>. The default
2764           for <clix:arg>value</clix:arg> is the empty string.
2765         </clix:description>
2766       </clix:function>
2767
2768       <clix:function name="set-cookie*">
2769         <clix:lambda-list>cookie <clix:lkw>optional</clix:lkw> reply</clix:lambda-list>
2770         <clix:returns>cookie</clix:returns>
2771         <clix:description>
2772           Adds the <code>COOKIE</code> object <clix:arg>cookie</clix:arg>
2773           to the outgoing cookies of
2774           the <a href="#replies"><code>REPLY</code> object</a>
2775           <clix:arg>reply</clix:arg>. If a cookie with the same name
2776           (case-sensitive) already exists, it is replaced. The default
2777           for <clix:arg>reply</clix:arg> is <clix:ref>*REPLY*</clix:ref>.
2778         </clix:description>
2779       </clix:function>
2780     </clix:subchapter>
2781
2782     <clix:subchapter name="logging" title="Logging">
2783       Hunchentoot can log accesses and diagnostic messages to two
2784       separate destinations, which can be either files in the file
2785       system or streams.  Logging can also be disabled by setting the
2786       <clix:code>ACCESS-LOG-DESTINATION</clix:code> and
2787       <clix:code>MESSAGE-LOG-DESTINATION</clix:code> slots in the
2788       <clix:ref>ACCEPTOR</clix:ref> instance of the running server,
2789       either by providing the :ACCESS-LOG-DESTINATION and
2790       :MESSAGE-LOG-DESTINATION initialization arguments when creating the
2791       acceptor or by setting the slots through its
2792       <clix:ref>ACCEPTOR-MESSAGE-LOG-DESTINATION</clix:ref> and
2793       <clix:ref>ACCEPTOR-ACCESS-LOG-DESTINATION</clix:ref> accessors.
2794       <p>
2795         When the path for the message or accept log is set to a
2796         variable holding an output stream, hunchentoots writes
2797         corresponding log entries to that stream.  By default,
2798         Hunchentoot logs to *STANDARD-ERROR*.
2799       </p>
2800       <p>
2801         Access logging is done in a format similar to what
2802         the Apache web server can write so that logfile analysis using
2803         standard tools is possible.  Errors during request processing are
2804         logged to a separate file.
2805       </p>
2806       <p>
2807         The standard logging mechanism is deliberately simple and slow.  The
2808         log files are opened for each log entry and closed again after
2809         writing, and access to them is protected by a global lock.  Derived
2810         acceptor classes can implement methods for the
2811         <clix:ref>ACCEPTOR-LOG-MESSAGE</clix:ref> and
2812         <clix:ref>ACCEPTOR-LOG-ACCESS</clix:ref> generic functions in order to
2813         log differently (e.g. to a central logging server or in a different
2814         file format.
2815       </p>
2816       <p>
2817         Errors happening within a <a href="#handlers">handler</a>
2818         which are not caught by the handler itself are handled by
2819         Hunchentoot by logging them to the established
2820         <clix:ref>ACCEPTOR-MESSAGE-LOG-DESTINATION</clix:ref>.
2821       </p>
2822
2823       <clix:function name='log-message*'>
2824         <clix:lambda-list>log-level format-string
2825         <clix:lkw>rest
2826         </clix:lkw> format-arguments
2827         </clix:lambda-list>
2828         <clix:returns>result
2829         </clix:returns>
2830         <clix:description>
2831           Convenience function which calls the message
2832           logger of the current acceptor (if there is one) with the same
2833           arguments it accepts.  Returns <code>NIL</code> if there is no message
2834           logger or whatever the message logger returns.
2835           <p>
2836             This is the function which Hunchentoot itself uses to log errors it
2837             catches during request processing.
2838           </p>
2839         </clix:description>
2840       </clix:function>
2841
2842       <clix:special-variable name='*log-lisp-errors-p*'>
2843         <clix:description>
2844           Whether Lisp errors in request handlers should be logged.
2845         </clix:description>
2846       </clix:special-variable>
2847
2848       <clix:special-variable name='*log-lisp-backtraces-p*'>
2849         <clix:description>
2850           Whether Lisp backtraces should be logged.  Only
2851           has an effect if <clix:ref>*LOG-LISP-ERRORS-P*</clix:ref> is true
2852           as well.
2853         </clix:description>
2854       </clix:special-variable>
2855
2856       <clix:special-variable name='*log-lisp-warnings-p*'>
2857         <clix:description>
2858           Whether Lisp warnings in request handlers should be logged.
2859         </clix:description>
2860       </clix:special-variable>
2861
2862       <clix:special-variable name='*lisp-errors-log-level*'>
2863         <clix:description>
2864           Log level for Lisp errors.  Should be one
2865           of <code>:ERROR</code> (the default), <code>:WARNING</code>,
2866           or <code>:INFO</code>.
2867         </clix:description>
2868       </clix:special-variable>
2869
2870       <clix:special-variable name='*lisp-warnings-log-level*'>
2871         <clix:description>
2872           Log level for Lisp warnings.
2873           Should be one of <code>:ERROR</code>, <code>:WARNING</code>
2874           (the default), or <code>:INFO</code>.
2875         </clix:description>
2876       </clix:special-variable>
2877     </clix:subchapter>
2878
2879     <clix:subchapter name="conditions" title="Conditions and error handling">
2880       <p>
2881         This section describes how Hunchentoot deals with exceptional
2882         situations.  See also the secion about <a href="#logging">logging</a>.
2883       </p>
2884       <p>
2885         When an error occurs while processing a request, Hunchentoot's
2886         default behavior is to catch catch the error, log it and
2887         optionally display it to the client in the HTML response.
2888         This behavior can be customized through the values of a number
2889         of special variables, which are documented below.
2890       </p>
2891
2892       <clix:special-variable name='*catch-errors-p*'>
2893         <clix:description>
2894           If the value of this variable is <code>NIL</code>
2895           (the default is <code>T</code>), then errors which happen while a
2896           request is handled aren't <a href="#logging">caught as usual</a>, but
2897           instead your
2898           Lisp's <a
2899           href="http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_d.htm#debugger">debugger</a>
2900           is <a
2901           href="http://www.lispworks.com/documentation/HyperSpec/Body/f_invoke.htm">invoked</a>.
2902           This variable should obviously always be set to a <em>true</em> value
2903           in a production environment.
2904           See <clix:ref>MAYBE-INVOKE-DEBUGGER</clix:ref>
2905           if you want to fine-tune this behaviour.
2906         </clix:description>
2907       </clix:special-variable>
2908
2909       <clix:special-variable name='*show-lisp-errors-p*'>
2910         <clix:description>
2911           Whether Lisp errors should be shown in HTML output.  Note
2912           that this only affects canned responses generated by Lisp.
2913           If an error template is present for the "internal server
2914           error" status code, this special variable is not used (see
2915           <clix:ref>acceptor-status-message</clix:ref>).
2916         </clix:description>
2917       </clix:special-variable>
2918
2919       <clix:special-variable name='*show-lisp-backtraces-p*'>
2920         <clix:description>
2921           Whether Lisp backtraces should be shown in HTML output if
2922           <clix:ref>*SHOW-LISP-ERRORS-P*</clix:ref> is true and an error occurs.
2923         </clix:description>
2924       </clix:special-variable>
2925
2926       <clix:function generic='true' name='maybe-invoke-debugger'>
2927         <clix:lambda-list>condition
2928         </clix:lambda-list>
2929         <clix:returns>|
2930         </clix:returns>
2931         <clix:description>
2932           This generic function is called whenever a
2933           <a
2934               href="http://www.lispworks.com/documentation/HyperSpec/Body/09_.htm">condition</a> <code><i>condition</i></code>
2935           is signaled in Hunchentoot.  You might want to specialize it on
2936           specific condition classes for debugging purposes.  The default
2937           method <a
2938           href="http://www.lispworks.com/documentation/HyperSpec/Body/f_invoke.htm">invokes
2939           the debugger</a> with <clix:arg>condition</clix:arg> if
2940           <clix:ref>*CATCH-ERRORS-P*</clix:ref> is <code>NIL</code>.
2941         </clix:description>
2942       </clix:function>
2943
2944       <clix:condition name='hunchentoot-condition'>
2945         <clix:description>
2946           Superclass for all conditions related to Hunchentoot.
2947         </clix:description>
2948       </clix:condition>
2949
2950       <clix:condition name='hunchentoot-error'>
2951         <clix:description>
2952           Superclass for all errors related to Hunchentoot and a subclass of <clix:ref>HUNCHENTOOT-CONDITION</clix:ref>.
2953         </clix:description>
2954       </clix:condition>
2955
2956       <clix:condition name='parameter-error'>
2957         <clix:description>
2958           Signalled if a function was called with incosistent or illegal parameters.  A subclass of <clix:ref>HUNCHENTOOT-ERROR</clix:ref>.
2959         </clix:description>
2960       </clix:condition>
2961
2962       <clix:condition name='hunchentoot-warning'>
2963         <clix:description>
2964           Superclass for all warnings related to Hunchentoot and a subclass of <clix:ref>HUNCHENTOOT-CONDITION</clix:ref>.
2965         </clix:description>
2966       </clix:condition>
2967
2968     </clix:subchapter>
2969
2970     <clix:subchapter name="misc" title="Miscellaneous">
2971
2972       Various functions and variables which didn't fit into one of the
2973       other categories.
2974
2975       <clix:function name='abort-request-handler'>
2976         <clix:lambda-list>
2977           <clix:lkw>optional
2978           </clix:lkw> result
2979         </clix:lambda-list>
2980         <clix:returns>result
2981         </clix:returns>
2982         <clix:description>
2983           This function can be called by a request handler
2984           at any time to immediately abort handling the request.  This works as
2985           if the handler had returned <clix:arg>result</clix:arg>.  See the
2986           source code of <clix:ref>REDIRECT</clix:ref> for an example.
2987         </clix:description>
2988       </clix:function>
2989
2990       <clix:function name="handle-if-modified-since">
2991         <clix:lambda-list>time <clix:lkw>optional</clix:lkw> request</clix:lambda-list>
2992         <clix:returns>|</clix:returns>
2993         <clix:description>
2994           This function is designed to be used inside
2995           a <a href="#handlers">handler</a>. If the client has sent an
2996           'If-Modified-Since' header
2997           (see <a href="http://www.faqs.org/rfcs/rfc2616.html">RFC 2616</a>,
2998           section 14.25) and the time specified matches the universal
2999           time
3000           <clix:arg>time</clix:arg> then the
3001           header <clix:ref>+HTTP-NOT-MODIFIED+</clix:ref> with no content
3002           is immediately returned to the client.
3003           <p>
3004             Note that for this function to be useful you should usually
3005             send 'Last-Modified' headers back to the client. See the
3006             code
3007             of <clix:ref>CREATE-STATIC-FILE-DISPATCHER-AND-HANDLER</clix:ref>
3008             for an example.
3009           </p>
3010         </clix:description>
3011       </clix:function>
3012
3013       <clix:function name="handle-static-file">
3014         <clix:lambda-list>path <clix:lkw>optional</clix:lkw> content-type</clix:lambda-list>
3015         <clix:returns>nil</clix:returns>
3016         <clix:description>
3017           Sends the file denoted by the pathname designator
3018           <clix:arg>path</clix:arg> with content type
3019           <clix:arg>content-type</clix:arg> to the client.  Sets the
3020           necessary handlers.  In particular the function employs
3021           <clix:ref>HANDLE-IF-MODIFIED-SINCE</clix:ref>.
3022           <p>
3023             If <clix:arg>content-type</clix:arg> is <code>NIL</code> the
3024             function tries to determine the correct content type from
3025             the file's suffix or falls back
3026             to <code>"application/octet-stream"</code> as a last resort.
3027           </p>
3028           <p>
3029             Note that this function
3030             calls <clix:ref>SEND-HEADERS</clix:ref> internally, so after
3031             you've called it, the headers are sent and the return value
3032             of your handler is ignored.
3033           </p>
3034         </clix:description>
3035       </clix:function>
3036
3037       <clix:function name="redirect">
3038         <clix:lambda-list>target <clix:lkw>key</clix:lkw> host port protocol add-session-id code</clix:lambda-list>
3039         <clix:returns>|</clix:returns>
3040         <clix:description>
3041           Sends back appropriate headers to redirect the client
3042           to <clix:arg>target</clix:arg> (a string).
3043           <p>
3044             If <clix:arg>target</clix:arg> is a full URL starting with a
3045             scheme, <clix:arg>host</clix:arg>, <clix:arg>port</clix:arg>,
3046             and <clix:arg>protocol</clix:arg> are ignored.
3047             Otherwise, <clix:arg>target</clix:arg> should denote the path
3048             part of a URL, <clix:arg>protocol</clix:arg> must be one of
3049             the keywords <code>:HTTP</code> or <code>:HTTPS</code>, and
3050             the URL to redirect to will be constructed
3051             from <clix:arg>host</clix:arg>, <clix:arg>port</clix:arg>, <clix:arg>protocol</clix:arg>,
3052             and <clix:arg>target</clix:arg>.
3053           </p>
3054           <p>
3055             If <clix:arg>code</clix:arg> is a 3xx redirection code, it
3056             will be sent as status code.  In case of <code>NIL</code>, a
3057             302 status code will be sent to the client.
3058             If <clix:arg>host</clix:arg> is not provided, the current host
3059             (see <clix:ref>HOST</clix:ref>) will be
3060             used. If <clix:arg>protocol</clix:arg> is the
3061             keyword <code>:HTTPS</code>, the client will be redirected
3062             to a https URL, if it's <code>:HTTP</code> it'll be sent to
3063             a http URL.  If both <clix:arg>host</clix:arg>
3064             and <clix:arg>protocol</clix:arg> aren't provided, then the
3065             value of <clix:arg>protocol</clix:arg> will match the current
3066             request.
3067           </p>
3068         </clix:description>
3069       </clix:function>
3070
3071       <clix:function name="require-authorization">
3072         <clix:lambda-list><clix:lkw>optional</clix:lkw> realm</clix:lambda-list>
3073         <clix:returns>|</clix:returns>
3074         <clix:description>
3075           Sends back appropriate headers to require basic HTTP
3076           authentication
3077           (see <a href="http://www.faqs.org/rfcs/rfc2617.html">RFC 2617</a>)
3078           for the realm <clix:arg>realm</clix:arg>. The default value
3079           for <clix:arg>realm</clix:arg> is <code>"Hunchentoot"</code>.
3080         </clix:description>
3081       </clix:function>
3082
3083       <clix:function name='no-cache'>
3084         <clix:lambda-list>
3085         </clix:lambda-list>
3086         <clix:returns>|
3087         </clix:returns>
3088         <clix:description>
3089           Adds appropriate headers to completely prevent caching on most browsers.
3090         </clix:description>
3091       </clix:function>
3092
3093       <clix:function name='ssl-p'>
3094         <clix:lambda-list>
3095           <clix:lkw>optional
3096           </clix:lkw> acceptor
3097         </clix:lambda-list>
3098         <clix:returns>generalized-boolean
3099         </clix:returns>
3100         <clix:description>
3101           Whether the current connection to the client is secure.  See <clix:ref>ACCEPTOR-SSL-P</clix:ref>.
3102         </clix:description>
3103       </clix:function>
3104
3105       <clix:function name='reason-phrase'>
3106         <clix:lambda-list>return-code
3107         </clix:lambda-list>
3108         <clix:returns>string
3109         </clix:returns>
3110         <clix:description>
3111           Returns a reason phrase for the HTTP return code <clix:arg>return-code</clix:arg>
3112           (which should be an integer) or <code>NIL</code> for return codes Hunchentoot
3113           doesn&#039;t know.
3114         </clix:description>
3115       </clix:function>
3116
3117       <clix:function name='rfc-1123-date'>
3118         <clix:lambda-list>
3119           <clix:lkw>optional
3120           </clix:lkw> time
3121         </clix:lambda-list>
3122         <clix:returns>string
3123         </clix:returns>
3124         <clix:description>
3125           Generates a time string according to <a href="http://www.faqs.org/rfcs/rfc1123.html">RFC 1123</a>.  Default is current time.
3126           This can be used to send a 'Last-Modified' header - see <clix:ref>HANDLE-IF-MODIFIED-SINCE</clix:ref>.
3127         </clix:description>
3128       </clix:function>
3129
3130       <clix:function name='url-encode'>
3131         <clix:lambda-list>string
3132         <clix:lkw>optional
3133         </clix:lkw> external-format
3134         </clix:lambda-list>
3135         <clix:returns>string
3136         </clix:returns>
3137         <clix:description>
3138           URL-encodes a string using the external format <clix:arg>external-format</clix:arg>.  The default for <clix:arg>external-format</clix:arg> is the value of <clix:ref>*HUNCHENTOOT-DEFAULT-EXTERNAL-FORMAT*</clix:ref>.
3139         </clix:description>
3140       </clix:function>
3141
3142       <clix:function name='url-decode'>
3143         <clix:lambda-list>string
3144         <clix:lkw>optional
3145         </clix:lkw> external-format
3146         </clix:lambda-list>
3147         <clix:returns>string
3148         </clix:returns>
3149         <clix:description>
3150           Decodes a URL-encoded string which is assumed to
3151           be encoded using the external
3152           format <clix:arg>external-format</clix:arg>, i.e. this is the inverse
3153           of <clix:ref>URL-ENCODE</clix:ref>. It is assumed that you'll rarely
3154           need this function, if ever. But just in case - here it is.  The
3155           default for <clix:arg>external-format</clix:arg> is the value
3156           of <clix:ref>*HUNCHENTOOT-DEFAULT-EXTERNAL-FORMAT*</clix:ref>.
3157         </clix:description>
3158       </clix:function>
3159
3160       <clix:function name='escape-for-html'>
3161         <clix:lambda-list>string
3162         </clix:lambda-list>
3163         <clix:returns>result
3164         </clix:returns>
3165         <clix:description>
3166           Escapes the characters #\&lt;, #\&gt;, #\&#039;, #\&quot;, and #\&amp; for HTML output.
3167         </clix:description>
3168       </clix:function>
3169
3170       <clix:function name="http-token-p">
3171         <clix:lambda-list>object</clix:lambda-list>
3172         <clix:returns>generalized-boolean</clix:returns>
3173         <clix:description>
3174           This function tests whether <clix:arg>object</clix:arg> is a
3175           non-empty string which is a <em>token</em> according
3176           to <a href="http://www.faqs.org/rfcs/rfc2068.html">RFC
3177           2068</a> (i.e. whether it may be used for, say, cookie names).
3178         </clix:description>
3179       </clix:function>
3180
3181       <clix:function name='mime-type'>
3182         <clix:lambda-list>pathspec
3183         </clix:lambda-list>
3184         <clix:returns>result
3185         </clix:returns>
3186         <clix:description>
3187           Given a pathname designator <clix:arg>pathspec</clix:arg> returns the <a href="http://en.wikipedia.org/wiki/Internet_media_type">MIME type</a>
3188           (as a string) corresponding to the suffix of the file denoted by
3189           <clix:arg>pathspec</clix:arg> (or <code>NIL</code>).
3190         </clix:description>
3191       </clix:function>
3192
3193       <clix:function name='within-request-p'>
3194         <clix:lambda-list>
3195         </clix:lambda-list>
3196         <clix:returns>generalized-boolean
3197         </clix:returns>
3198         <clix:description>
3199           Returns true if in the context of a request. Otherwise, <code>NIL</code>.
3200         </clix:description>
3201       </clix:function>
3202
3203       <clix:special-variable name="*tmp-directory*">
3204         <clix:description>
3205           This should be a pathname denoting a directory where temporary
3206           files can be stored. It is used for <a href="#upload">file
3207           uploads</a>.
3208         </clix:description>
3209       </clix:special-variable>
3210
3211       <clix:special-variable name='*header-stream*'>
3212         <clix:description>
3213           If this variable is not <code>NIL</code>, it should be bound to a stream to
3214           which incoming and outgoing headers will be written for debugging
3215           purposes.
3216         </clix:description>
3217       </clix:special-variable>
3218
3219
3220       <clix:special-variable name='*cleanup-function*'>
3221         <clix:description>
3222           A designator for a function without arguments which is called on a
3223           regular basis if <clix:ref>*CLEANUP-INTERVAL*</clix:ref> is not <code>NIL</code>.  The initial value is
3224           the name of a function which invokes a garbage collection on 32-bit
3225           versions of LispWorks.
3226           <p>
3227             This variable is only available on LispWorks.
3228           </p>
3229         </clix:description>
3230       </clix:special-variable>
3231
3232       <clix:special-variable name='*cleanup-interval*'>
3233         <clix:description>
3234           Should be <code>NIL</code> or a positive integer.  The system calls
3235           <clix:ref>*CLEANUP-FUNCTION*</clix:ref>
3236           whenever <clix:ref>*CLEANUP-INTERVAL*</clix:ref> new worker threads
3237           (counted globally across all acceptors) have been created unless the
3238           value is <code>NIL</code>.  The initial value is 100.
3239           <p>
3240             This variable is only available on LispWorks.
3241           </p>
3242         </clix:description>
3243       </clix:special-variable>
3244     </clix:subchapter>
3245   </clix:chapter>
3246
3247   <clix:chapter name="testing" title="Testing">
3248     Hunchentoot comes with a test script which verifies that the
3249     example web server responds as expected.  This test script uses the
3250     <a href="http://weitz.de/drakma/">Drakma</a> HTTP client library
3251     and thus shares a significant amount of its base code with
3252     Hunchentoot itself.  Still, running the test script is a useful
3253     confidence test, and it is also possible to run the script across
3254     machines in order to verify a new Hunchentoot (or, for that matter
3255     Drakma) port.
3256     <p>
3257       To run the confidence test, <a href="#start">start
3258       the example web server</a>.  Then, in your Lisp
3259       listener, type
3260 <pre>(<a class="noborder" href="hunchentoot-test:test-hunchentoot">hunchentoot-test:test-hunchentoot</a> "http://localhost:4242")</pre>
3261 You will see some diagnostic output and a summary line that
3262 reports whether any tests have failed.  (You can also use the
3263 example certificate and key files in the test directory and
3264 start and test an https server instead.)
3265     </p>
3266
3267     <clix:function name="hunchentoot-test:test-hunchentoot">
3268       <clix:lambda-list>base-url <clix:lkw>key</clix:lkw></clix:lambda-list>
3269       <clix:returns>|</clix:returns>
3270       <clix:description>
3271         Runs the built-in confidence
3272         test.  <clix:arg>base-url</clix:arg> is the base URL to use
3273         for testing, it should not have a trailing slash.  The keyword
3274         arguments accepted are for future extension and should not
3275         currently be used.
3276         <p>
3277           The script expects the Hunchentoot example test server to be
3278           running at the given <clix:arg>base-url</clix:arg> and
3279           retrieves various pages from that server, expecting certain
3280           responses.
3281         </p>
3282       </clix:description>
3283     </clix:function>
3284   </clix:chapter>
3285
3286   <clix:chapter name="debugging" title="Debugging">
3287     By default, Hunchentoot intercepts all errors that occur while
3288     executing request handlers, logs them to the log file and displays
3289     a static error page to the user.  While developing applications,
3290     you may want to change that behavior so that the debugger is
3291     invoked when an error occurs.  You can set
3292     the <clix:ref>*CATCH-ERRORS-P*</clix:ref> to <code>NIL</code> to
3293     make that happen.  Alternatively, you may want to have Hunchentoot
3294     display detailed error information in the error response page.
3295     You can set the <clix:ref>*SHOW-LISP-ERRORS-P*</clix:ref> to a
3296     true value to make that happen.  If you don't want to see Lisp
3297     backtraces in these error pages, you can
3298     set <clix:ref>*SHOW-LISP-BACKTRACES-P*</clix:ref>
3299     to <code>NIL</code>.
3300   </clix:chapter>
3301
3302   <clix:chapter name="history" title="History">
3303
3304     Hunchentoot's predecessor <a href="http://weitz.de/tbnl/">TBNL</a>
3305     (which is short for "To Be Named Later") grew over the years as a
3306     toolkit that I used for various commercial and private
3307     projects. In August 2003, Daniel Barlow started
3308     a <a href="http://article.gmane.org/gmane.lisp.web/148">review of
3309       web APIs</a> on
3310     the <a href="http://www.red-bean.com/lispweb/">lispweb</a> mailing
3311     list and
3312     I <a href="http://article.gmane.org/gmane.lisp.web/153">described</a>
3313     the API of my hitherto-unreleased bunch of code (and christened it
3314     "TBNL").
3315     <p>
3316       It turned out that
3317       <a href="http://www.jeffcaldwell.com/">Jeff Caldwell</a> had
3318       worked on something similar so he emailed me and proposed to
3319       join our efforts. As I had no immediate plans to release my code
3320       (which was poorly organized, undocumented, and mostly
3321       CMUCL-specific), I gave it to Jeff and he worked towards a
3322       release. He added docstrings, refactored, added some stuff, and
3323       based it on KMRCL to make it portable across several Lisp
3324       implementations.
3325     </p>
3326     <p>
3327       Unfortunately, Jeff is at least as busy as I am so he didn't
3328       find the time to finish a full release.  But in spring 2004 I
3329       needed a documented version of the code for a client of mine who
3330       thought it would be good if the toolkit were publicly available
3331       under an open source license. So I took Jeff's code, refactored
3332       again (to sync with the changes I had done in the meantime), and
3333       added documentation.  This resulted in TBNL 0.1.0 (which
3334       initially required mod_lisp as its front-end).
3335     </p>
3336     <p>
3337       In March 2005, Bob Hutchinson sent patches which enabled TBNL to
3338       use other front-ends than mod_lisp.  This made me aware that
3339       TBNL was already <em>almost</em> a full web server, so
3340       eventually I wrote Hunchentoot which <em>was</em> a full web
3341       server, implemented as a wrapper around TBNL.  Hunchentoot 0.1.0
3342       was released at the end of 2005 and was originally
3343       LispWorks-only.
3344     </p>
3345     <p>
3346       Hunchentoot 0.4.0, released in October 2006, was the first
3347       release which also worked with other Common Lisp
3348       implementations.  It is a major rewrite and also incorporates
3349       most of TBNL and replaces it completely.
3350     </p>
3351     <p>
3352       Hunchentoot 1.0.0, released in February 2009, is again a major
3353       rewrite and should be considered work in progress.  It moved to
3354       using
3355       the <a href="http://common-lisp.net/project/usocket/">usocket</a>
3356       and <a href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux
3357       Threads</a> libraries for non-LispWorks Lisps, thereby removing most of
3358       the platform dependent code.  Threading behaviour was made
3359       controllable through the introduction of
3360       taskmasters.  <a href="http://www.cliki.net/mod_lisp">mod_lisp</a>
3361       support and several other things were removed in this release to
3362       simplify the code base (and partly due to the lack of interest).
3363       Several architectural changes (lots of them not
3364       backwards-compatible) were made to ease customization of
3365       Hunchentoot's behaviour.  A significant part of the 1.0.0
3366       redesign was done
3367       by <a href="http://netzhansa.blogspot.com/">Hans Hübner</a>.
3368     </p>
3369   </clix:chapter>
3370
3371   <clix:chapter name="index" title="Symbol index">
3372
3373     Here are all exported symbols of the <code>HUNCHENTOOT</code>
3374     package in alphabetical order linked to their corresponding
3375     documentation entries:
3376
3377     <clix:index/>
3378
3379   </clix:chapter>
3380
3381   <clix:chapter name="ack" title="Acknowledgements">
3382
3383     Thanks to Jeff Caldwell - TBNL would not have been released
3384     without his efforts.  Thanks
3385     to <a href="http://www.cliki.net/Stefan%20Scholl">Stefan
3386     Scholl</a> and Travis Cross for various additions and fixes to
3387     TBNL, to <a href="http://www.foldr.org/~michaelw/">Michael
3388     Weber</a> for initial file upload code, and
3389     to <a href="http://www.ltn.lv/~jonis/">Janis Dzerins</a> for
3390     his <a href="http://common-lisp.net/project/rfc2388/">RFC 2388
3391     code</a>. Thanks to Bob Hutchison for his code for multiple
3392     front-ends (which made me realize that TBNL was already pretty
3393     close to a "real" web server) and the initial UTF-8 example.
3394     Thanks to <a href="http://netzhansa.blogspot.com/">Hans Hübner</a>
3395     for a lot of architectural and implementation enhancements for the
3396     1.0.0 release and also for transferring the documentation to sane
3397     XHTML.  Thanks to John
3398     Foderaro's <a href="http://opensource.franz.com/aserve/index.html">AllegroServe</a>
3399     for inspiration.  Thanks to <a href="http://www.htg1.de/">Uwe von
3400     Loh</a> for
3401     the <a href="http://www.htg1.de/hunchentoot/hunchentoot.html">Hunchentoot
3402     logo</a>.
3403
3404     <p>
3405       Hunchentoot originally used code
3406       from <a href="http://www.cliki.net/ACL-COMPAT">ACL-COMPAT</a>,
3407       specifically the chunking code from Jochen Schmidt.  (This has been
3408       replaced by <a href="http://weitz.de/chunga/">Chunga</a>.)  When I ported
3409       Hunchentoot to other Lisps than LispWorks, I stole code from
3410       ACL-COMPAT, <a href="http://www.cliki.net/kmrcl">KMRCL</a>,
3411       and <a href="http://www.cliki.net/trivial-sockets">trivial-sockets</a> for
3412       implementation-dependent stuff like sockets and MP.  (This has been replaced by
3413       <a href="http://common-lisp.net/project/bordeaux-threads/">Bordeaux
3414       Threads</a>
3415       and <a href="http://common-lisp.net/project/usocket/">usocket</a>.)
3416     </p>
3417     <p>
3418       Parts of this documentation were prepared
3419       with <a href="http://weitz.de/documentation-template/">DOCUMENTATION-TEMPLATE</a>,
3420       no animals were harmed.
3421     </p>
3422   </clix:chapter>
3423   <p>
3424     <a href='http://weitz.de/index.html'>BACK TO MY HOMEPAGE
3425     </a>
3426   </p>
3427 </clix:documentation>