SETLOCALE(3C) Standard C Library Functions SETLOCALE(3C)

NAME

setlocale - modify and query a program's locale

SYNOPSIS

#include <locale.h>

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

DESCRIPTION

The setlocale() function 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. The LC_ALL
variable names all of a program's locale categories.


The LC_CTYPE variable affects the behavior of character handling
functions such as isdigit(3C) and tolower(3C), and multibyte
character functions such as mbtowc(3C) and wctomb(3C).


The LC_NUMERIC variable affects the decimal point character and
thousands separator character for the formatted input/output
functions and string conversion functions.


The LC_TIME variable affects the date and time format as delivered by
ascftime(3C), cftime(3C), getdate(3C), strftime(3C), and
strptime(3C).


The LC_COLLATE variable affects the sort order produced by collating
functions such as strcoll(3C) and strxfrm(3C).


The LC_MONETARY variable affects the monetary formatted information
returned by localeconv(3C).


The LC_MESSAGES variable affects the behavior of messaging functions
such as dgettext(3C), gettext(3C), and gettxt(3C).


A value of "C" for locale specifies the traditional UNIX system
behavior. 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".


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 | 3rd Env Var |
+-------------+-------------+-------------+-------------+
|LC_CTYPE: | LC_ALL | LC_CTYPE | LANG |
+-------------+-------------+-------------+-------------+
|LC_COLLATE: | LC_ALL | LC_COLLATE | LANG |
+-------------+-------------+-------------+-------------+
|LC_TIME: | LC_ALL | LC_TIME | LANG |
+-------------+-------------+-------------+-------------+
|LC_NUMERIC: | LC_ALL | LC_NUMERIC | LANG |
+-------------+-------------+-------------+-------------+
|LC_MONETARY: | LC_ALL | LC_MONETARY | LANG |
+-------------+-------------+-------------+-------------+
|LC_MESSAGES: | LC_ALL | LC_MESSAGES | LANG |
+-------------+-------------+-------------+-------------+


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. If the locales for all the categories
are the same after all the attempted locale changes, setlocale() will
return a pointer to the common simple locale. If there is a mixture
of locales among the categories, setlocale() will return a composite
locale.

RETURN VALUES

Upon successful completion, setlocale() returns the string associated
with the specified category for the new locale. Otherwise,
setlocale() returns a null pointer and the program's locale is not
changed.


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


The string returned by setlocale() is such that a subsequent call
with that string and its associated category will restore that part
of the program's locale. The string returned must not be modified by
the program, but may be overwritten by a subsequent call to
setlocale().

ERRORS

No errors are defined.

FILES

/usr/lib/locale/locale
locale database directory for locale

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+--------------------+-------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-------------------------+
|CSI | Enabled |
+--------------------+-------------------------+
|Interface Stability | Standard |
+--------------------+-------------------------+
|MT-Level | MT-Safe with exceptions |
+--------------------+-------------------------+

SEE ALSO

locale(1), ctype(3C), getdate(3C) gettext(3C), gettxt(3C),
isdigit(3C), libc(3LIB), localeconv(3C), mbtowc(3C), strcoll(3C),
strftime(3C), strptime(3C) strxfrm(3C) tolower(3C), wctomb(3C),
attributes(7), environ(7), locale(7), standards(7)

NOTES

It is unsafe for any thread to change locale (by calling setlocale()
with a non-null locale argument) in a multithreaded application while
any other thread in the application is using any locale-sensitive
routine. To change locale in a multithreaded application, setlocale()
should be called prior to using any locale-sensitive routine. Using
setlocale() to query the current locale is safe and can be used
anywhere in a multithreaded application except when some other thread
is changing locale.


It is the user's responsibility to ensure that mixed locale
categories are compatible. For example, setting LC_CTYPE=C and
LC_TIME=ja (where ja indicates Japanese) will not work, because
Japanese time cannot be represented in the "C" locale's ASCII
codeset.

September 19, 2005 SETLOCALE(3C)