mod_charset_lite.html revision dff77f20d3ca0296e740d4369989e57949a06e92
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby BGCOLOR="#FFFFFF"
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby TEXT="#000000"
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby LINK="#0000FF"
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby VLINK="#000080"
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby ALINK="#FF0000"
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby<!--#include virtual="header.html" -->
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <H1 ALIGN="CENTER">Module mod_charset_lite</H1>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby<p>This module provides the ability to specify character set
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby translation or recoding.</p>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin MaltbyHREF="module-dict.html#SourceFile"
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby><STRONG>Source File:</STRONG></A> mod_charset_lite.c
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin MaltbyHREF="module-dict.html#ModuleIdentifier"
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby><STRONG>Module Identifier:</STRONG></A> charset_lite_module
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby This is an <STRONG>experimental</STRONG> module and should be used with
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby care. Experiment with your <CODE>mod_charset_lite</CODE> configuration to
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby ensure that it performs the desired function.
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <CODE>mod_charset_lite</CODE> allows the administrator to specify the
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby source character set of objects as well as the character set they should
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby be translated into before sending to the client.
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <CODE>mod_charset_lite</CODE> does not translate the data itself but
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby instead tells Apache what translation to perform.
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <CODE>mod_charset_lite</CODE> is applicable to EBCDIC and ASCII
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby host environments. In an EBCDIC environment, Apache normally translates
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby text content from the code page of the Apache process locale to
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby ISO-8859-1. <CODE>mod_charset_lite</CODE> can be used to specify that
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby a different translation is to be performed. In an ASCII environment,
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby Apache normally performs no translation, so <CODE>mod_charset_lite</CODE>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby is needed in order for any translation to take place.
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <p>This module will only work if <code>APACHE_XLATE</code> is defined
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby at compile time.</p>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby This module provides a small subset of configuration mechanisms
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby implemented by Russian Apache and its associated <CODE>mod_charset</CODE>.
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <LI><A HREF="#charsetsourceenc">CharsetSourceEnc</A>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <LI><A HREF="#charsetdefault">CharsetDefault</A>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <LI><A HREF="#charsetoptions">CharsetOptions</A>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby The character set name parameters of CharsetSourceEnc and CharsetDefault
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby must be acceptable to the translation mechanism used by APR on the system
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby where mod_charset_lite is deployed. These character set names are not
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby standardized and are usually not the same as the corresponding values used
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby in http headers. Currently, APR can only use iconv(3), so you can easily
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby test your character set names using the iconv(1) program, as follows:
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby iconv -f charsetsourceenc-value -t charsetdefault-value
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <H3>Mismatch between character set of content and translation rules</H3>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby If the translation rules don't make sense for the content, translation
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby can fail in various ways, including:
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby The translation mechanism may return a bad return code, and the connection
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby will be aborted.
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby The translation mechanism may silently place special characters (e.g., question
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby marks) in the output buffer when it cannot translate the input buffer.
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <H2><A NAME="charsetsourceenc">CharsetSourceEnc</A></H2>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby ><STRONG>Syntax:</STRONG></A> CharsetSourceEnc <EM>charset</EM>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby ><STRONG>Context:</STRONG></A> directory, virtual host
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby ><STRONG>Override:</STRONG></A> <EM>FileInfo</EM>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby The <CODE>CharsetSourceEnc</CODE> directive specifies the source charset
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby of files in the associated container.
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby The value of the <EM>charset</EM> argument must be accepted as a valid
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby character set name by the character set support in APR. Generally, this
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby means that it must be supported by iconv.
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <Directory "/export/home/trawick/apacheinst/htdocs/convert">
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby CharsetSourceEnc UTF-16BE
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby CharsetDefault ISO8859-1
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby </Directory>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby The character set names in this example work with the iconv
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby translation support in Solaris 8.
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <H2><A NAME="charsetdefault">CharsetDefault</A></H2>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby ><STRONG>Syntax:</STRONG></A> CharsetDefault <EM>charset</EM>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby ><STRONG>Context:</STRONG></A> directory, virtual host
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby ><STRONG>Override:</STRONG></A> <EM>FileInfo</EM>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby The <CODE>CharsetDefault</CODE> directive specifies the charset that
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby content in the associated container should be translated to.
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby The value of the <EM>charset</EM> argument must be accepted as a valid
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby character set name by the character set support in APR. Generally, this
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby means that it must be supported by iconv.
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <Directory "/export/home/trawick/apacheinst/htdocs/convert">
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby CharsetSourceEnc UTF-16BE
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby CharsetDefault ISO8859-1
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby </Directory>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <H2><A NAME="charsetoptions">CharsetOptions</A></H2>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby ><STRONG>Syntax:</STRONG></A> CharsetOptions <EM>option</em>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby ><STRONG>Default:</STRONG></A> <EM>DebugLevel=0</EM> <EM>NoImplicitAdd</EM>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby ><STRONG>Context:</STRONG></A> directory, virtual host
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby ><STRONG>Override:</STRONG></A> <EM>FileInfo</EM>
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby The <CODE>CharsetOptions</CODE> directive configures certain behaviors
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby of <CODE>mod_charset_lite</CODE>. <EM>Option</EM> can be one of
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby The <SAMP>DebugLevel</SAMP> keyword allows you to specify the level of
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby debug messages generated by <CODE>mod_charset_lite</CODE>. By default, no
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby messages are generated. This is equivalent to <SAMP>DebugLevel=0</SAMP>.
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby With higher numbers, more debug messages are generated, and server
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby performance will be degraded. The actual meanings of the numeric values
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby are described with the definitions of the DBGLVL_ constants near the
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <DT>ImplicitAdd | NoImplicitAdd
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby The <SAMP>ImplicitAdd</SAMP> keyword specifies that
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby <CODE>mod_charset_lite</CODE> should implicitly insert its filter when
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby the configuration specifies that the character set of content should be
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby translated. If the filter chain is explicitly configured using the
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby AddOutputFilter directive, <SAMP>NoImplicitAdd</SAMP> should be specified so
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby that <CODE>mod_charset_lite</CODE> doesn't add its filter.
f6e214c7418f43af38bd8c3a557e3d0a1d311cfaGavin Maltby<!--#include virtual="footer.html" -->