setlocale(3C) SDK R4.11 setlocale(3C)
NAME
setlocale - modify and query a program's locale
SYNOPSIS
#include <locale.h>
char *setlocale(int category, const char *locale);
DESCRIPTION
setlocale changes or queries the program's entire locale or portions
thereof.
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 file. LC_CTYPE affects the
behavior of the character handling functions such as isalpha, and
tolower as well as the multibyte character functions such as mbtowc
and wctomb. LC_NUMERIC affects the decimal-point and thousands
separator characters for the formatted input/output functions, the
string conversion functions and the non-monetary formatting
information returned by localeconv [see localeconv(3C)]. LC_TIME
affects the behavior of functions such as ascftime, cftime, and
strftime. LC_COLLATE affects the behavior of strcoll, strxfrm, and
the regular expression code described in regexpr(3C). LC_MONETARY
affects the monetary formatted information returned by localeconv.
LC_MESSAGES affects the behavior of message catalog functions such as
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 the
system's 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/de/LC_CTYPE.
A value of ``C'' for locale specifies the default environment.
A value of "" for locale specifies that the name of the new locale
for the specified category should be taken from the environment. If
LC_ALL is defined in the environment and is not null, the value of
LC_ALL is used. Otherwise, if there is a variable defined in the
environment with the same name as category and that is not null, the
value specified by that environment variable is used. Otherwise, if
LANG is defined in the environment and is not null, the value of LANG
is used. Otherwise, the value ``C'' is used.
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 locale ``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, the locale is returned. If setlocale fails, a null pointer
is returned and the program's locale is not changed.
For programs that do not depend upon the C locale, the normal use of
setlocale is to execute
setlocale(LC_ALL, "")
as the first action in the application code. This has the effect of
initializing each category according to the environment variables
described above.
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 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, locale is returned.
If a composite locale string has fewer than six elements, the last
element is propagated to the missing locale categories. For
instance, the composite locale string "/en_AU/en_CA/en_US/en_US"
would set LC_MONETARY and LC_MESSAGES to "en_US".
On the 88K platform, the composite locale string is ordered as
/LC_CTYPE/LC_COLLATE/LC_TIME/LC_NUMERIC/LC_MONETARY/LC_MESSAGES. For
example, a string of "/en_AU/en_CA/en_GB/it/it/es" would set LC_CTYPE
to "en_AU", LC_COLLATE to "en_CA", LC_TIME to "en_GB", LC_NUMERIC to
"it", LC_MONETARY to "it" and LC_MESSAGES to "es".
On the Intel platform, the composite locale string is ordered as
/LC_CTYPE/LC_NUMERIC/LC_TIME/LC_COLLATE/LC_MONETARY/LC_MESSAGES. The
above example would set LC_NUMERIC to "en_CA" and LC_COLLATE to "it".
The values of the other catgories are the same as on the 88K.
On the Intel platform it is possible to specify the 88K platform
composite string ordering. To obtain this ordering, define
_OLD_LOCALE_ORDER_FLAVOR before including <locale.h>.
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/category
files containing the locale-specific information for each
locale and category
Considerations for Threads Programming
+----------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+----------+-----------------------------+
|setlocale | Y N N |
+----------+-----------------------------+
setlocale immediately changes the specified locale information for
all threads in a process. Calling setlocale with the argument LC_ALL
will change each portion of locale information for all threads in a
process. setlocale should be called when other threads in a process
do not rely on locale information for processing or can handle a
change in locale information.
Different shared library functions rely on the locale information
during processing. For instance, gettxt uses the LC_MESSAGES portion
of the locale in order to access the correct messages. Other
functions such as isalpha access the locale information to properly
process strings. Changing LC_CTYPE in the middle of string
processing may cause incorrect results.
Changing locale information should be done at a time when other
threads do not access the locale information which is changing. One
method is to set the locale information before the process is multi-
threaded. Another method may be to use user defined mutexes to
prevent modification of the locale at certain times. When
programming with setlocale, keep in mind two issues. The first is
when the call will take place. The second is how changing the locale
will impact the other threads in a process.
REFERENCES
reentrant(3), catgets(3C), catopen(3C), ctime(3C), ctype(3C),
getdate(3C), gettxt(3C), localeconv(3C), mbchar(3C), mbstring(3C),
printf(3S), strcoll(3C), strftime(3C), strtod(3C), strxfrm(3C),
environ(5).
Licensed material--property of copyright holder(s)