 |
Index for
Section 3 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
setlocale(3)
NAME
setlocale - 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 standards
as follows:
setlocale(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
category
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.
locale
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:
LC_COLLATE
Affects the behavior of collation functions and regular expressions.
LC_CTYPE
Affects the behavior of character classification functions, character
conversion functions, and regular expressions.
LC_MESSAGES
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.
LC_MONETARY
Affects the behavior of functions that handle monetary values.
LC_NUMERIC
Affects the radix character for the formatted input/output functions
and the string conversion functions.
LC_TIME
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:
C 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.
POSIX
Equivalent to C.
"" Specifies that the locale should be set based on the user's current
values for the locale environment variables.
NULL
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:
1. 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).
2. 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.
3. 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.
4. 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.
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 category,
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_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.
EXAMPLES
1. 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.
2. The following example sets a specific category in the international
environment to an explicit locale.
(void)setlocale(LC_MESSAGES,"fr_FR.ISO8859-1");
3. 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;
}
SEE ALSO
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
|
Index for
Section 3 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|