setlocale() — Set Locale
Format
#include <locale.h>
char *setlocale(int category, const char *locale);
Language Level
ANSI
Threadsafe
No
Locale Sensitive
For more information, see Understanding CCSIDs and Locales.
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 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. |
|
setlocale()
and
other locale-sensitive C functions. 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 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.
Category | Default Locale |
---|---|
LC_ALL |
|
LC_CTYPE
LC_COLLATE LC_TIME LC_NUMERIC LC_MESSAGES LC_MONETARY LC_TOD |
|
LC_UNI_ALL | If your module is compiled with the LOCALETYPE(*LOCALEUCS2) option:
If your module is compiled with the LOCALETYPE(*LOCALEUTF) option:
|
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:
If your module is compiled with the LOCALETYPE(*LOCALEUTF) option:
|
- the LOCALE parameter in your user profile (see the CHGUSRPRF (Change User Profile) command information in the Information Center).
- the QLOCALE system value (see the QLOCALE system value information in the Information Center).
/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.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 Information Center) for
locales created with CCSID(*UTF).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()
.
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.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);
}