*** UNIX MANUAL PAGE BROWSER ***

setlocale(3) Library Functions Manual setlocale(3) NAME setlocale - Changes or queries the program's current locale LIBRARY Standard C Library (libc.so, libc.a) SYNOPSIS #include <locale.h> char *setlocale( int category, const char *locale); STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: setlocale(): ISO C, XPG4, POSIX.1c Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS 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. 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: 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 trans- lations of the messages are available) and the strings expected as af- firmative and negative responses. Affects the behavior of functions that handle monetary values. Affects the radix character for the for- matted input/output functions and the string conversion functions. Af- fects 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 pa- rameter. 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 af- fected by the locale string. Equivalent to C. Specifies that the lo- cale 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 set- ting. 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 environ- ment 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 in- ternational 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 cat- egory 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 cat- egory 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. EXAMPLES The following example sets all categories in the international environ- ment 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 interna- tional 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 envi- ronment variables. The following example sets a specific cate- gory 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 opera- tions 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=setlo- cale(LC_ALL,saved_l); return; } NOTES The POSIX.1c standard specifies that there be only one locale per process. This means that applications should call setlocale() only in the main part of a program before any threads are created. If a call to setlocale() changes the setting of the LC_MESSAGES cate- gory, 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 lo- cale. Note that the locale parameter can specify the locale name ex- plicitly or, if locale is an empty string, the locale is specified by the value of the corresponding environment variable. If the setlo- cale() function cannot set the program's locale as requested, the func- tion 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_MONE- TARY LC_NUMERIC LC_TIME LC_MESSAGES If the locale parameter is a null pointer, the setlocale() function re- turns the string associated with the category parameter for the pro- gram's current locale, and leaves the program's locale unchanged. The string returned by the setlocale() function is such that a subse- quent 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 setlo- cale() function. RELATED INFORMATION Functions: atof(3), catclose(3), catgets(3), catopen(3), ctype(3), lo- caleconv(3), nl_langinfo(3), printf(3), scanf(3), strfmon(3), strf- time(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 delim off setlocale(3)