| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
ISO C |
both |
#include <locale.h>
char *setlocale(int category, const char *locale);Sets, changes, or queries locale categories or groups of categories. It does this action according to values of the locale and category arguments.
A locale is the complete definition of the part of a user's program that depends on language and cultural conventions. You can accept the default value of locale, or you can set it to one of the supplied locales listed in the topic, “Supplied Locales”, in z/OS XL C/C++ Programming Guide. Some examples of the supplied locales are: “C”, “POSIX”, “SAA”, “S370”, “Fr_BE.IBM-1047”, “En_GB.IBM-285”, “En_US.IBM_1047”, “Fr_BE.IBM-1148@euro”, and “Fr_BE.IBM-1148”.
Note that non-POSIX programs may exploit the POSIX style of locale support. This use of environment variables also applies to non-POSIX programs that use POSIX locale support.
Effect of setlocale() on Language Environment: The current locale set with the setlocale() function affects only some C library functions. (See Table 1). It does not affect the CEE locale set and query functions available under Language Environment and described in the IBM Language Environment Programming Reference.
The category argument may be set to one of these values:
| Category | Purpose |
|---|---|
| LC_ALL | Specifies all categories associated with the program's locale. |
| LC_COLLATE | Defines the collation sequence, that is, the relative order
of collation elements (characters and multicharacter collation elements)
in the program's locale. The collation sequence definition is used
by regular expression, pattern matching, and sorting functions. These string functions are affected by the defined collation sequence: strcoll(), strxfrm(), wcscoll(), and wcsxfrm(). LC_CTYPE, LC_COLLATE, and LC_SYNTAX should refer to the same locale. Changing just one of them may invalidate another. |
| LC_CTYPE | Defines character classification and case conversion for characters
in the program's locale. Affects the behavior of character-handling
functions defined in the ctype.h header file: csid(), isalnum(), isalpha(),
isblank(), iswblank() iscntrl(), isdigit(), isgraph(), islower(),
isprint(), ispunct(), isspace(), isupper(), iswalnum(), iswalpha(),
iswcntrl(), iswctype(), iswdigit(), iswgraph(), iswlower(), iswprint(),
iswpunct(), iswspace(), iswupper(), iswxdigit(), isxdigit(), tolower(),
toupper(), towlower(), towupper(), wcsid(), and wctype(). Affects behavior of the printf() and scanf() families of functions: fprintf(), printf(), sprintf(), fscanf(), scanf(), and sscanf(). Affects the behavior of wide-character input/output functions: fgetwc(), fgetws(), getwc(), getwchar(), fputwc(), fputws(), putwc(), putwchar(), and ungetwc(). Affects the behavior of multibyte and wide-character functions: mblen(), mbtowc(), mbstowcs(), wctomb(), wcstombs(), mbrlen(), mbrtowc(), mbsrtowcs(), wcrtomb(), wcsrtombs(), wcswidth(), wcwidth(), wcstod(), wcstol(), and wcstoul(). LC_CTYPE, LC_COLLATE, and LC_SYNTAX should refer to the same locale. Changing just one of them may invalidate another. |
| LC_MESSAGES | Under z/OS XL C/C++ support,
it affects the messages returned by the nl_langinfo() function and
it also has an effect on rpmatch(). The LC_MESSAGES category will not affect the messages for the following functions: perror(), strerror(), and regerror(). In the locale of a C program running with POSIX(ON), it defines affirmative and negative response patterns. |
| LC_MONETARY | Affects monetary information returned by localeconv() and the strfmon() function. It defines the rules and symbols used to format monetary numeric information in the program's locale. The formatting rules and symbols are strings. localeconv() returns pointers to these strings with names found in the locale.h header file. |
| 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() function, specifically:
The formatting rules and symbols are strings. localeconv() returns pointers to the strings with names found in the locale.h header file. |
| LC_TIME | Defines time and date format information in the program's locale used by the strftime(), strptime(), and wcsftime() functions. |
| LC_SYNTAX | Affects the behavior of functions that use encoded values to
format characters:
LC_SYNTAX also affects values that may be retrieved using the getsyntx() function. LC_CTYPE, LC_COLLATE, and LC_SYNTAX should refer to the same locale. Changing just one of them may invalidate another. |
| LC_TOD | Affects the behavior of the functions related to time zone and Daylight Savings Time information in the program's locale, when time zone and Daylight Savings Time information is not defined by the TZ environment variable. This information is used by ctime(), localtime(), mktime(), and strftime(). |
For a POSIX program, the functions ctime(), localtime(), mktime(), setlocale(), and strftime() call the tzset() function to override LC_TOD category information when TZ is defined and valid.
Identifies the locale. For a list of locales provided by IBM®, see the topic about supplied locales in z/OS XL C/C++ Programming Guide.
If the value of an environment variable is used, it must be a valid locale name. If this is the case, setlocale() sets the specified category to the named locale, and returns a string giving the name of the locale. Otherwise, setlocale() does not change the program's locale and returns a NULL pointer. Valid category names include names of locales provided by IBM. Also, names of locales, which are created using the z/OS XL C/C++ locale definition mechanism, are valid.
The null-string ("") locale value: If “” is specified, the locale-related environment variables are checked. If the locale name is not defined by the environment variables, the default is "S370" when running POSIX(OFF) and "C" when running POSIX(ON).
If a program using POSIX-style locale support specifies LC_ALL for the value of category and "" for the value of locale, setlocale() searches environment variables in the way just described to obtain a locale name for each category. If all the locale names obtained identify valid locales, setlocale() sets each category to the appropriate locale and returns a string naming the locale associated with each category. Otherwise, setlocale() does not change the program's locale and returns a NULL pointer.
Default locale: The relationship between the POSIX C and SAA C locales is as follows.
The source file EDC$SAAC LOCALE is provided for reference, but cannot be used to alter the definition of this prebuilt locale.
The source file EDC$POSX LOCALE is provided for reference, but cannot be used to alter the definition of this prebuilt locale.
The setlocale() function supports locales built by using the localedef utility, as well as locales built using the assembler language source and produced by the EDCLOC macro. Find more information about old format locales in “Internationalization: Locales and Character Sets”, in z/OS XL C/C++ Programming Guide.
The LOCPATH environment variable specifies a colon separated list of HFS directories. If LOCPATH is defined, setlocale() searches HFS directories in the order specified by LOCPATH for locale object files it requires. Locale object files in the HFS are produced by the localedef utility running under z/OS UNIX. If LOCPATH is not defined and setlocale() is called by a POSIX program, setlocale() looks in the default HFS locale directory, /usr/lib/nls/locale, for locale object files it requires. If setlocale() does not find a locale object it requires in the HFS, it converts the locale name to a PDS member name as described in z/OS XL C/C++ Programming Guide and searches locale PDS load libraries associated with the program calling setlocale().
Locale names may be file names, relative path names, or absolute path names. LOCPATH is used if file name rather than path name is specified. Also, // preceding a file name tells setlocale() to skip HFS search and to convert the name to a load module name of the form EDC$xxxx, and to search MVS™ load libraries for a member to load with this name. Also, // preceding a file name tells setlocale() to skip HFS search, to convert the name to a load module PDS name. XPLINK locale object PDS names begin with EDC. Non-XPLINK locale object load module names begin with CEH. See z/OS XL C/C++ Programming Guide, topic titled Locale Naming Conventions for further information regarding locale object names.
All locales supplied by IBM come in two versions: non-XPLINK and XPLINK. The HFS-resident XPLINK locale objects are distinguished from their non-XPLINK versions by an ".xplink" suffix on the HFS path name. PDS-resident XPLINK locale objects are distinguished from their non-XPLINK versions by a "CEH" prefix. The non-XPLINK PDS-resident locale objects have a prefix of "EDC".
It is the convention to specify locales using the locale descriptive names as they are listed in Appendix D of z/OS XL C/C++ Programming Guide. The runtime loads the non-XPLINK or XPLINK locale as appropriate.
It is also possible to specify a locale's relative or full path name on the setlocale call. However, the runtime does nothing to ensure the locale is the appropriate version. Setlocale uses the locale object exactly as specified if it is a relative or fully qualified path name. For example, setlocale() will fail if it is given an XPLINK locale full path name but the application is a non-XPLINK application. Similarly, setlocale() will fail if it is given a non-XPLINK locale full path name but the application is an XPLINK application. These problems are avoided if the locale names are the descriptive locale names.
In all three variations of the setlocale() function call, a pointer to a string that represents the locale value is returned. Also, in all variations, if the value for either category or locale is invalid, setlocale() returns a NULL pointer and the operating environment is not changed.
When an explicit locale is named, the category named in the call is set according to the named locale.
When the locale argument of the setlocale() function is given as a NULL string (""), the setlocale() function sets the locale environment according to the environment variables. If these are not set, the default locale "S370" is used. This locale may be customized when the z/OS XL C/C++ product is installed. See “Using Environment Variables” in z/OS XL C/C++ Programming Guide.
The environment variables are not currently supported under all z/OS XL C/C++ environments. The processing above will allow the setlocale() function to use the environment variables if they are available, and to use the "S370" locale otherwise.
setlocale(category, setlocale(category, (char *) 0));The setlocale() function uses the getenv() function to retrieve the environment variables if the system supports the getenv() function. Under CICS® it is not supported.
char *string = setlocale(LC_ALL, NULL);If successful, setlocale() returns a pointer to the string associated with the specified category for the new locale. The string can be used on a subsequent call to restore that part of the program's locale.
If unsuccessful, setlocale() returns a NULL pointer and the program's locale is not changed.
If successful, setlocale() returns a string whose contents depend on the values of the category and locale arguments as shown in the following table.
| Category Value | Locale Value | Return String |
|---|---|---|
| Specific category | NULL pointer | current-locale-name for category |
| new-locale-name | new-locale-name for category | |
| "" (Null string) |
If the environmental variables are set, new-locale-name: environment-variable-value
or C. If the environmental variables are not set, and if non-POSIX Program, then S370 or SAA. |
|
| LC_ALL | NULL pointer | One of these:
|
| new-locale-name | new-locale-name (same for all categories) | |
| "" (Null string) |
One of these:
If environmental variables are not set, and if non-POSIX program, then S370 (same for all categories). |
⁄* CELEBS07
This example sets the locale of the program to be
Fr_FR.IBM-1047 and prints the string that is associated with
the locale.
*⁄
#include <stdio.h>
#include <locale.h>
char *string;
int main(void)
{
string = setlocale(LC_ALL, "Fr_FR.IBM-1047");
if (string != NULL)
printf(" %s \n",string);
} ⁄* CELEBS08
This example uses &setenv. to set the value of the
environment variable LC_TIME to FRAN, calls &setloc. to set
all categories to default values, uses &setloc. to query all
categories, and uses &printf. to print results.
*⁄
#include <stdio.h>
#include <stdlib.h>
#include <env.h>
#include <locale.h>
int main(void)
{
char *string;
setenv("LC_TIME", "FRAN", 1);
setlocale(LC_ALL, "");
string = setlocale(LC_ALL, NULL);
printf("string = %s \n", string);
} Output
string = "S370,S370,S370,S370,FRAN,S370,S370,S370"string = "C,C,C,C,FRAN,C,C,C"Example
/* EUROSAMP
This example sets the locale of the program to be
Fr_BE.IBM-1148 and Fr_BE.IBM-1148@euro and prints
the string associated with each locale.
*/
#include <stdio.h>
#include <locale.h>
int main(void)
{
char *string;
string = setlocale(LC_ALL,"Fr_BE.IBM-1148");
if (string != NULL)
printf("String = %s \n",string);
string = setlocale(LC_ALL,"Fr_BE.IBM-1148@euro");
if (string != NULL)
printf("String = %s \n",string);
}Output
String = Fr_BE.IBM-1148
String = Fr_BE.IBM-1148@euro