setlocale(3)setlocale(3)Namesetlocale - set localization for internationalized program
Syntax
#include <locale.h>
char *setlocale (category, locale)
int category;
char *locale;
Description
The function changes or queries the run-time environment of the pro‐
gram. The function can affect the settings of language, territory, and
codeset in the program's environment.
In the category argument, you specify what part of the run-time envi‐
ronment you want to affect. Possible values for category are shown in
the following table:
───────────────────────────────────────────────────────────
Effect of Specifying Environment Variable
category the Value Affected
───────────────────────────────────────────────────────────
LC_ALL Sets or queries LANG
entire environment
LC_COLLATE Changes or queries LC_COLLATE
collation sequences
LC_CTYPE Changes or queries LC_CTYPE
character classifi‐
cation
LC_NUMERIC Changes or queries LC_NUMERIC
number format infor‐
mation
LC_TIME Changes or queries LC_TIME
time conversion
parameters
LC_MONETARY Changes or queries LC_MONETARY
monetary information
───────────────────────────────────────────────────────────
You change only one part of the program's locale in a single call to
unless you use the category
The locale argument is a pointer to a character string containing the
required setting of category in the following format:
language[_territory[.codeset]][@modifier]
You use language to specify the native language you want in the program
environment. You can specify what dialect of the native language you
want in _territory, and the codeset to be used in codeset. For exam‐
ple, the following string specifies the French native language, as spo‐
ken in France (as opposed to Switzerland), and the Digital Multina‐
tional Character Set:
LANG = FRE_FR.MCS
You use @modifier to select a specific instance of an environment set‐
ting within a single category. For example, you could use @modifier to
select dictionary sorting of data, as opposed to telephone directory
sorting. You can use @modifier for all categories, except
The following preset values of locale are defined for all the settings
of category:
"C" Specifies setting the locale to the minimum C language envi‐
ronment, as specified by the ANSI standard for the C lan‐
guage. (Draft ANSI X3.159)
"" Specifies using the environment variable corresponding to
category to set the locale. If the appropriate environment
variable is not set, the environment variable is used. If is
not set, returns an error.
NULL Queries the current international environment and returns
current locale setting. You can use the string returns only
as input to a subsequent call; in particular, the string can‐
not be printed for category The string returns is a pointer
to static data area that might be written over.
International Environment
INTLINFO The INTLINFO environment variable specifies the direc‐
tory to search for language databases. The default is to
search the directory.
Examples
The following calls to the function set the environment to the French
language and then modify the collating sequence to German dictionary
collation:
setlocale (LC_ALL, "FRE_FR.MCS");
setlocale (LC_COLLATE, "GER_DE.MCS@dict");
You can use the function to bind the specific language requirements of
a user to the program as follows:
status = setlocale (LC_ALL, "");
For this example to work properly, the user of the international pro‐
gram sets the LANG variable before running the program. Once LANG is
set and the program runs, this call causes to use the definition of
LANG to set the current locale. You should test the value of after the
call completes to be sure no errors occur.
Return Values
If you pass valid setting for category and locale, other than NULL,
changes the current locale and returns the string associated with that
locale.
If locale is NULL, returns the string associated with category for the
current locale. The current locale is unchanged. The string returns
may not be in a printable format.
If either the category or locale argument is invalid, returns The func‐
tion does not modify the locale if any part of the call is invalid.
The function stores its return values in a data area that may be writ‐
ten over. You should move the return value to another location if you
want to use it in your program.
See Alsoic(1int), nl_langinfo(3int), printf(3int), environ(5int), lang(5int)
Guide to Developing International Software
setlocale(3)
