setlocale(3) Library Functions Manual setlocale(3)
Name
setlocale - 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 program. 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 environment 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 entire environment LANG
LC_COLLATE Changes or queries collation LC_COLLATE
sequences
LC_CTYPE Changes or queries character classi- LC_CTYPE
fication
LC_NUMERIC Changes or queries number format LC_NUMERIC
information
LC_TIME Changes or queries time conversion LC_TIME
parameters
LC_MONETARY Changes or queries monetary informa- LC_MONETARY
tion
---------------------------------------------------------------------------
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 example, the following string specifies the French native language, as
spoken in France (as opposed to Switzerland), and the Digital Multinational Character Set:
LANG = FRE_FR.MCS
You use @modifier to select a specific instance of an environment setting 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 environment, as specified by the ANSI standard for the C language. (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 cannot 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 directory 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 program 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 function 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 written over. You should move the return value to another location if you
want to use it in your program.
See Also
ic(1int), nl_langinfo(3int), printf(3int), environ(5int), lang(5int)
Guide to Developing International Software
setlocale(3)