Name

setlocale − set localization for internationalized program

Syntax

#include <locale.h>

char *setlocale (category, locale)
int category;
char *locale;

Description

The setlocale 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:

You change only one part of the program’s locale in a single call to setlocale, unless you use the category LC_ALL.

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 LC_ALL.

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 LANG environment variable is used. If LANG is not set, setlocale returns an error.

NULLQueries the current international environment and returns current locale setting.  You can use the string setlocale returns only as input to a subsequent setlocale call; in particular, the string cannot be printed for category LC_ALL. The string setlocale returns is a pointer to static data area that might be written over.

International Environment

INTLINFOThe INTLINFO environment variable specifies the directory to search for language databases. The default is to search the /usr/lib/intln directory.

Examples

The following calls to the setlocale 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 setlocale 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 setlocale to use the definition of LANG to set the current locale.  You should test the value of status after the call completes to be sure no errors occur.

Return Values

If you pass valid setting for category and locale, other than NULL, setlocale changes the current locale and returns the string associated with that locale.

If locale is NULL, setlocale returns the string associated with category for the current locale.  The current locale is unchanged.  The string setlocale returns may not be in a printable format.

If either the category or locale argument is invalid, setlocale returns NULL. The setlocale function does not modify the locale if any part of the call is invalid.

The setlocale 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