NAME

setlocale − Changes or queries the program’s current locale

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <locale.h>

char ∗setlocale(
        int category,
        const char ∗locale);

PARAMETERS

categorySpecifies 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. 

localePoints 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_TIMEAffects 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:

CSpecifies 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. 

POSIXEquivalent to C. 

""""Specifies that the locale should be set based on the user’s current values for the locale environment variables. 

NULLUsed to direct setlocale() to query the current internationalized environment and return the name of the locale; does not change the locale. 

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 or for all categories, if the value of the category parameter is LC_ALL. 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 C locale. 

If the locale parameter is the null pointer, the setlocale() function returns the name of the program’s locale for the specified category and does not change the international environment. 

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 international environment. 

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 existing international environment, then explicitly sets the locale to the C locale, performs some operations in the C locale, and finally, restores the locale to the saved environment. The main program typically uses setlocale() to set the international environment to the locale specified by the user’s environment program.  If a subroutine needs to execute in a specific locale, the subroutine must save and restore the international environment. 

#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;
}

NOTES

The setlocale() function is not threadsafe, and does not have any threadsafe equivalent.  This means that the setlocale() function should be called only in the main part of a program, before any threads are created. 

AES Support Level:
Full use (setlocale()). 

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 a null 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. 

RELATED INFORMATION

Functions: atof(3), catgets(3), catopen(3), ctype(3), localeconv(3), nl_langinfo(3), printf(3), scanf(3), strfmon(3), strftime(3), string(3), wctype(3). 

Files: locale(4).