<!-- This HTML file has been created by texi2html 1.27
     from library.texinfo on 3 March 1994 -->

<TITLE>The GNU C Library - Locales and Internationalization</TITLE>
<P>Go to the <A HREF="library_6.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_6.html">previous</A>, <A HREF="library_8.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_8.html">next</A> section.<P>
<H1><A NAME="SEC76" HREF="library_toc.html#SEC76" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC76">Locales and Internationalization</A></H1>
<P>
Different countries and cultures have varying conventions for how to
communicate.  These conventions range from very simple ones, such as the
format for representing dates and times, to very complex ones, such as
the language spoken.
<A NAME="IDX356"></A>
<A NAME="IDX357"></A>
<P>
<DFN>Internationalization</DFN> of software means programming it to be able
to adapt to the user's favorite conventions.  In ANSI C,
internationalization works by means of <DFN>locales</DFN>.  Each locale
specifies a collection of conventions, one convention for each purpose.
The user chooses a set of conventions by specifying a locale (via
environment variables).
<P>
All programs inherit the chosen locale as part of their environment.
Provided the programs are written to obey the choice of locale, they
will follow the conventions preferred by the user.
<P>
<H2><A NAME="SEC77" HREF="library_toc.html#SEC77" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC77">What Effects a Locale Has</A></H2>
<P>
Each locale specifies conventions for several purposes, including the
following:
<P>
<UL>
<LI>
What multibyte character sequences are valid, and how they are
interpreted (see section <A HREF="library_6.html#SEC66" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_6.html#SEC66">Extended Characters</A>).
<P>
<LI>
Classification of which characters in the local character set are
considered alphabetic, and upper- and lower-case conversion conventions
(see section <A HREF="library_4.html#SEC54" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_4.html#SEC54">Character Handling</A>).
<P>
<LI>
The collating sequence for the local language and character set
(see section <A HREF="library_5.html#SEC63" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_5.html#SEC63">Collation Functions</A>).
<P>
<LI>
Formatting of numbers and currency amounts.
<P>
<LI>
Formatting of dates and times (see section <A HREF="library_19.html#SEC317" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC317">Formatting Date and Time</A>).
<P>
<LI>
What language to use for output, including error messages.
(The C library doesn't yet help you implement this.)
<P>
<LI>
What language to use for user answers to yes-or-no questions.
<P>
<LI>
What language to use for more complex user input.
(The C library doesn't yet help you implement this.)
</UL>
<P>
Some aspects of adapting to the specified locale are handled
automatically by the library subroutines.  For example, all your program
needs to do in order to use the collating sequence of the chosen locale
is to use <CODE>strcoll</CODE> or <CODE>strxfrm</CODE> to compare strings.
<P>
Other aspects of locales are beyond the comprehension of the library.
For example, the library can't automatically translate your program's
output messages into other languages.  The only way you can support
output in the user's favorite language is to program this more or less
by hand.  (Eventually, we hope to provide facilities to make this
easier.)
<P>
This chapter discusses the mechanism by which you can modify the current
locale.  The effects of the current locale on specific library functions
are discussed in more detail in the descriptions of those functions.
<P>
<H2><A NAME="SEC78" HREF="library_toc.html#SEC78" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC78">Choosing a Locale</A></H2>
<P>
The simplest way for the user to choose a locale is to set the
environment variable <CODE>LANG</CODE>.  This specifies a single locale to use
for all purposes.  For example, a user could specify a hypothetical
locale named <SAMP>`espana-castellano'</SAMP> to use the standard conventions of
most of Spain.
<P>
The set of locales supported depends on the operating system you are
using, and so do their names.  We can't make any promises about what
locales will exist, except for one standard locale called <SAMP>`C'</SAMP> or
<SAMP>`POSIX'</SAMP>.
<A NAME="IDX358"></A>
<P>
A user also has the option of specifying different locales for different
purposes--in effect, choosing a mixture of two locales.
<P>
For example, the user might specify the locale <SAMP>`espana-castellano'</SAMP>
for most purposes, but specify the locale <SAMP>`usa-english'</SAMP> for
currency formatting.  This might make sense if the user is a
Spanish-speaking American, working in Spanish, but representing monetary
amounts in US dollars.
<P>
Note that both locales <SAMP>`espana-castellano'</SAMP> and <SAMP>`usa-english'</SAMP>,
like all locales, would include conventions for all of the purposes to
which locales apply.  However, the user can choose to use each locale
for a particular subset of those purposes.
<P>
<A NAME="IDX359"></A>
<A NAME="IDX360"></A>
<H2><A NAME="SEC79" HREF="library_toc.html#SEC79" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC79">Categories of Activities that Locales Affect</A></H2>
<P>
The purposes that locales serve are grouped into <DFN>categories</DFN>, so
that a user or a program can choose the locale for each category
independently.  Here is a table of categories; each name is both an
environment variable that a user can set, and a macro name that you can
use as an argument to <CODE>setlocale</CODE>.
<P>
<DL COMPACT>
<A NAME="IDX361"></A>
<DT><CODE>LC_COLLATE</CODE>
<DD>This category applies to collation of strings (functions <CODE>strcoll</CODE>
and <CODE>strxfrm</CODE>); see section <A HREF="library_5.html#SEC63" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_5.html#SEC63">Collation Functions</A>.
<P>
<A NAME="IDX362"></A>
<DT><CODE>LC_CTYPE</CODE>
<DD>This category applies to classification and conversion of characters;
see section <A HREF="library_4.html#SEC54" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_4.html#SEC54">Character Handling</A>.
<P>
<A NAME="IDX363"></A>
<DT><CODE>LC_MONETARY</CODE>
<DD>This category applies to formatting monetary values; see section <A HREF="library_7.html#SEC82" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_7.html#SEC82">Numeric Formatting</A>.
<P>
<A NAME="IDX364"></A>
<DT><CODE>LC_NUMERIC</CODE>
<DD>This category applies to formatting numeric values that are not
monetary; see section <A HREF="library_7.html#SEC82" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_7.html#SEC82">Numeric Formatting</A>.
<P>
<A NAME="IDX365"></A>
<DT><CODE>LC_TIME</CODE>
<DD>This category applies to formatting date and time values; see
section <A HREF="library_19.html#SEC317" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC317">Formatting Date and Time</A>.
<P>
<A NAME="IDX366"></A>
<DT><CODE>LC_ALL</CODE>
<DD>This is not an environment variable; it is only a macro that you can use
with <CODE>setlocale</CODE> to set a single locale for all purposes.
<P>
<A NAME="IDX367"></A>
<DT><CODE>LANG</CODE>
<DD>If this environment variable is defined, its value specifies the locale
to use for all purposes except as overridden by the variables above.
</DL>
<P>
<H2><A NAME="SEC80" HREF="library_toc.html#SEC80" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC80">How Programs Set the Locale</A></H2>
<P>
A C program inherits its locale environment variables when it starts up.
This happens automatically.  However, these variables do not
automatically control the locale used by the library functions, because
ANSI C says that all programs start by default in the standard <SAMP>`C'</SAMP>
locale.  To use the locales specified by the environment, you must call
<CODE>setlocale</CODE>.  Call it as follows:
<P>
<PRE>
setlocale (LC_ALL, "");
</PRE>
<P>
to select a locale based on the appropriate environment variables.
<A NAME="IDX368"></A>
<A NAME="IDX369"></A>
<P>
You can also use <CODE>setlocale</CODE> to specify a particular locale, for
general use or for a specific category.
<A NAME="IDX370"></A>
<P>
The symbols in this section are defined in the header file <TT>`locale.h'</TT>.
<P>
<A NAME="IDX371"></A>
<U>Function:</U> char * <B>setlocale</B> <I>(int <VAR>category</VAR>, const char *<VAR>locale</VAR>)</I><P>
The function <CODE>setlocale</CODE> sets the current locale for 
category <VAR>category</VAR> to <VAR>locale</VAR>.
<P>
If <VAR>category</VAR> is <CODE>LC_ALL</CODE>, this specifies the locale for all
purposes.  The other possible values of <VAR>category</VAR> specify an
individual purpose (see section <A HREF="library_7.html#SEC79" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_7.html#SEC79">Categories of Activities that Locales Affect</A>).
<P>
You can also use this function to find out the current locale by passing
a null pointer as the <VAR>locale</VAR> argument.  In this case,
<CODE>setlocale</CODE> returns a string that is the name of the locale
currently selected for category <VAR>category</VAR>.
<P>
The string returned by <CODE>setlocale</CODE> can be overwritten by subsequent
calls, so you should make a copy of the string (see section <A HREF="library_5.html#SEC61" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_5.html#SEC61">Copying and Concatenation</A>) if you want to save it past any further calls to
<CODE>setlocale</CODE>.  (The standard library is guaranteed never to call
<CODE>setlocale</CODE> itself.)
<P>
You should not modify the string returned by <CODE>setlocale</CODE>.
It might be the same string that was passed as an argument in a 
previous call to <CODE>setlocale</CODE>.
<P>
When you read the current locale for category <CODE>LC_ALL</CODE>, the value
encodes the entire combination of selected locales for all categories.
In this case, the value is not just a single locale name.  In fact, we
don't make any promises about what it looks like.  But if you specify
the same "locale name" with <CODE>LC_ALL</CODE> in a subsequent call to
<CODE>setlocale</CODE>, it restores the same combination of locale selections.
<P>
When the <VAR>locale</VAR> argument is not a null pointer, the string returned
by <CODE>setlocale</CODE> reflects the newly modified locale.
<P>
If you specify an empty string for <VAR>locale</VAR>, this means to read the
appropriate environment variable and use its value to select the locale
for <VAR>category</VAR>.
<P>
If you specify an invalid locale name, <CODE>setlocale</CODE> returns a null
pointer and leaves the current locale unchanged.
<P>
Here is an example showing how you might use <CODE>setlocale</CODE> to
temporarily switch to a new locale.
<P>
<PRE>
#include &#60;stddef.h&#62;
#include &#60;locale.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;string.h&#62;

void
with_other_locale (char *new_locale,
                   void (*subroutine) (int),
                   int argument)
{
  char *old_locale, *saved_locale;

  /* Get the name of the current locale.  */
  old_locale = setlocale (LC_ALL, NULL);
  
  /* Copy the name so it won't be clobbered by <CODE>setlocale</CODE>. */
  saved_locale = strdup (old_locale);
  if (old_locale == NULL)
    fatal ("Out of memory");
  
  /* Now change the locale and do some stuff with it. */
  setlocale (LC_ALL, new_locale);
  (*subroutine) (argument);
  
  /* Restore the original locale. */
  setlocale (LC_ALL, saved_locale);
  free (saved_locale);
}
</PRE>
<P>
<STRONG>Portability Note:</STRONG> Some ANSI C systems may define additional
locale categories.  For portability, assume that any symbol beginning
with <SAMP>`LC_'</SAMP> might be defined in <TT>`locale.h'</TT>.
<P>
<H2><A NAME="SEC81" HREF="library_toc.html#SEC81" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC81">Standard Locales</A></H2>
<P>
The only locale names you can count on finding on all operating systems
are these three standard ones:
<P>
<DL COMPACT>
<DT><CODE>"C"</CODE>
<DD>This is the standard C locale.  The attributes and behavior it provides
are specified in the ANSI C standard.  When your program starts up, it
initially uses this locale by default.
<P>
<DT><CODE>"POSIX"</CODE>
<DD>This is the standard POSIX locale.  Currently, it is an alias for the
standard C locale.
<P>
<DT><CODE>""</CODE>
<DD>The empty name stands for a site-specific default locale.  It's supposed
to be a good default for the machine on which the program is running.