<!--
    Licensed to the Apache Software  Foundation (ASF) under one or more
    contributor  license agreements.  See  the NOTICE  file distributed
    with  this  work  for  additional information  regarding  copyright
    ownership.   The ASF  licenses this  file to  you under  the Apache
    License, Version  2.0 (the  License); you may  not use  this file
    except in  compliance with the License.   You may obtain  a copy of
    the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the  License is distributed on an  "AS IS" BASIS,
    WITHOUT  WARRANTIES OR CONDITIONS  OF ANY  KIND, either  express or
    implied.   See  the License  for  the  specific language  governing
    permissions and limitations under the License.

    Copyright 1999-2007 Rogue Wave Software, Inc.
-->

<HTML>
<HEAD>
<TITLE>localedef utility</TITLE>
<LINK REL=StyleSheet HREF="../rw.css" TYPE="text/css" TITLE="Apache stdcxx Stylesheet"></HEAD>
<BODY BGCOLOR=#FFFFFF>
<A HREF="localeutility.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="logic-error.html"><IMG SRC="images/bnext.gif" WIDTH=20 HEIGHT=21 ALT="Next file" BORDER=O></A><DIV CLASS="DOCUMENTNAME"><B>Apache C++ Standard Library Reference Guide</B></DIV>
<H2>localedef utility</H2><PRE><HR><B><I>Utility Program</I></B><HR></PRE>

<UL>
<LI><A HREF="#sec1">Local Index</A></LI>
<LI><A HREF="#sec2">Summary</A></LI>
<LI><A HREF="#sec3">Synopsis</A></LI>
<LI><A HREF="#sec4">Description</A></LI>
<LI><A HREF="#sec5">Options</A></LI>
<LI><A HREF="#sec6">Operands</A></LI>
<LI><A HREF="#sec7">Environment Variables</A></LI>
<LI><A HREF="#sec8">Input</A></LI>
<LI><A HREF="#sec9">Output</A></LI>
<LI><A HREF="#sec10">Exit Status</A></LI>
<LI><A HREF="#sec11">Examples</A></LI>
<LI><A HREF="#sec12">See Also</A></LI>
<LI><A HREF="#sec13">Standards Conformance</A></LI>
</UL>
<A NAME="sec1"><H3>Local Index</H3></A>
<H4>Members</H4>
<UL><TABLE CELLPADDING=3>
<TR><TD VALIGN=top>
<A HREF="#idx835">RWSTD_SRC_ROOT</A><BR>
</TD>
<TD VALIGN=top></TD></TR>
</TABLE></UL>

<A NAME="sec2"><H3>Summary</H3></A>
<P>A utility program to define a localization environment. </P>
<A NAME="sec3"><H3>Synopsis</H3></A>

<PRE>localedef [-c][-f <I>charmap</I>][-i <I>sourcefile</I>][-u <I>code_set_name</I>]         <I>name</I>
</PRE>
<P>Extensions of this implementation:</P>

<PRE>
localedef [-w][-w<I>N</I>][-f <I>charmap</I>][-i <I>sourcefile</I>][--help][--ucs]         <I>name</I>
localedef -g [-m <I>locale_list</I>][-r <I>charmap_dir</I>][-s <I>source_dir</I>]         [-d <I>output_dir</I>]
</PRE>
<A NAME="sec4"><H3>Description</H3></A>
<P>The <SAMP>localedef</SAMP> utility reads one or more locale definition files and character set description files and translates them into binary files suitable for interpretation by this implementation of the C++ Standard Library. The binary files produced by <SAMP>localedef</SAMP> are referred to in this document as <I>locale databases</I>. In particular, the localization library makes use of this information to implement its behavior. The behavior of the utility is affected by the environment variable <SAMP>${RWSTD_SRC_ROOT}</SAMP>.</P>
<A NAME="sec5"><H3>Options</H3></A>
<P><A HREF="localedefutility.html#Table&nbsp;25">Table&nbsp;25</A> illustrates options that conform to the requirements of the IEEE Std 1003.1-2001 (POSIX) standard. </P>
<H4><A NAME="Table&nbsp;25">Table&nbsp;25: localedef option requirements of the IEEE Std. 1003.1-2001 (POSIX) standard&nbsp;</A></H4>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="3">
<tr><td valign=top><B>Option</B>
</td>
<td valign=top><B>Meaning</B>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>-c</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Create output regardless of warnings.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>-f </SAMP><SAMP><I>charmap</I></SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Use <SAMP><I>charmap</I></SAMP> as the pathname of the character set description file.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>-i </SAMP><SAMP><I>sourcefile</I></SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Use <SAMP><I>sourcefile</I></SAMP> as the pathname of the locale description file. If this option is not specified, <SAMP>localdef</SAMP> reads the locale definition from its standard input.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>-u </SAMP><SAMP><I>code_set_name</I></SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Use <SAMP><I>code_set_name</I></SAMP> as the target mapping for character symbols and collating element symbols whose encoding values are defined in terms of the ISO/IEC 10646-1:2000 standard position constant values.</P>
</td>
</tr>
</TABLE>
<P><A HREF="localedefutility.html#Table&nbsp;26">Table&nbsp;26</A> illustrates options that are provided as extensions to the IEEE Std 1003.1-2001 (POSIX) standard.   </P>
<H4><A NAME="Table&nbsp;26">Table&nbsp;26: localedef option extensions to the IEEE Std 1003.1-2001 (POSIX) standard&nbsp;</A></H4>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="3">
<tr><td valign=top><B>Option</B>
</td>
<td valign=top><B>Meaning</B>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>-w</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Disable all warnings.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>-w</SAMP><SAMP><I>N</I></SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Disable warning number <SAMP><I>N</I></SAMP>, where <SAMP><I>N</I></SAMP> is a non-negative integer. The option can be repeated any number of times to disable multiple warnings.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>-g</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Enter <SAMP><I>batch mode</I></SAMP>.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE">-m <SAMP><I>locale_list</I></SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Use <SAMP><I>locale_list</I></SAMP> as the name of a file containing a list associating locale names with the names of encodings. This option is only allowed in batch mode.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>-r</SAMP> <SAMP><I>charmap_dir</I></SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Use <SAMP><I>charmap_dir</I></SAMP> as the name of the directory under which <SAMP>localedef</SAMP> should look for character set description files. This option is only allowed in batch mode.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>-r</SAMP> <SAMP><I>source_dir</I></SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Use <SAMP><I>source_dir</I></SAMP> as the name of the directory under which <SAMP>localedef</SAMP> should look for locale definition files. This option is only allowed in batch mode.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>-d output_dir</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Use <SAMP><I>output_dir</I></SAMP> as the name of the directory under which <SAMP>localedef</SAMP> should place binary files produced in batch mode.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>--ucs</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Use the Universal Character Set (either UCS-4 or UCS-2) to encode characters of type <SAMP>wchar_t</SAMP>. This option may require character set description files in an extended format.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>--help</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Print a usage message to <SAMP>stdout</SAMP> and exit with <SAMP>0</SAMP> exit status.</P>
</td>
</tr>
</TABLE>
<A NAME="sec6"><H3>Operands</H3></A>
<P>The following operands are accepted:</P>

<UL><PRE><B><I>name</I></B>
</PRE></UL>
<UL>
<P>The name of a locale database to produce. If <I>name</I> contains at least one slash character it is considered to be a pathname, and will be created under the directory tree specified. Otherwise, <I>name</I> is considered to be a filename and will be created in the current working directory.</P>
</UL>

<A NAME="sec7"><H3>Environment Variables</H3></A>

<A NAME="idx835"></A><PRE><B>RWSTD_SRC_ROOT</B></PRE>
<UL>
<P>The pathname of the root of the directory tree containing character set description files and locale definition files. The character set description files are assumed to reside in <SAMP>${RWSTD_SRC_ROOT}/charmaps</SAMP>, the locale definition files in <SAMP>${RWSTD_SRC_ROOT}/src</SAMP>.</P>
</UL>

<A NAME="sec8"><H3>Input</H3></A>
<P>Unless the <SAMP>-i</SAMP> option is used, <SAMP>localedef</SAMP> reads the locale definition from <SAMP>stdin</SAMP>. Otherwise, <SAMP>localedef</SAMP> reads the locale definition from the filename specified with the <SAMP>-i</SAMP> option. The utility also attempts to read files named by any copy directives that appear in the locale definition. <SAMP>localedef</SAMP> reads character set descriptions from the files specified with the <SAMP>-f</SAMP> option.</P>
<P>The required format of the character set description file follows that described in section 6.4, Character Set Description File, of IEEE Std 1003.1-2001.</P>
<P>The required format of the locale definition file follows that described in section 7.3, Locale Definition, of IEEE Std 1003.1-2001. </P>
<P>Any files that conform to the required format can be used with <SAMP>localedef</SAMP> to produce binary locale database files suitable for use with the Apache C++ Standard Library.</P>
<P>A limited number of character set description files and locale definition files in the conforming format can be purchased from The Open Group. See   <SAMP>http://www.opengroup.org/pubs/catalog/lo.htm</SAMP>.</P>
<P>Character set description files and locale definition files in an extended format can be obtained without charge from the JTC1/SC22/WG15 -- POSIX pages at <SAMP>ftp://dkuug.dk/i18n/WG15-collection/</SAMP>. These files are distributed with the Apache C++ Standard Library sources.</P>
<P>Additionally, the <SAMP>localedef</SAMP> utility also accepts files in an extended format used by GNU C library, glibc 2<br><SAMP>(http://www.gnu.org/software/libc/libc.html)</SAMP>. The locale definition files that accompany glibc 2.2.5 are distributed with the Apache C++ Standard Library sources. </P>
<P>Finally, <SAMP>localedef</SAMP> utility accepts files shipped with HP-UX 11.00 and later. The character set description files are installed in<br><SAMP>/usr/lib/nls/loc/charmaps</SAMP>, the locale definition files are in <br><SAMP>/usr/lib/nls/loc/src</SAMP>. These files are not distributed with the Apache C++ Standard Library sources.</P>
<A NAME="sec9"><H3>Output</H3></A>
<P>On success, <SAMP>localedef</SAMP> will create one or more files. If the <SAMP>name</SAMP> argument does not contain the slash character, files are created in the current working directory. Otherwise, the output files will be created in the directory specified by <SAMP>name</SAMP>. The following directory tree describes the organization of the output files:</P>

<UL><PRE><I>encoding<br>name</I>/<br><I>name</I>/LC_COLLATE<br><I>name</I>/LC_CTYPE<br><I>name</I>/LC_MONETARY<br><I>name</I>/LC_NUMERIC<br><I>name</I>/LC_TIME<br><I>name</I>/LC_MESSAGES 
</PRE></UL>
<P>The name of the <SAMP><I>encoding</I></SAMP> file reflects the used character set definition as specified by the <SAMP>-f</SAMP> option. The name of the directory name corresponds to the name argument passed to <SAMP>localedef</SAMP>. Under the directory, <SAMP>localedef</SAMP> creates up to six files named <SAMP>LC_COLLATE</SAMP>, <SAMP>LC_CTYPE</SAMP>, etc., one for each section that appears in the locale definition.</P>
<P>Any warning or error diagnostic messages produced by <SAMP>localedef</SAMP> are sent to <SAMP>stderr</SAMP>.</P>
<A NAME="sec10"><H3>Exit Status</H3></A>
<P>The <SAMP>localedef</SAMP> utility exits with the status codes listed in <A HREF="localedefutility.html#Table&nbsp;27">Table&nbsp;27</A>:  </P>
<H4><A NAME="Table&nbsp;27">Table&nbsp;27: localedef exit status&nbsp;</A></H4>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="3">
<tr><td valign=top><B>Exit Status</B>
</td>
<td valign=top><B>Meaning</B>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>0</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">No errors occurred and locale databases were successfully created.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>1</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Warnings occurred and locale databases were successfully created.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>2</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">The locale specification exceeded implementation limits or the coded character set or sets used are not supported, and no locale databases were created.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>&gt; 3</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Warnings or errors occurred and no locale databases were created.</P>
</td>
</tr>
</TABLE>
<A NAME="sec11"><H3>Examples</H3></A>
<P>Please note that the examples in this section use extensions of this implementation to the <SAMP>localedef</SAMP> utility.</P>
<P>The following command tries to create a locale database called <SAMP>german</SAMP> for the German locale <SAMP>de_DE</SAMP> using the ISO 8859-1 character set, and the locale definition file <SAMP>de_DE</SAMP>:</P>

<UL><PRE>$ localedef -f nls/charmaps/ISO-8859-1 \
    -i nls/src/de_DE german
</PRE></UL>
<P>Warnings normally prevent the successful creation of the output binary file. Since not all of the provided files are entirely clean of warnings, the following command forces <SAMP>localedef</SAMP> to produce output even in the presence of warnings. This command creates a locale database called <SAMP>french@euro</SAMP> for the French locale using the ISO 8859-15 character set, and the locale definition file <SAMP>fr_FR.euro</SAMP>:</P>

<UL><PRE>$ localedef -c -f nls/charmaps/ISO-8859-15 \
    -i nls/src/fr_FR.euro french@euro
</PRE></UL>
<P>This command may still produce a number of warnings, but assuming there are no errors, <SAMP>localedef</SAMP> will create a valid binary locale database. The command below makes use of the <SAMP>-w</SAMP> option to indiscriminately silence all warning messages. It creates a locale database called <SAMP>ja.euc</SAMP> in the <SAMP>/tmp </SAMP>directory from the Japanese locale definition file <SAMP>ja_JP</SAMP> using the <SAMP>EUC-JP</SAMP> encoding:</P>

<UL><PRE>$ localedef -c -w -f nls/charmaps/EUC-JP \
   -i nls/src/ja_JP /tmp/ja.euc
</PRE></UL>
<A NAME="sec12"><H3>See Also</H3></A>
<P><A HREF="locale.html">locale</A> utility,<B> </B>class <B><I>locale</I></B></P>
<A NAME="sec13"><H3>Standards Conformance</H3></A>
<P><I>IEEE Std 1003.1-2001 -- The Open Group Base Specifications Issue 6</I></P>

<BR>
<HR>
<A HREF="localeutility.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="logic-error.html"><IMG SRC="images/bnext.gif" WIDTH=20 HEIGHT=21 ALT="Next file" BORDER=O></A>

<!-- Google Analytics tracking code -->
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
    _uacct = "UA-1775151-1";
    urchinTracker();
</script>
<!-- end of Google Analytics tracking code -->

</BODY>
</HTML>