httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sl...@apache.org
Subject cvs commit: httpd-2.0/docs/manual/mod mod_example.xml mod_ext_filter.xml mod_file_cache.xml mod_headers.xml mod_imap.xml
Date Fri, 08 Mar 2002 17:19:00 GMT
slive       02/03/08 09:19:00

  Added:       docs/manual/mod mod_example.xml mod_ext_filter.xml
                        mod_file_cache.xml mod_headers.xml mod_imap.xml
  Log:
  Add some more xml versions.
  
  Revision  Changes    Path
  1.1                  httpd-2.0/docs/manual/mod/mod_example.xml
  
  Index: mod_example.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
  <?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
  <modulesynopsis>
  
  <name>mod_example</name>
  <description>Illustrates the Apache module API</description>
  <status>Experimental</status>
  <sourcefile>mod_example.c</sourcefile>
  <identifier>example_module</identifier>
  
  <summary>
  <note type="warning">
        This document has not been updated
        to take into account changes made in the 2.0 version of the
        Apache HTTP Server. Some of the information may still be
        relevant, but please use it with care.
  </note>
  
      <p>The files in the <code>src/modules/example directory</code>
      under the Apache distribution directory tree are provided as an
      example to those that wish to write modules that use the Apache
      API.</p>
  
      <p>The main file is <code>mod_example.c</code>, which
      illustrates all the different callback mechanisms and call
      syntaxes. By no means does an add-on module need to include
      routines for all of the callbacks - quite the contrary!</p>
  
      <p>The example module is an actual working module. If you link
      it into your server, enable the "example-handler" handler for a
      location, and then browse to that location, you will see a
      display of some of the tracing the example module did as the
      various callbacks were made.</p>
  </summary>
  
  <section><title>Compiling the example module</title>
  
      <p>To include the example module in your server, follow the
      steps below:</p>
  
      <ol>
        <li>
          Uncomment the "AddModule modules/example/mod_example" line
          near the bottom of the <code>src/Configuration</code> file.
          If there isn't one, add it; it should look like this: 
  <example>
       AddModule modules/example/mod_example.o
  </example>
        </li>
  
        <li>Run the <code>src/Configure</code> script
        ("<code>cd&nbsp;src;&nbsp;./Configure</code>"). This will
        build the Makefile for the server itself, and update the
        <code>src/modules/Makefile</code> for any additional modules
        you have requested from beneath that subdirectory.</li>
  
        <li>Make the server (run "<code>make</code>" in the
        <code>src</code> directory).</li>
      </ol>
  
      <p>To add another module of your own:</p>
  
      <ol type="A">
        <li><code>mkdir src/modules/<em>mymodule</em></code></li>
  
        <li><code>cp src/modules/example/*
        src/modules/<em>mymodule</em></code></li>
  
        <li>Modify the files in the new directory.</li>
  
        <li>Follow steps [1] through [3] above, with appropriate
        changes.</li>
      </ol>
  </section>
  
  <section><title>Using the <code>mod_example</code> Module</title>
  
      <p>To activate the example module, include a block similar to
      the following in your <code>srm.conf</code> file:</p>
  <example>
     &lt;Location /example-info&gt;<br />
         SetHandler example-handler<br />
     &lt;/Location&gt;
  </example>
  
      <p>As an alternative, you can put the following into a <a
      href="core.html#accessfilename"><code>.htaccess</code></a> file
      and then request the file "test.example" from that location:</p>
  <example>
     AddHandler example-handler .example
  </example>
  
      <p>After reloading/restarting your server, you should be able
      to browse to this location and see the brief display mentioned
      earlier.</p>
  </section>
  
  <directivesynopsis>
  <name>Example</name>
  <description>Demonstration directive to illustrate the Apache module
  API</description>
  <syntax>Example</syntax>
  <contextlist><context>server config</context>
  <context>virtual host</context><context>directory</context>
  <context>.htaccess</context></contextlist>
  
  <usage>
      <p>The <directive>Example</directive> directive just sets a demonstration
      flag which the example module's content handler displays. It
      takes no arguments. If you browse to an URL to which the
      example content-handler applies, you will get a display of the
      routines within the module and how and in what order they were
      called to service the document request. The effect of this
      directive one can observe under the point "<code>Example
      directive declared here: YES/NO</code>".</p>
  </usage>
  </directivesynopsis>
  
  </modulesynopsis>
  
  
  
  1.1                  httpd-2.0/docs/manual/mod/mod_ext_filter.xml
  
  Index: mod_ext_filter.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
  <?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
  <modulesynopsis>
  
  <name>mod_ext_filter</name>
  <description>Pass the response body
      through an external program before delivery to the
      client</description>
  <status>Experimental</status>
  <sourcefile>mod_ext_filter.c</sourcefile>
  <identifier>ext_filter_module</identifier>
  
  <summary>
      <p>This is an <strong>experimental</strong> module and should
      be used with care. Test your <module>mod_ext_filter</module>
      configuration carefully to ensure that it performs the desired
      function. You may wish to review <a href="../filter.html">
      this information</a> for background on the Apache filtering 
      model.</p>
  
      <p><module>mod_ext_filter</module> presents a simple and familiar
      programming model for filters. With this module, a program
      which reads from stdin and writes to stdout (i.e., a Unix-style
      filter command) can be a filter for Apache. This filtering
      mechanism is much slower than using a filter which is specially
      written for the Apache API and runs inside of the Apache server
      process, but it does have the following benefits:</p>
  
      <ul>
        <li>the programming model is much simpler</li>
  
        <li>any programming/scripting language can be used, provided
        that it allows the program to read from standard input and
        write to standard output</li>
  
        <li>existing programs can be used unmodified as Apache
        filters</li>
      </ul>
  
      <p>Even when the performance characteristics are not suitable
      for production use, <code>mod_ext_filter</code> can be used as
      a prototype environment for filters.</p>
  </summary>
  
  <section><title>Examples</title>
  
  <section><title>Generating HTML from some other type of response</title>
  <example>
  <pre>
      # mod_ext_filter directive to define a filter to HTML-ize text/c files 
      # using the external program /usr/bin/enscript, with the type of the 
      # result set to text/html
      ExtFilterDefine c-to-html mode=output intype=text/c outtype=text/html \
                      cmd="/usr/bin/enscript --color -W html -Ec -o - -"
  
      &lt;Directory "/export/home/trawick/apacheinst/htdocs/c"&gt;
  
      # core directive to cause the new filter to be run on output
      SetOutputFilter c-to-html
  
      # mod_mime directive to set the type of .c files to text/c
      AddType text/c .c
  
      # mod_ext_filter directive to set the debug level just high 
      # enough to see a log message per request showing the configuration
      # in force
      ExtFilterOptions DebugLevel=1
  
      &lt;/Directory&gt;
  </pre>
  </example>
  </section>
  
  <section><title>Implementing a content encoding filter</title>
  <example>
  <pre>
    # mod_ext_filter directive to define the external filter
    ExtFilterDefine gzip mode=output cmd=/bin/gzip
  
    &lt;Location /gzipped&gt;
  
    # core directive to cause the gzip filter to be run on output
    SetOutputFilter gzip
  
    # mod_header directive to add "Content-Encoding: gzip" header field
    Header set Content-Encoding gzip
  
    &lt;/Location&gt;
  </pre>
  </example>
  
    <p>Note: this gzip example is just for the purposes of illustration.
    Please refer to <module>mod_deflate</module> for a practical
    implementation.</p>
  </section>
  
  <section><title>Slowing down the server</title>
  <example>
  <pre>
    # mod_ext_filter directive to define a filter which runs everything 
    # through cat; cat doesn't modify anything; it just introduces extra
    # pathlength and consumes more resources
    ExtFilterDefine slowdown mode=output cmd=/bin/cat preservescontentlength
  
    &lt;Location /&gt;
  
    # core directive to cause the slowdown filter to be run several times on 
    # output
    SetOutputFilter slowdown slowdown slowdown
  
    &lt;/Location&gt;
  </pre>
  </example>
  </section>
  
  </section> <!-- Examples -->
  
  <directivesynopsis>
  <name>ExtFilterDefine</name>
  <syntax>ExtFilterDefine <em>filtername</em> <em>parameters</em></syntax>
  <contextlist><context>server config</context></contextlist>
  
  <usage>
      <p>The <directive>ExtFilterDefine</directive> directive defines the
      characteristics of an external filter, including the program to
      run and its arguments.</p>
  
      <p><em>filtername</em> specifies the name of the filter being
      defined. This name can then be used in SetOutputFilter
      directives. It must be unique among all registered filters.
      <em>At the present time, no error is reported by the
      register-filter API, so a problem with duplicate names isn't
      reported to the user.</em></p>
  
      <p>Subsequent parameters can appear in any order and define the
      external command to run and certain other characteristics. The
      only required parameter is <em>cmd=</em>. These parameters
      are:</p>
  
      <dl>
        <dt>cmd=<em>cmdline</em></dt>
  
        <dd>The <code>cmd=</code> keyword allows you to specify the
        external command to run. If there are arguments after the
        program name, the command line should be surrounded in
        quotation marks.</dd>
  
        <dt>mode=<em>mode</em></dt>
  
        <dd><em>mode</em> should be <em>output</em> for now (the
        default). In the future, <em>mode=input</em> will be used to
        specify a filter for request bodies.</dd>
  
        <dt>intype=<em>imt</em></dt>
  
        <dd>This parameter specifies the internet media type (i.e.,
        MIME type) of documents which should be filtered. By default,
        all documents are filtered. If <code>intype=</code> is
        specified, the filter will be disabled for documents of other
        types.</dd>
  
        <dt>outtype=<em>imt</em></dt>
  
        <dd>This parameter specifies the internet media type (i.e.,
        MIME type) of filtered documents. It is useful when the
        filter changes the internet media type as part of the
        filtering operation. By default, the internet media type is
        unchanged.</dd>
  
        <dt>PreservesContentLength</dt>
  
        <dd>The <code>PreservesContentLength</code> keyword specifies
        that the filter preserves the content length. This is not the
        default, as most filters change the content length. In the
        event that the filter doesn't modify the length, this keyword
        should be specified.</dd>
      </dl>
  </usage>
  </directivesynopsis>
  
  <directivesynopsis>
  <name>ExtFilterOptions</name>
  <syntax>ExtFilterOptions
      <em>option</em> [<em>option</em>] ...</syntax>
  <default>ExtFilterOptions DebugLevel=0 NoLogStderr</default>
  <contextlist><context>directory</context></contextlist>
  
  <usage>
      <p>The <directive>ExtFilterOptions</directive> directive specifies
      special processing options for <code>mod_ext_filter</code>.
      <em>Option</em> can be one of</p>
  
      <dl>
        <dt>DebugLevel=<em>n</em></dt>
  
        <dd>
          The <code>DebugLevel</code> keyword allows you to specify
          the level of debug messages generated by
          <code>mod_ext_filter</code>. By default, no debug messages
          are generated. This is equivalent to
          <code>DebugLevel=0</code>. With higher numbers, more debug
          messages are generated, and server performance will be
          degraded. The actual meanings of the numeric values are
          described with the definitions of the DBGLVL_ constants
          near the beginning of <code>mod_ext_filter.c</code>. 
  
          <p>Note: The core directive LogLevel should be used to
          cause debug messages to be stored in the Apache error
          log.</p>
        </dd>
  
        <dt>LogStderr | NoLogStderr</dt>
  
        <dd>The <code>LogStderr</code> keyword specifies that
        messages written to standard error by the external filter
        program will be saved in the Apache error log.
        <code>NoLogStderr</code> disables this feature.</dd>
      </dl>
  
       <p>Example:</p>
  <example>
      ExtFilterOptions  LogStderr DebugLevel=0
  </example>
  
      <p>Messages written to the filter's standard error will be stored
      in the Apache error log. No debug messages will be generated by
      <module>mod_ext_filter</module>. </p>
  </usage>
  </directivesynopsis>
  
  </modulesynopsis>
  
  
  1.1                  httpd-2.0/docs/manual/mod/mod_file_cache.xml
  
  Index: mod_file_cache.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
  <?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
  <modulesynopsis>
  
  <name>mod_file_cache</name>
  <description>Caches a static list of files in memory</description>
  <status>Experimental</status>
  <sourcefile>mod_file_cache.c</sourcefile>
  <identifier>file_cache_module</identifier>
  
  <summary>
  
  <note type="warning">
  This module should be used with care. You can easily
      create a broken site using mod_file_cache, so read this
      document carefully.
  </note>
  
      <p><em>Caching</em> frequently requested files that change very
      infrequently is a technique for reducing server load.
      mod_file_cache provides two techniques for caching frequently
      requested <em>static</em> files. Through configuration
      directives, you can direct mod_file_cache to either open then
      mmap()a file, or to pre-open a file and save the file's open
      <em>file handle</em>. Both techniques reduce server load when
      processing requests for these files by doing part of the work
      (specifically, the file I/O) for serving the file when the
      server is started rather than during each request.</p>
  
      <p>Notice: You cannot use this for speeding up CGI programs or
      other files which are served by special content handlers. It
      can only be used for regular files which are usually served by
      the Apache core content handler.</p>
  
      <p>This module is an extension of and borrows heavily from the
      mod_mmap_static module in Apache 1.3.</p>
  </summary>
  
  <section><title>Using mod_file_cache</title>
  
      <p><module>mod_file_cache</module> caches a list of statically
      configured files via <directive
      module="mod_file_cache">MMapFile</directive> or <directive
      module="mod_file_cache">CacheFile</directive> directives in the
      main server configuration.</p>
  
      <p>Not all platforms support both directives. For example, Apache
      on Windows does not currently support the <directive
      module="mod_file_cache">MMapStatic</directive> directive, while
      other platforms, like AIX, support both. You will receive an error
      message in the server error log if you attempt to use an
      unsupported directive. If given an unsupported directive, the
      server will start but the file will not be cached. On platforms
      that support both directives, you should experiment with both to
      see which works best for you.</p>
  
  <section><title>MmapFile Directive</title>
  
      <p>The <directive module="mod_file_cache">MmapFile</directive>
      directive of <module>mod_file_cache</module> maps a list of
      statically configured files into memory through the system call
      <code>mmap()</code>. This system call is available on most modern
      Unix derivates, but not on all. There are sometimes
      system-specific limits on the size and number of files that can be
      mmap()d, experimentation is probably the easiest way to find
      out.</p>
  
      <p>This mmap()ing is done once at server start or restart,
      only. So whenever one of the mapped files changes on the
      filesystem you <em>have</em> to restart the server (see the <a
      href="../stopping.html">Stopping and Restarting</a>
      documentation). To reiterate that point: if the files are
      modified <em>in place</em> without restarting the server you
      may end up serving requests that are completely bogus. You
      should update files by unlinking the old copy and putting a new
      copy in place. Most tools such as <code>rdist</code> and
      <code>mv</code> do this. The reason why this modules doesn't
      take care of changes to the files is that this check would need
      an extra <code>stat()</code> every time which is a waste and
      against the intent of I/O reduction.</p>
  </section>
  
  <section><title>CacheFile Directive</title>
  
      <p>The <directive module="mod_file_cache">CacheFile</directive>
      directive of <module>mod_file_cache</module> opens an active
      <em>handle</em> or <em>file descriptor</em> to the file (or files)
      listed in the configuration directive and places these open file
      handles in the cache. When the file is requested, the server
      retrieves the handle from the cache and passes it to the
      sendfile() (or TransmitFile() on Windows), socket API.</p>
  
      <p>Insert more details about sendfile API...</p>
  
      <p>This file handle caching is done once at server start or
      restart, only. So whenever one of the cached files changes on
      the filesystem you <em>have</em> to restart the server (see the
      <a href="../stopping.html">Stopping and Restarting</a>
      documentation). To reiterate that point: if the files are
      modified <em>in place</em> without restarting the server you
      may end up serving requests that are completely bogus. You
      should update files by unlinking the old copy and putting a new
      copy in place. Most tools such as <code>rdist</code> and
      <code>mv</code> do this.</p>
  </section>
  
  <note><title>Note</title> Don't bother asking for a for a
      directive which recursively caches all the files in a
      directory. Try this instead... See the 
      <directive module="core">Include</directive> directive, and consider
      this command:
  <example>
    find /www/htdocs -type f -print \ <br />
    | sed -e 's/.*/mmapfile &amp;/' &gt; /www/conf/mmap.conf
  </example>
  </note>
  
  </section>
  
  <directivesynopsis>
  <name>MMapFile</name>
  <syntax>MMapFile <em>file-path</em> [<em>file-path</em>] ...</syntax>
  <contextlist><context>server config</context></contextlist>
  
  <usage>
      <p>The <directive>MMapFile</directive> directive maps one or more files
      (given as whitespace separated arguments) into memory at server
      startup time. They are automatically unmapped on a server
      shutdown. When the files have changed on the filesystem at
      least a HUP or USR1 signal should be send to the server to
      re-mmap them.</p>
  
      <p>Be careful with the <em>file-path</em> arguments: They have
      to literally match the filesystem path Apache's URL-to-filename
      translation handlers create. We cannot compare inodes or other
      stuff to match paths through symbolic links <em>etc.</em>
      because that again would cost extra <code>stat()</code> system
      calls which is not acceptable. This module may or may not work
      with filenames rewritten by <module>mod_alias</module> or
      <module>mod_rewrite</module>.</p>
  
  <example><title>Example</title>
    MMapFile /usr/local/apache/htdocs/index.html
  </example>
  </usage>
  </directivesynopsis>
  
  <directivesynopsis>
  <name>CacheFile</name>
  <syntax>CacheFile
      <em>file-path</em> [<em>file-path</em>] ...</syntax>
  <contextlist><context>server config</context></contextlist>
  
  <usage>
      <p>The <directive>CacheFile</directive> directive opens handles to
      one or more files (given as whitespace separated arguments) and
      places these handles into the cache at server startup
      time. Handles to cached files are automatically closed on a server
      shutdown.  When the files have changed on the filesystem, the
      server should be restarted to to re-cache them.</p>
  
      <p>Be careful with the <em>file-path</em> arguments: They have
      to literally match the filesystem path Apache's URL-to-filename
      translation handlers create. We cannot compare inodes or other
      stuff to match paths through symbolic links <em>etc.</em>
      because that again would cost extra <code>stat()</code> system
      calls which is not acceptable. This module may or may not work
      with filenames rewritten by <module>mod_alias</module> or
      <module>mod_rewrite</module>.</p>
  
  <example><title>Example</title>
    CacheFile /usr/local/apache/htdocs/index.html
  </example>
  </usage>
  
  </directivesynopsis>
  </modulesynopsis>
  
  
  1.1                  httpd-2.0/docs/manual/mod/mod_headers.xml
  
  Index: mod_headers.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
  <?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
  <modulesynopsis>
  
  <name>mod_headers</name>
  <description>Customization of HTTP request
      and response headers</description>
  <status>Extension</status>
  <sourcefile>mod_headers.c</sourcefile>
  <identifier>headers_module</identifier>
  <compatibility>RequestHeader is available only in Apache 2.0</compatibility>
  
  <summary>
      <p>This module provides directives to control and modify HTTP
      request and response headers. Headers can be merged, replaced
      or removed.</p>
  </summary>
  
  <section><title>Order of Processing</title>
  
      <p>The directives provided by mod_header can occur almost
      anywhere within the server configuration. They are valid in the
      main server config and virtual host sections, inside
      &lt;Directory&gt;, &lt;Location&gt; and &lt;Files&gt; sections,
      and within .htaccess files.</p>
  
      <p>The directives are processed in the following order:</p>
  
      <ol>
        <li>main server</li>
  
        <li>virtual host</li>
  
        <li>&lt;Directory&gt; sections and .htaccess</li>
  
        <li>&lt;Location&gt;</li>
  
        <li>&lt;Files&gt;</li>
      </ol>
  
      <p>Order is important. These two headers have a different
      effect if reversed:</p>
  
  <example>
  RequestHeader append MirrorID "mirror 12"<br />
         RequestHeader unset MirrorID
  </example>
  
      <p>This way round, the MirrorID header is not set. If reversed,
      the MirrorID header is set to "mirror 12".</p>
  </section>
  
  <section><title>Example</title>
  
      <ol>
        <li>Copy all request headers that begin with "TS" to the
        response headers:
  
  <example>
     Header echo ^TS*
  </example></li>
  
        <li>Add a header, MyHeader, to the response including a
        timestamp for when the request was received and how long it
        took to begin serving the request. This header can be used by
        the client to intuit load on the server or in isolating
        bottlenecks between the client and the server.
  
  <example>
     Header add MyHeader "%D %t"
  </example>
          results in this header being added to the response:
  <example>
     MyHeader: D=3775428 t=991424704447256
  </example>
        </li>
  
        <li>Say hello to Joe
  
  <example>
     Header add MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request."
  </example>
          results in this header being added to the response: 
  <example>
     MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request.
  </example>
        </li>
  
        <li>Conditionally send MyHeader on the response if and only
        if header "MyRequestHeader" is present on the request. This
        is useful for constructing headers in response to some client
        stimulus. Note that this example requires the services of the
        mod_setenvif module.
  
  <example>
     SetEnvIf MyRequestHeader value HAVE_MyRequestHeader<br />
     Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader
  </example>
          If the header "MyRequestHeader: value" is present on the
          HTTP request, the response will contain the following
          header: 
  <example>
     MyHeader: D=3775428 t=991424704447256 mytext
  </example>
        </li>
      </ol>
  </section>
  
  <directivesynopsis>
  <name>RequestHeader</name>
  <description>Configure HTTP request headers</description>
  <syntax>RequestHeader   set|append|add|unset <em>header</em> 
  [<em>value</em>]</syntax>
  <contextlist><context>server config</context>
  <context>virtual host</context>
  <context>directory</context>
  <context>.htaccess</context></contextlist>
  <override>FileInfo</override>
  
  <usage>
      <p>This directive can replace, merge or remove HTTP request
      headers. The header is modified just before the content handler
      is run, allowing incoming headers to be modified. The action it
      performs is determined by the first argument. This can be one
      of the following values:</p>
  
      <ul>
        <li><strong>set</strong><br />
         The request header is set, replacing any previous header
        with this name</li>
  
        <li><strong>append</strong><br />
         The request header is appended to any existing header of the
        same name. When a new value is merged onto an existing header
        it is separated from the existing header with a comma. This
        is the HTTP standard way of giving a header multiple
        values.</li>
  
        <li><strong>add</strong><br />
         The request header is added to the existing set of headers,
        even if this header already exists. This can result in two
        (or more) headers having the same name. This can lead to
        unforeseen consequences, and in general "append" should be
        used instead.</li>
  
        <li><strong>unset</strong><br />
         The request header of this name is removed, if it exists. If
        there are multiple headers of the same name, all will be
        removed.</li>
      </ul>
  
      <p>This argument is followed by a header name, which can
      include the final colon, but it is not required. Case is
      ignored. For <code>add</code>, <code>append</code> and
      <code>set</code> a value is given as the third argument. If
      this value contains spaces, it should be surrounded by double
      quotes. For unset, no value should be given.</p>
  
      <p>The <directive>RequestHeader</directive> directive is processed
      just before the request is run by its handler in the fixup phase.
      This should allow headers generated by the browser, or by Apache
      input filters to be overridden or modified.</p>
  </usage>
  </directivesynopsis>
  
  <directivesynopsis>
  <name>Header</name>
  <description>Configure HTTP response headers</description>
  <syntax>Header set|append|add|unset|echo  <em>header</em> 
  [<em>value</em>]</syntax>
  <contextlist><context>server config</context>
  <context>virtual host</context>
  <context>directory</context>
  <context>.htaccess</context></contextlist>
  <override>FileInfo</override>
  
  <usage>
      <p>This directive can replace, merge or remove HTTP response
      headers. The header is modified just after the content handler
      and output filters are run, allowing outgoing headers to be
      modified. The action it performs is determined by the first
      argument. This can be one of the following values:</p>
  
      <ul>
        <li><strong>set</strong><br />
         The response header is set, replacing any previous header
        with this name. The <em>value</em> may be a format
        string.</li>
  
        <li><strong>append</strong><br />
         The response header is appended to any existing header of
        the same name. When a new value is merged onto an existing
        header it is separated from the existing header with a comma.
        This is the HTTP standard way of giving a header multiple
        values.</li>
  
        <li><strong>add</strong><br />
         The response header is added to the existing set of headers,
        even if this header already exists. This can result in two
        (or more) headers having the same name. This can lead to
        unforeseen consequences, and in general "append" should be
        used instead.</li>
  
        <li><strong>unset</strong><br />
         The response header of this name is removed, if it exists.
        If there are multiple headers of the same name, all will be
        removed.</li>
  
        <li><strong>echo</strong><br />
         Request headers with this name are echoed back in the
        response headers. <em>header</em> may be a regular
        expression.</li>
      </ul>
  
      <p>This argument is followed by a <em>header</em> name, which
      can include the final colon, but it is not required. Case is
      ignored for set, append, add and unset. The <em>header</em>
      name for echo is case sensitive and may be a regular
      expression.</p>
  
      <p>For <code>add</code>, <code>append</code> and
      <code>set</code> a <em>value</em> is specified as the third
      argument. If <em>value</em> contains spaces, it should be
      surrounded by doublequotes. <em>value</em> may be a character
      string, a string containing format specifiers or a combination
      of both. The following format specifiers are supported in
      <em>value</em>:</p>
  <table>
  <tr><td>%t: </td> <td>The time the request was received in Universal
  Coordinated Time since the epoch (Jan. 1, 1970) measured in
  microseconds. The value is preceded by "t=".</td></tr>
  
  <tr><td>%D: </td> <td>The time from when the request was received to
  the time the headers are sent on the wire. This is a measure of the
  duration of the request. The value is preceded by "D=".</td></tr>
  
  <tr><td>%{FOOBAR}e:</td> <td>The contents of the <a href="../env.html">environment
  variable</a> FOOBAR.</td></tr>
  </table>
  
      <p>When the <directive>Header</directive> directive is used with the
      <code>add</code>, <code>append</code>, or <code>set</code>
      argument, a fourth argument may be used to specify conditions
      under which the action will be taken. If the <a
      href="../env.html">environment variable</a> specified in the
      <code>env=...</code> argument exists (or if the environment
      variable does not exist and <code>env=!...</code> is specified)
      then the action specified by the <directive>Header</directive> directive
      will take effect. Otherwise, the directive will have no effect
      on the request.</p>
  
      <p>The Header directives are processed just before the response
      is sent to the network. These means that it is possible to set
      and/or override most headers, except for those headers added by
      the header filter.</p>
  </usage>
  </directivesynopsis>
  
  </modulesynopsis>
  
  
  
  
  1.1                  httpd-2.0/docs/manual/mod/mod_imap.xml
  
  Index: mod_imap.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
  <?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
  <modulesynopsis>
  
  <name>mod_imap</name>
  <description>Server-side imagemap processing</description>
  <status>Base</status>
  <sourcefile>mod_imap.c</sourcefile>
  <identifier>imap_module</identifier>
  
  <summary>
      <p>This module processes <code>.map</code> files, thereby
      replacing the functionality of the <code>imagemap</code> CGI
      program. Any directory or document type configured to use the
      handler <code>imap-file</code> (using either 
      <directive module="mod_mime">AddHandler</directive> or
      <directive module="core">SetHandler</directive>)
      will be processed by this module.</p>
  
      <p>The following directive will activate files ending with
      <code>.map</code> as imagemap files:</p>
  
  <example>AddHandler imap-file map</example>
  
      <p>Note that the following is still supported:</p>
  
  <example>AddType application/x-httpd-imap map</example>
  
      <p>However, we are trying to phase out "magic MIME types" so we
      are deprecating this method.</p>
  </summary>
  
  <section><title>New Features</title>
  
      <p>The imagemap module adds some new features that were not
      possible with previously distributed imagemap programs.</p>
  
      <ul>
        <li>URL references relative to the Referer: information.</li>
  
        <li>Default &lt;BASE&gt; assignment through a new map
        directive <code>base</code>.</li>
  
        <li>No need for <code>imagemap.conf</code> file.</li>
  
        <li>Point references.</li>
  
        <li>Configurable generation of imagemap menus.</li>
      </ul>
  </section>
  
  <section><title>Imagemap File</title>
  
      <p>The lines in the imagemap files can have one of several
      formats:</p>
  
  <example>
        directive value [x,y ...]<br />
        directive value "Menu text" [x,y ...]<br />
        directive value x,y ... "Menu text"
  </example>
      <p>The directive is one of <code>base</code>,
      <code>default</code>, <code>poly</code>, <code>circle</code>,
      <code>rect</code>, or <code>point</code>. The value is an
      absolute or relative URL, or one of the special values listed
      below. The coordinates are <code>x,y</code> pairs separated by
      whitespace. The quoted text is used as the text of the link if
      a imagemap menu is generated. Lines beginning with '#' are
      comments.</p>
  
  <section><title>Imagemap File Directives</title>
      <p>There are six directives allowed in the imagemap file. The
      directives can come in any order, but are processed in the
      order they are found in the imagemap file.</p>
  
      <dl>
        <dt><code>base</code> Directive</dt>
  
        <dd>Has the effect of <code>&lt;BASE HREF="value"&gt;</code>.
        The non-absolute URLs of the map-file are taken relative to
        this value. The <code>base</code> directive overrides
        ImapBase as set in a .htaccess file or in the server
        configuration files. In the absence of an ImapBase
        configuration directive, <code>base</code> defaults to
        <code>http://server_name/</code>.<br />
         <code>base_uri</code> is synonymous with <code>base</code>.
        Note that a trailing slash on the URL is significant.</dd>
  
        <dt><code>default</code> Directive</dt>
  
        <dd>The action taken if the coordinates given do not fit any
        of the <code>poly</code>, <code>circle</code> or
        <code>rect</code> directives, and there are no
        <code>point</code> directives. Defaults to
        <code>nocontent</code> in the absence of an ImapDefault
        configuration setting, causing a status code of <code>204 No
        Content</code> to be returned. The client should keep the
        same page displayed.</dd>
  
        <dt><code>poly</code> Directive</dt>
  
        <dd>Takes three to one-hundred points, and is obeyed if the
        user selected coordinates fall within the polygon defined by
        these points.</dd>
  
        <dt><code>circle</code></dt>
  
        <dd>Takes the center coordinates of a circle and a point on
        the circle. Is obeyed if the user selected point is with the
        circle.</dd>
  
        <dt><code>rect</code> Directive</dt>
  
        <dd>Takes the coordinates of two opposing corners of a
        rectangle. Obeyed if the point selected is within this
        rectangle.</dd>
  
        <dt><code>point</code> Directive</dt>
  
        <dd>Takes a single point. The point directive closest to the
        user selected point is obeyed if no other directives are
        satisfied. Note that <code>default</code> will not be
        followed if a <code>point</code> directive is present and
        valid coordinates are given.</dd>
      </dl>
  </section>
  
  <section><title>Values</title>
  
      <p>The values for each of the directives can any of the following:</p>
      
  
      <dl>
        <dt>a URL</dt>
  
        <dd>The URL can be relative or absolute URL. Relative URLs
        can contain '..' syntax and will be resolved relative to the
        <code>base</code> value.<br />
         <code>base</code> itself will not resolved according to the
        current value. A statement <code>base mailto:</code> will
        work properly, though.</dd>
  
        <dt><code>map</code></dt>
  
        <dd>Equivalent to the URL of the imagemap file itself. No
        coordinates are sent with this, so a menu will be generated
        unless ImapMenu is set to 'none'.</dd>
  
        <dt><code>menu</code></dt>
  
        <dd>Synonymous with <code>map</code>.</dd>
  
        <dt><code>referer</code></dt>
  
        <dd>Equivalent to the URL of the referring document. Defaults
        to <code>http://servername/</code> if no Referer: header was
        present.</dd>
  
        <dt><code>nocontent</code></dt>
  
        <dd>Sends a status code of <code>204 No Content</code>,
        telling the client to keep the same page displayed. Valid for
        all but <code>base</code>.</dd>
  
        <dt><code>error</code></dt>
  
        <dd>Fails with a <code>500 Server Error</code>. Valid for all
        but <code>base</code>, but sort of silly for anything but
        <code>default</code>.</dd>
      </dl>
  </section>
  
  <section><title>Coordinates</title>
  
      <dl>
        <dt><code>0,0 200,200</code></dt>
  
        <dd>A coordinate consists of an <code>x</code> and a <code>y</code>
        value separated by a comma. The coordinates are separated
        from each other by whitespace. To accommodate the way Lynx
        handles imagemaps, should a user select the coordinate
        <code>0,0</code>, it is as if no coordinate had been
        selected.</dd>
      </dl>
  
  </section>
  
  <section><title>Quoted Text</title>
  
      <dl>
        <dt><code>"Menu Text"</code></dt>
  
        <dd>After the value or after the coordinates, the line
        optionally may contain text within double quotes. This string
        is used as the text for the link if a menu is
        generated:<br />
         <code>&lt;a HREF="http://foo.com/"&gt;Menu
        text&lt;/a&gt;</code><br />
         If no quoted text is present, the name of the link will be
        used as the text:<br />
         <code>&lt;a
        HREF="http://foo.com/"&gt;http://foo.com&lt;/a&gt;</code><br />
         It is impossible to escape double quotes within this
        text.</dd>
      </dl>
  </section>
  </section>
  
  <section><title>Example Mapfile</title>
  
  <example>
        #Comments are printed in a 'formatted' or
        'semiformatted' menu.<br />
         #And can contain html tags. &lt;hr&gt;<br />
         base referer<br />
         poly map "Could I have a menu, please?" 0,0 0,10 10,10
        10,0<br />
         rect .. 0,0 77,27 "the directory of the referer"<br />
         circle http://www.inetnebr.com/lincoln/feedback/ 195,0
        305,27<br />
         rect another_file "in same directory as referer" 306,0
        419,27<br />
         point http://www.zyzzyva.com/ 100,100<br />
         point http://www.tripod.com/ 200,200<br />
         rect mailto:nate@tripod.com 100,150 200,0 "Bugs?"<br />
  </example>
  
  </section>
  
  <section><title>Referencing your mapfile</title>
  
  <example>
        &lt;A HREF="/maps/imagemap1.map"&gt;<br />
         &lt;IMG ISMAP SRC="/images/imagemap1.gif"&gt;<br />
         &lt;/A&gt;
  </example>
  </section>
  
  <directivesynopsis>
  <name>ImapMenu</name>
  <description>Action if no coordinates are given when calling
  an imagemap</description>
  <syntax>ImapMenu
      none|formatted|semiformatted|unformatted</syntax>
  <contextlist><context>server config</context>
  <context>virtual host</context>
  <context>directory</context>
  <context>.htaccess</context></contextlist>
  <override>Indexes</override>
  
  <usage>
      <p>The <directive>ImapMenu</directive> directive determines the
      action taken if an imagemap file is called without valid
      coordinates.</p>
  
      <dl>
        <dt><code>none</code></dt>
  
        <dd>If ImapMenu is <code>none</code>, no menu is generated,
        and the <code>default</code> action is performed.</dd>
  
        <dt><code>formatted</code></dt>
  
        <dd>A <code>formatted</code> menu is the simplest menu.
        Comments in the imagemap file are ignored. A level one header
        is printed, then an hrule, then the links each on a separate
        line. The menu has a consistent, plain look close to that of
        a directory listing.</dd>
  
        <dt><code>semiformatted</code></dt>
  
        <dd>In the <code>semiformatted</code> menu, comments are
        printed where they occur in the imagemap file. Blank lines
        are turned into HTML breaks. No header or hrule is printed,
        but otherwise the menu is the same as a
        <code>formatted</code> menu.</dd>
  
        <dt><code>unformatted</code></dt>
  
        <dd>Comments are printed, blank lines are ignored. Nothing is
        printed that does not appear in the imagemap file. All breaks
        and headers must be included as comments in the imagemap
        file. This gives you the most flexibility over the appearance
        of your menus, but requires you to treat your map files as
        HTML instead of plaintext.</dd>
      </dl>
  </usage>
  </directivesynopsis>
  
  <directivesynopsis>
  <name>ImapDefault</name>
  <description>Default action when an imagemap is called with coordinates
  that are not explicitly mapped</description>
  <syntax>ImapDefault error|nocontent|map|referer|<em>URL</em></syntax>
  <default>ImapDefault nocontent</default>
  <contextlist><context>server config</context>
  <context>virtual host</context>
  <context>directory</context>
  <context>.htaccess</context></contextlist>
  <override>Indexes</override>
  
  <usage>
      <p>The <directive>ImapDefault</directive> directive sets the default
      <code>default</code> used in the imagemap files. Its value is
      overridden by a <code>default</code> directive within the
      imagemap file. If not present, the <code>default</code> action
      is <code>nocontent</code>, which means that a <code>204 No
      Content</code> is sent to the client. In this case, the client
      should continue to display the original page.</p>
  </usage>
  </directivesynopsis>
  
  <directivesynopsis>
  <name>ImapBase</name>
  <description>Default <code>base</code> for imagemap files</description>
  <syntax>ImapBase map|referer|<em>URL</em></syntax>
  <default>ImapBase http://servername/</default>
  <contextlist><context>server config</context>
  <context>virtual host</context>
  <context>directory</context>
  <context>.htaccess</context></contextlist>
  <override>Indexes</override>
  
  <usage>
      <p>The <directive>ImapBase</directive> directive sets the default
      <code>base</code> used in the imagemap files. Its value is
      overridden by a <code>base</code> directive within the imagemap
      file. If not present, the <code>base</code> defaults to
      <code>http://servername/</code>.</p>
  </usage>
  </directivesynopsis>
  
  </modulesynopsis>
  
  

Mime
View raw message