setlocale(3)setlocale(3)NAMEsetlocale - Change or queries the program's current locale
SYNOPSIS
#include <locale.h>
char *setlocale(
int category,
const char *locale );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
setlocale(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the category of the locale to set or query. The category can
be LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC,
or LC_TIME. Points to a string that specifies the locale.
DESCRIPTION
The setlocale() function sets or queries the appropriate portion of the
program's locale as specified by the category and locale parameters.
The LC_ALL value for the category parameter names the entire locale;
the other values name only a portion of the program locale, as follows:
Affects the behavior of collation functions and regular expressions.
Affects the behavior of character classification functions, character
conversion functions, and regular expressions. Affects the language
used to display application program and utilities messages (when trans‐
lations of the messages are available) and the strings expected as
affirmative and negative responses. Affects the behavior of functions
that handle monetary values. Affects the radix character for the for‐
matted input/output functions and the string conversion functions.
Affects the behavior of the time conversion functions.
The behavior of the language information function defined in the
nl_langinfo() function is also affected by settings of the category
parameter.
The locale parameter points to a character string that identifies the
locale that is to be used to set the category parameter. The locale
parameter can specify either the name of a locale, such as
fr_CA.ISO8859-1, or one of the following: Sets the locale to be the
minimal environment for C-language translation. If setlocale() is not
invoked, the C locale is the default. Operational behavior within the C
locale is defined separately for each interface function that is
affected by the locale string. Equivalent to C. Specifies that the
locale should be set based on the user's current values for the locale
environment variables. Queries the program's current locale setting
and returns the name of the locale; does not change the current set‐
ting.
If the locale parameter is set to the empty string (""), setlocale()
checks the user's environment variables in the following order: First
it checks the value of the LC_ALL environment variable. If it is set,
setlocale() sets the specified category of the international environ‐
ment to that value and returns the string corresponding to the locale
set (that is, the value of the environment variable, not "", the null
string). If the environment variable LC_ALL is not set or is set to
the empty string, setlocale() next checks the corresponding environment
variable for the category specified. If the environment variable for
the category is set, setlocale() sets the specified category of the
international environment to that value. If the environment variable
corresponding to the specified category is not set or is set to the
empty string, then setlocale() checks the LANG environment variable. If
the LANG environment variable is set, then setlocale() sets the cate‐
gory to the locale specified by the LANG environment variable. Lastly,
if the LANG environment variable is not set or is set to the empty
string, the setlocale() function sets the category to the POSIX (C)
locale.
If the locale parameter is a pointer to NULL, the setlocale() function
returns the name of the program's current locale for the specified cat‐
egory but does not change the locale.
If the locale specified by the locale parameter or by the environment
variable is invalid, setlocale() returns a null pointer and does not
change the program's locale.
NOTES
There is only one locale per process and the locale state is common to
all threads within that process. Because setlocale() modifies a process
global state without locking code, the function call is not threadsafe.
A threaded application should only call setlocale() in the main part of
the application before any threads are created.
If a call to setlocale() changes the setting of the LC_MESSAGES cate‐
gory, this operation has no effect on any message catalogs that are
currently open.
RETURN VALUES
If the setlocale() function succeeds in setting the program's locale to
the one specified by the locale parameter, the function returns the
string associated with the specified category parameter for the new
locale. Note that the locale parameter can specify the locale name
explicitly or, if locale is an empty string, the locale is specified by
the value of the corresponding environment variable. If the setlocale()
function cannot set the program's locale as requested, the function
returns a null pointer and leaves the program's locale unchanged.
If the category parameter has a value of LC_ALL, the return value is a
series of locale names separated by spaces. The locale names correspond
to the categories in the following order: LC_COLLATE LC_CTYPE LC_MONE‐
TARY LC_NUMERIC LC_TIME LC_MESSAGES
If the locale parameter is a null pointer, the setlocale() function
returns the string associated with the category parameter for the pro‐
gram's current locale, and leaves the program's locale unchanged.
The string returned by the setlocale() function is such that a subse‐
quent call with that string and its associated category restores that
part of the program's locale. The string returned must not be modified
by the program, but is overwritten by a subsequent call to the setlo‐
cale() function.
EXAMPLES
The following example sets all categories in the international environ‐
ment based on the user's environment variables:
(void)setlocale (LC_ALL, );
To satisfy this request, the setlocale() function first checks
all the environment variables. If any environment variable is
invalid, setlocale() returns a null pointer and the interna‐
tional environment is not changed by this function call. If all
the relevant environment variables are valid, setlocale() sets
the international environment to reflect the values of the envi‐
ronment variables. The following example sets a specific cate‐
gory in the international environment to an explicit locale.
(void)setlocale(LC_MESSAGES,"fr_FR.ISO8859-1"); The following
subroutine queries and saves the current program locale, then
explicitly sets the locale to the C locale, performs some opera‐
tions in the C locale, and finally, restores the locale to one
saved. The main program typically uses setlocale() to set the
program's locale to the one specified by the user's environment.
However, if a subroutine needs to execute in a specific locale,
the subroutine must save and later restore the setting made by
the main program.
#include <locale.h> #include <string.h>
void Do_stuff(void) { char *test_l, *saved_l;
test_l=setlocale(LC_ALL,NULL); saved_l=strdup(test_l);
test_l=setlocale(LC_ALL,"C"); /* Perform operations in
the C locale */
/* Restore the original locale */ test_l=setlo‐
cale(LC_ALL,saved_l); return;
}
SEE ALSO
Functions: atof(3), catclose(3), catgets(3), catopen(3), ctype(3),
localeconv(3), nl_langinfo(3), printf(3), scanf(3), strfmon(3), strf‐
time(3), string(3), wctype(3), wprintf(3), wscanf(3)
Files: locale(4)
Others: i18n_intro(5), l10n_intro(5), standards(5)
Writing Software for the International Market
setlocale(3)