mirror of
https://github.com/apache/httpd.git
synced 2025-05-30 01:07:09 +03:00
44fa6e0073
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@420990 13f79535-47bb-0310-9956-ffa450edef68
793 lines
32 KiB
XML
793 lines
32 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
<!-- $LastChangedRevision$ -->
|
|
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<modulesynopsis metafile="mod_include.xml.meta">
|
|
|
|
<name>mod_include</name>
|
|
<description>Server-parsed html documents (Server Side Includes)</description>
|
|
<status>Base</status>
|
|
<sourcefile>mod_include.c</sourcefile>
|
|
<identifier>include_module</identifier>
|
|
<compatibility>Implemented as an output filter since Apache
|
|
2.0</compatibility>
|
|
|
|
<summary>
|
|
<p>This module provides a filter which will process files
|
|
before they are sent to the client. The processing is
|
|
controlled by specially formatted SGML comments, referred to as
|
|
<dfn>elements</dfn>. These elements allow conditional text, the
|
|
inclusion of other files or programs, as well as the setting and
|
|
printing of environment variables.</p>
|
|
</summary>
|
|
<seealso><directive module="core">Options</directive></seealso>
|
|
<seealso><directive module="core">AcceptPathInfo</directive></seealso>
|
|
<seealso><a href="../filter.html">Filters</a></seealso>
|
|
<seealso><a href="../howto/ssi.html">SSI Tutorial</a></seealso>
|
|
|
|
<section id="enabling">
|
|
<title>Enabling Server-Side Includes</title>
|
|
|
|
<p>Server Side Includes are implemented by the
|
|
<code>INCLUDES</code> <a href="../filter.html">filter</a>. If
|
|
documents containing server-side include directives are given
|
|
the extension .shtml, the following directives will make Apache
|
|
parse them and assign the resulting document the mime type of
|
|
<code>text/html</code>:</p>
|
|
|
|
<example>
|
|
AddType text/html .shtml<br />
|
|
AddOutputFilter INCLUDES .shtml
|
|
</example>
|
|
|
|
<p>The following directive must be given for the directories
|
|
containing the shtml files (typically in a
|
|
<directive module="core" type="section">Directory</directive> section,
|
|
but this directive is also valid in <code>.htaccess</code> files if
|
|
<directive module="core">AllowOverride</directive> <code>Options</code>
|
|
is set):</p>
|
|
|
|
<example>
|
|
Options +Includes
|
|
</example>
|
|
|
|
<p>For backwards compatibility, the <code>server-parsed</code>
|
|
<a href="../handler.html">handler</a> also activates the
|
|
INCLUDES filter. As well, Apache will activate the INCLUDES
|
|
filter for any document with mime type
|
|
<code>text/x-server-parsed-html</code> or
|
|
<code>text/x-server-parsed-html3</code> (and the resulting
|
|
output will have the mime type <code>text/html</code>).</p>
|
|
|
|
<p>For more information, see our <a
|
|
href="../howto/ssi.html">Tutorial on Server Side Includes</a>.</p>
|
|
</section> <!-- /enabling -->
|
|
|
|
<section id="pathinfo">
|
|
<title>PATH_INFO with Server Side Includes</title>
|
|
|
|
<p>Files processed for server-side includes no longer accept
|
|
requests with <code>PATH_INFO</code> (trailing pathname information)
|
|
by default. You can use the <directive
|
|
module="core">AcceptPathInfo</directive> directive to
|
|
configure the server to accept requests with <code>PATH_INFO</code>.</p>
|
|
</section> <!-- /pathinfo -->
|
|
|
|
<section id="elements"><title>Basic Elements</title>
|
|
<p>The document is parsed as an HTML document, with special
|
|
commands embedded as SGML comments. A command has the syntax: </p>
|
|
|
|
<example>
|
|
<!--#<var>element</var> <var>attribute</var>=<var>value</var>
|
|
<var>attribute</var>=<var>value</var> ... -->
|
|
</example>
|
|
|
|
<p>The value will often be enclosed in double quotes, but single
|
|
quotes (<code>'</code>) and backticks (<code>`</code>) are also
|
|
possible. Many commands only allow a single attribute-value pair.
|
|
Note that the comment terminator (<code>--></code>) should be
|
|
preceded by whitespace to ensure that it isn't considered part of
|
|
an SSI token. Note that the leading <code><!--#</code> is <em>one</em>
|
|
token and may not contain any whitespaces.</p>
|
|
|
|
<p>The allowed elements are listed in the following table:</p>
|
|
|
|
<table border="1">
|
|
<tr><th>Element</th><th>Description</th></tr>
|
|
<tr><td><code><a href="#element.config">config</a></code></td>
|
|
<td>configure output formats</td></tr>
|
|
<tr><td><code><a href="#element.echo">echo</a></code></td>
|
|
<td>print variables</td></tr>
|
|
<tr><td><code><a href="#element.exec">exec</a></code></td>
|
|
<td>execute external programs</td></tr>
|
|
<tr><td><code><a href="#element.fsize">fsize</a></code></td>
|
|
<td>print size of a file</td></tr>
|
|
<tr><td><code><a href="#element.flastmod">flastmod</a></code></td>
|
|
<td>print last modification time of a file</td></tr>
|
|
<tr><td><code><a href="#element.include">include</a></code></td>
|
|
<td>include a file</td></tr>
|
|
<tr><td><code><a href="#element.printenv">printenv</a></code></td>
|
|
<td>print all available variables</td></tr>
|
|
<tr><td><code><a href="#element.set">set</a></code></td>
|
|
<td>set a value of a variable</td></tr>
|
|
</table>
|
|
|
|
<p>SSI elements may be defined by modules other than
|
|
<module>mod_include</module>. In fact, the <code><a
|
|
href="#element.exec">exec</a></code> element is provided by
|
|
<module>mod_cgi</module>, and will only be available if this
|
|
module is loaded.</p>
|
|
|
|
<section id="element.config"><title>The config Element</title>
|
|
<p>This command controls various aspects of the parsing. The
|
|
valid attributes are:</p>
|
|
|
|
<dl>
|
|
<dt><code>echomsg</code> (<em>Apache 2.1 and later</em>)</dt>
|
|
<dd>The value is a message that is sent back to the
|
|
client if the <code><a href="#element.echo">echo</a></code> element
|
|
attempts to echo an undefined variable. This overrides any <directive
|
|
module="mod_include">SSIUndefinedEcho</directive> directives.</dd>
|
|
|
|
<dt><code>errmsg</code></dt>
|
|
<dd>The value is a message that is sent back to the
|
|
client if an error occurs while parsing the
|
|
document. This overrides any <directive
|
|
module="mod_include">SSIErrorMsg</directive> directives.</dd>
|
|
|
|
<dt><code>sizefmt</code></dt>
|
|
<dd>The value sets the format to be used which displaying
|
|
the size of a file. Valid values are <code>bytes</code>
|
|
for a count in bytes, or <code>abbrev</code> for a count
|
|
in Kb or Mb as appropriate, for example a size of 1024 bytes
|
|
will be printed as "1K".</dd>
|
|
|
|
<dt><code>timefmt</code></dt>
|
|
<dd>The value is a string to be used by the
|
|
<code>strftime(3)</code> library routine when printing
|
|
dates.</dd>
|
|
</dl>
|
|
</section> <!-- /config -->
|
|
|
|
<section id="element.echo"><title>The echo Element</title>
|
|
<p>This command prints one of the <a href="#includevars">include
|
|
variables</a>, defined below. If the variable is unset, the result is
|
|
determined by the <directive module="mod_include"
|
|
>SSIUndefinedEcho</directive> directive. Any dates printed are
|
|
subject to the currently configured <code>timefmt</code>.</p>
|
|
|
|
<p>Attributes:</p>
|
|
|
|
<dl>
|
|
<dt><code>var</code></dt>
|
|
<dd>The value is the name of the variable to print.</dd>
|
|
|
|
<dt><code>encoding</code></dt>
|
|
<dd><p>Specifies how Apache should encode special characters
|
|
contained in the variable before outputting them. If set
|
|
to <code>none</code>, no encoding will be done. If set to
|
|
<code>url</code>, then URL encoding (also known as %-encoding;
|
|
this is appropriate for use within URLs in links, etc.) will be
|
|
performed. At the start of an <code>echo</code> element,
|
|
the default is set to <code>entity</code>, resulting in entity
|
|
encoding (which is appropriate in the context of a block-level
|
|
HTML element, <em>e.g.</em> a paragraph of text). This can be
|
|
changed by adding an <code>encoding</code> attribute, which will
|
|
remain in effect until the next <code>encoding</code> attribute
|
|
is encountered or the element ends, whichever comes first.</p>
|
|
|
|
<p>The <code>encoding</code> attribute must <em>precede</em> the
|
|
corresponding <code>var</code> attribute to be effective, and
|
|
only special characters as defined in the ISO-8859-1 character
|
|
encoding will be encoded. This encoding process may not have the
|
|
desired result if a different character encoding is in use.</p>
|
|
|
|
<note type="warning">
|
|
In order to avoid cross-site scripting issues, you should
|
|
<em>always</em> encode user supplied data.
|
|
</note>
|
|
</dd>
|
|
</dl>
|
|
</section> <!-- /echo -->
|
|
|
|
<section id="element.exec"><title>The exec Element</title>
|
|
<p>The <code>exec</code> command executes a given shell command or
|
|
CGI script. It requires <module>mod_cgi</module> to be present
|
|
in the server. If <directive module="core">Options</directive>
|
|
<code>IncludesNOEXEC</code> is set, this command is completely
|
|
disabled. The valid attributes are:</p>
|
|
|
|
<dl>
|
|
<dt><code>cgi</code></dt>
|
|
<dd><p>The value specifies a (%-encoded) URL-path to
|
|
the CGI script. If the path does not begin with a slash (/),
|
|
then it is taken to be relative to the current
|
|
document. The document referenced by this path is
|
|
invoked as a CGI script, even if the server would not
|
|
normally recognize it as such. However, the directory
|
|
containing the script must be enabled for CGI scripts
|
|
(with <directive module="mod_alias">ScriptAlias</directive>
|
|
or <directive module="core">Options</directive>
|
|
<code>ExecCGI</code>).</p>
|
|
|
|
<p>The CGI script is given the <code>PATH_INFO</code> and query
|
|
string (<code>QUERY_STRING</code>) of the original request from the
|
|
client; these <em>cannot</em> be specified in the URL path. The
|
|
include variables will be available to the script in addition to
|
|
the standard <a href="mod_cgi.html">CGI</a> environment.</p>
|
|
|
|
<example><title>Example</title>
|
|
<!--#exec cgi="/cgi-bin/example.cgi" -->
|
|
</example>
|
|
|
|
<p>If the script returns a <code>Location:</code> header instead of
|
|
output, then this will be translated into an HTML anchor.</p>
|
|
|
|
<p>The <code><a href="#includevirtual">include virtual</a></code>
|
|
element should be used in preference to <code>exec cgi</code>. In
|
|
particular, if you need to pass additional arguments to a CGI program,
|
|
using the query string, this cannot be done with <code>exec
|
|
cgi</code>, but can be done with <code>include virtual</code>, as
|
|
shown here:</p>
|
|
|
|
<example>
|
|
<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->
|
|
</example>
|
|
</dd>
|
|
|
|
<dt><code>cmd</code></dt>
|
|
<dd><p>The server will execute the given string using
|
|
<code>/bin/sh</code>. The <a href="#includevars"
|
|
>include variables</a> are available to the command, in addition
|
|
to the usual set of CGI variables.</p>
|
|
|
|
<p>The use of <code><a href="#includevirtual"
|
|
>#include virtual</a></code> is almost always prefered to using
|
|
either <code>#exec cgi</code> or <code>#exec cmd</code>. The former
|
|
(<code>#include virtual</code>) uses the standard Apache sub-request
|
|
mechanism to include files or scripts. It is much better tested and
|
|
maintained.</p>
|
|
|
|
<p>In addition, on some platforms, like Win32, and on unix when
|
|
using <a href="../suexec.html">suexec</a>, you cannot pass arguments
|
|
to a command in an <code>exec</code> directive, or otherwise include
|
|
spaces in the command. Thus, while the following will work under a
|
|
non-suexec configuration on unix, it will not produce the desired
|
|
result under Win32, or when running suexec:</p>
|
|
|
|
<example>
|
|
<!--#exec cmd="perl /path/to/perlscript arg1 arg2" -->
|
|
</example>
|
|
</dd>
|
|
</dl>
|
|
</section> <!-- /exec -->
|
|
|
|
<section id="element.fsize"><title>The fsize Element</title>
|
|
<p>This command prints the size of the specified file, subject
|
|
to the <code>sizefmt</code> format specification. Attributes:</p>
|
|
|
|
<dl>
|
|
<dt><code>file</code></dt>
|
|
<dd>The value is a path relative to the directory
|
|
containing the current document being parsed.</dd>
|
|
|
|
<dt><code>virtual</code></dt>
|
|
<dd>The value is a (%-encoded) URL-path. If it does not begin with
|
|
a slash (/) then it is taken to be relative to the current document.
|
|
Note, that this does <em>not</em> print the size of any CGI output,
|
|
but the size of the CGI script itself.</dd>
|
|
</dl>
|
|
</section> <!-- /fsize -->
|
|
|
|
<section id="element.flastmod"><title>The flastmod Element</title>
|
|
<p>This command prints the last modification date of the
|
|
specified file, subject to the <code>timefmt</code> format
|
|
specification. The attributes are the same as for the
|
|
<code><a href="#element.fsize">fsize</a></code> command.</p>
|
|
</section> <!-- /flastmod -->
|
|
|
|
<section id="element.include"><title>The include Element</title>
|
|
<p>This command inserts the text of another document or file
|
|
into the parsed file. Any included file is subject to the usual
|
|
access control. If the directory containing the parsed file has
|
|
<a href="core.html#options">Options</a>
|
|
<code>IncludesNOEXEC</code> set, then only documents with a text
|
|
<glossary>MIME-type</glossary> (<code>text/plain</code>,
|
|
<code>text/html</code> etc.) will be included. Otherwise CGI
|
|
scripts are invoked as normal using the complete URL given in
|
|
the command, including any query string.</p>
|
|
|
|
<p>An attribute defines the location of the document; the
|
|
inclusion is done for each attribute given to the include
|
|
command. The valid attributes are:</p>
|
|
|
|
<dl>
|
|
<dt><code>file</code></dt>
|
|
<dd>The value is a path relative to the directory
|
|
containing the current document being parsed. It cannot
|
|
contain <code>../</code>, nor can it be an absolute path.
|
|
Therefore, you cannot include files that are outside of the
|
|
document root, or above the current document in the directory
|
|
structure. The <code>virtual</code> attribute should always be
|
|
used in preference to this one.</dd>
|
|
|
|
<dt><code><a id="includevirtual" name="includevirtual"
|
|
>virtual</a></code></dt>
|
|
<dd><p>The value is a (%-encoded) URL-path. The URL cannot contain a
|
|
scheme or hostname, only a path and an optional query string. If it
|
|
does not begin with a slash (/) then it is taken to be relative to the
|
|
current document.</p>
|
|
|
|
<p>A URL is constructed from the attribute, and the output the
|
|
server would return if the URL were accessed by the client is
|
|
included in the parsed output. Thus included files can be nested.</p>
|
|
|
|
<p>If the specified URL is a CGI program, the program will be
|
|
executed and its output inserted in place of the directive in the
|
|
parsed file. You may include a query string in a CGI url:</p>
|
|
|
|
<example>
|
|
<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->
|
|
</example>
|
|
|
|
<p><code>include virtual</code> should be used in preference
|
|
to <code>exec cgi</code> to include the output of CGI programs
|
|
into an HTML document.</p>
|
|
</dd>
|
|
</dl>
|
|
</section> <!-- /include -->
|
|
|
|
<section id="element.printenv"><title>The printenv Element</title>
|
|
<p>This prints out a listing of all existing variables and
|
|
their values. Special characters are entity encoded (see the <code><a
|
|
href="#element.echo">echo</a></code> element for details)
|
|
before being output. There are no attributes.</p>
|
|
|
|
<example><title>Example</title>
|
|
<!--#printenv -->
|
|
</example>
|
|
</section> <!-- /printenv -->
|
|
|
|
<section id="element.set"><title>The set Element</title>
|
|
<p>This sets the value of a variable. Attributes:</p>
|
|
|
|
<dl>
|
|
<dt><code>var</code></dt>
|
|
<dd>The name of the variable to set.</dd>
|
|
|
|
<dt><code>value</code></dt>
|
|
<dd>The value to give a variable.</dd>
|
|
</dl>
|
|
|
|
<example><title>Example</title>
|
|
<!--#set var="category" value="help" -->
|
|
</example>
|
|
</section> <!-- /set -->
|
|
</section> <!-- /basic elements -->
|
|
|
|
<section id="includevars">
|
|
<title>Include Variables</title>
|
|
|
|
<p>In addition to the variables in the standard CGI environment,
|
|
these are available for the <code>echo</code> command, for
|
|
<code>if</code> and <code>elif</code>, and to any program
|
|
invoked by the document.</p>
|
|
|
|
<dl>
|
|
<dt><code>DATE_GMT</code></dt>
|
|
<dd>The current date in Greenwich Mean Time.</dd>
|
|
|
|
<dt><code>DATE_LOCAL</code></dt>
|
|
<dd>The current date in the local time zone.</dd>
|
|
|
|
<dt><code>DOCUMENT_NAME</code></dt>
|
|
<dd>The filename (excluding directories) of the document
|
|
requested by the user.</dd>
|
|
|
|
<dt><code>DOCUMENT_URI</code></dt>
|
|
<dd>The (%-decoded) URL path of the document requested by the
|
|
user. Note that in the case of nested include files, this is
|
|
<em>not</em> the URL for the current document.</dd>
|
|
|
|
<dt><code>LAST_MODIFIED</code></dt>
|
|
<dd>The last modification date of the document requested by
|
|
the user.</dd>
|
|
|
|
<dt><code>QUERY_STRING_UNESCAPED</code></dt>
|
|
<dd>If a query string is present, this variable contains the
|
|
(%-decoded) query string, which is <em>escaped</em> for shell
|
|
usage (special characters like <code>&</code> etc. are
|
|
preceded by backslashes).</dd>
|
|
</dl>
|
|
</section>
|
|
|
|
<section id="substitution"><title>Variable Substitution</title>
|
|
|
|
<p>Variable substitution is done within quoted strings in most
|
|
cases where they may reasonably occur as an argument to an SSI
|
|
directive. This includes the <code>config</code>,
|
|
<code>exec</code>, <code>flastmod</code>, <code>fsize</code>,
|
|
<code>include</code>, <code>echo</code>, and <code>set</code>
|
|
directives, as well as the arguments to conditional operators.
|
|
You can insert a literal dollar sign into the string using backslash
|
|
quoting:</p>
|
|
|
|
<example>
|
|
<!--#if expr="$a = \$test" -->
|
|
</example>
|
|
|
|
<p>If a variable reference needs to be substituted in the
|
|
middle of a character sequence that might otherwise be
|
|
considered a valid identifier in its own right, it can be
|
|
disambiguated by enclosing the reference in braces,
|
|
<em>a la</em> shell substitution:</p>
|
|
|
|
<example>
|
|
<!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->
|
|
</example>
|
|
|
|
<p>This will result in the <code>Zed</code> variable being set
|
|
to "<code>X_Y</code>" if <code>REMOTE_HOST</code> is
|
|
"<code>X</code>" and <code>REQUEST_METHOD</code> is
|
|
"<code>Y</code>".</p>
|
|
|
|
<p>The below example will print "in foo" if the
|
|
<code>DOCUMENT_URI</code> is <code>/foo/file.html</code>, "in bar"
|
|
if it is <code>/bar/file.html</code> and "in neither" otherwise:</p>
|
|
|
|
<example>
|
|
<!--#if expr='"$DOCUMENT_URI" = "/foo/file.html"' --><br />
|
|
<indent>
|
|
in foo<br />
|
|
</indent>
|
|
<!--#elif expr='"$DOCUMENT_URI" = "/bar/file.html"' --><br />
|
|
<indent>
|
|
in bar<br />
|
|
</indent>
|
|
<!--#else --><br />
|
|
<indent>
|
|
in neither<br />
|
|
</indent>
|
|
<!--#endif -->
|
|
</example>
|
|
</section>
|
|
|
|
<section id="flowctrl">
|
|
<title>Flow Control Elements</title>
|
|
|
|
<p>The basic flow control elements are:</p>
|
|
|
|
<example>
|
|
<!--#if expr="<var>test_condition</var>" --><br />
|
|
<!--#elif expr="<var>test_condition</var>" --><br />
|
|
<!--#else --><br />
|
|
<!--#endif -->
|
|
</example>
|
|
|
|
<p>The <code>if</code> element works like an if statement in a
|
|
programming language. The test condition is evaluated and if
|
|
the result is true, then the text until the next <code>elif</code>,
|
|
<code>else</code> or <code>endif</code> element is included in the
|
|
output stream.</p>
|
|
|
|
<p>The <code>elif</code> or <code>else</code> statements are be used
|
|
to put text into the output stream if the original
|
|
<var>test_condition</var> was false. These elements are optional.</p>
|
|
|
|
<p>The <code>endif</code> element ends the <code>if</code> element
|
|
and is required.</p>
|
|
|
|
<p><var>test_condition</var> is one of the following:</p>
|
|
|
|
<dl>
|
|
<dt><code><var>string</var></code></dt>
|
|
<dd>true if <var>string</var> is not empty</dd>
|
|
|
|
<dt><code><var>string1</var> = <var>string2</var><br />
|
|
<var>string1</var> == <var>string2</var><br />
|
|
<var>string1</var> != <var>string2</var></code></dt>
|
|
|
|
<dd><p>Compare <var>string1</var> with <var>string2</var>. If
|
|
<var>string2</var> has the form <code>/<var>string2</var>/</code>
|
|
then it is treated as a regular expression. Regular expressions are
|
|
implemented by the <a href="http://www.pcre.org">PCRE</a> engine and
|
|
have the same syntax as those in <a href="http://www.perl.com">perl
|
|
5</a>. Note that <code>==</code> is just an alias for <code>=</code>
|
|
and behaves exactly the same way.</p>
|
|
|
|
<p>If you are matching positive (<code>=</code> or <code>==</code>), you
|
|
can capture grouped parts of the regular expression. The captured parts
|
|
are stored in the special variables <code>$1</code> ..
|
|
<code>$9</code>.</p>
|
|
|
|
<example><title>Example</title>
|
|
<!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" --><br />
|
|
<indent>
|
|
<!--#set var="session" value="$1" --><br />
|
|
</indent>
|
|
<!--#endif -->
|
|
</example>
|
|
</dd>
|
|
|
|
<dt><code><var>string1</var> < <var>string2</var><br />
|
|
<var>string1</var> <= <var>string2</var><br />
|
|
<var>string1</var> > <var>string2</var><br />
|
|
<var>string1</var> >= <var>string2</var></code></dt>
|
|
|
|
<dd>Compare <var>string1</var> with <var>string2</var>. Note, that
|
|
strings are compared <em>literally</em> (using
|
|
<code>strcmp(3)</code>). Therefore the string "100" is less than
|
|
"20".</dd>
|
|
|
|
<dt><code>( <var>test_condition</var> )</code></dt>
|
|
<dd>true if <var>test_condition</var> is true</dd>
|
|
|
|
<dt><code>! <var>test_condition</var></code></dt>
|
|
<dd>true if <var>test_condition</var> is false</dd>
|
|
|
|
<dt><code><var>test_condition1</var> &&
|
|
<var>test_condition2</var></code></dt>
|
|
<dd>true if both <var>test_condition1</var> and
|
|
<var>test_condition2</var> are true</dd>
|
|
|
|
<dt><code><var>test_condition1</var> ||
|
|
<var>test_condition2</var></code></dt>
|
|
<dd>true if either <var>test_condition1</var> or
|
|
<var>test_condition2</var> is true</dd>
|
|
</dl>
|
|
|
|
<p>"<code>=</code>" and "<code>!=</code>" bind more tightly than
|
|
"<code>&&</code>" and "<code>||</code>". "<code>!</code>" binds
|
|
most tightly. Thus, the following are equivalent:</p>
|
|
|
|
<example>
|
|
<!--#if expr="$a = test1 && $b = test2" --><br />
|
|
<!--#if expr="($a = test1) && ($b = test2)" -->
|
|
</example>
|
|
|
|
<p>The boolean operators <code>&&</code> and <code>||</code>
|
|
share the same priority. So if you want to bind such an operator more
|
|
tightly, you should use parentheses.</p>
|
|
|
|
<p>Anything that's not recognized as a variable or an operator
|
|
is treated as a string. Strings can also be quoted:
|
|
<code>'string'</code>. Unquoted strings can't contain whitespace
|
|
(blanks and tabs) because it is used to separate tokens such as
|
|
variables. If multiple strings are found in a row, they are
|
|
concatenated using blanks. So,</p>
|
|
|
|
<example>
|
|
<p><code><var>string1</var> <var
|
|
>string2</var></code> results in <code><var>string1</var> <var
|
|
>string2</var></code><br />
|
|
<br />
|
|
and<br />
|
|
<br />
|
|
<code>'<var>string1</var> <var
|
|
>string2</var>'</code> results in <code><var
|
|
>string1</var> <var>string2</var></code>.</p>
|
|
</example>
|
|
|
|
<note><title>Optimization of Boolean Expressions</title>
|
|
<p>If the expressions become more complex and slow down processing
|
|
significantly, you can try to optimize them according to the
|
|
evaluation rules:</p>
|
|
<ul>
|
|
<li>Expressions are evaluated from left to right</li>
|
|
<li>Binary boolean operators (<code>&&</code> and <code>||</code>)
|
|
are short circuited wherever possible. In conclusion with the rule
|
|
above that means, <module>mod_include</module> evaluates at first
|
|
the left expression. If the left result is sufficient to determine
|
|
the end result, processing stops here. Otherwise it evaluates the
|
|
right side and computes the end result from both left and right
|
|
results.</li>
|
|
<li>Short circuit evaluation is turned off as long as there are regular
|
|
expressions to deal with. These must be evaluated to fill in the
|
|
backreference variables (<code>$1</code> .. <code>$9</code>).</li>
|
|
</ul>
|
|
<p>If you want to look how a particular expression is handled, you can
|
|
recompile <module>mod_include</module> using the
|
|
<code>-DDEBUG_INCLUDE</code> compiler option. This inserts for every
|
|
parsed expression tokenizer information, the parse tree and how it is
|
|
evaluated into the output sent to the client.</p>
|
|
</note>
|
|
</section>
|
|
|
|
<directivesynopsis>
|
|
<name>SSIEndTag</name>
|
|
<description>String that ends an include element</description>
|
|
<syntax>SSIEndTag <var>tag</var></syntax>
|
|
<default>SSIEndTag "-->"</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
<compatibility>Available in version 2.0.30 and later.</compatibility>
|
|
|
|
<usage>
|
|
<p>This directive changes the string that <module>mod_include</module>
|
|
looks for to mark the end of an include element.</p>
|
|
|
|
<example><title>Example</title>
|
|
SSIEndTag "%>"
|
|
</example>
|
|
|
|
</usage>
|
|
<seealso><directive module="mod_include">SSIStartTag</directive></seealso>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSIUndefinedEcho</name>
|
|
<description>String displayed when an unset variable is echoed</description>
|
|
<syntax>SSIUndefinedEcho <var>string</var></syntax>
|
|
<default>SSIUndefinedEcho "(none)"</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context></contextlist>
|
|
<override>All</override>
|
|
<compatibility>Available in version 2.0.34 and later.</compatibility>
|
|
|
|
<usage>
|
|
<p>This directive changes the string that <module>mod_include</module>
|
|
displays when a variable is not set and "echoed".</p>
|
|
|
|
<example><title>Example</title>
|
|
SSIUndefinedEcho "<!-- undef -->"
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSIErrorMsg</name>
|
|
<description>Error message displayed when there is an SSI
|
|
error</description>
|
|
<syntax>SSIErrorMsg <var>message</var></syntax>
|
|
<default>SSIErrorMsg "[an error occurred while processing this
|
|
directive]"</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context></contextlist>
|
|
<override>All</override>
|
|
<compatibility>Available in version 2.0.30 and later.</compatibility>
|
|
|
|
<usage>
|
|
<p>The <directive>SSIErrorMsg</directive> directive changes the error
|
|
message displayed when <module>mod_include</module> encounters an
|
|
error. For production servers you may consider changing the default
|
|
error message to <code>"<!-- Error -->"</code> so that
|
|
the message is not presented to the user.</p>
|
|
|
|
<p>This directive has the same effect as the <code><!--#config
|
|
errmsg=<var>message</var> --></code> element.</p>
|
|
|
|
<example><title>Example</title>
|
|
SSIErrorMsg "<!-- Error -->"
|
|
</example>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSIStartTag</name>
|
|
<description>String that starts an include element</description>
|
|
<syntax>SSIStartTag <var>tag</var></syntax>
|
|
<default>SSIStartTag "<!--#"</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
</contextlist>
|
|
<compatibility>Available in version 2.0.30 and later.</compatibility>
|
|
|
|
<usage>
|
|
<p>This directive changes the string that <module>mod_include</module>
|
|
looks for to mark an include element to process.</p>
|
|
|
|
<p>You may want to use this option if you have 2 servers parsing the
|
|
output of a file each processing different commands (possibly at
|
|
different times).</p>
|
|
|
|
<example><title>Example</title>
|
|
SSIStartTag "<%"<br />
|
|
SSIEndTag "%>"
|
|
</example>
|
|
|
|
<p>The example given above, which also specifies a matching
|
|
<directive module="mod_include">SSIEndTag</directive>, will
|
|
allow you to use SSI directives as shown in the example
|
|
below:</p>
|
|
|
|
<example><title>SSI directives with alternate start and end tags</title>
|
|
<%printenv %>
|
|
</example>
|
|
</usage>
|
|
<seealso><directive module="mod_include">SSIEndTag</directive></seealso>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>SSITimeFormat</name>
|
|
<description>Configures the format in which date strings are
|
|
displayed</description>
|
|
<syntax>SSITimeFormat <var>formatstring</var></syntax>
|
|
<default>SSITimeFormat "%A, %d-%b-%Y %H:%M:%S %Z"</default>
|
|
<contextlist>
|
|
<context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context></contextlist>
|
|
<override>All</override>
|
|
<compatibility>Available in version 2.0.30 and later.</compatibility>
|
|
|
|
<usage>
|
|
<p>This directive changes the format in which date strings are displayed
|
|
when echoing <code>DATE</code> environment variables. The
|
|
<var>formatstring</var> is as in <code>strftime(3)</code> from the
|
|
C standard library.</p>
|
|
|
|
<p>This directive has the same effect as the <code><!--#config
|
|
timefmt=<var>formatstring</var> --></code> element.</p>
|
|
|
|
<example><title>Example</title>
|
|
SSITimeFormat "%R, %B %d, %Y"
|
|
</example>
|
|
|
|
<p>The above directive would cause times to be displayed in the
|
|
format "22:26, June 14, 2002".</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>XBitHack</name>
|
|
<description>Parse SSI directives in files with the execute bit
|
|
set</description>
|
|
<syntax>XBitHack on|off|full</syntax>
|
|
<default>XBitHack off</default>
|
|
<contextlist><context>server config</context><context>virtual host</context>
|
|
<context>directory</context><context>.htaccess</context></contextlist>
|
|
<override>Options</override>
|
|
|
|
<usage>
|
|
<p>The <directive>XBitHack</directive> directive controls the parsing
|
|
of ordinary html documents. This directive only affects files associated
|
|
with the <glossary>MIME-type</glossary> <code>text/html</code>. <directive
|
|
>XBitHack</directive> can take on the following values:</p>
|
|
|
|
<dl>
|
|
<dt><code>off</code></dt>
|
|
<dd>No special treatment of executable files.</dd>
|
|
|
|
<dt><code>on</code></dt>
|
|
<dd>Any <code>text/html</code> file that has the user-execute bit
|
|
set will be treated as a server-parsed html document.</dd>
|
|
|
|
<dt><code>full</code></dt>
|
|
<dd>As for <code>on</code> but also test the group-execute bit.
|
|
If it is set, then set the <code>Last-modified</code> date of the
|
|
returned file to be the last modified time of the file. If
|
|
it is not set, then no last-modified date is sent. Setting
|
|
this bit allows clients and proxies to cache the result of
|
|
the request.
|
|
|
|
<note><title>Note</title>
|
|
<p>You would not want to use the full option, unless you assure the
|
|
group-execute bit is unset for every SSI script which might <code
|
|
>#include</code> a CGI or otherwise produces different output on
|
|
each hit (or could potentially change on subsequent requests).</p>
|
|
</note>
|
|
</dd>
|
|
</dl>
|
|
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
</modulesynopsis>
|
|
|