setlocale(3C)setlocale(3C)NAMEsetlocale(), getlocale() - set and get the locale of a program
SYNOPSIS
Obsolescent Interfaces
DESCRIPTION
The function sets, queries, or restores the aspect of a program's
locale that is specified by the category argument. A program's locale
refers to those areas of the program's Native Language Support (NLS)
environment for which the following values of category have been
defined:
Affects behavior of all categories below, as well as all
nl_langinfo(3C) items.
Affects behavior of regular expressions and the NLS
string collation functions (see string(3C),
and regexp(5)).
Affects behavior of regular expressions, character classifica‐
tion,
and conversion functions (see ctype(3C),
wctype(3C), wconv(3C), conv(3C), and reg‐
exp(5)). The category also affects the
behavior of all routines that process multi‐
byte characters (see multibyte(3C)).
Affects the language in which messages are displayed and the
processing of affirmative and negative
responses (see catopen(3C) and nl_lang‐
info(3C)).
Affects behavior of functions that handle monetary values (see
localeconv(3C) and strfmon(3C)).
Affects handling of the radix character in the formatted
input/output functions (see printf(3S),
scanf(3S) and vprintf(3S)) and the string
conversion functions (see ecvt(3C) and str‐
tod(3C)). also affects the numeric values
found in the localeconv structure.
Affects the behavior of time conversion functions (see
getdate(3C), strftime(3C), and strp‐
time(3C)).
All nl_langinfo(3C) items are affected by the setting of one of the
categories listed above. See langinfo(5) to determine which categories
affect each item.
The value of the locale argument determines the action taken by locale
is a pointer to a character string.
Note that while can be called concurrently from multiple threads, the
locale data structures that get updated are not protected against reads
by other threads. Hence it is up to the application developer to
ensure proper synchronization when changing locales.
Setting the Locale of a Program
To set the program's locale for category, accepts one of the following
values as the locale argument: locale name, or (the empty string). The
actions prescribed by these values are as follows:
locale name If locale is a valid locale name (see
lang(5)), sets that part of the NLS environ‐
ment associated with category as defined for
that locale.
If the value of locale is set to sets that part of the NLS
environment associated with category as
defined for the locale (see lang(5)). The
locale is the default prior to successfully
calling
Same as
If the value of locale is the empty string, the setting of
that part of the NLS environment associated
with category depends upon the setting of
the following environment variables in the
user's environment (see environ(5)):
If category is any defined value other than
sets that category as specified by the value
of the environment. This is also the case
if is not set to the corresponding environ‐
ment variable. If the environment variable
is not set or is set to the empty string,
sets the category as specified by the value
of the environment variable. If is not set
or is set to the empty string, then sets the
category to the locale. For example,
sets the program's NLS environment associ‐
ated with the category to the value speci‐
fied by the user's environment variable.
All other aspects of the NLS environment are
unaffected.
If category is then all categories are set
corresponding to the value of if is set, or
if is not set, except for those categories
in which the corresponding environment vari‐
able is set to a valid language name (see
lang(5)). In this case the value of the
environment variable overrides the values of
and for that category. If the values of
both and are not set or are set to the empty
string, then the locale is used.
The following usage of results in the pro‐
gram's locale being set according to the
user's language requirements:
Querying the Locale of a Program
queries the current NLS environment pertaining to category, if the
value of locale is NULL. The query operation does not change the envi‐
ronment. The purpose of performing a query is to save that aspect of
the user's current NLS environment associated with category, in the
value returned by such that it can be restored with a subsequent call
to
Restoring the Locale of a Program
To restore a category within the program locale, a call is made with
the same category argument and the return string of the previous call
given as the locale argument.
returns a pointer to a structure (see The members of the structure con‐
tain information about the setting of each category. type determines
what information is contained in the structure. The only supported
value of type is:
The structure member corresponding to each category contains a
string
with the name of the locale currently set
for that category. The string does not
include modifier information.
Obsolescent Interfaces
and set and get the locale of a program..
RETURN VALUE
If the pointer to a string is given for locale and the selection can be
honored, the function returns a pointer to the string associated with
the specified category for the new locale. The maximum length of this
string is bytes (see If the selection cannot be honored, the function
returns a null pointer and the program's locale is not changed.
A null pointer for locale causes to return a string associated with the
category for the program's current locale.
The string returned by is such that a subsequent call with that string
as the locale argument and its associated category restores that part
of the program's locale.
ERRORS
If a language name given through the locale argument does not identify
a valid language name, or if the language name is more than 256 charac‐
ters, or if the language is not available on the system (see lang(5)),
then a null pointer is returned and the program's locale is not
changed. The same behavior occurs when the call:
is made and any category related environment variable in the user's
environment identifies an invalid language name or a language that is
not available on the system.
If the category argument is not a defined category value, a null
pointer is returned and the program's locale is not changed.
returns a string that reflects the current setting of that aspect of
the NLS environment corresponding to the category argument. If this
return string is used in a subsequent call and the category arguments
of the two calls do not match, the locale remains unchanged and a null
pointer is returned.
EXAMPLES
To set a program's entire locale based on the language requirements
specified via the user's environment variables:
If in the example the user's environment variables were set as follows:
the and category items would be set to correspond to the language defi‐
nition, the category items would be set to correspond to the language
definition for collation and the category items would be set corre‐
sponding to the language definition.
Using the same example, if the following call was made:
the contents of would be:
The next example shows the precedence of the environment variable:
with the following settings in the user's environment:
All categories will be loaded with
Another example showing the precedence of the environment variable:
with the following settings in the user's environment:
All categories will be loaded with
Another example with the environment variable:
with the following settings in the user's environment:
The category will be set to but all other categories will be set to
To set the date/time formats to
To set the collating sequence to the locale:
To set monetary handling to the value of the user's environment vari‐
able:
Note that if the environment variable is not set or is empty, the value
of the user's environment variable is used.
To query a user's locale:
To restore the locale saved in the above example:
To query only the part of the user's locale pertaining to the category:
To restore the category of the user's locale saved in the above exam‐
ple:
WARNINGS
The format of the return string from is implementation specific, is not
standardized across vendor's platforms, and is subject to change in
future releases. The return string is valid only for the life of the
process invoking the and should only be used for restoring a previously
stored locale setting within the same process.
Using as the locale argument is not recommended. An example of such
incorrect usage is:
returns a character string which can be a language name, an empty
string, or a null pointer; depending on the setting of the user's envi‐
ronment variable. Each of these values as the locale argument define a
specific action to be taken by Therefore the action taken by depends
upon the value returned from the call. To ensure that sets the pro‐
gram's locale based upon the setting of the user's environment vari‐
ables the following usage is recommended:
The value returned by points to an area that is overwritten during the
next call to Be sure to copy these values to another area if they are
to be used after a subsequent call.
is an HP proprietary interface, which will be in a future release, and
is not portable to other vendor's platforms.
The structure returned through a call to is overwritten during the next
call to Be sure to save these values if they are to be used after a
subsequent call.
It should be noted that the locale state is common to all threads
within a process.
and are obsolescent interfaces supported for compatibility with exist‐
ing DCE applications. New multithreaded applications should use and
Any program that calls before with the oflag parameter set to may
behave differently in this release than in previous releases because of
the addition of to In the past, was directed to the desired language by
Now, with the oflag parameter set to is controlled by can modify the
category. For example, if the environment variables are set as fol‐
lows:
and the following call to is made:
followed by a call to then will open the message catalogs for rather
than
If you use and compile/link your application archive on PA-RISC sys‐
tems, please note that has a dependency on that will require a change
to the compile/link command.
Compile:
Or compile with and
The option is positionally dependent and should occur at the beginning
of the compile line. For optimum compatibility in future releases,
avoid using archive with other shared libraries except for as needed
above.
AUTHOR
and were developed by OSF and HP.
FILESSEE ALSOlocale(1), localedef(1M), conv(3C), ctype(3C), ecvt(3C), getdate(3C),
multibyte(3C), nl_langinfo(3C), regcomp(3C), string(3C), perror(3C),
strfmon(3C), strftime(3C), string(3C), strptime(3C), strtod(3C), wcsf‐
time(3C), wcstring(3C), printf(3S), scanf(3S), vprintf(3S), wconv(3C),
wctype(3C), wcstod(3C), wcstol(3C), environ(5), lang(5), langinfo(5),
thread_safety(5).
STANDARDS CONFORMANCEsetlocale(3C)
