Selects the appropriate portion of the program's locale as
specified by the category and locale arguments. You can use this
function to change or query one category or the program's entire
current locale.
Format
#include <locale.h>
char *setlocale (int category, const char *locale);
1 – Arguments
category
The name of the category. Specify LC_ALL to change or query the
entire locale. Other valid category names are:
o LC_COLLATE
o LC_CTYPE
o LC_MESSAGES
o LC_MONETARY
o LC_NUMERIC
o LC_TIME
locale
Pointer to a string that specifies the locale.
2 – Description
The setlocale function sets or queries the appropriate portion
of the program's locale as specified by the category and locale
arguments. Specifying LC_ALL for the category argument names the
entire locale; specifying the other values name only a portion of
the program's locale.
The locale argument points to a character string that identifies
the locale to be used. This argument can be one of the following:
o Name of the public locale
Specifies the public locale in the following format:
language_country.codeset[@modifier]
The function searches for the public locale binary file in
the location defined by the logical name SYS$I18N_LOCALE. The
file type defaults to .LOCALE. The period (.) and at-sign (@)
characters in the name are replaced by an underscore (_).
For example, if the specified name is
"zh_CN.dechanzi@radical", the function searches for the
SYS$I18N_LOCALE:ZH_CN_DECHANZI_RADICAL.LOCALE binary locale
file.
o A file specification
Specifies the binary locale file. It can be any valid file
specification. If either the device or directory is omitted,
the function first applies the current caller's device and
directory as defaults for any missing component. If the file
is not found, the function applies the device and directory
defined by the SYS$I18N_LOCALE logical name as defaults. The
file type defaults to .LOCALE.
No wildcards are allowed. The binary locale file cannot reside
on a remote node.
o "C"
Specifies the C locale. If a program does not call setlocale,
the C locale is the default.
o "POSIX"
This is the same as the C locale.
o ""
Specifies that the locale is initialized from the setting
of the international environment logical names. The function
checks the following logical names in the order shown until it
finds a logical that is defined:
1. LC_ALL
2. Logical names corresponding to the category. For example,
if LC_NUMERIC is specified as the category, then the first
logical name that setlocale checks is LC_NUMERIC.
3. LANG
4. SYS$LC_ALL
5. The system default for the category, which is defined by
the SYS$LC_* logical names. For example, the default for
the LC_NUMERIC category is defined by the SYS$LC_NUMERIC
logical name.
6. SYS$LANG
If none of the logical names is defined, the C locale is
used as the default. The SYS$LC_* logical names are set up
at the system startup time.
Like the locale argument, the equivalence name of the
international environment logical name can be either the name
of the public locale or the file specification. The setlocale
function treats this equivalence name as if it were specified
as the locale argument.
o NULL
Causes setlocale to query the current locale. The function
returns a pointer to a string describing the portion of the
program's locale associated with category. Specifying the LC_
ALL category returns the string describing the entire locale.
The locale is not changed.
o The string returned from the previous call to setlocale
Causes the function to restore the portion of the program's
locale associated with category. If the string contains the
description of the entire locale, the part of the string
corresponding to category is used. If the string describes the
portion of the program's locale for a single category, this
locale is used. For example, this means that you can use the
string returned from the call setlocale with the LC_COLLATE
category to set the same locale for the LC_MESSAGES category.
If the specified locale is available, then setlocale returns
a pointer to the string that describes the portion of the
program's locale associated with category. For the LC_ALL
category, the returned string describes the entire program's
locale. If an error occurs, a NULL pointer is returned and the
program's locale is not changed.
Subsequent calls to setlocale overwrite the returned string.
If that part of the locale needs to be restored, the program
should save the string. The calling program should make no
assumptions about the format or length of the returned string.
3 – Return Values
x Pointer to a string describing the locale.
NULL Indicates an error occurred; errno is set.
4 – Example
#include <errno.h>
#include <stdio.h>
#include <locale.h>
/* This program calls setlocale() three times. The second call */
/* is for a nonexistent locale. The third call is for an */
/* existing file that is not a locale file. */
main()
{
char *ret_str;
errno = 0;
printf("setlocale (LC_ALL, \"POSIX\")");
ret_str = (char *) setlocale(LC_ALL, "POSIX");
if (ret_str == NULL)
perror("setlocale error");
else
printf(" call was successful\n");
errno = 0;
printf("\n\nsetlocale (LC_ALL, \"junk.junk_codeset\")");
ret_str = (char *) setlocale(LC_ALL, "junk.junk_codeset");
if (ret_str == NULL)
perror(" returned error");
else
printf(" call was successful\n");
errno = 0;
printf("\n\nsetlocale (LC_
ALL, \"sys$login:login.com\")");
ret_str = (char *) setlocale(LC_
ALL, "sys$login:login.com");
if (ret_str == NULL)
perror(" returned error");
else
printf(" call was successful\n");
}
Running the example program produces the following result:
setlocale (LC_ALL, "POSIX") call was successful
setlocale (LC_ALL, "junk.junk_codeset")
returned error: no such file or directory
setlocale (LC_ALL, "sys$login:login.com")
returned error: nontranslatable vms error code: 0x35C07C
%c-f-localebad, not a locale file