| <!--%hypertext --> |
| <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> |
| <HTML> |
| <HEAD> |
| <TITLE>Apache module mod_include</TITLE> |
| </HEAD> |
| |
| <BODY> |
| <IMG SRC="../images/apache_sub.gif" ALT=""> |
| <!--/%hypertext --> |
| <H1>Module mod_include</h1> |
| |
| This module is contained in the <code>mod_include.c</code> file, and |
| is compiled in by default. It provides for server-parsed html documents, |
| known as SPML documents. |
| Any document with mime type <code>text/x-server-parsed-html</code> or |
| <code>text/x-server-parsed-html3</code> will be parsed by this module, |
| with the resulting output given the mime type <code>text/html</code>. |
| <!--%plaintext <?INDEX {\tt text/x-server-parsed-html} mime type> --> |
| <!--%plaintext <?INDEX {\tt text/x-server-parsed-html3} mime type> --> |
| |
| <h2>SPML -- Include file Format</h2> |
| |
| The document is parsed as an HTML document, with special commands embedded |
| as SGML comments. A command has the syntax: |
| <blockquote><code> |
| <!--#</code><em>element attribute=value attribute=value ...</em> <code>--> |
| </code></blockquote> |
| The value will often be enclosed in double quotes; many commands only allow |
| a single attribute-value pair. |
| <p> |
| The allowed elements are:<p> |
| <dl> |
| <dt><strong>config</strong> |
| <dd> |
| <!--%plaintext <?INDEX {\tt config} SPML element> --> |
| This command controls various aspects of the parsing. The valid attributes |
| are: |
| <dl> |
| <dt>errmsg |
| <dd>The value is a message that is sent back to the client if an error occurs |
| whilst parsing the document. |
| <dt>sizefmt |
| <dd>The value sets the format to be used which displaying the size of a file. |
| Valid values are <code>bytes</code> for a count in bytes, or |
| <code>abbrev</code> for a count in Kb or Mb as appropriate. |
| <dt>timefmt |
| <dd>The value is a string to be used by the <code>strftime(3)</code> library |
| routine when printing dates. |
| </dl> |
| |
| <dt><strong>echo</strong> |
| <dd> |
| <!--%plaintext <?INDEX {\tt echo} SPML element> --> |
| This command prints one of the include variables, defined below. |
| If the variable is unset, it is printed as <code>(none)</code>. |
| Any dates printed are subject to the currently configured <code>timefmt</code>. |
| Attributes: |
| <dl> |
| <dt>var |
| <dd>The value is the name of the variable to print. |
| </dl> |
| |
| <dt><strong>exec</strong> |
| <dd> |
| <!--%plaintext <?INDEX {\tt exec} SPML element> --> |
| The exec command executes a given shell command or CGI script. |
| The IncludesNOEXEC <A HREF="core.html#options">Option</A> disables this command |
| completely. The valid attributes are: |
| <dl> |
| <dt>cgi |
| <dd> |
| <!--%plaintext <?INDEX CGI scripts, {\tt exec} element and> --> |
| The value specifies a (%-encoded) URL relative path to the CGI script. |
| If the path does not begin with a (/), then it is taken to be relative to |
| the current document. The document referenced by this path is invoked |
| as a CGI script, even if the server would not normally recognise it as |
| such. However, the directory containing the script must be enabled for |
| CGI scripts (with <A HREF="mod_alias.html#scriptalias">ScriptAlias</A> |
| or the ExecCGI <A HREF="core.html#options">Option</A>).<p> |
| <!--%plaintext <?INDEX PATH\_INFO CGI variable> --> |
| <!--%plaintext <?INDEX QUERY\_STRING CGI variable> --> |
| The CGI script is given the PATH_INFO and query string (QUERY_STRING) of the |
| original request from the client; these cannot be specified in the URL path. |
| The include variables will be available to the script in addition to the |
| standard <A HREF="mod_cgi.html">CGI</A> environment.<p> |
| If the script returns a Location: header instead of output, then this |
| will be translated into an HTML anchor.<p> |
| The <code>include virtual</code> element should be used in preference to |
| <code>exec cgi</code>. |
| <dt>cmd |
| <dd>The server will execute the given string using <code>/bin/sh</code>. |
| The include variables are available to the command. |
| </dl> |
| |
| <dt><strong>fsize</strong> |
| <dd> |
| <!--%plaintext <?INDEX {\tt fsize} SPML element> --> |
| This command prints the size of the specified file, subject to the |
| <code>sizefmt</code> format specification. Attributes: |
| <dl> |
| <dt>file |
| <dd>The value is a path relative to the directory containing the current |
| document being parsed. |
| <dt>virtual |
| <dd>The value is a (%-encoded) URL-path relative to the current document being |
| parsed. If it does not begin with a slash (/) then it is taken to be relative |
| to the current document. |
| </dl> |
| |
| <dt><strong>flastmod</strong> |
| <dd><!--%plaintext <?INDEX {\tt exec} flastmod element> --> |
| This command prints the last modification date of the specified file, |
| subject to the <code>timefmt</code> format specification. The attributes are |
| the same as for the <code>fsize</code> command. |
| |
| <dt><strong>include</strong> |
| <dd><!--%plaintext <?INDEX {\tt include} SPML element> --> |
| This command inserts the text of another document or file into the parsed |
| file. Any included file is subject to the usual access control. If the |
| directory containing the parsed file has the |
| <A HREF="core.html#options">Option</A> |
| IncludesNOEXEC set, and the including the document would cause a program |
| to be executed, then it will not be included; this prevents the execution of |
| CGI scripts. Otherwise CGI scripts are invoked as normal using the complete |
| URL given in the command, including any query string. |
| <!--%plaintext <?INDEX CGI scripts, {\tt include} element and> --> |
| <p> |
| |
| An attribute defines the location of the document; the inclusion is done for |
| each attribute given to the include command. The valid attributes are: |
| <dl> |
| <dt>file |
| <dd>The value is a path relative to the directory containing the current |
| document being parsed. It cannot contain <code>../</code>, nor can it be an |
| absolute path. The <code>virtual</code> attribute should always be used |
| in preference to this one. |
| <dt>virtual |
| <dd>The value is a (%-encoded) URL relative to the current document being |
| parsed. The URL cannot contain a scheme or hostname, only a path and |
| an optional query string. If it does not begin with a slash (/) then it |
| is taken to be relative to the current document. |
| </dl> |
| A URL is constructed from the attribute, and the output the server |
| would return if the URL were accessed by the client is included in the parsed |
| output. Thus included files can be nested. |
| </dl> |
| |
| <h2>Include variables</h2> |
| These are available for the <code>echo</code> command, and to any program |
| invoked by the document. |
| <dl> |
| <dt>DATE_GMT |
| <dd>The current date in Greenwich Mean Time. |
| <dt>DATE_LOCAL |
| <dd>The current date in the local time zone. |
| <dt>DOCUMENT_NAME |
| <dd>The filename (excluding directories) of the document requested by the |
| user. |
| <dt>DOCUMENT_URI |
| <dd>The (%-decoded) URL path of the document requested by the user. Note that |
| in the case of nested include files, this is <em>not</em> then URL for the |
| current document. |
| <dt>LAST_MODIFIED |
| <dd>The last modification date of the document requested by the user. |
| </dl> |
| <p> |
| |
| <!--%hypertext --> |
| <hr> |
| <h2>Directives</h2> |
| <ul> |
| <li><A HREF="#xbithack">XBitHack</A> |
| </ul> |
| <hr> |
| <!--/%hypertext --> |
| |
| <A name="xbithack"><h2>XBitHack</h2></A> |
| <!--%plaintext <?INDEX {\tt XBitHack} directive> --> |
| <strong>Syntax:</strong> XBitHack <em>status</em><br> |
| <strong>Default:</strong> <code>XBitHack off</code><br> |
| <Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> |
| <Strong>Override:</strong> Options<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_include<p> |
| |
| The XBitHack directives controls the parsing of ordinary html documents. |
| <em>Status</em> can have the following values: |
| <dl> |
| <dt>off |
| <dd>No special treatment of executable files. |
| <dt>on |
| <dd>Any file that has the user-execute bit set will be treated as a |
| server-parsed html document. |
| <dt>full |
| <dd>As for <code>on</code> but also test the group-execute bit. If it |
| is set, then set the Last-modified date of the returned file to be the |
| last modified time of the file. If it is not set, then no last-modified date |
| is sent. Setting this bit allows clients and proxies to cache the result of |
| the request. |
| </dl> |
| <p> |
| <!--%hypertext --> |
| <hr> |
| |
| <A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> |
| <A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> |
| |
| </BODY> |
| </HTML> |
| <!--/%hypertext --> |