setlocale(3C)setlocale(3C)NAMEsetlocale - modify and query a program's locale
SYNOPSIS
#include <locale.h>
char *setlocale (int category, const char *locale);
DESCRIPTIONsetlocale 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 file. LC_CTYPE affects the behavior of the character
handling functions (isalpha, tolower, etc.) and the multibyte character
functions (such as mbtowc and wctomb). 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 that 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:
Category 1st Env. Var. 2nd Env. Var
___________________________________________
LC_CTYPE: LC_CTYPE LANG
LC_COLLATE: LC_COLLATE LANG
LC_TIME: LC_TIME LANG
LC_NUMERIC: LC_NUMERIC LANG
LC_MONETARY: LC_MONETARY LANG
LC_MESSAGES: LC_MESSAGES LANG
At program startup, the equivalent of
setlocale(LC_ALL, "C")
Page 1
setlocale(3C)setlocale(3C)
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 returned by a previous call to
setlocale with LC_ALL for which the locale did not consist of identical
category values. If setlocale fails to set the locale for any category,
a null pointer is returned and the program's locale for all categories is
not changed. Otherwise, a description of the new 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/C/LC_CTYPE LC_CTYPE database for the C locale
/usr/lib/locale/C/LC_NUMERIC LC_NUMERIC database for the C locale
/usr/lib/locale/C/LC_TIME LC_TIME database for the C locale
/usr/lib/locale/C/LC_COLLATE LC_COLLATE database for the C locale
/usr/lib/locale/C/LC_MESSAGES LC_MESSAGES database for the C locale
/usr/lib/locale/locale/category files containing the locale-specific
information for each locale and
category
SEE ALSOctime(3C), ctype(3C), getdate(3C), gettxt(3G), localeconv(3C),
mbchar(3C), mbstring, strcoll(3C), strftime(3C), strtod(3C), strxfrm(3C),
printf(3S), environ(5).
BUGS
Because setlocale() may call dlopen(3), and because dlopen(3) calls are
forbidden from init sections of DSO's, setlocale() should not be called
from such sections. See DSO(5) for more information.
Page 2
