INTERNATIONAL VERSION
Page 1 (printed 6/20/89)
SETLOCALE(S) UNIX System V SETLOCALE(S)
Name
setlocale - set or read international environment
Syntax
#include <locale.h>
char *setlocale(category, locale)
int category
char *locale
Description
The function setlocale sets all or part of the current
program's locale (definitions of language and conventions).
Once invoked, setlocale immediately updates the information
used by the routines that support locale-specific
capabilities (for example character and string handling
routines, collation, and so on).
The setlocale function accepts two arguments. The category
argument describes the category of international information
to set. The following categories (defined in locale.h) are
recognised:
LC_ALL Set all categories in the international
environment.
LC_COLLATE
Set only the category that contains collating
information.
LC_CTYPE Set only the category that contains character
classification and case conversion information.
LC_NUMERIC
Set only the category that contains numeric
formatting information.
LC_TIME Set only the category that contains date and time
formatting information.
LC_MESSAGES
Set only the category that contains message
language information.
LC_MONETARY
Set only the category that contains currency
formatting information.
The locale argument should be a character string that
corresponds to the name of a particular international
environment. There are three special locale strings, as
follows:
"C" Defines the minimal environment needed for the C
programming language.
"" Specifies that the locale is set as defined in the
user environment (see environ(M)).
(char *) 0
Used to query the current locale for a specific
category. When returned by setlocale, indicates an
error.
Other strings use the same format as the user environment
variables (see environ(M)).
At program startup (before main), the equivalent of:
setlocale(LC_ALL, "");
is executed, so that the initial locale for the program is
as defined in the user environment.
In addition to setting the locale, setlocale may be used to
query the current locale. This is done by calling setlocale
with a null pointer (i.e. (char *)0) as the locale argument.
setlocale will return the current locale associated with
this category and the program's locale is not changed.
If setlocale is unable to successfully set the locale for
any category, the active locale is unchanged; if the
unsuccessful call was during program startup, the effect is
as if the previous locale was "C". When the failing call
was for the category LC_ALL, all subcategories which could
be set are changed; only those which could not be set remain
as before.
Return Value
If successful, setlocale returns the locale name string
associated with the locale just set. On error, setlocale
returns a null pointer.
When a null pointer is given as the locale, setlocale
returns the locale name string of the current locale. If
the individual categories differ at all, and the specified
category is LC_ALL, then an expanded locale name string is
returned containing the information for each category.
The name string returned by setlocale is such that a
subsequent call to setlocale with that locale name string
and its associated category will restore that part of the
program's locale.
When a locale is partially defined and does not have a
corresponding entry in the file /etc/default/lang , the
following error message is displayed:
libc: setlocale: xxxx: no LANG= line in /etc/default/lang
where xxxx is one of the environment variables found in
environ (M). For example, LC_CTYPE.
When a locale is inaccurately defined, the following error
message is displayed:
libc: setlocale: xxxx: cannot open locale file
where xxxx is one of the environment variables found in
environ (M). For example, LC_CTYPE.
See Also
environ(M), locale(M), ctype(S), collation(S), ctime(S)
Notes
The return values from setlocale are pointers to static
data, the content of which is overwritten with each call.
Standards Conformance
setlocale is conformant with:
ANSI X3.159-198X C Language Draft Standard, May 13, 1988;
IEEE POSIX Std 1003.1-1988 with C Standard Language-
Dependent System Support;
and NIST FIPS 151-1.
(printed 6/20/89)