Technical Reference: Base Operating System and Extensions, Volume 2

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. See Understanding Locale Subroutines in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs for setlocale subroutine examples.

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

Parameters

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.
The Language Territory Table contains supported language_territory values for the Locale parameter:

Table 1. Language Territory Table
Locale Value	Language	Territory	Code Set
Ar_AA	Arabic	Arabic Countries	IBM-1046
ar_AA	Arabic	Arabic Countries	ISO8859-6
bg_BG	Bulgarian	Bulgaria	ISO8856-5
cs_CZ	Czech	Czech Republic	ISO8859-2
da_DK	Danish	Denmark	ISO8859-1
de_CH	German	Switzerland	ISO8859-1
de_DE	German	Germany	ISO8859-1
el_GR	Greek	Greece	ISO8859-7
en_GB	English	Great Britain	ISO8859-1
en_US	English	United States	ISO8859-1
es_ES	Spanish	Spain	ISO8859-1
fi_FI	Finnish	Finland	ISO8859-1
fr_BE	French	Belgium	ISO8859-1
fr_CA	French	Canada	ISO8859-1
fr_FR	French	France	ISO8859-1
fr_CH	French	Switzerland	ISO8859-1
hr_HR	Croatian	Croatia	ISO8859-2
hu_HU	Hungarian	Hungary	ISO8859-2
is_IS	Icelandic	Iceland	ISO8859-1
it_IT	Italian	Italy	ISO8859-1
Iw_IL	Hebrew	Israel	IBM-856
iw_IL	Hebrew	Israel	ISO8859-8
Ja_JP	Japanese	Japan	IBM-943
ja_JP	Japanese	Japan	IBM-eucJP
ko_KR	Korean	Korea	IBM-eucKR
mk_MK	Macedonian	Former Yugoslav Republic of Macedonia	ISO8859-5
nl_BE	Dutch	Belgium	ISO8859-1
nl_NL	Dutch	Netherlands	ISO8859-1
no_NO	Norwegian	Norway	ISO8859-1
pl_PL	Polish	Poland	ISO8859-2
pt_PT	Portuguese	Portugal	ISO8859-1
ro_RO	Romanian	Romania	ISO8859-2
ru_RU	Russian	Russia	ISO8859-5
sh_SP	Serbian Latin	Yugoslavia	ISO8859-2
sl_SI	Slovene	Slovenia	ISO8859-2
sk_SK	Slovak	Slovakia	ISO8859-2
sr_SP	Serbian Cyrillic	Yugoslavia	ISO8859-5
Zh_CN	Simplified Chinese	PRC	GBK
sv_SE	Swedish	Sweden	ISO8859-1
tr_TR	Turkish	Turkey	ISO8859-9
zh_TW	Chinese (trad)	Taiwan	IBM-eucTW

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.

Related Information

The localeconv subroutine, nl_langinfo subroutine, rpmatch (rpmatch Subroutine) subroutine.

The localedef command.

Subroutines, Example Programs, and Libraries in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

National Language Support Overview and Setting the Locale in AIX 5L Version 5.2 National Language Support Guide and Reference.