handler.html.en revision aaf7b7f4cc1be050310c3d7f48bce0ec67e174e4
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<?xml version="1.0" encoding="ISO-8859-1"?>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding This file is generated from xml source: DO NOT EDIT
7c1827557873d94e3a0323172837fca1c3b27f6cwrowe XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding -->
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<title>Apache's Handler Use - Apache HTTP Server</title>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
95db5a4aa11a83bd25a6e11b53dd62c0af243e92wrowe<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
83bee7f569bee7534741915e173e6a7de9ddae81stoddard<link href="/images/favicon.ico" rel="shortcut icon" /></head>
7c1827557873d94e3a0323172837fca1c3b27f6cwrowe<body id="manual-page"><div id="page-header">
f6bd1c0924641e60dcc56cbaba27d3cb3ce4917erbb<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>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<p class="apache">Apache HTTP Server Version 2.1</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<img alt="" src="/images/feather.gif" /></div>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="/images/left.gif" /></a></div>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<div id="path">
0f82a7f1947a43d187796fca1606ccfca3e13b87stoddard<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs-project/">Documentation</a> &gt; <a href="./">Version 2.1</a></div><div id="page-content"><div id="preamble"><h1>Apache's Handler Use</h1>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<div class="toplang">
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<p><span>Available Languages: </span><a href="/en/handler.html" title="English">&nbsp;en&nbsp;</a> |
f1e6cde4b93eae1d6e248a1dad14ef9017bb546dstoddard<a href="/ja/handler.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<a href="/ko/handler.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding</div>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding
0f82a7f1947a43d187796fca1606ccfca3e13b87stoddard <p>This document describes the use of Apache's Handlers.</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding </div>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#definition">What is a Handler</a></li>
0f82a7f1947a43d187796fca1606ccfca3e13b87stoddard<li><img alt="" src="/images/down.gif" /> <a href="#examples">Examples</a></li>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<li><img alt="" src="/images/down.gif" /> <a href="#programmer">Programmer's Note</a></li>
db920ff940978fe01db8d4de8c2a9d507bc0bbcdstoddard</ul></div>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
c032b37ad682c1da5382258811e8e35a8ec0d78dwrowe<div class="section">
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<h2><a name="definition" id="definition">What is a Handler</a></h2>
95db5a4aa11a83bd25a6e11b53dd62c0af243e92wrowe
7b3590ada24130fe5d52ce7fbf98177e3d121a4cstoddard <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="/mod/mod_actions.html">mod_actions</a></code></li><li><code class="module"><a href="/mod/mod_asis.html">mod_asis</a></code></li><li><code class="module"><a href="/mod/mod_cgi.html">mod_cgi</a></code></li><li><code class="module"><a href="/mod/mod_imap.html">mod_imap</a></code></li><li><code class="module"><a href="/mod/mod_info.html">mod_info</a></code></li><li><code class="module"><a href="/mod/mod_mime.html">mod_mime</a></code></li><li><code class="module"><a href="/mod/mod_negotiation.html">mod_negotiation</a></code></li><li><code class="module"><a href="/mod/mod_status.html">mod_status</a></code></li></ul></td><td><ul><li><code class="directive"><a href="/mod/mod_actions.html#action">Action</a></code></li><li><code class="directive"><a href="/mod/mod_mime.html#addhandler">AddHandler</a></code></li><li><code class="directive"><a href="/mod/mod_mime.html#removehandler">RemoveHandler</a></code></li><li><code class="directive"><a href="/mod/core.html#sethandler">SetHandler</a></code></li></ul></td></tr></table>
7c1827557873d94e3a0323172837fca1c3b27f6cwrowe
f6bd1c0924641e60dcc56cbaba27d3cb3ce4917erbb
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>A "handler" is an internal Apache representation of the
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding action to be performed when a file is called. Generally, files
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding have implicit handlers, based on the file type. Normally, all
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding files are simply served by the server, but certain file types
0f82a7f1947a43d187796fca1606ccfca3e13b87stoddard are "handled" separately.</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>Apache 1.1 adds the ability to use handlers explicitly.
f1e6cde4b93eae1d6e248a1dad14ef9017bb546dstoddard Based on either filename extensions or on location, handlers
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding can be specified without relation to file type. This is
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding advantageous both because it is a more elegant solution, and
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding because it also allows for both a type <strong>and</strong> a
0f82a7f1947a43d187796fca1606ccfca3e13b87stoddard handler to be associated with a file. (See also <a href="mod/mod_mime.html#multipleext">Files with Multiple
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding Extensions</a>.)</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding
0f82a7f1947a43d187796fca1606ccfca3e13b87stoddard <p>Handlers can either be built into the server or included in
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding a module, or they can be added with the <code class="directive"><a href="/mod/mod_actions.html#action">Action</a></code> directive. The
db920ff940978fe01db8d4de8c2a9d507bc0bbcdstoddard built-in handlers in the standard distribution are as
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding follows:</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding
c032b37ad682c1da5382258811e8e35a8ec0d78dwrowe <ul>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <li><strong>default-handler</strong>: Send the file using the
95db5a4aa11a83bd25a6e11b53dd62c0af243e92wrowe <code>default_handler()</code>, which is the handler used by
7b3590ada24130fe5d52ce7fbf98177e3d121a4cstoddard default to handle static content. (core)</li>
7c1827557873d94e3a0323172837fca1c3b27f6cwrowe
f6bd1c0924641e60dcc56cbaba27d3cb3ce4917erbb <li><strong>send-as-is</strong>: Send file with HTTP headers
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding as is. (<code class="module"><a href="/mod/mod_asis.html">mod_asis</a></code>)</li>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <li><strong>cgi-script</strong>: Treat the file as a CGI
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding script. (<code class="module"><a href="/mod/mod_cgi.html">mod_cgi</a></code>)</li>
0f82a7f1947a43d187796fca1606ccfca3e13b87stoddard
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <li><strong>imap-file</strong>: Parse as an imagemap rule
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding file. (<code class="module"><a href="/mod/mod_imap.html">mod_imap</a></code>)</li>
f1e6cde4b93eae1d6e248a1dad14ef9017bb546dstoddard
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <li><strong>server-info</strong>: Get the server's
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding configuration information. (<code class="module"><a href="/mod/mod_info.html">mod_info</a></code>)</li>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding
0f82a7f1947a43d187796fca1606ccfca3e13b87stoddard <li><strong>server-status</strong>: Get the server's status
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding report. (<code class="module"><a href="/mod/mod_status.html">mod_status</a></code>)</li>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding
0f82a7f1947a43d187796fca1606ccfca3e13b87stoddard <li><strong>type-map</strong>: Parse as a type map file for
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding content negotiation. (<code class="module"><a href="/mod/mod_negotiation.html">mod_negotiation</a></code>)</li>
db920ff940978fe01db8d4de8c2a9d507bc0bbcdstoddard </ul>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<div class="section">
<h2><a name="examples" id="examples">Examples</a></h2>
<h3><a name="example1" id="example1">Modifying static content using a CGI script</a></h3>
<p>The following directives will cause requests for files with
the <code>html</code> extension to trigger the launch of the
<code>footer.pl</code> CGI script.</p>
<div class="example"><p><code>
Action add-footer /cgi-bin/footer.pl<br />
AddHandler add-footer .html
</code></p></div>
<p>Then the CGI script is responsible for sending the
originally requested document (pointed to by the
<code>PATH_TRANSLATED</code> environment variable) and making
whatever modifications or additions are desired.</p>
<h3><a name="example2" id="example2">Files with HTTP headers</a></h3>
<p>The following directives will enable the
<code>send-as-is</code> handler, which is used for files which
contain their own HTTP headers. All files in the
<code>/web/htdocs/asis/</code> directory will be processed by
the <code>send-as-is</code> handler, regardless of their
filename extensions.</p>
<div class="example"><p><code>
&lt;Directory /web/htdocs/asis&gt;<br />
SetHandler send-as-is<br />
&lt;/Directory&gt;
</code></p></div>
</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="programmer" id="programmer">Programmer's Note</a></h2>
<p>In order to implement the handler features, an addition has
been made to the <a href="developer/API.html">Apache API</a> that
you may wish to make use of. Specifically, a new record has
been added to the <code>request_rec</code> structure:</p>
<div class="example"><p><code>
char *handler
</code></p></div>
<p>If you wish to have your module engage a handler, you need
only to set <code>r-&gt;handler</code> to the name of the
handler at any time prior to the <code>invoke_handler</code>
stage of the request. Handlers are implemented as they were
before, albeit using the handler name instead of a content
type. While it is not necessary, the naming convention for
handlers is to use a dash-separated word, with no slashes, so
as to not invade the media type name-space.</p>
</div></div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="/en/handler.html" title="English">&nbsp;en&nbsp;</a> |
<a href="/ja/handler.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
<a href="/ko/handler.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
</div><div id="footer">
<p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p>
<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>
</body></html>