OSF  —  Environment_Note_Added

NAME

setlocale − Changes or queries the program’s entire current locale or portions thereof

LIBRARY

Standard C Library (libc.a)

SYNOPSIS

#include <locale.h> char ∗setlocale (
int category,
const char ∗locale ); int setlocale_r (
int category,
const char ∗locale,
char ∗result );

PARAMETERS

categorySpecifies a value from the locale.h header file that names the program’s entire locale or a portion thereof. 

localePoints to a string defining the locale. 

resultPoints to the string associated with category for the new locale. 

DESCRIPTION

The setlocale() function selects the appropriate portion of the program’s locale as specified by the category and locale parameters.  The setlocale() function can be used to change or query the program’s entire current locale or portions thereof.  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 the strcoll() and strxfrm() functions. 

LC_CTYPEAffects the behavior of the character handling functions (except for the isdigit() and isxdigit() functions) and the multibyte functions. 

LC_MONETARY
Affects the monetary formatting information returned by the localeconv() function. 

LC_NUMERIC
Affects the decimal-point character for the formatted input/output functions and the string conversion functions, as well as the nonmonetary formatting information returned by the localeconv() function. 

LC_TIMEAffects the behavior of the strftime() function. 

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 containing the required setting of the category parameter.  The following values of locale are defined for all settings of category:

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. 

“”Specifies a native environment, corresponding to the value of the associated environment variables.  In all cases, the setlocale() function first checks the value of the corresponding environment variable and if valid, 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 "").  If the value is invalid, setlocale() returns a null pointer and the international environment is not changed by this function call.  If the environment variable corresponding to the specified category is not set or is set to the empty string, and the LANG environment variable is set and valid, then setlocale() sets the category to the corresponding value of LANG.  If the LANG environment variable is not set, the setlocale() function uses a system-wide default.  To set all categories in the international environment, the setlocale() function is invoked in the following manner:

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 categories are set in the following order: LC_CTYPE
LC_COLLATE
LC_TIME
LC_NUMERIC
LC_MONETARY Using this scheme, the categories corresponding to the environment variables will override the value of the LANG environment variable for a particular category. 

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

The reentrant version of the setlocale() function, setlocale_r(), stores the string associated with the category for the new locale in the buffer pointed to by the result parameter. 

NOTES

AES Support Level:
Full use (setlocale())

RETURN VALUES

If a pointer to a string is given for the locale parameter and the selection can be honored, the setlocale() function returns the string associated with the specified category parameter for the new locale.  If the selection cannot be honored, a null pointer is returned and the program locale is unchanged. 

If a null pointer for the locale parameter causes the setlocale() function to return the string associated with the category parameter for the program current locale, the program locale is 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 locale.  The string returned is not modified by the program, but can be overwritten by a subsequent call to the setlocale() function. 

Upon successful completion, the setlocale_r() function returns a value of 0 (zero).  Otherwise, -1 is returned and errno is set to indicate the error. 

ERRORS

If the setlocale_r() function fails, errno may be set to the following value:

[EINVAL]Either result is a null pointer, or the selection is invalid.  setlocale.3

ENVIRONMENT NOTES

This section describes system features that are not generic to OSF/1 but that are provided in this OSF/1 implementation. 

Digital Extensions

On a Digital system, if none of the internationalization environment variables are set (LC_ALL, LANG, LC_COLLATE, and so on), the setlocale routine sets the category to the locale specified in the locale configuration file, /etc/nls/native_locale.conf. This file specifies the default system-wide locale. By default, the system-wide locale is the Cextend locale. 

If you want to change the system-wide locale you can specify a locale other than Cextend in the native_locale.conf file. 

For more information about the native_locale.conf file, see native_locale.conf(4). 

RELATED INFORMATION

Functions: atof(3), ctype(3), jctype(3), localeconv(3), nl_langinfo(3), printf(3), scanf(3), strftime(3), string(3)