diff --git a/doc/latex/httpd.tex b/doc/latex/httpd.tex index 0b02224..dca970f 100644 --- a/doc/latex/httpd.tex +++ b/doc/latex/httpd.tex @@ -72,37 +72,8 @@ one argument, a \ex{httpd\=options}-record: \defun{httpd}{options}{\noreturn} \begin{desc} - The \semvar{options} can be set via the various options-transformers - that can be found in the \ex{httpd\=make\=options}-structure: - \ex{with\=port}, \ex{with\=root\=directory}, \ex{with\=fqdn}, - \ex{with\=reported-port}, \ex{with\=path\=handler}, - \ex{with\=server\=admin}, \ex{with\=simultaneous-requests}, - \ex{with\=logfile}, \ex{with\=syslog?} that set the port the server - is listening to, the root-directory of the server, the FQDN of the - server, the port the server assumes it is listening to, the - path-handler of the server (see below), the mail-address of the - server-admin, the maximum number of simultaneous handled requests, - the name of the file or the port logging in the Common Log Format - (CLF) is output to and if the server shall create syslog messages, - respectively. The port defaults to 80, the root directory defaults - to ``\ex{/}'', the mail address of the server-admin defaults to - ``\ex{sperber@\ob{}informatik.\ob{}uni\=tuebingen.\ob{}de}'', - \FIXME{Why does the server admin mail address have - sperber@informatik... as default value?}logging is done to - ``\ex{httpd.log}'' and syslog is enabled. All other options default - to \sharpf. - - For example - \begin{code} -(httpd (with-path-handler - (rooted-file-handler "/usr/local/etc/httpd") - (with-root-directory "/usr/local/etc/httpd"))) - \end{code} - - starts the server on port 80 with - ``\ex{/usr/\ob{}local/\ob{}etc/\ob{}httpd}'' as root directory and - let it serve any files out from this directory. Note that - \ex{with\=root\=directory} is nested in \ex{with\=path\=handler}. + This procedure starts the server. The various \semvar{options} can + be set via the options transformers that are explained below. The server's basic loop is to wait on the port for a connection from an HTTP client. When it receives a connection, it reads in and @@ -125,6 +96,93 @@ one argument, a \ex{httpd\=options}-record: The basic server loop, and the associated request data structure are the fixed architecture of the S.U. Web server; its flexibility lies in the notion of path handlers. +\end{desc} + +\defun{with-port}{port \ovar{options}}{options} +\defunx{with-root-directory}{root-directory + \ovar{options}}{options} +\defunx{with-fqdn}{fqdn \ovar{options}}{options} +\defunx{with-reported-port}{reported-port + \ovar{options}}{options} +\defunx{with-path-handler}{path-handler + \ovar{options}}{options} +\defunx{with-server-admin}{mail-address + \ovar{options}}{options} +\defunx{with-simultaneous-requests}{requests + \ovar{options}}{options} +\defunx{with-logfile}{logfile \ovar{options}}{options} +\defunx{with-syslog?}{syslog? \ovar{options}}{options} +\begin{desc} + As noted above, these transformers set the options for the web + server. Every transformer changes one aspect of the + \semvar{options} (for the \ex{httpd}). If this optional argument is missing, the + default values are used. These are the following: + + \begin{tabular}{ll} + \bf{transformer} & \bf{default value} \\ + \hline + \ex{with\=port} & 80 \\ + \ex{with\=root\=directory} & ``\ex{/}'' \\ + \ex{with\=fqdn} & \sharpf \\ + \ex{with\=reported-port} & \sharpf \\ + \ex{with\=path\=handler} & \sharpf \\ + \ex{with\=server\=admin} & ``\ex{sperber@\ob{}informatik.} \\ + & \ex{\ob{}uni\=tuebingen.\ob{}de}'' + \FIXME{Why does the server admin mail address have + sperber@informatik... as default value?}\\ + \ex{with\=simultaneous\=requests} & \sharpf \\ + \ex{with\=logfile} & ``\ex{/httpd.log}''\\ + \ex{with\=syslog?} & \sharpt \\ + \end{tabular} + +% that can be found in the \ex{httpd\=make\=options}-structure: +% \ex{with\=port}, \ex{with\=root\=directory}, \ex{with\=fqdn}, +% \ex{with\=reported-port}, \ex{with\=path\=handler}, +% \ex{with\=server\=admin}, \ex{with\=simultaneous-requests}, +% \ex{with\=logfile}, \ex{with\=syslog?} that set the port the server +% is listening to, the root-directory of the server, the FQDN of the +% server, the port the server assumes it is listening to, the +% path-handler of the server (see below), the mail-address of the +% server-admin, the maximum number of simultaneous handled requests, +% the name of the file or the port logging in the Common Log Format +% (CLF) is output to and if the server shall create syslog messages, +% respectively. The port defaults to 80, the root directory defaults +% to ``\ex{/}'', the mail address of the server-admin defaults to +% ``\ex{sperber@\ob{}informatik.\ob{}uni\=tuebingen.\ob{}de}'', +% \FIXME{Why does the server admin mail address have +% sperber@informatik... as default value?}logging is done to +% ``\ex{httpd.log}'' and syslog is enabled. All other options default +% to \sharpf. + + For example + \begin{code} +(httpd (with-path-handler + (rooted-file-handler "/usr/local/etc/httpd") + (with-root-directory "/usr/local/etc/httpd"))) + \end{code} + + starts the server on port 80 with + ``\ex{/usr/\ob{}local/\ob{}etc/\ob{}httpd}'' as root directory and + lets it serve any file out from this directory. + \ex{rooted\=file\=handler} creates a path handler and is explained + below. You see, the transformers are used nested. So, every + transformer changes one aspect of the options that the following + transformer returns and the last transformer (here: + \ex{with\=root\=directory}) changes an aspect of the default values + + + \semvar{port} is the port the server is listening to, + \semvar{root-directory} is the directory in the file system the + server uses as root, \semvar{fqdn} is the fully qualified domain + name the server reports, \semvar{reported-port} is the port the + server reports it is listening to and \semvar{server-admin} is the + mail address of the server admin. \semvar{requests} denote the + maximum number of allowed simultaneous requests to the server. + \sharpf\ means infinite. \semvar{logfile} is either a string, then + it is the file name of the logfile, or a port, where the log entries + are written to, or \sharpf, that means no logging is made. The + logfile is in Common Log Format (CLF). \semvar{syslog?} tells the + server to write syslog messages (\sharpt) or not (\sharpf). \end{desc} \subsubsection*{Path handlers}