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 han-
dling 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_CTIME: | LC_ALL | LC_CTIME | 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(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| MT-Level | MT-Safe with exceptions |
| CSI | Enabled |
|_____________________________|_____________________________|
SEE ALSO
locale(1), ctype(3C), getdate(3C) gettext(3C), gettxt(3C),
isdigit(3C), localeconv(3C), mbtowc(3C), strcoll(3C),
strftime(3C), strptime(3C) strxfrm(3C) tolower(3C),
wctomb(3C), libc(3LIB), attributes(5), environ(5), locale(5)
NOTES
To change locale in a multithreaded application, setlocale()
should be called prior to using any locale-sensitive rou-
tine. Using setlocale() to query the current locale is safe
and can be used anywhere in a multithreaded application.
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.
Internationalization functions by setlocale() are supported
only when the dynamic linking version of libc has been
linked with the application. If the static linking version
of libc has been linked with the application, setlocale()
can handle only C and POSIX locales.
Man(1) output converted with
man2html