mod_charset_lite.html revision 240a5b8962329911d02566b600be6226e1f857ae
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock<html xmlns="http://www.w3.org/TR/xhtml1/strict"><head><!--
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrockXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock This file is generated from xml source: DO NOT EDIT
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrockXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock--><title>mod_charset_lite - Apache HTTP Server</title><link rel="stylesheet" type="text/css" href="/style/manual.css"/></head><body><blockquote><div align="center"><img src="/images/sub.gif" alt="[APACHE DOCUMENTATION]"/><h3>Apache HTTP Server Version 2.0</h3></div><h1 align="center">Apache Module mod_charset_lite</h1><table bgcolor="#cccccc" cellpadding="0" cellspacing="1"><tr><td><table bgcolor="#ffffff"><tr><td valign="top"><span class="help">Description:</span></td><td>Specify character set translation or recoding</td></tr><tr><td><a class="help" href="module-dict.html#Status">Status:</a></td><td>Experimental</td></tr><tr><td><a class="help" href="module-dict.html#ModuleIdentifier">Module Identifier:</a></td><td>charset_lite_module</td></tr></table></td></tr></table><h2>Summary</h2>
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock <p>This is an <strong>experimental</strong> module and should
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock be used with care. Experiment with your
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock <code>mod_charset_lite</code> configuration to ensure that it
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock performs the desired function.</p>
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock <p><code><a href="mod_charset_lite.html">mod_charset_lite</a></code> allows the administrator to
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock specify the source character set of objects as well as the
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock character set they should be translated into before sending to the
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock client. <code><a href="mod_charset_lite.html">mod_charset_lite</a></code> does not translate the
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock data itself but instead tells Apache what translation to
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock perform. <code><a href="mod_charset_lite.html">mod_charset_lite</a></code> is applicable to EBCDIC
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock and ASCII host environments. In an EBCDIC environment, Apache
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock normally translates text content from the code page of the Apache
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock process locale to ISO-8859-1. <code><a href="mod_charset_lite.html">mod_charset_lite</a></code>
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock can be used to specify that a different translation is to be
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock performed. In an ASCII environment, Apache normally performs no
1d7132005da8d75994a6ad204e6ec05ef5ffaa4bEric Schrock translation, so <code><a href="mod_charset_lite.html">mod_charset_lite</a></code> is needed in
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock order for any translation to take place.</p>
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock <p>This module provides a small subset of configuration
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock mechanisms implemented by Russian Apache and its associated
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock<h2>Directives</h2><ul><li><a href="#charsetdefault">CharsetDefault</a></li><li><a href="#charsetoptions">CharsetOptions</a></li><li><a href="#charsetsourceenc">CharsetSourceEnc</a></li></ul><h2>Common Problems</h2>
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock <p>The character set name parameters of <a class="directive" href="#charsetsourceenc"><code class="directive">CharsetSourceEnc</code></a> and
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock <a class="directive" href="#charsetdefault"><code class="directive">CharsetDefault</code></a>
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock must be acceptable to the translation mechanism used by APR on the
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock system where <code><a href="mod_charset_lite.html">mod_charset_lite</a></code> is deployed. These
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock character set names are not standardized and are usually not the
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock same as the corresponding values used in http headers. Currently,
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock APR can only use iconv(3), so you can easily test your character
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock set names using the iconv(1) program, as follows:</p>
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock iconv -f charsetsourceenc-value -t charsetdefault-value
51ece83525fa18f5e72627610f480dffc7e492fdeschrock<h3>Mismatch between character set of content and translation
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock <p>If the translation rules don't make sense for the content,
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock translation can fail in various ways, including:</p>
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock <li>The translation mechanism may return a bad return code,
51ece83525fa18f5e72627610f480dffc7e492fdeschrock and the connection will be aborted.</li>
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock <li>The translation mechanism may silently place special
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock characters (e.g., question marks) in the output buffer when
51ece83525fa18f5e72627610f480dffc7e492fdeschrock it cannot translate the input buffer.</li>
51ece83525fa18f5e72627610f480dffc7e492fdeschrock<hr/><h2><a name="CharsetDefault">CharsetDefault</a> <a name="charsetdefault">Directive</a></h2><table bgcolor="#cccccc" border="0" cellspacing="0" cellpadding="1"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>Charset to translate into</td></tr><tr><td><a class="help" href="directive-dict.html#Syntax">Syntax:</a></td><td>CharsetDefault <em>charset</em></td></tr><tr><td><a class="help" href="directive-dict.html#Context">Context:</a></td><td>server config, virtual host, directory, .htaccess</td></tr><tr><td><a class="help" href="directive-dict.html#Override">Override:</a></td><td>FileInfo</td></tr><tr><td><a class="help" href="directive-dict.html#Status">Status:</a></td><td>Experimental</td></tr><tr><td><a class="help" href="directive-dict.html#Module">Module:</a></td><td>mod_charset_lite</td></tr></table></td></tr></table>
51ece83525fa18f5e72627610f480dffc7e492fdeschrock <p>The <code class="directive">CharsetDefault</code> directive specifies the
51ece83525fa18f5e72627610f480dffc7e492fdeschrock charset that content in the associated container should be
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock translated to.</p>
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock <p>The value of the <em>charset</em> argument must be accepted
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock as a valid character set name by the character set support in
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock APR. Generally, this means that it must be supported by
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><p align="center"><strong>Example</strong></p><code>
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock <Directory "/export/home/trawick/apacheinst/htdocs/convert"><br/>
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock CharsetSourceEnc UTF-16BE<br/>
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock CharsetDefault ISO8859-1<br/>
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock </Directory>
51ece83525fa18f5e72627610f480dffc7e492fdeschrock<hr/><h2><a name="CharsetOptions">CharsetOptions</a> <a name="charsetoptions">Directive</a></h2><table bgcolor="#cccccc" border="0" cellspacing="0" cellpadding="1"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>Configures charset tranlation behavior</td></tr><tr><td><a class="help" href="directive-dict.html#Syntax">Syntax:</a></td><td>CharsetOptions <em>option</em> [<em>option</em>] ...</td></tr><tr><td><a class="help" href="directive-dict.html#Default">Default:</a></td><td><code>CharsetOptions DebugLevel=0
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrockNoImplicitAdd</code></td></tr><tr><td><a class="help" href="directive-dict.html#Context">Context:</a></td><td>server config, virtual host, directory, .htaccess</td></tr><tr><td><a class="help" href="directive-dict.html#Override">Override:</a></td><td>FileInfo</td></tr><tr><td><a class="help" href="directive-dict.html#Status">Status:</a></td><td>Experimental</td></tr><tr><td><a class="help" href="directive-dict.html#Module">Module:</a></td><td>mod_charset_lite</td></tr></table></td></tr></table>
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock <p>The <code class="directive">CharsetOptions</code> directive configures certain
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock behaviors of <code><a href="mod_charset_lite.html">mod_charset_lite</a></code>. <em>Option</em> can
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock be one of</p>
51ece83525fa18f5e72627610f480dffc7e492fdeschrock <dd>The <code>DebugLevel</code> keyword allows you to specify
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock the level of debug messages generated by
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock <code><a href="mod_charset_lite.html">mod_charset_lite</a></code>. By default, no messages are
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock generated. This is equivalent to <code>DebugLevel=0</code>.
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock With higher numbers, more debug messages are generated, and
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock server performance will be degraded. The actual meanings of
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock the numeric values are described with the definitions of the
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock DBGLVL_ constants near the beginning of
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock <dd>The <code>ImplicitAdd</code> keyword specifies that
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock <code><a href="mod_charset_lite.html">mod_charset_lite</a></code> should implicitly insert its
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock filter when the configuration specifies that the character
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock set of content should be translated. If the filter chain is
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock explicitly configured using the AddOutputFilter directive,
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock <code>NoImplicitAdd</code> should be specified so that
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock <code><a href="mod_charset_lite.html">mod_charset_lite</a></code> doesn't add its filter.</dd>
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock<hr/><h2><a name="CharsetSourceEnc">CharsetSourceEnc</a> <a name="charsetsourceenc">Directive</a></h2><table bgcolor="#cccccc" border="0" cellspacing="0" cellpadding="1"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>Source charset of files</td></tr><tr><td><a class="help" href="directive-dict.html#Syntax">Syntax:</a></td><td>CharsetSourceEnc <em>charset</em></td></tr><tr><td><a class="help" href="directive-dict.html#Context">Context:</a></td><td>server config, virtual host, directory, .htaccess</td></tr><tr><td><a class="help" href="directive-dict.html#Override">Override:</a></td><td>FileInfo</td></tr><tr><td><a class="help" href="directive-dict.html#Status">Status:</a></td><td>Experimental</td></tr><tr><td><a class="help" href="directive-dict.html#Module">Module:</a></td><td>mod_charset_lite</td></tr></table></td></tr></table>
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock <p>The <code class="directive">CharsetSourceEnc</code> directive specifies the
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock source charset of files in the associated container.</p>
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock <p>The value of the <em>charset</em> argument must be accepted
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock as a valid character set name by the character set support in
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock APR. Generally, this means that it must be supported by
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><p align="center"><strong>example</strong></p><code>
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock <Directory "/export/home/trawick/apacheinst/htdocs/convert"><br/>
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock CharsetSourceEnc UTF-16BE<br/>
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock CharsetDefault ISO8859-1<br/>
ea8dc4b6d2251b437950c0056bc626b311c73c27eschrock </Directory>
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock <p>The character set names in this example work with the iconv
3d7072f8bd27709dba14f6fe336f149d25d9e207eschrock translation support in Solaris 8.</p>
