SETLOCALE(3C)
NAME
setlocale, getlocale − set and get the locale of a program
SYNOPSIS
#include <locale.h>
char *setlocale(category, locale)
const int category;
const char ∗locale;
struct locale_data *getlocale(type)
int type;
DESCRIPTION
Setlocale will set, query or restore that aspect of a program’s locale as 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:
LC_ALL affects the behavior of all categories below as well as all nl_langinfo(3C) items. Note that some nl_langinfo items are only affected by the setting of the LC_ALL category.
LC_COLLATE affects the behavior of regular expressions and the NLS string collation functions (see string(3C), and regexp(5)).
LC_CTYPE affects the behavior of regular expressions, character classification and conversion functions (see ctype(3C), conv(3C), and regexp(5)). The LC_CTYPE category also affects the behavior of all routines which process multibyte characters (see multibyte(3C) and nl_tools_16(3C)).
LC_MONETARY affects the behavior of functions which handle monetary values (see localeconv(3C)).
LC_NUMERIC affects the handling of the radix character in the formatted input/output functions (see printf(3C), scanf(3C) and vprintf(3C)) and the string conversion functions (see ecvt(3C) and strtod(3C)). LC_NUMERIC also affects the numeric values found in the localeconv structure.
LC_TIME affects the behavior of time conversion functions (see strftime(3C)).
All nl_langinfo(3C) items are affected by the setting of one of the categories listed above. See langinfo(5) to determine which category affect each item.
The value of the locale argument will determine the action taken by setlocale. Locale is a pointer to a character string.
Setting the Locale of a Program
To set the program’s locale for category, setlocale will accept one of the following values as the locale argument: locale name ,"C", 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)), setlocale will set that part of the NLS environment associated with category as defined for that locale.
"C" If the value of locale is set to "C", setlocale will set that part of the NLS environment associated with category as defined for the "C" locale (see lang(5)). The "C" locale is the default prior to successfully calling setlocale.
"" If the value of locale is the empty string, the setting of that part of the NLS environment associated with category will depend on the setting of the following environment variables in the user’s environment (see environ(5)) :
LANG
LC_COLLATE
LC_CTYPE
LC_MONETARY
LC_NUMERIC
LC_TIME
If category is any defined value other than LC_ALL, setlocale will set that category as specified by the value of the corresponding environment variable. If the environment variable is not set or set to the empty string, setlocale will set the category as specified by the value of the LANG environment variable. If LANG is not set or is set to the empty string , then setlocale will set the category to the "C" locale. For example, setlocale(LC_TIME,"") will set the program’s NLS environment associated with the LC_TIME category to the value specified by the user’s LC_TIME environment variable. All other aspects of the NLS environment will be unaffected.
If category is LC_ALL, then all categories will be set corresponding to the value of LANG, except for those categories in which the corresponding environment variable is set to a valid language name (see lang(5)). In this case the value of the environment variable will override the value of LANG for that category. If the value of LANG is not set or is set to the empty string, then the "C" locale is used.
The following usage of setlocale will result in the program’s locale being set according to the the user’s language requirements:
setlocale(LC_ALL,"");
Querying the Locale of a Program
Setlocale will query the current NLS environment pertaining to category if the value of locale is NULL. The query operation will not change the environment. 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 setlocale, such that it can be restored with a subsequent call to setlocale.
Restoring the Locale of a Program
To restore a category within the program locale, a setlocale call is made with the same category argument and the return string of the previous setlocale call given as the locale argument.
The getlocale function will return a pointer to a locale_data structure (see /usr/include/locale.h). The members of the locale_data structure contain information about the setting of each setlocale category. Type determines what information is contained in the locale_data structure. Defined values of type and their behaviour are :
LOCALE_STATUS
The structure member corresponding to each category will contain a string with the name of the locale currently set for that category. The string will not include modifier information.
MODIFIER_STATUS
The structure member corresponding to each category will contain a string with the name of the modifier currently set for that category. If no modifier is set then the entry will contain an empty string.
ERROR_STATUS
The structure member will contain information about errors which occurred during the previous call to setlocale. If setlocale could not satisfy a request corresponding to a particular category, the structure member for that category will contain a string with the name of the invalid locale. In all other cases the member for the category will contain an empty string.
RETURN VALUE
If the pointer to a string is given for locale and the selection can be honored, the setlocale function returns a pointer to the string associated with the specified category for the new locale. The is LC_BUFSIZ bytes (see <locale.h>). If the selection cannot be honored, the setlocale function returns a null pointer and the program’s locale is not changed.
A null pointer for locale causes setlocale to return a string associated with the category for the program’s current locale.
The string returned by setlocale is such that a subsequent call with that string as the locale argument and its associated category will restore 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 the language is not available on the system (see lang(5)) a null pointer is returned and the program’s locale is not changed. The same behavior will occur when the call :
setlocale(LC_ALL, getenv("LANG"));
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.
Setlocale returns a string which 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 setlocale call and the category arguments of the two calls do not match, the locale remains unchanged and a null pointer is returned.
WARNINGS
The use of the getenv() function as the locale argument is not recommended. An example of this usage is :
setlocale(LC_ALL, getenv("LANG"));
Getenv will return a character string which may be a language name, an empty string or a null pointer depending on the setting of the user’s LANG environment variable. Each of these values as the locale argument define a specific action to be taken by setlocale. Therefore the action taken by setlocale will depend upon the value returned from the getenv call. To ensure setlocale will set the program’s locale based upon the setting of the user’s environment variables the following usage is recommended :
setlocale(LC_ALL, "");
The value returned by setlocale points to a static area that will be overwritten with the next call to setlocale. It is recommended that these values be copied to another area if they are to be used after a subsequent setlocale call.
The structure which is returned through a call to getlocale will be overwritten with the next call to getlocale. It is recommended that these values be saved if they are to be used after a subsequent getlocale call.
EXAMPLES
To set a program’s entire locale based on the language requirements specified via the user’s environment variables :
setlocale(LC_ALL,"");
If, in the previous example, the user’s environment variables were set as follows :
LANG="german"
LC_COLLATE="spanish@nofold"
LC_MONETARY=""
LC_TIME="american"
the LC_ALL, LC_CTYPE, LC_MONETARY, and LC_NUMERIC category items would be set to correspond to the "german" language definition, the LC_COLLATE category items would be set to correspond to the "spanish" language definition for unfolded collation (see hpnls(5)) and the LC_TIME category items would be set corresponding to the "american" language definition.
Using the same example, if the following call was made :
struct locale_data *locale_info=getlocale(LOCALE_STATUS);
the contents of *locale_info would be :
locale_info->LC_ALL_D="german"
locale_info->LC_COLLATE_D="spanish"
locale_info->LC_CTYPE_D="german"
locale_info->LC_MONETARY_D="german"
locale_info->LC_NUMERIC_D="german"
locale_info->LC_TIME_D="american"
Continuing with the same example, if the following call was made :
struct locale_data *modifier_info=getlocale(MODIFIER_STATUS);
the contents of *modifier_info would now be :
modifier_info->LC_ALL_D=""
modifier_info->LC_COLLATE_D="nofold"
modifier_info->LC_CTYPE_D=""
modifier_info->LC_MONETARY_D=""
modifier_info->LC_NUMERIC_D=""
modifier_info->LC_TIME_D=""
The calls :
setlocale(LC_ALL,"");
struct locale_data *error_info=getlocale(ERROR_STATUS);
with the following settings in the users environment :
LANG=german
LC_COLLATE=junk
where "junk" is an invalid language, would result in the contents of *error_info being :
_error_info->LC_ALL_D=""
_error_info->LC_COLLATE_D="junk"
_error_info->LC_CTYPE_D=""
_error_info->LC_MONETARY_D=""
_error_info->LC_NUMERIC_D=""
_error_info->LC_TIME_D=""
To set the date/time formats to French :
setlocale(LC_TIME, "french");
To set the collating sequence to the "C" locale :
setlocale(LC_COLLATE, "C");
To set monetary handling to the value of the user’s LC_MONETARY environment variable :
setlocale(LC_MONETARY, "");
(Note that if the LC_MONETARY environment variable is not set or empty the value of the user’s LANG environment variable will be used.)
To query a user’s locale :
char *ch = setlocale(LC_ALL, NULL);
To restore the locale saved in the above example :
setlocale(LC_ALL, ch);
To query just that part of the user’s locale pertaining to the LC_NUMERIC category :
char *ch = setlocale(LC_NUMERIC, NULL);
To restore the LC_NUMERIC category of the user’s locale saved in the above example :
setlocale(LC_NUMERIC, ch);
AUTHOR
Setlocale was developed by HP.
SEE ALSO
nlsinfo(1), buildlang(1M), conv(3C), ctype(3C), ecvt(3C), langinfo(3C), multibyte(3C), nl_tools_16(3C), printf(3S), scanf(3S), strcoll(3C), strftime(3C), string(3C), strtod(3C), vprintf(3S), hpnls(5), environ(5), langinfo(5).
STANDARDS CONFORMANCE
setlocale: XPG3, POSIX.1, FIPS 151-1, ANSI C
Hewlett-Packard Company — HP-UX Release 7.0: Sept 1989