setlocale(3C)
NAME
setlocale(), setlocale_r(), getlocale(), getlocale_r() − set and get the locale of a program
SYNOPSIS
#include <locale.h>
char *setlocale(int category, const char *locale);
int setlocale_r(int category, const char *locale, char *buffer,
int buflen);
struct locale_data *getlocale(int type);
int getlocale_r(int type, struct locale_data *ld);
DESCRIPTION
The setlocale() 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:
LC_ALL Affects behavior of all categories below, as well as all nl_langinfo(3C) items.
LC_COLLATE Affects behavior of regular expressions and the NLS string collation functions (see strcoll(3C), strfxrm(3C), wcscoll(3C), wcsxfrm(3C), and regexp(5)).
LC_CTYPE Affects behavior of regular expressions, character classification, and conversion functions (see ctype(3C), wctype(3X), wconv(3X), conv(3C), and regexp(5)). The LC_CTYPE category also affects the behavior of all routines that process multibyte characters (see multibyte(3C)).
LC_MESSAGES Affects the language in which messages are displayed and the processing of affirmative and negative responses (see catopen(3C) and nl_langinfo(3C)).
LC_MONETARY Affects behavior of functions that handle monetary values (see localeconv(3C) and strfmon(3C)).
LC_NUMERIC Affects 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 getdate(3C), strftime(3C), and strptime(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 setlocale(). locale is a pointer to a character string.
Setting the Locale of a Program
To set the program’s locale for category, setlocale() accepts one of the following values as the locale argument: locale name, C, POSIX, 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() sets 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() sets 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().
POSIX Same as C.
"" 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)):
LANG LC_MESSAGES
LC_ALL LC_MONETARY
LC_COLLATE LC_NUMERIC
LC_CTYPE LC_TIME
If category is any defined value other than LC_ALL, setlocale() sets that category as specified by the value of the LC_ALL environment. This is also the case if LC_ALL is not set to the corresponding environment variable. If the environment variable is not set or is set to the empty string, setlocale() sets 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() sets the category to the C locale. For example,
setlocale(LC_TIME,"")
sets 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 are unaffected.
If category is LC_ALL, then all categories are set corresponding to the value of LC_ALL if LC_ALL is set, or LANG if LC_ALL is not set, 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 overrides the values of LC_ALL and LANG for that category. If the values of both LC_ALL and LANG are not set or are set to the empty string, then the C locale is used.
The following usage of setlocale() results 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() queries the current NLS environment pertaining to category, if the value of locale is NULL. The query operation does 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.
getlocale() returns 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. The only supported value of type is:
LOCALE_STATUS 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.
Reentrant Interfaces
The setlocale_r() function performs the same function as the setlocale() function except the result string describing locale information for the given category is passed back in the supplied buffer. Note that while setlocale_r() 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. A buffer size of length LC_BUFSIZ (defined in <locale.h>) is recommended.
The getlocale_r() function expects to be passed the address of a struct locale_data and stores the requested locale information at the given location.
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 maximum length of this string 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 restores that part of the program’s locale.
For the Reentrant Interfaces, if an error is detected or, in the case of setlocale_r(), the buffer is of insufficient length, −1 is returned. If the operation is successful, 0 is returned.
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 occurs when the call:
setlocale(LC_ALL, "");
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 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 setlocale() 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:
setlocale(LC_ALL, "");
If in the example the user’s environment variables were set as follows:
LANG ="de_DE.iso88591"
LC_COLLATE ="es_ES.iso88591"
LC_MONETARY =""
LC_TIME ="en_US.iso88591"
the LC_CTYPE, LC_MONETARY, and LC_NUMERIC category items would be set to correspond to the de_DE.iso88591 language definition, the LC_COLLATE category items would be set to correspond to the es_ES.iso88591 language definition for collation and the LC_TIME category items would be set corresponding to the en_US.iso88591 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="de_DE.iso88591"
locale_info->LC_COLLATE_D="es_ES.iso88591"
locale_info->LC_CTYPE_D="de_DE.iso88591"
locale_info->LC_MESSAGES_D="de_DE.iso88591"
locale_info->LC_MONETARY_D="de_DE.iso88591"
locale_info->LC_NUMERIC_D="de_DE.iso88591"
locale_info->LC_TIME_D="en_US.iso88591"
The next example shows the precedence of the LC_ALL environment variable:
setlocale(LC_ALL, "");
with the following settings in the user’s environment:
LANG=de_DE.iso88591
LC_ALL=fr_FR.iso88591
All categories will be loaded with fr_FR.iso88591.
Another example showing the precedence of the LC_ALL environment variable:
setlocale(LC_CTYPE, "");
with the following settings in the user’s environment:
LANG=tr_TR.iso88599
LC_ALL=da_DK.iso88591
LC_CTYPE=ru_RU.iso88595
All categories will be loaded with da_DK.iso88591.
Another example with the LC_ALL environment variable:
setlocale(LC_TIME, "pl_PL.iso88592");
with the following settings in the user’s environment:
LANG=it_IT.iso88591
LC_ALL=nl_NL.iso88591
The LC_TIME category will be set to pl_PL.iso88592, but all other categories will be set to nl_NL.iso88591.
To set the date/time formats to fr_FR.iso88591:
setlocale(LC_TIME, "fr_FR.iso88591");
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 is empty, the value of the user’s LANG environment variable is 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 only the 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);
WARNINGS
The format of the return string from setlocale() 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 setlocale() and should only be used for restoring a previously stored locale setting within the same process.
Using getenv() as the locale argument is not recommended. An example of such incorrect usage is:
setlocale(LC_ALL, getenv("LANG"));
getenv() 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 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() depends upon the value returned from the getenv() call. To ensure that setlocale() sets 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 is overwritten during the next call to setlocale(). Be sure to copy these values to another area if they are to be used after a subsequent setlocale() call.
getlocale() is an HP proprietary interface, which will be obsoleted in a future release, and is not portable to other vendor’s platforms.
The structure returned through a call to getlocale() is overwritten during the next call to getlocale(). Be sure to save these values if they are to be used after a subsequent getlocale() call.
getlocale() and setlocale() are unsafe in multi-thread applications. getlocale_r() and setlocale_r() are MT-Safe and should be used instead.
Any program that calls setlocale() before catopen() with the oflag parameter set to NL_CAT_LOCALE may behave differently in this release than in previous releases because of the addition of LC_MESSAGES to XPG4. In the past, catopen() was directed to the desired language by LANG. Now, catopen() with the oflag parameter set to NL_CAT_LOCALE, is controlled by LC_MESSAGES. setlocale() can modify the LC_MESSAGES category. For example, if the environment variables are set as follows:
LC_MESSAGES="fr_FR.iso88591"
and the following call to setlocale() is made:
setlocale(LC_ALL, "de_DE.iso88591");
followed by a call to catopen(), then catopen() will open the message catalogs for de_DE.iso88591 rather than fr_FR.iso88591.
If you use setlocale() and compile/link your application archive, please note that setlocale() has a dependency on libdld.sl that will require a change to the compile/link command.
Compile:
cc -Wl,-a,archive -Wl,-E -Wl,+n -l:libdld.sl -o <outfile> <source>
or,
Compile with CCOPTS and LDOPTS:
export CCOPTS="-Wl,-a,archive <options> -Wl,-E -l:libdld.sl"
export LDOPTS="<options> -E +n -l:libdld.sl"
cc -o <outfile> <source>
The option -Wl,-a,archive is positionally dependent and should occur at the beginning of the compile line. For optimum compatibility in future releases, avoid using archive libc with other shared libraries except for libdld.sl as needed above.
AUTHOR
setlocale(), setlocale_r(), getlocale(), and getlocale_r() were developed by OSF and HP.
FILES
/usr/include/langinfo.h
/usr/include/locale.h
SEE ALSO
locale(1), localedef(1M), conv(3C), ctype(3C), ecvt(3C), getdate(3C), multibyte(3C), nl_langinfo(3C), regcomp(3C), strcoll(3C), strerror(3C), strfmon(3C), strftime(3C), string(3C), strptime(3C), strtod(3C), wcsftime(3C), wcstring(3C), printf(3S), scanf(3S), vprintf(3S), wconv(3X), wctype(3X), wstod(3X), wstol(3X), environ(5), hpnls(5), lang(5), langinfo(5).
STANDARDS COMPLIANCE
setlocale(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
Hewlett-Packard Company — HP-UX Release 10.20: July 1996