ILE C/C++ Run-Time Library Functions
Format
#include <locale.h>
char *setlocale(int category, const char *locale);
Language Level: ANSI
Threadsafe: No.
Description
The setlocale() function changes or queries variables that are
defined in the <locale.h> include file, that indicate
location. The values for category are listed below.
Category
| Purpose
|
LC_ALL
| Names entire locale of program.
|
LC_COLLATE
| Affects behavior of the strcoll() and strxfrm()
functions.
|
LC_CTYPE
| Affects behavior of character handling functions.
|
LC_MONETARY
| Affects monetary information returned by localeconv() and
nl_langinfo() functions.
|
LC_NUMERIC
| Affects the decimal-point character for the formatted input/output and
string conversion functions, and the non-monetary formatting information
returned by the localeconv() and nl_langinfo()
functions.
|
LC_TIME
| Affects behavior of the strftime() function and the time
formatting information returned by the nl_langinfo()
function.
|
LC_TOD
| Affects the behavior of the time functions.
The category LC_TOD has several fields in it. The TNAME field is
the time zone name. The TZDIFF field is the difference between local
time and Greenwich Meridian time. If the TNAME field is nonblank, then
the TZDIFF field is used when determining the values that are returned by some
of the time functions. This value takes precedence over the system
value, QUTCOFFSET.
|
LC_UNI_ALL*
| This category causes setlocale() to load all of the the
LC_UNI_ categories from the locale specified. This category accepts
only a locale with a UCS2 or UTF-32 CCSID.
|
LC_UNI_COLLATE*
| Affects behavior of the wcscoll() and wcsxfrm()
functions. This category accepts only a locale with a UCS2 or UTF-32
CCSID.
- Note:
- This category is not supported for UCS2.
|
LC_UNI_CTYPE*
| Affects the behavior of the wide character handling functions.
This category accepts only a locale with a UCS2 or UTF-32
CCSID.
|
LC_UNI_MESSAGES*
| Affects the message formatting information returned by the
_WCS_nl_langinfo() function. This category accepts only a
locale with a UCS2 or UTF-32 CCSID.
|
LC_UNI_MONETARY*
| Affects the monetary information returned by the
wcslocaleconv() and _WCS_nl_langinfo() functions.
This category accepts only a locale with a UCS2 or UTF-32
CCSID.
|
LC_UNI_NUMERIC*
| Affects the decimal-point character for the wide character formatted
input/output and wide character string conversion functions, and the
non-monetary information returned by the wcslocaleconv() and
_WCS_nl_langinfo() functions. This category accepts only a
locale with a UCS2 or UTF-32 CCSID.
|
LC_UNI_TIME*
| Affects the behavior of the wcsftime() function and the time
formatting information returned by the _WCS_nl_langinfo()
functions. This category accepts only a locale with a UCS2 or UTF-32
CCSID.
|
LC_UNI_TOD*
| Affects the behavior of the wide character time functions. This
category accepts only a locale with a UCS2 or UTF-32
CCSID.
|
- *
- To use categories with UNI in the name, LOCALETYPE(*LOCALEUCS2) or
LOCALETYPE(*LOCALEUTF) must be specified on the compilation command. If
LOCALETYPE(*LOCALEUCS2) is used, the locale specified must be a UCS2
locale. If LOCALETYPE(*LOCALEUTF) is used, the locale specified must be
a UTF-32 locale.
|
- Note:
- There are two ways of defining setlocale() and other
locale-sensitive C functions on the iSeries server. The original way to
define setlocale() uses *CLD locale objects to set the locale and
retrieve locale-sensitive data. The second way to define
setlocale() uses *LOCALE objects to set the locale and retrieve
locale-sensitive data. The original way is accessed by specifying
LOCALETYPE(*CLD) on the compilation command. The second way is accessed
by specifying LOCALETYPE(*LOCALE), LOCALETYPE(*LOCALEUCS2), or
LOCALETYPE(*LOCALEUTF) on the compilation command. For more information
on the two methods of locale definition in ILE C, see "International Locale
Support" in the WebSphere Development Studio: ILE
C/C++ Programmer's Guide.
Setlocale using *CLD locale objects
You can set the value of locale to "C", "",
LC_C, LC_C_GERMANY, LC_C_FRANCE, LC_C_SPAIN,
LC_C_ITALY, LC_C_USA or LC_C_UK. A locale
value of "C" indicates the default C environment. A locale
value of "" tells the setlocale() function to use the
default locale for the implementation.
Setlocale with *LOCALE objects.
You can set the value of locale to "", "C",
"POSIX", or the fully qualified Integrated File System path name of a
*LOCALE object enclosed in double quotes. A locale value of
"C" or "POSIX" indicates the default C *LOCALE object.
A locale value of "" tells the setlocale()
function to use the default locale for the process.
The default locale for the process is determined using the following
table:
LC_ALL
|
- Check the LC_ALL environment variable1. If it is defined
and not null, use the specified locale2 for all POSIX locale
categories. Otherwise, go to the next step.
- For each POSIX locale category (LC_CTYPE, LC_COLLATE, LC_TIME, LC_NUMERIC,
LC_MESSAGES, LC_MONETARY, and LC_TOD), check the environment variable with the
same name1. If it is defined and not null, use the locale
specified2.
- Check the LANG environment variable1. For every locale
category that was not set in the previous step, if the LANG environment
variable is defined and not null, set the locale category to the specified
locale2. Otherwise, set it to the default C *LOCALE
object.
|
LC_CTYPE
LC_COLLATE
LC_TIME
LC_NUMERIC
LC_MESSAGES
LC_MONETARY
LC_TOD
|
- Check the LC_ALL environment variable1. If it is defined
and not null, use the specified locale2. Otherwise, go to
the next step.
- Check the environment variable with the same name1 as the
specified locale category. If it is defined and not null, use the
locale specified2. Otherwise, go to the next step.
- Check the LANG environment variable1. If it is defined
and not null, set the locale category to the specified
locale2. Otherwise, go to the next step.
- Set the locale category to the default C *LOCALE object.
|
LC_UNI_ALL
|
If your module is compiled with the LOCALETYPE(*LOCALEUCS2) option:
- Check the LC_UCS2_ALL environment variable1. If it is
defined and not null, use the specified locale for all Unicode locale
categories. Otherwise, go to the next step.
- For each Unicode locale category check the corresponding environment
variable1 (LC_UCS2_CTYPE, LC_UCS2_COLLATE, LC_UCS2_TIME,
LC_UCS2_NUMERIC, LC_UCS2_MESSAGES, LC_UCS2_MONETARY, or
LC_UCS2_TOD)3. If it is defined and not null, use the locale
specified.
- Set the locale category to the default UCS2 *LOCALE object.
If your module is compiled with the LOCALETYPE(*LOCALEUTF) option:
- Check the LC_UTF_ALL environment variable1. If it is
defined and not null, use the specified locale for all Unicode locale
categories. Otherwise, go to the next step.
- For each Unicode locale category check the corresponding environment
variable1 (LC_UTF_CTYPE, LC_UTF_COLLATE, LC_UTF_TIME,
LC_UTF_NUMERIC, LC_UTF_MESSAGES, LC_UTF_MONETARY, or
LC_UTF_TOD)3. If it is defined and not null, use the locale
specified.
- Check the LANG environment variable1. For every locale
category that was not set in the previous step, if the LANG environment
variable is defined and not null, set the locale category to the specified
locale. Otherwise, set it to the default UTF *LOCALE object.
|
LC_UNI_CTYPE
LC_UNI_COLLATE
LC_UNI_TIME
LC_UNI_NUMERIC
LC_UNI_MESSAGES
LC_UNI_MONETARY
LC_UNI_TOD
|
If your module is compiled with the LOCALETYPE(*LOCALEUCS2) option:
- Check the environment variable corresponding to the specified locale
category1 (LC_UCS2_CTYPE, LC_UCS2_COLLATE, LC_UCS2_TIME,
LC_UCS2_NUMERIC, LC_UCS2_MESSAGES, LC_UCS2_MONETARY, or
LC_UCS2_TOD)3. If it is defined and not null, use the locale
specified. Otherwise, go to the next step.
- Check the LC_UCS2_ALL environment variable1. If it is
defined and not null, use the specified locale. Otherwise, go to the
next step.
- Set the locale category to the default UCS2 *LOCALE object.
If your module is compiled with the LOCALETYPE(*LOCALEUTF) option:
- Check the environment variable corresponding to the specified locale
category1 (LC_UTF_CTYPE, LC_UTF_COLLATE, LC_UTF_TIME,
LC_UTF_NUMERIC, LC_UTF_MESSAGES, LC_UTF_MONETARY, or
LC_UTF_TOD)3. If it is defined and not null, use the locale
specified. Otherwise, go to the next step.
- Check the LC_UTF_ALL environment variable1. If it is
defined and not null, use the specified locale. Otherwise, go to the
next step.
- Check the LANG environment variable1. If the LANG
environment variable is defined and not null, set the locale category to the
specified locale. Otherwise, set it to the default UTF *LOCALE
object.
|
- Note:
- 1 The environment variables with names corresponding to locale
categories are created by the user. The LANG environment variable is
automatically created during job initiation when you specify a locale path
name for either of the following:
The locale environment variables are expected to contain a locale path
name of the form /QSYS.LIB/<locname>.LOCALE or
/QSYS.LIB/<libname>.LIB/<locname>.LOCALE.
If your module is compiled with the LOCALETYPE(*LOCALEUTF) option, the
environment variable will be ignored if the <locname> portion of
the path exceeds 8 characters. This restriction exists because a 2
character suffix must be appended to the locale name to get the name of the
corresponding UTF locale.
- Note:
- 2 When LOCALETYPE(*LOCALEUTF) is specified on the compilation
command, the setlocale() function appends a trailing "_8" to
the LC_ALL, LC_CTYPE, LC_COLLATE, LC_TIME, LC_NUMERIC, LC_MESSAGES,
LC_MONETARY, LC_TOD, and LANG environment variables. If this locale is
not found, the UTF default locale object is used. For example,
setlocale(LC_ALL, "") when LANG is set to
/QSYS.LIB/EN_US.LOCALE causes setlocale()
to attempt to load the locale
/QSYS.LIB/EN_US_8.LOCALE. If the LANG
environment variable is used to set one of the Unicode locale categories
(LC_UNI_ALL, LC_UNI_CTYPE, LC_UNI_COLLATE, LC_UNI_TIME, LC_UNI_NUMERIC,
LC_UNI_MESSAGES, LC_UNI_MONETARY, or LC_UNI_TOD), setlocale()
appends a trailing "_4" to the locale name stored in the environment
variable. This is an attempt to locate the corresponding UTF32
locale. If this locale is not found, the default UTF32 locale object is
used. For example, setlocale(LC_UNI_TIME, "") when LANG is
set to /QSYS.LIB/EN_US.LOCALE causes
setlocale() to attempt to load the locale
/QSYS.LIB/EN_US_4.LOCALE. Locale names ending
in "_4" and "_8" follow a naming convention introduced by the
CRTLOCALE CL command (see the CRTLOCALE (Create Locale)
command information in the iSeries Information Center) for locales created
with CCSID(*UTF).
- Note:
- 3 The LC_UNI_ALL, LC_UNI_COLLATE, LC_UNI_CTYPE, LC_UNI_TIME,
LC_UNI_NUMERIC, LC_UNI_MESSAGES, LC_UNI_MONETARY, and LC_UNI_TOD locale
category names are shared between UCS2 and UTF. The environment
variables corresponding to these categories cannot be shared, so the names of
the environment variables do not exactly match the locale category
names. For UCS2 environment variable names, "UNI" is replaced with
"UCS2" (for example, LC_UNI_ALL locale category becomes LC_UCS2_ALL
environment variable). For UTF environment variable names, "UNI"
is replaced with "UTF" (for example, LC_UNI_ALL locale category becomes
LC_UTF_ALL environment variable).
If compiled with LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF),
the locale must be a pointer to a valid Unicode locale for the categories
starting with LC_UNI_, and must not be a Unicode locale for the other
categories.
Return Value
The setlocale() function returns a pointer to a string that, if
passed back to the setlocale() function, would restore the locale
to the previous setting. This string should be copied by the user as it
will be overwritten on subsequent calls to setlocale().
- Note:
- Because the string to which a successful call to
setlocale() points may be overwritten by subsequent calls to the
setlocale() function, you should copy the string if you plan to use
it later. The exact format of the locale string is different between
locale types of *CLD, *LOCALE, *LOCALEUCS2, and *LOCALEUTF.
To query the locale, give a NULL as the second parameter. For
example, to query all the categories of your locale, enter the following
statement:
char *string = setlocale(LC_ALL, NULL);
Error Conditions
On error, the setlocale() function returns NULL, and the
program's locale is not changed.
Example that uses *CLD locale objects
/************************************************************************
This example sets the locale of the program to
LC_C_FRANCE *CLD and prints the string
that is associated with the locale. This example must be compiled with
the LOCALETYPE(*CLD) parameter on the compilation command.
*
************************************************************************/
#include <stdio.h>
#include <locale.h>
char *string;
int main(void)
{
string = setlocale(LC_ALL, LC_C_FRANCE);
if (string != NULL)
printf(" %s \n",string);
}
Example that uses *LOCALE objects
/************************************************************************
This example sets the locale of the program to be "POSIX" and prints
the string that is associated with the locale. This example must be
compiled with the LOCALETYPE(*LOCALE) parameter on the CRTCMOD or
CRTBNDC command.
************************************************************************/
#include <stdio.h>
#include <locale.h>
char *string;
int main(void)
{
string = setlocale(LC_ALL, "POSIX");
if (string != NULL)
printf(" %s \n",string);
}
Related Information
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.