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 UCS-2 or UTF-32
CCSID.
LC_UNI_COLLATE*
Affects behavior of the wcscoll() and wcsxfrm() functions.
This category accepts only a locale with a UCS-2 or UTF-32
CCSID.
Note:
This category is not supported for UCS-2.
LC_UNI_CTYPE*
Affects the behavior of the wide
character handling functions. This category accepts only a locale
with a UCS-2 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 UCS-2 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 UCS-2 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 UCS-2 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 UCS-2 or UTF-32
CCSID.
LC_UNI_TOD*
Affects the behavior of the wide
character time functions. This category accepts only a locale with
a UCS-2 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
UCS-2 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 System i® platform.
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 about the two methods of locale definition
in ILE C, see the International Locale Support section in the IBM Rational Development Studio for i: 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.
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 UCS-2 *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.
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 UCS-2 *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 QLOCALE system value (see the QLOCALE
system value information in the i5/OS Information
Center).
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
UTF-32 locale. If this locale is not found, the default UTF-32
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 i5/OS 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 UCS-2 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 UCS-2 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 represents the current locale setting. If the returned string
is stored, the stored string value can be used as input to the setlocale() function
to restore the locale setting at any time. However, you need to copy
the string to a user-defined buffer; otherwise, the string is 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);
}