explain usage of httpd-options-transformers.

This commit is contained in:
interp 2002-04-02 09:44:14 +00:00
parent 86a71b09a2
commit ea3615a633
1 changed files with 89 additions and 31 deletions

View File

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