Content-type: text/html Man page of setlocale

setlocale

Section: C Library Functions (3)
Index Return to Main Contents
 

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 standards as follows:

setlocale(): ISO C, XPG4, POSIX.1c

Refer to the standards(5) reference page for more information about industry 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 translations of the messages are available) and the strings expected as affirmative and negative responses. Affects the behavior of functions that handle monetary values. Affects the radix character for the formatted input/output functions and the string conversion functions. 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: 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. Equivalent to C. Specifies that the locale 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 setting.

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

EXAMPLES

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. The following example sets a specific category 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 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;
}

 

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

RELATED INFORMATION

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 delim off


 

Index

NAME
LIBRARY
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
EXAMPLES
NOTES
RETURN VALUES
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:42:13 GMT, October 02, 2010