setlocale(3C)

NAME

setlocale − modify and query a program’s locale

SYNOPSIS

#include <locale.h>

char ∗setlocale(int category, const char ∗locale);

DESCRIPTION

setlocale() selects the appropriate piece of the program’s locale as specified by the category and locale arguments. The category argument may have the following values: LC_CTYPE, LC_NUMERIC, LC_TIME, LC_COLLATE, LC_MONETARY, LC_MESSAGES, and LC_ALL. These names are defined in the <locale.h> header. LC_CTYPE affects the behavior of the character handling functions (isdigit(), tolower(), etc.) and the multibyte character functions (such as mbtowc() and wctomb() (see mbchar(3C)). LC_NUMERIC affects the decimal-point character for the formatted input/output functions and the string conversion functions as well as the non-monetary formatting information returned by localeconv(). (See localeconv(3C)). LC_TIME affects the behavior of ascftime(), cftime(), getdate(), and strftime(). LC_COLLATE affects the behavior of strcoll() and strxfrm(). LC_MONETARY affects the monetary formatted information returned by localeconv(). LC_MESSAGES affects the behavior of gettxt(), catopen(), catclose(), and catgets(). (See catopen(3C) and catgets(3C).) LC_ALL names the program’s entire locale.

Each category corresponds to a set of databases which contain the relevant information for each defined locale. The location of a database is given by the following path, /usr/lib/locale/locale/category, where locale and category are the names of locale and category, respectively. For example, the database for the LC_CTYPE category for the "german" locale would be found in /usr/lib/locale/german/LC_CTYPE.

A value of "C" for locale specifies the default environment.

A value of "" for locale specifies that the locale should be taken from environment variables. The order in which the environment variables are checked for the various categories is given below:

Category1st Env. Var.2nd Env. Var.3rd Env. Var
LC_CTYPE:LC_ALLLC_CTYPELANG
LC_COLLATE:LC_ALLLC_COLLATELANG
LC_TIME:LC_ALLLC_TIMELANG
LC_NUMERIC:LC_ALLLC_NUMERIC LANG
LC_MONETARY:LC_ALLLC_MONETARY LANG
LC_MESSAGES:LC_ALLLC_MESSAGES LANG

At program startup, the equivalent of

setlocale(LC_ALL, "C")

is executed. This has the effect of initializing each category to the locale described by the environment "C".

If a pointer to a string is given for locale, setlocale() attempts to set the locale for the given category to locale. If setlocale() succeeds, locale is returned. If setlocale() fails, a null pointer is returned and the program’s locale is not changed.

For category LC_ALL, the behavior is slightly different. If a pointer to a string is given for locale and LC_ALL is given for category, setlocale() attempts to set the locale for all the categories to locale. The locale may be a simple locale, consisting of a single locale, or a composite locale. A composite locale is a string beginning with a "/" followed by the locale of each category separated by a "/". If setlocale() fails to set the locale for any category, a null pointer is returnedand the program’s locale for all categories is not changed. Otherwise, locale is returned.

A null pointer for locale causes setlocale() to return the current locale associated with the category. The program’s locale is not changed.

FILES

/usr/lib/locale/locale/LC_CTYPE character type database for locale

/usr/lib/locale/locale/LC_NUMERIC numeric format data for locale

/usr/lib/locale/locale/LC_TIME date and time formats for locale

/usr/lib/locale/locale/LC_COLLATE sort ordering information for locale

/usr/lib/locale/locale/LC_MESSAGES message catalogs for locale

/usr/lib/locale/locale/LC_MONETARY
currency format data for locale

Museum

Related Articles

setlocale(3C)

NAME

SYNOPSIS

DESCRIPTION

FILES

SEE ALSO