setlocale - Change or queries the program's current locale
#include <locale.h>
char *setlocale(
int category,
const char *locale );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
setlocale(): XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
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.
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 translations
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 formatted 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 setting.
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 environment 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 category 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 category 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.
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 category, this operation has no effect on any
message catalogs that are currently open.
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_MONETARY
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 program's current locale, and leaves the
program's locale unchanged.
The string returned by the setlocale() function is such
that a subsequent 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 setlocale()
function.
The following example sets all categories in the international
environment 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 international 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 environment variables.
The following example sets a specific category 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 operations 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=setlocale(LC_ALL,saved_l); return;
}
Functions: atof(3), catclose(3), catgets(3), catopen(3),
ctype(3), localeconv(3), nl_langinfo(3), printf(3),
scanf(3), strfmon(3), strftime(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)
[ Back ] |
