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