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