setlocale(3C) DG/UX 5.4R3.00 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: LCCTYPE, LCNUMERIC,
LCTIME, LCCOLLATE, LCMONETARY, LCMESSAGES and LCALL. These
names are defined in the locale.h header file. LCCTYPE affects the
behavior of the character handling functions (isdigit, tolower, etc.)
and the multibyte character functions (such as mbtowc and wctomb).
LCNUMERIC 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).]. LCTIME affects the behavior of ascftime, cftime,
getdate and strftime. LCCOLLATE affects the behavior of strcoll and
strxfrm, and the regular expression code described in regexpr3C).
LCMONETARY affects the monetary formatted information returned by
localeconv. LCMESSAGES affects the behavior of gettxt, catopen,
catclose, and catgets. [See catopen(3C) and catgets(3C).] LCALL
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 LCCTYPE category for the Italian locale would be
found in /usr/lib/locale/it/LCCTYPE.
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. If LCALL is defined in the environment
and it is not null, the value of LCALL is used for the selected
category. If the LCALL environment variable is not defined or is
null, the following chart applies. The following 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
----------------------------------------------------------
LCCTYPE LCCTYPE LANG CHRCLASS
LCCOLLATE LCCOLLATE LANG
LCTIME LCTIME LANG LANGUAGE
LCNUMERIC LCNUMERIC LANG
LCMONETARY LCMONETARY LANG
LCMESSAGES LCMESSAGES LANG
At program startup, the equivalent of
Licensed material--property of copyright holder(s) 1
setlocale(3C) DG/UX 5.4R3.00 setlocale(3C)
setlocale(LCALL, "C")
is executed automatically. This has the effect of initializing each
category to the locale described by the environment "C".
For programs that do not depend upon the C locale, the normal use of
setlocale is to execute
setlocale(LCALL, "")
as the first action in the application code. This has the effect of
initializing each category according to the environment variables
described above.
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 LCALL, the behavior is slightly different. If a
pointer to a string is given for locale and LCALL 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.
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 LCALL
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 LCMESSAGES 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 LCCTYPE in the middle of string
Licensed material--property of copyright holder(s) 2
setlocale(3C) DG/UX 5.4R3.00 setlocale(3C)
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.
FILES
/usr/lib/locale/C/LCCTYPE - LCCTYPE database for the C locale.
/usr/lib/locale/C/LCMONETARY - LCMONETARY database for the C
locale.
/usr/lib/locale/C/LCNUMERIC - LCNUMERIC database for the C locale.
/usr/lib/locale/C/LCTIME - LCTIME database for the C locale.
/usr/lib/locale/C/LCCOLLATE - LCCOLLATE database for the C locale.
/usr/lib/locale/C/LCMESSAGES - LCMESSAGES database for the C locale
(this is a directory).
/usr/lib/locale/locale/category - files containing the locale
specific information for each locale and category.
SEE ALSO
testlocale(1M),
reentrant(3), ctime(3C), ctype(3C), getdate(3C), gettxt(3C),
localeconv(3C), mbtowc(3C), printf(3S), strcoll(3C), strftime(3C),
strtod(3C), strxfrm(3C), wctomb(3C), environ(5).
Licensed material--property of copyright holder(s) 3