[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Base Operating System and Extensions Technical Reference, Volume 2

setlocale Subroutine


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


Standard C Library (libc.a)


#include <locale.h>
char *setlocale (CategoryLocale)
int Category;
const char *Locale;


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 General Programming Concepts: Writing and Debugging Programs for setlocale subroutine examples.

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


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:

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 IBM-850
da_DK Danish Denmark ISO8859-1
De_CH German Switzerland IBM-850
de_CH German Switzerland ISO8859-1
De_DE German Germany IBM-850
de_DE German Germany ISO8859-1
el_GR Greek Greece ISO8859-7
En_GB English Great Britain IBM-850
en_GB English Great Britain ISO8859-1
En_US English United States IBM-850
en_US English United States ISO8859-1
Es_ES Spanish Spain IBM-850
es_ES Spanish Spain ISO8859-1
Fi_FI Finnish Finland IBM-850
fi_FI Finnish Finland ISO8859-1
Fr_BE French Belgium IBM-850
fr_BE French Belgium ISO8859-1
Fr_CA French Canada IBM-850
fr_CA French Canada ISO8859-1
Fr_FR French France IBM-850
fr_FR French France ISO8859-1
Fr_CH French Switzerland IBM-850
fr_CH French Switzerland ISO8859-1
hr_HR Croatian Croatia ISO8859-2
hu_HU Hungarian Hungary ISO8859-2
Is_IS Icelandic Iceland IBM-850
is_IS Icelandic Iceland ISO8859-1
It_IT Italian Italy IBM-850
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 IBM-850
nl_BE Dutch Belgium ISO8859-1
Nl_NL Dutch Netherlands IBM-850
nl_NL Dutch Netherlands ISO8859-1
No_NO Norwegian Norway IBM-850
no_NO Norwegian Norway ISO8859-1
pl_PL Polish Poland ISO8859-2
Pt_PT Portuguese Portugal IBM-850
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 IBM-850
sv_SE Swedish Sweden ISO8859-1
tr_TR Turkish Turkey ISO8859-9
zh_TW Chinese (trad) Republic of China 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.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The localeconv subroutine, nl_langinfo subroutine, rpmatch subroutine.

The localedef command.

National Language Support Overview for Programming and Understanding Locale Subroutines in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

Subroutines Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]