setlocale(3P) INTERACTIVE UNIX System (POSIX) setlocale(3P)
NAME
setlocale - locale control
SYNOPSIS
#include <locale.h>
char *setlocale (int category, const char *locale);
DESCRIPTION
The setlocale function selects the appropriate portion of
the program's locale as specified by the category and locale
arguments. The setlocale function may be used to change or
query the program's entire current locale or portions
thereof. The value LC_ALL for category names the program's
entire locale; the other values for category name only a
portion of the program's locale.
LC_ALL Names the entire locale.
LC_CTYPE Affects the behavior of the character han-
dling functions. The functions isdigit and
isxdigit are not affected by the current
locale.
LC_COLLATE Affects the behavior of the string collation
functions.
LC_NUMERIC Affects the decimal-point character for the
formatted input/output functions and the
string conversion functions, as well as the
non-monetary formatting information returned
by the localeconv function.
LC_MONETARY Affects the monetary formatting information
returned by the localeconv function.
LC_TIME Affects the behavior of the strftime func-
tion.
A value of C or POSIX for locale specifies the minimal
environment for C translation. Other implementation-defined
strings may be passed as the second argument to setlocale.
At program startup, the equivalent of
setlocale (LC_ALL, "C");
is executed.
The locale argument is a pointer to a character string that
can be an explicit string, a NULL pointer, or an empty
string.
When locale is an explicit string, the argument must
Rev. 1.1 Page 1
setlocale(3P) INTERACTIVE UNIX System (POSIX) setlocale(3P)
identify a locale which can be set for the specified
category. If the category is LC_ALL, the named locale must
be valid for all supported categories. The values POSIX or
C for locale are reserved for the default locale.
When locale is a NULL pointer, setlocale returns a pointer
to a string identifying the current locale for the specified
category. The returned string value can be used as the
locale argument in a subsequent call to setlocale with the
same category.
When locale is an empty string the setlocale function inter-
rogates the values of environment variables to determine the
locale. If the category is not LC_ALL, the value of an
environment variable corresponding to the category name is
searched. If the environment variable is not set, set to an
empty string, or identifying an invalid locale, the value of
the environment variable LANG is used. If the
LANG variable is not set, set to an empty string, or identi-
fying an invalid locale, the environment will be set to the
C locale.
If the category value is LC_ALL, the entire environment is
set, i.e. the following invocation of setlocale first veri-
fies that all supported categories can be set to a valid
locale as defined by the environment variables, and then
sets the environment:
setlocale(LC_ALL,"");
Unless all supported categories can be set to a valid
locale, the environment is not changed and setlocale will
return a NULL pointer.
If the environment variable corresponding to the specified
category is set to a non-empty string identifying a valid
locale, the category will be set to that localen. If a
named locale is invalid, the environment is not changed and
setlocale will return a NULL pointer.
If the category-specific environment variable is not set or
set to an empty string, the value of the LANG environment
variable, if set and identifying a valid locale, is used for
that category.
If none of the environment variables identify a valid locale
for a category, the environment is set to the C locale.
A valid locale is one which can be set and referenced for
the named category.
RETURN VALUES
If a pointer to a string is given for locale and the
Rev. 1.1 Page 2
setlocale(3P) INTERACTIVE UNIX System (POSIX) setlocale(3P)
selection can be honored, the setlocale function returns a
pointer to the string associated with the specified category
for the new locale. If the selection cannot be honored, the
setlocale function returns a NULL pointer and the program's
locale is not changed.
A NULL pointer for locale causes the setlocale function to
return a pointer to the string associated with the category
for the program's current locale; the program's locale is
not changed.
The pointer to the string returned by the setlocale function
is such that a subsequent call with that string value and
its associated category will restore that part of the
program's locale. The string pointed to shall not be modi-
fied by the program, but may be overwritten by a subsequent
call to the setlocale function.
RESTRICTIONS
Currently, the category LC_COLLATE cannot be set to any
value but C. A call to setlocale with the value LC_ALL and
a locale (or the empty string) will be honored if the locale
contains valid data for all categories except LC_COLLATE.
Rev. 1.1 Page 3