530eba85dbd41b8a0fa5255d3648d1440199a661slive<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding Licensed to the Apache Software Foundation (ASF) under one or more
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding contributor license agreements. See the NOTICE file distributed with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding this work for additional information regarding copyright ownership.
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding The ASF licenses this file to You under the Apache License, Version 2.0
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding (the "License"); you may not use this file except in compliance with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding the License. You may obtain a copy of the License at
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Unless required by applicable law or agreed to in writing, software
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd distributed under the License is distributed on an "AS IS" BASIS,
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd See the License for the specific language governing permissions and
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd limitations under the License.
c1ce37b2dcce132ff0abf6a15f5225a0e89af5e4slive<description>Specify character set translation or recoding</description>
69f999c99a7ef01d78764bddf02c85cd084b10fdcovener <p><module>mod_charset_lite</module> allows the server to change
69f999c99a7ef01d78764bddf02c85cd084b10fdcovener the character set of responses before sending them to the client.
69f999c99a7ef01d78764bddf02c85cd084b10fdcovener In an EBCDIC environment, Apache always translates HTTP protocol
69f999c99a7ef01d78764bddf02c85cd084b10fdcovener content (e.g. response headers) from the code page of the Apache
69f999c99a7ef01d78764bddf02c85cd084b10fdcovener process locale to ISO-8859-1, but not the body of responses. In
69f999c99a7ef01d78764bddf02c85cd084b10fdcovener any environment, <module>mod_charset_lite</module> can be used to
69f999c99a7ef01d78764bddf02c85cd084b10fdcovener specify that response bodies should be translated. For example,
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim if files are stored in EBCDIC, then
69f999c99a7ef01d78764bddf02c85cd084b10fdcovener <module>mod_charset_lite</module> can translate them to
69f999c99a7ef01d78764bddf02c85cd084b10fdcovener ISO-8859-1 before sending them to the client.</p>
6b040c2a2a566388097aab66dff8c3c94e853f22slive <p>This module provides a small subset of configuration
6b040c2a2a566388097aab66dff8c3c94e853f22slive mechanisms implemented by Russian Apache and its associated
cee399b097f61ab31c81399957f1293b55e1a984nd module="mod_charset_lite">CharsetSourceEnc</directive> and
cee399b097f61ab31c81399957f1293b55e1a984nd <directive module="mod_charset_lite">CharsetDefault</directive>
1d9308ed0075062953a246d16bcda888a1be1adeslive must be acceptable to the translation mechanism used by
1d9308ed0075062953a246d16bcda888a1be1adeslive <module>mod_charset_lite</module> is deployed. These character
1d9308ed0075062953a246d16bcda888a1be1adeslive set names are not standardized and are usually not the same as
1d9308ed0075062953a246d16bcda888a1be1adeslive the corresponding values used in http headers. Currently, APR
1d9308ed0075062953a246d16bcda888a1be1adeslive can only use iconv(3), so you can easily test your character set
1d9308ed0075062953a246d16bcda888a1be1adeslive names using the iconv(1) program, as follows:</p>
cee399b097f61ab31c81399957f1293b55e1a984nd iconv -f charsetsourceenc-value -t charsetdefault-value
cee399b097f61ab31c81399957f1293b55e1a984nd </example>
cee399b097f61ab31c81399957f1293b55e1a984nd </section>
cee399b097f61ab31c81399957f1293b55e1a984nd <section><title>Mismatch between character set of content and translation
6b040c2a2a566388097aab66dff8c3c94e853f22slive rules</title>
cee399b097f61ab31c81399957f1293b55e1a984nd <p>If the translation rules don't make sense for the content,
cee399b097f61ab31c81399957f1293b55e1a984nd translation can fail in various ways, including:</p>
6b040c2a2a566388097aab66dff8c3c94e853f22slive <li>The translation mechanism may return a bad return code,
6b040c2a2a566388097aab66dff8c3c94e853f22slive and the connection will be aborted.</li>
6b040c2a2a566388097aab66dff8c3c94e853f22slive <li>The translation mechanism may silently place special
6b040c2a2a566388097aab66dff8c3c94e853f22slive characters (e.g., question marks) in the output buffer when
6b040c2a2a566388097aab66dff8c3c94e853f22slive it cannot translate the input buffer.</li>
cee399b097f61ab31c81399957f1293b55e1a984nd </section>
6b040c2a2a566388097aab66dff8c3c94e853f22slive<directivesynopsis>
6b040c2a2a566388097aab66dff8c3c94e853f22slive<context>virtual host</context><context>directory</context>
6b040c2a2a566388097aab66dff8c3c94e853f22slive</contextlist>
6b040c2a2a566388097aab66dff8c3c94e853f22slive <p>The <directive>CharsetSourceEnc</directive> directive specifies the
6b040c2a2a566388097aab66dff8c3c94e853f22slive source charset of files in the associated container.</p>
cee399b097f61ab31c81399957f1293b55e1a984nd <p>The value of the <var>charset</var> argument must be accepted
6b040c2a2a566388097aab66dff8c3c94e853f22slive as a valid character set name by the character set support in
1d9308ed0075062953a246d16bcda888a1be1adeslive <glossary>APR</glossary>. Generally, this means that it must be
1d9308ed0075062953a246d16bcda888a1be1adeslive supported by iconv.</p>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<Directory "/export/home/trawick/apacheinst/htdocs/convert">
d84dc356814b255affe3abe2ad93ce17f98e632chumbedooh CharsetSourceEnc UTF-16BE
d84dc356814b255affe3abe2ad93ce17f98e632chumbedooh CharsetDefault ISO-8859-1
d84dc356814b255affe3abe2ad93ce17f98e632chumbedooh</Directory>
d84dc356814b255affe3abe2ad93ce17f98e632chumbedooh </highlight>
cee399b097f61ab31c81399957f1293b55e1a984nd </example>
6b040c2a2a566388097aab66dff8c3c94e853f22slive <p>The character set names in this example work with the iconv
6b040c2a2a566388097aab66dff8c3c94e853f22slive translation support in Solaris 8.</p>
db965e00e32a191217813eba97d8978887942501covener Specifying the same charset for both <directive module="mod_charset_lite">CharsetSourceEnc</directive>
db965e00e32a191217813eba97d8978887942501covener and <directive module="mod_charset_lite">CharsetDefault</directive> disables translation. The charset
db965e00e32a191217813eba97d8978887942501covener need not match the charset of the response, but it must be a valid charset on the system.
6b040c2a2a566388097aab66dff8c3c94e853f22slive</directivesynopsis>
6b040c2a2a566388097aab66dff8c3c94e853f22slive<directivesynopsis>
6b040c2a2a566388097aab66dff8c3c94e853f22slive<context>virtual host</context><context>directory</context>
6b040c2a2a566388097aab66dff8c3c94e853f22slive</contextlist>
6b040c2a2a566388097aab66dff8c3c94e853f22slive <p>The <directive>CharsetDefault</directive> directive specifies the
6b040c2a2a566388097aab66dff8c3c94e853f22slive charset that content in the associated container should be
6b040c2a2a566388097aab66dff8c3c94e853f22slive translated to.</p>
cee399b097f61ab31c81399957f1293b55e1a984nd <p>The value of the <var>charset</var> argument must be accepted
6b040c2a2a566388097aab66dff8c3c94e853f22slive as a valid character set name by the character set support in
1d9308ed0075062953a246d16bcda888a1be1adeslive <glossary>APR</glossary>. Generally, this means that it must be
1d9308ed0075062953a246d16bcda888a1be1adeslive supported by iconv.</p>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<Directory "/export/home/trawick/apacheinst/htdocs/convert">
d84dc356814b255affe3abe2ad93ce17f98e632chumbedooh CharsetSourceEnc UTF-16BE
d84dc356814b255affe3abe2ad93ce17f98e632chumbedooh CharsetDefault ISO-8859-1
d84dc356814b255affe3abe2ad93ce17f98e632chumbedooh</Directory>
d84dc356814b255affe3abe2ad93ce17f98e632chumbedooh </highlight>
cee399b097f61ab31c81399957f1293b55e1a984nd </example>
db965e00e32a191217813eba97d8978887942501covener Specifying the same charset for both <directive module="mod_charset_lite">CharsetSourceEnc</directive>
db965e00e32a191217813eba97d8978887942501covener and <directive module="mod_charset_lite">CharsetDefault</directive> disables translation. The charset
db965e00e32a191217813eba97d8978887942501covener need not match the charset of the response, but it must be a valid charset on the system.
6b040c2a2a566388097aab66dff8c3c94e853f22slive</directivesynopsis>
6b040c2a2a566388097aab66dff8c3c94e853f22slive<directivesynopsis>
cee399b097f61ab31c81399957f1293b55e1a984nd<description>Configures charset translation behavior</description>
cee399b097f61ab31c81399957f1293b55e1a984nd<syntax>CharsetOptions <var>option</var> [<var>option</var>] ...</syntax>
6b040c2a2a566388097aab66dff8c3c94e853f22slive<context>virtual host</context><context>directory</context>
6b040c2a2a566388097aab66dff8c3c94e853f22slive</contextlist>
6b040c2a2a566388097aab66dff8c3c94e853f22slive <p>The <directive>CharsetOptions</directive> directive configures certain
cee399b097f61ab31c81399957f1293b55e1a984nd behaviors of <module>mod_charset_lite</module>. <var>Option</var> can
6b040c2a2a566388097aab66dff8c3c94e853f22slive be one of</p>
6b040c2a2a566388097aab66dff8c3c94e853f22slive <dd>The <code>ImplicitAdd</code> keyword specifies that
6b040c2a2a566388097aab66dff8c3c94e853f22slive <module>mod_charset_lite</module> should implicitly insert its
6b040c2a2a566388097aab66dff8c3c94e853f22slive filter when the configuration specifies that the character
6b040c2a2a566388097aab66dff8c3c94e853f22slive set of content should be translated. If the filter chain is
cee399b097f61ab31c81399957f1293b55e1a984nd explicitly configured using the <directive module="mod_mime"
cee399b097f61ab31c81399957f1293b55e1a984nd >AddOutputFilter</directive> directive, <code>NoImplicitAdd</code>
cee399b097f61ab31c81399957f1293b55e1a984nd should be specified so that <module>mod_charset_lite</module>
cee399b097f61ab31c81399957f1293b55e1a984nd doesn't add its filter.</dd>
5b34403770a5a65a807ab969af707902d93929e4covener <dt><code>TranslateAllMimeTypes | NoTranslateAllMimeTypes</code></dt>
dac9980d05f87d3ebdb3d2dde673a0f24dfcf248covener <dd>Normally, <module>mod_charset_lite</module> will only perform
dac9980d05f87d3ebdb3d2dde673a0f24dfcf248covener translation on a small subset of possible mimetypes. When the
29a85d70ade6f1d222578f987738ea4dea415eabcovener <code>TranslateAllMimeTypes</code> keyword is specified for a given
dac9980d05f87d3ebdb3d2dde673a0f24dfcf248covener configuration section, translation is performed without regard for
dac9980d05f87d3ebdb3d2dde673a0f24dfcf248covener mimetype.</dd>
6b040c2a2a566388097aab66dff8c3c94e853f22slive</directivesynopsis>
7db9f691a00ead175b03335457ca296a33ddf31bnd</modulesynopsis>