rubbos/app/apache2/manual/mod/mod_include.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>mod_include - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body>
  14 <div id="page-header">
  15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  16 <p class="apache">Apache HTTP Server Version 2.0</p>
  17 <img alt="" src="../images/feather.gif" /></div>
  18 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  19 <div id="path">
  20 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.0</a> &gt; <a href="./">Modules</a></div>
  21 <div id="page-content">
  22 <div id="preamble"><h1>Apache Module mod_include</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/mod/mod_include.html" title="English">&nbsp;en&nbsp;</a> |
  25 <a href="../ja/mod/mod_include.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a></p>
  26 </div>
  27 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Server-parsed html documents (Server Side Includes)</td></tr>
  28 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr>
  29 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>include_module</td></tr>
  30 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_include.c</td></tr>
  31 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Implemented as an output filter since Apache
  32 2.0</td></tr></table>
  33 <h3>Summary</h3>
  34
  35     <p>This module provides a filter which will process files
  36     before they are sent to the client. The processing is
  37     controlled by specially formatted SGML comments, referred to as
  38     <dfn>elements</dfn>. These elements allow conditional text, the
  39     inclusion of other files or programs, as well as the setting and
  40     printing of environment variables.</p>
  41 </div>
  42 <div id="quickview"><h3 class="directives">Directives</h3>
  43 <ul id="toc">
  44 <li><img alt="" src="../images/down.gif" /> <a href="#ssiendtag">SSIEndTag</a></li>
  45 <li><img alt="" src="../images/down.gif" /> <a href="#ssierrormsg">SSIErrorMsg</a></li>
  46 <li><img alt="" src="../images/down.gif" /> <a href="#ssistarttag">SSIStartTag</a></li>
  47 <li><img alt="" src="../images/down.gif" /> <a href="#ssitimeformat">SSITimeFormat</a></li>
  48 <li><img alt="" src="../images/down.gif" /> <a href="#ssiundefinedecho">SSIUndefinedEcho</a></li>
  49 <li><img alt="" src="../images/down.gif" /> <a href="#xbithack">XBitHack</a></li>
  50 </ul>
  51 <h3>Topics</h3>
  52 <ul id="topics">
  53 <li><img alt="" src="../images/down.gif" /> <a href="#enabling">Enabling Server-Side Includes</a></li>
  54 <li><img alt="" src="../images/down.gif" /> <a href="#pathinfo">PATH_INFO with Server Side Includes</a></li>
  55 <li><img alt="" src="../images/down.gif" /> <a href="#elements">Basic Elements</a></li>
  56 <li><img alt="" src="../images/down.gif" /> <a href="#includevars">Include Variables</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#substitution">Variable Substitution</a></li>
  58 <li><img alt="" src="../images/down.gif" /> <a href="#flowctrl">Flow Control Elements</a></li>
  59 </ul><h3>See also</h3>
  60 <ul class="seealso">
  61 <li><code class="directive"><a href="../mod/core.html#options">Options</a></code></li>
  62 <li><code class="directive"><a href="../mod/core.html#acceptpathinfo">AcceptPathInfo</a></code></li>
  63 <li><a href="../misc/custom_errordocs.html">International Customized
  64 Server Error Messages</a></li>
  65 <li><a href="../filter.html">Filters</a></li>
  66 <li><a href="../howto/ssi.html">SSI Tutorial</a></li>
  67 </ul></div>
  68 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  69 <div class="section">
  70 <h2><a name="enabling" id="enabling">Enabling Server-Side Includes</a></h2>
  71
  72
  73     <p>Server Side Includes are implemented by the
  74     <code>INCLUDES</code> <a href="../filter.html">filter</a>. If
  75     documents containing server-side include directives are given
  76     the extension .shtml, the following directives will make Apache
  77     parse them and assign the resulting document the mime type of
  78     <code>text/html</code>:</p>
  79
  80     <div class="example"><p><code>
  81       AddType text/html .shtml<br />
  82       AddOutputFilter INCLUDES .shtml
  83     </code></p></div>
  84
  85     <p>The following directive must be given for the directories
  86     containing the shtml files (typically in a
  87     <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> section,
  88     but this directive is also valid in <code>.htaccess</code> files if
  89     <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> <code>Options</code>
  90     is set):</p>
  91
  92     <div class="example"><p><code>
  93       Options +Includes
  94     </code></p></div>
  95
  96     <p>For backwards compatibility, the <code>server-parsed</code>
  97     <a href="../handler.html">handler</a> also activates the
  98     INCLUDES filter. As well, Apache will activate the INCLUDES
  99     filter for any document with mime type
 100     <code>text/x-server-parsed-html</code> or
 101     <code>text/x-server-parsed-html3</code> (and the resulting
 102     output will have the mime type <code>text/html</code>).</p>
 103
 104     <p>For more information, see our <a href="../howto/ssi.html">Tutorial on Server Side Includes</a>.</p>
 105 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 106 <div class="section">
 107 <h2><a name="pathinfo" id="pathinfo">PATH_INFO with Server Side Includes</a></h2>
 108
 109
 110     <p>Files processed for server-side includes no longer accept
 111     requests with <code>PATH_INFO</code> (trailing pathname information)
 112     by default.  You can use the <code class="directive"><a href="../mod/core.html#acceptpathinfo">AcceptPathInfo</a></code> directive to
 113     configure the server to accept requests with <code>PATH_INFO</code>.</p>
 114 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 115 <div class="section">
 116 <h2><a name="elements" id="elements">Basic Elements</a></h2>
 117     <p>The document is parsed as an HTML document, with special
 118     commands embedded as SGML comments. A command has the syntax: </p>
 119
 120     <div class="example"><p><code>
 121       &lt;!--#<var>element</var> <var>attribute</var>=<var>value</var>
 122       <var>attribute</var>=<var>value</var> ... --&gt;
 123     </code></p></div>
 124
 125     <p>The value will often be enclosed in double quotes, but single
 126     quotes (<code>'</code>) and backticks (<code>`</code>) are also
 127     possible. Many commands only allow a single attribute-value pair.
 128     Note that the comment terminator (<code>--&gt;</code>) should be
 129     preceded by whitespace to ensure that it isn't considered part of
 130     an SSI token. Note that the leading <code>&lt;!--#</code> is <em>one</em>
 131     token and may not contain any whitespaces.</p>
 132
 133     <p>The allowed elements are listed in the following table:</p>
 134
 135     <table class="bordered">
 136     <tr><th>Element</th><th>Description</th></tr>
 137     <tr><td><code><a href="#element.config">config</a></code></td>
 138         <td>configure output formats</td></tr>
 139     <tr><td><code><a href="#element.echo">echo</a></code></td>
 140         <td>print variables</td></tr>
 141     <tr><td><code><a href="#element.exec">exec</a></code></td>
 142         <td>execute external programs</td></tr>
 143     <tr><td><code><a href="#element.fsize">fsize</a></code></td>
 144         <td>print size of a file</td></tr>
 145     <tr><td><code><a href="#element.flastmod">flastmod</a></code></td>
 146         <td>print last modification time of a file</td></tr>
 147     <tr><td><code><a href="#element.include">include</a></code></td>
 148         <td>include a file</td></tr>
 149     <tr><td><code><a href="#element.printenv">printenv</a></code></td>
 150         <td>print all available variables</td></tr>
 151     <tr><td><code><a href="#element.set">set</a></code></td>
 152         <td>set a value of a variable</td></tr>
 153     </table>
 154
 155     <p>SSI elements may be defined by modules other than
 156     <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>. In fact, the <code><a href="#element.exec">exec</a></code> element is provided by
 157     <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>, and will only be available if this
 158     module is loaded.</p>
 159
 160     <h3><a name="element.config" id="element.config">The config Element</a></h3>
 161       <p>This command controls various aspects of the parsing. The
 162       valid attributes are:</p>
 163
 164       <dl>
 165       <dt><code>errmsg</code></dt>
 166       <dd>The value is a message that is sent back to the
 167       client if an error occurs while parsing the
 168       document. This overrides any <code class="directive"><a href="#ssierrormsg">SSIErrorMsg</a></code> directives.</dd>
 169
 170       <dt><code>sizefmt</code></dt>
 171       <dd>The value sets the format to be used which displaying
 172       the size of a file. Valid values are <code>bytes</code>
 173       for a count in bytes, or <code>abbrev</code> for a count
 174       in Kb or Mb as appropriate, for example a size of 1024 bytes
 175       will be printed as "1K".</dd>
 176
 177       <dt><code>timefmt</code></dt>
 178       <dd>The value is a string to be used by the
 179       <code>strftime(3)</code> library routine when printing
 180       dates.</dd>
 181       </dl>
 182
 183
 184     <h3><a name="element.echo" id="element.echo">The echo Element</a></h3>
 185       <p>This command prints one of the <a href="#includevars">include
 186       variables</a>, defined below. If the variable is unset, the result is
 187       determined by the <code class="directive"><a href="#ssiundefinedecho">SSIUndefinedEcho</a></code> directive. Any dates printed are
 188       subject to the currently configured <code>timefmt</code>.</p>
 189
 190       <p>Attributes:</p>
 191
 192       <dl>
 193       <dt><code>var</code></dt>
 194       <dd>The value is the name of the variable to print.</dd>
 195
 196       <dt><code>encoding</code></dt>
 197       <dd><p>Specifies how Apache should encode special characters
 198       contained in the variable before outputting them. If set
 199       to <code>none</code>, no encoding will be done. If set to
 200       <code>url</code>, then URL encoding (also known as %-encoding;
 201       this is appropriate for use within URLs in links, etc.) will be
 202       performed. At the start of an <code>echo</code> element,
 203       the default is set to <code>entity</code>, resulting in entity
 204       encoding (which is appropriate in the context of a block-level
 205       HTML element, <em>e.g.</em> a paragraph of text). This can be
 206       changed by adding an <code>encoding</code> attribute, which will
 207       remain in effect until the next <code>encoding</code> attribute
 208       is encountered or the element ends, whichever comes first.</p>
 209
 210       <p>The <code>encoding</code> attribute must <em>precede</em> the
 211       corresponding <code>var</code> attribute to be effective, and
 212       only special characters as defined in the ISO-8859-1 character
 213       encoding will be encoded. This encoding process may not have the
 214       desired result if a different character encoding is in use.</p>
 215
 216       <div class="warning">
 217         In order to avoid cross-site scripting issues, you should
 218         <em>always</em> encode user supplied data.
 219       </div>
 220       </dd>
 221       </dl>
 222
 223
 224     <h3><a name="element.exec" id="element.exec">The exec Element</a></h3>
 225       <p>The <code>exec</code> command executes a given shell command or
 226       CGI script. It requires <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code> to be present
 227       in the server. If <code class="directive"><a href="../mod/core.html#options">Options</a></code>
 228       <code>IncludesNOEXEC</code> is set, this command is completely
 229       disabled. The valid attributes are:</p>
 230
 231       <dl>
 232       <dt><code>cgi</code></dt>
 233       <dd><p>The value specifies a (%-encoded) URL-path to
 234       the CGI script. If the path does not begin with a slash (/),
 235       then it is taken to be relative to the current
 236       document. The document referenced by this path is
 237       invoked as a CGI script, even if the server would not
 238       normally recognize it as such. However, the directory
 239       containing the script must be enabled for CGI scripts
 240       (with <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>
 241       or <code class="directive"><a href="../mod/core.html#options">Options</a></code>
 242       <code>ExecCGI</code>).</p>
 243
 244       <p>The CGI script is given the <code>PATH_INFO</code> and query
 245       string (<code>QUERY_STRING</code>) of the original request from the
 246       client; these <em>cannot</em> be specified in the URL path. The
 247       include variables will be available to the script in addition to
 248       the standard <a href="mod_cgi.html">CGI</a> environment.</p>
 249
 250       <div class="example"><h3>Example</h3><p><code>
 251         &lt;!--#exec cgi="/cgi-bin/example.cgi" --&gt;
 252       </code></p></div>
 253
 254       <p>If the script returns a <code>Location:</code> header instead of
 255       output, then this will be translated into an HTML anchor.</p>
 256
 257       <p>The <code><a href="#includevirtual">include virtual</a></code>
 258       element should be used in preference to <code>exec cgi</code>. In
 259       particular, if you need to pass additional arguments to a CGI program,
 260       using the query string, this cannot be done with <code>exec
 261       cgi</code>, but can be done with <code>include virtual</code>, as
 262       shown here:</p>
 263
 264       <div class="example"><p><code>
 265         &lt;!--#include virtual="/cgi-bin/example.cgi?argument=value" --&gt;
 266       </code></p></div>
 267       </dd>
 268
 269       <dt><code>cmd</code></dt>
 270       <dd><p>The server will execute the given string using
 271       <code>/bin/sh</code>. The <a href="#includevars">include variables</a> are available to the command, in addition
 272       to the usual set of CGI variables.</p>
 273
 274       <p>The use of <code><a href="#includevirtual">#include virtual</a></code> is almost always prefered to using
 275       either <code>#exec cgi</code> or <code>#exec cmd</code>. The former
 276       (<code>#include virtual</code>) uses the standard Apache sub-request
 277       mechanism to include files or scripts. It is much better tested and
 278       maintained.</p>
 279
 280       <p>In addition, on some platforms, like Win32, and on unix when
 281       using <a href="../suexec.html">suexec</a>, you cannot pass arguments
 282       to a command in an <code>exec</code> directive, or otherwise include
 283       spaces in the command. Thus, while the following will work under a
 284       non-suexec configuration on unix, it will not produce the desired
 285       result under Win32, or when running suexec:</p>
 286
 287       <div class="example"><p><code>
 288         &lt;!--#exec cmd="perl /path/to/perlscript arg1 arg2" --&gt;
 289       </code></p></div>
 290       </dd>
 291       </dl>
 292
 293
 294     <h3><a name="element.fsize" id="element.fsize">The fsize Element</a></h3>
 295       <p>This command prints the size of the specified file, subject
 296       to the <code>sizefmt</code> format specification. Attributes:</p>
 297
 298       <dl>
 299       <dt><code>file</code></dt>
 300       <dd>The value is a path relative to the directory
 301       containing the current document being parsed.</dd>
 302
 303       <dt><code>virtual</code></dt>
 304       <dd>The value is a (%-encoded) URL-path. If it does not begin with
 305       a slash (/) then it is taken to be relative to the current document.
 306       Note, that this does <em>not</em> print the size of any CGI output,
 307       but the size of the CGI script itself.</dd>
 308       </dl>
 309
 310
 311     <h3><a name="element.flastmod" id="element.flastmod">The flastmod Element</a></h3>
 312       <p>This command prints the last modification date of the
 313       specified file, subject to the <code>timefmt</code> format
 314       specification. The attributes are the same as for the
 315       <code><a href="#element.fsize">fsize</a></code> command.</p>
 316
 317
 318     <h3><a name="element.include" id="element.include">The include Element</a></h3>
 319       <p>This command inserts the text of another document or file
 320       into the parsed file. Any included file is subject to the
 321       usual access control. If the directory containing the
 322       parsed file has <a href="core.html#options">Options</a>
 323       <code>IncludesNOEXEC</code> set, then only documents with
 324       a text MIME type (<code>text/plain</code>, <code>text/html</code>
 325       etc.) will be included. Otherwise CGI scripts are invoked as normal
 326       using the complete URL given in the command, including any query
 327       string.</p>
 328
 329       <p>An attribute defines the location of the document; the
 330       inclusion is done for each attribute given to the include
 331       command. The valid attributes are:</p>
 332
 333       <dl>
 334       <dt><code>file</code></dt>
 335       <dd>The value is a path relative to the directory
 336       containing the current document being parsed. It cannot
 337       contain <code>../</code>, nor can it be an absolute path.
 338       Therefore, you cannot include files that are outside of the
 339       document root, or above the current document in the directory
 340       structure. The <code>virtual</code> attribute should always be
 341       used in preference to this one.</dd>
 342
 343       <dt><code><a id="includevirtual" name="includevirtual">virtual</a></code></dt>
 344       <dd><p>The value is a (%-encoded) URL-path. The URL cannot contain a
 345       scheme or hostname, only a path and an optional query string. If it
 346       does not begin with a slash (/) then it is taken to be relative to the
 347       current document.</p>
 348
 349       <p>A URL is constructed from the attribute, and the output the
 350       server would return if the URL were accessed by the client is
 351       included in the parsed output. Thus included files can be nested.</p>
 352
 353       <p>If the specified URL is a CGI program, the program will be
 354       executed and its output inserted in place of the directive in the
 355       parsed file. You may include a query string in a CGI url:</p>
 356
 357       <div class="example"><p><code>
 358         &lt;!--#include virtual="/cgi-bin/example.cgi?argument=value" --&gt;
 359       </code></p></div>
 360
 361       <p><code>include virtual</code> should be used in preference
 362       to <code>exec cgi</code> to include the output of CGI programs
 363       into an HTML document.</p>
 364       </dd>
 365       </dl>
 366
 367
 368     <h3><a name="element.printenv" id="element.printenv">The printenv Element</a></h3>
 369       <p>This prints out a listing of all existing variables and
 370       their values. Special characters are entity encoded (see the <code><a href="#element.echo">echo</a></code> element for details)
 371       before being output. There are no attributes.</p>
 372
 373       <div class="example"><h3>Example</h3><p><code>
 374         &lt;!--#printenv --&gt;
 375       </code></p></div>
 376
 377
 378     <h3><a name="element.set" id="element.set">The set Element</a></h3>
 379       <p>This sets the value of a variable. Attributes:</p>
 380
 381       <dl>
 382       <dt><code>var</code></dt>
 383       <dd>The name of the variable to set.</dd>
 384
 385       <dt><code>value</code></dt>
 386       <dd>The value to give a variable.</dd>
 387       </dl>
 388
 389       <div class="example"><h3>Example</h3><p><code>
 390         &lt;!--#set var="category" value="help" --&gt;
 391       </code></p></div>
 392
 393 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 394 <div class="section">
 395 <h2><a name="includevars" id="includevars">Include Variables</a></h2>
 396
 397
 398     <p>In addition to the variables in the standard CGI environment,
 399     these are available for the <code>echo</code> command, for
 400     <code>if</code> and <code>elif</code>, and to any program
 401     invoked by the document.</p>
 402
 403     <dl>
 404       <dt><code>DATE_GMT</code></dt>
 405       <dd>The current date in Greenwich Mean Time.</dd>
 406
 407       <dt><code>DATE_LOCAL</code></dt>
 408       <dd>The current date in the local time zone.</dd>
 409
 410       <dt><code>DOCUMENT_NAME</code></dt>
 411       <dd>The filename (excluding directories) of the document
 412       requested by the user.</dd>
 413
 414       <dt><code>DOCUMENT_URI</code></dt>
 415       <dd>The (%-decoded) URL path of the document requested by the
 416       user. Note that in the case of nested include files, this is
 417       <em>not</em> the URL for the current document.  Note also that
 418       if the URL is modified internally (e.g. by an <code class="directive"><a href="../mod/mod_alias.html#alias">alias</a></code> or <code class="directive"><a href="../mod/mod_dir.html#directoryindex">directoryindex</a></code>), the modified
 419       URL is shown.</dd>
 420
 421       <dt><code>LAST_MODIFIED</code></dt>
 422       <dd>The last modification date of the document requested by
 423       the user.</dd>
 424
 425       <dt><code>QUERY_STRING_UNESCAPED</code></dt>
 426       <dd>If a query string is present, this variable contains the
 427       (%-decoded) query string, which is <em>escaped</em> for shell
 428       usage (special characters like <code>&amp;</code> etc. are
 429       preceded by backslashes).</dd>
 430     </dl>
 431 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 432 <div class="section">
 433 <h2><a name="substitution" id="substitution">Variable Substitution</a></h2>
 434
 435     <p>Variable substitution is done within quoted strings in most
 436     cases where they may reasonably occur as an argument to an SSI
 437     directive. This includes the <code>config</code>,
 438     <code>exec</code>, <code>flastmod</code>, <code>fsize</code>,
 439     <code>include</code>, <code>echo</code>, and <code>set</code>
 440     directives, as well as the arguments to conditional operators.
 441     You can insert a literal dollar sign into the string using backslash
 442     quoting:</p>
 443
 444     <div class="example"><p><code>
 445       &lt;!--#if expr="$a = \$test" --&gt;
 446     </code></p></div>
 447
 448     <p>If a variable reference needs to be substituted in the
 449     middle of a character sequence that might otherwise be
 450     considered a valid identifier in its own right, it can be
 451     disambiguated by enclosing the reference in braces,
 452     <em>a la</em> shell substitution:</p>
 453
 454     <div class="example"><p><code>
 455       &lt;!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" --&gt;
 456     </code></p></div>
 457
 458     <p>This will result in the <code>Zed</code> variable being set
 459     to "<code>X_Y</code>" if <code>REMOTE_HOST</code> is
 460     "<code>X</code>" and <code>REQUEST_METHOD</code> is
 461     "<code>Y</code>".</p>
 462
 463     <p>The below example will print "in foo" if the
 464     <code>DOCUMENT_URI</code> is <code>/foo/file.html</code>, "in bar"
 465     if it is <code>/bar/file.html</code> and "in neither" otherwise:</p>
 466
 467     <div class="example"><p><code>
 468       &lt;!--#if expr='"$DOCUMENT_URI" = "/foo/file.html"' --&gt;<br />
 469       <span class="indent">
 470         in foo<br />
 471       </span>
 472       &lt;!--#elif expr='"$DOCUMENT_URI" = "/bar/file.html"' --&gt;<br />
 473       <span class="indent">
 474         in bar<br />
 475       </span>
 476       &lt;!--#else --&gt;<br />
 477       <span class="indent">
 478         in neither<br />
 479       </span>
 480       &lt;!--#endif --&gt;
 481     </code></p></div>
 482 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 483 <div class="section">
 484 <h2><a name="flowctrl" id="flowctrl">Flow Control Elements</a></h2>
 485
 486
 487     <p>The basic flow control elements are:</p>
 488
 489     <div class="example"><p><code>
 490       &lt;!--#if expr="<var>test_condition</var>" --&gt;<br />
 491       &lt;!--#elif expr="<var>test_condition</var>" --&gt;<br />
 492       &lt;!--#else --&gt;<br />
 493       &lt;!--#endif --&gt;
 494     </code></p></div>
 495
 496     <p>The <code>if</code> element works like an if statement in a
 497     programming language. The test condition is evaluated and if
 498     the result is true, then the text until the next <code>elif</code>,
 499     <code>else</code> or <code>endif</code> element is included in the
 500     output stream.</p>
 501
 502     <p>The <code>elif</code> or <code>else</code> statements are be used
 503     to put text into the output stream if the original
 504     <var>test_condition</var> was false. These elements are optional.</p>
 505
 506     <p>The <code>endif</code> element ends the <code>if</code> element
 507     and is required.</p>
 508
 509     <p><var>test_condition</var> is one of the following:</p>
 510
 511     <dl>
 512       <dt><code><var>string</var></code></dt>
 513       <dd>true if <var>string</var> is not empty</dd>
 514
 515       <dt><code><var>string1</var> = <var>string2</var><br />
 516       <var>string1</var> != <var>string2</var></code></dt>
 517
 518       <dd><p>Compare <var>string1</var> with <var>string2</var>. If
 519       <var>string2</var> has the form <code>/<var>string2</var>/</code>
 520       then it is treated as a regular expression. Regular expressions are
 521       implemented by the <a href="http://www.pcre.org">PCRE</a> engine and
 522       have the same syntax as those in <a href="http://www.perl.com">perl
 523       5</a>.</p>
 524
 525       <p>If you are matching positive (<code>=</code>), you can capture
 526       grouped parts of the regular expression. The captured parts are
 527       stored in the special variables <code>$1</code> ..
 528       <code>$9</code>.</p>
 529
 530       <div class="example"><h3>Example</h3><p><code>
 531         &lt;!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" --&gt;<br />
 532         <span class="indent">
 533           &lt;!--#set var="session" value="$1" --&gt;<br />
 534         </span>
 535         &lt;!--#endif --&gt;
 536       </code></p></div>
 537       </dd>
 538
 539       <dt><code><var>string1</var> &lt; <var>string2</var><br />
 540        <var>string1</var> &lt;= <var>string2</var><br />
 541        <var>string1</var> &gt; <var>string2</var><br />
 542        <var>string1</var> &gt;= <var>string2</var></code></dt>
 543
 544       <dd>Compare <var>string1</var> with <var>string2</var>. Note, that
 545       strings are compared <em>literally</em> (using
 546       <code>strcmp(3)</code>). Therefore the string "100" is less than
 547       "20".</dd>
 548
 549       <dt><code>( <var>test_condition</var> )</code></dt>
 550       <dd>true if <var>test_condition</var> is true</dd>
 551
 552       <dt><code>! <var>test_condition</var></code></dt>
 553       <dd>true if <var>test_condition</var> is false</dd>
 554
 555       <dt><code><var>test_condition1</var> &amp;&amp;
 556         <var>test_condition2</var></code></dt>
 557       <dd>true if both <var>test_condition1</var> and
 558       <var>test_condition2</var> are true</dd>
 559
 560       <dt><code><var>test_condition1</var> ||
 561         <var>test_condition2</var></code></dt>
 562       <dd>true if either <var>test_condition1</var> or
 563       <var>test_condition2</var> is true</dd>
 564     </dl>
 565
 566     <p>"<code>=</code>" and "<code>!=</code>" bind more tightly than
 567     "<code>&amp;&amp;</code>" and "<code>||</code>". "<code>!</code>" binds
 568     most tightly. Thus, the following are equivalent:</p>
 569
 570     <div class="example"><p><code>
 571       &lt;!--#if expr="$a = test1 &amp;&amp; $b = test2" --&gt;<br />
 572       &lt;!--#if expr="($a = test1) &amp;&amp; ($b = test2)" --&gt;
 573     </code></p></div>
 574
 575     <p>The boolean operators <code>&amp;&amp;</code> and <code>||</code>
 576     share the same priority. So if you want to bind such an operator more
 577     tightly, you should use parentheses.</p>
 578
 579     <p>Anything that's not recognized as a variable or an operator
 580     is treated as a string. Strings can also be quoted:
 581     <code>'string'</code>. Unquoted strings can't contain whitespace
 582     (blanks and tabs) because it is used to separate tokens such as
 583     variables. If multiple strings are found in a row, they are
 584     concatenated using blanks. So,</p>
 585
 586     <div class="example"><p><code><var>string1</var>&nbsp;&nbsp;&nbsp;&nbsp;<var>string2</var></code> results in <code><var>string1</var>&nbsp;<var>string2</var></code><br />
 587       <br />
 588       and<br />
 589       <br />
 590       <code>'<var>string1</var>&nbsp;&nbsp;&nbsp;&nbsp;<var>string2</var>'</code> results in <code><var>string1</var>&nbsp;&nbsp;&nbsp;&nbsp;<var>string2</var></code>.</p></div>
 591
 592     <div class="note"><h3>Escaping slashes in regex strings</h3>
 593      <p>All slashes which are not intended to act as delimiters in your regex must
 594      be escaped.  This is regardless of their meaning to the regex engine.</p>
 595     </div>
 596
 597
 598 </div>
 599 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 600 <div class="directive-section"><h2><a name="SSIEndTag" id="SSIEndTag">SSIEndTag</a> <a name="ssiendtag" id="ssiendtag">Directive</a></h2>
 601 <table class="directive">
 602 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>String that ends an include element</td></tr>
 603 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIEndTag <var>tag</var></code></td></tr>
 604 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIEndTag "--&gt;"</code></td></tr>
 605 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 606 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 607 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 608 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.0.30 and later.</td></tr>
 609 </table>
 610     <p>This directive changes the string that <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
 611     looks for to mark the end of an include element.</p>
 612
 613     <div class="example"><h3>Example</h3><p><code>
 614       SSIEndTag "%&gt;"
 615     </code></p></div>
 616
 617
 618 <h3>See also</h3>
 619 <ul>
 620 <li><code class="directive"><a href="#ssistarttag">SSIStartTag</a></code></li>
 621 </ul>
 622 </div>
 623 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 624 <div class="directive-section"><h2><a name="SSIErrorMsg" id="SSIErrorMsg">SSIErrorMsg</a> <a name="ssierrormsg" id="ssierrormsg">Directive</a></h2>
 625 <table class="directive">
 626 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Error message displayed when there is an SSI
 627 error</td></tr>
 628 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIErrorMsg <var>message</var></code></td></tr>
 629 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIErrorMsg "[an error occurred while processing this
 630 directive]"</code></td></tr>
 631 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 632 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
 633 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 634 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 635 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.0.30 and later.</td></tr>
 636 </table>
 637     <p>The <code class="directive">SSIErrorMsg</code> directive changes the error
 638     message displayed when <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> encounters an
 639     error. For production servers you may consider changing the default
 640     error message to <code>"&lt;!-- Error --&gt;"</code> so that
 641     the message is not presented to the user.</p>
 642
 643     <p>This directive has the same effect as the <code>&lt;!--#config
 644     errmsg=<var>message</var> --&gt;</code> element.</p>
 645
 646     <div class="example"><h3>Example</h3><p><code>
 647       SSIErrorMsg "&lt;!-- Error --&gt;"
 648     </code></p></div>
 649
 650 </div>
 651 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 652 <div class="directive-section"><h2><a name="SSIStartTag" id="SSIStartTag">SSIStartTag</a> <a name="ssistarttag" id="ssistarttag">Directive</a></h2>
 653 <table class="directive">
 654 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>String that starts an include element</td></tr>
 655 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIStartTag <var>tag</var></code></td></tr>
 656 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIStartTag "&lt;!--#"</code></td></tr>
 657 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 658 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 659 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 660 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.0.30 and later.</td></tr>
 661 </table>
 662     <p>This directive changes the string that <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
 663     looks for to mark an include element to process.</p>
 664
 665     <p>You may want to use this option if you have 2 servers parsing the
 666     output of a file each processing different commands (possibly at
 667     different times).</p>
 668
 669     <div class="example"><h3>Example</h3><p><code>
 670       SSIStartTag "&lt;%"<br />
 671       SSIEndTag   "%&gt;"
 672     </code></p></div>
 673
 674     <p>The example given above, which also specifies a matching
 675     <code class="directive"><a href="#ssiendtag">SSIEndTag</a></code>, will
 676     allow you to use SSI directives as shown in the example
 677     below:</p>
 678
 679     <div class="example"><h3>SSI directives with alternate start and end tags</h3><p><code>
 680       &lt;%printenv %&gt;
 681     </code></p></div>
 682
 683 <h3>See also</h3>
 684 <ul>
 685 <li><code class="directive"><a href="#ssiendtag">SSIEndTag</a></code></li>
 686 </ul>
 687 </div>
 688 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 689 <div class="directive-section"><h2><a name="SSITimeFormat" id="SSITimeFormat">SSITimeFormat</a> <a name="ssitimeformat" id="ssitimeformat">Directive</a></h2>
 690 <table class="directive">
 691 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the format in which date strings are
 692 displayed</td></tr>
 693 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSITimeFormat <var>formatstring</var></code></td></tr>
 694 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSITimeFormat "%A, %d-%b-%Y %H:%M:%S %Z"</code></td></tr>
 695 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 696 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
 697 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 698 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 699 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.0.30 and later.</td></tr>
 700 </table>
 701 <p>This directive changes the format in which date strings are displayed
 702     when echoing <code>DATE</code> environment variables. The
 703     <var>formatstring</var> is as in <code>strftime(3)</code> from the
 704     C standard library.</p>
 705
 706     <p>This directive has the same effect as the <code>&lt;!--#config
 707     timefmt=<var>formatstring</var> --&gt;</code> element.</p>
 708
 709     <div class="example"><h3>Example</h3><p><code>
 710       SSITimeFormat "%R, %B %d, %Y"
 711     </code></p></div>
 712
 713     <p>The above directive would cause times to be displayed in the
 714     format "22:26, June 14, 2002".</p>
 715
 716 </div>
 717 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 718 <div class="directive-section"><h2><a name="SSIUndefinedEcho" id="SSIUndefinedEcho">SSIUndefinedEcho</a> <a name="ssiundefinedecho" id="ssiundefinedecho">Directive</a></h2>
 719 <table class="directive">
 720 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>String displayed when an unset variable is echoed</td></tr>
 721 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIUndefinedEcho <var>string</var></code></td></tr>
 722 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIUndefinedEcho "(none)"</code></td></tr>
 723 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 724 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 725 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 726 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.0.34 and later.</td></tr>
 727 </table>
 728     <p>This directive changes the string that <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
 729     displays when a variable is not set and "echoed".</p>
 730
 731     <div class="example"><h3>Example</h3><p><code>
 732       SSIUndefinedEcho "&lt;!-- undef --&gt;"
 733     </code></p></div>
 734
 735 </div>
 736 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 737 <div class="directive-section"><h2><a name="XBitHack" id="XBitHack">XBitHack</a> <a name="xbithack" id="xbithack">Directive</a></h2>
 738 <table class="directive">
 739 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Parse SSI directives in files with the execute bit
 740 set</td></tr>
 741 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>XBitHack on|off|full</code></td></tr>
 742 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>XBitHack off</code></td></tr>
 743 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 744 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
 745 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 746 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 747 </table>
 748     <p>The <code class="directive">XBitHack</code> directive controls the parsing
 749     of ordinary html documents. This directive only affects files associated
 750     with the MIME type <code>text/html</code>. <code class="directive">XBitHack</code> can take on the following values:</p>
 751
 752     <dl>
 753       <dt><code>off</code></dt>
 754       <dd>No special treatment of executable files.</dd>
 755
 756       <dt><code>on</code></dt>
 757       <dd>Any <code>text/html</code> file that has the user-execute bit
 758       set will be treated as a server-parsed html document.</dd>
 759
 760       <dt><code>full</code></dt>
 761       <dd>As for <code>on</code> but also test the group-execute bit.
 762       If it is set, then set the <code>Last-modified</code> date of the
 763       returned file to be the last modified time of the file. If
 764       it is not set, then no last-modified date is sent. Setting
 765       this bit allows clients and proxies to cache the result of
 766       the request.
 767
 768       <div class="note"><h3>Note</h3>
 769       <p>You would not want to use the full option, unless you assure the
 770       group-execute bit is unset for every SSI script which might <code>#include</code> a CGI or otherwise produces different output on
 771       each hit (or could potentially change on subsequent requests).</p>
 772       </div>
 773       </dd>
 774     </dl>
 775
 776
 777 </div>
 778 </div>
 779 <div class="bottomlang">
 780 <p><span>Available Languages: </span><a href="../en/mod/mod_include.html" title="English">&nbsp;en&nbsp;</a> |
 781 <a href="../ja/mod/mod_include.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a></p>
 782 </div><div id="footer">
 783 <p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 784 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 785 </body></html>