setlocale Subroutine

Purpose

Changes or queries the program's entire current locale or portions thereof.

Library

Standard C Library (libc.a)

Syntax

#include <locale.h>

char *setlocale ( Category, Locale) int Category; const char *Locale;

Description

The setlocale subroutine selects all or part of the program's locale specified by the Category and Locale parameters. The setlocale subroutine then changes or queries the specified portion of the locale. The LC_ALL value for the Category parameter names the entire locale (all the categories). The other Category values name only a portion of the program locale.

The Locale parameter specifies a string that provides information needed to set certain conventions in the Category parameter. The components of the Locale parameter are language and territory. Values allowed for the locale argument are the predefined language_territory combinations or a user-defined locale.

If a user defines a new locale, a uniquely named locale definition source file must be provided. The character collation, character classification, monetary, numeric, time, and message information should be provided in this file. The locale definition source file is converted to a binary file by the localedef command. The binary locale definition file is accessed in the directory specified by the LOCPATH environment variable.

Note: All setuid and setgid programs will ignore the LOCPATH environment variable.

The default locale at program startup is the C locale. A call to the setlocale subroutine must be made explicitly to change this default locale environment.

The locale state is common to all threads within a process.

Parameters

Item	Description
Category	Specifies a value representing all or part of the locale for a program. Depending on the value of the Locale parameter, these categories may be initiated by the values of environment variables with corresponding names. Valid values for the Category parameter, as defined in the locale.h file, are: LC_ALL Affects the behavior of a program's entire locale. LC_COLLATE Affects the behavior of regular expression and collation subroutines. LC_CTYPE Affects the behavior of regular expression, character-classification, case-conversion, and wide character subroutines. LC_MESSAGES Affects the content of messages and affirmative and negative responses. LC_MONETARY Affects the behavior of subroutines that format monetary values. LC_NUMERIC Affects the behavior of subroutines that format nonmonetary numeric values. LC_TIME Affects the behavior of time-conversion subroutines.
Locale	Points to a character string containing the required setting for the Category parameter. The following are special values for the Locale parameter: "C" The C locale is the locale all programs inherit at program startup. "POSIX" Specifies the same locale as a value of "C". "" Specifies categories be set according to locale environment variables. NULL Queries the current locale environment and returns the name of the locale. For more information about supported locale values for the Locale parameter, see Supported languages and locales in Globalization Guide and Reference.

Item

Description

Category

Specifies a value representing all or part of the locale for a program. Depending on the value of the Locale parameter, these categories may be initiated by the values of environment variables with corresponding names. Valid values for the Category parameter, as defined in the locale.h file, are:

LC_ALL: Affects the behavior of a program's entire locale.
LC_COLLATE: Affects the behavior of regular expression and collation subroutines.
LC_CTYPE: Affects the behavior of regular expression, character-classification, case-conversion, and wide character subroutines.
LC_MESSAGES: Affects the content of messages and affirmative and negative responses.
LC_MONETARY: Affects the behavior of subroutines that format monetary values.
LC_NUMERIC: Affects the behavior of subroutines that format nonmonetary numeric values.
LC_TIME: Affects the behavior of time-conversion subroutines.

Locale

Points to a character string containing the required setting for the Category parameter.

The following are special values for the Locale parameter:

"C": The C locale is the locale all programs inherit at program startup.
"POSIX": Specifies the same locale as a value of "C".
"": Specifies categories be set according to locale environment variables.
NULL: Queries the current locale environment and returns the name of the locale.

For more information about supported locale values for the Locale parameter, see Supported languages and locales in Globalization Guide and Reference.

Return Values

If a pointer to a string is given for the Locale parameter and the selection can be honored, the setlocale subroutine 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 is used for the Locale parameter, the setlocale subroutine returns the string associated with the Category parameter for the program's current locale. The program's locale is not changed.

A subsequent call with the string returned by the setlocale subroutine, and its associated category, will restore 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 subroutine.