Chapter Contents |
Previous |
Next |
setlocale |
Portability: | ISO/ANSI C conforming, POSIX.1 conforming |
SYNOPSIS | |
DESCRIPTION | |
RETURN VALUE | |
CAUTIONS | |
IMPLEMENTATION | |
EXAMPLE |
SYNOPSIS |
#include <locale.h> char *setlocale(int category, const char *locale);
DESCRIPTION |
setlocale
selects the current locale or a portion thereof, as specified
by the
category
and
locale
arguments. Here are the
valid categories:
locale
points to a
locale_string
that has one of the following formats:
xxxx
1ln
setlocale(LC_ALL, "C");
xxxx;category=yyyy< ;category=zzzz ...>
1ln
setlocale(LC_MONETARY, "C;LC_TIME=SAMP");
category=yyyy< ;category=zzzz
...>
1ln
setlocale(LC_MONETARY, "LC_TIME=SAMP");
""
(null string)
NULL
(pointer)
setlocale(LC_ALL, NULL);
In the
locale_string
formats, xxxx, yyyy, and zzzz have the following
meanings:
Any number of category overrides can be specified; however,
only the first one per category is honored. Category overrides are honored
only when the
LC_ALL
category
is requested or the specific category and the override match. For example,
this statement sets only the
LC_MONETARY
category; the
LC_TIME
override is ignored.
setlocale(LC_MONETARY,"C;LC_TIME=SAMP");
When
NULL
is specified,
setlocale
returns the current locale string in the same format as described
earlier.
If the locale string is specified as
""
, the library consults a number of environment
variables to determine the appropriate settings. If none of the environment
variables are defined, the
"C"
locale is used.
The locale
""
is resolved in the following steps:
LC_ALL
is defined and
not NULL, the value of
LC_ALL
is used as the locale.
LC_ALL
was specified, and there is an environment
variable with the same name as the category, the value of that variable is
used (if not NULL). For instance, if the category was
LC_COLLATE
, and the environment variable
LC_COLLATE
is
"DBEX"
, then the
LC_COLLATE
component of the
"DBEX"
locale is used. Note that if the category is
LC_ALL
, the effect is the same as if
each other
category were set independently.
LANG
is defined and not NULL, the value of
LANG
is used as the
locale.
_LOCALE
is defined and not NULL, the value of
_LOCALE
is used as the locale.
RETURN VALUE |
setlocale
returns the string associated with the specified
category
value. If the value for
locale
is not valid or an error occurs when loading
the requested locale,
setlocale
returns
NULL
and
the locale is not affected.
If
locale
is specified as
NULL
,
setlocale
returns the string
associated with the
category
for the current locale and the locale is not affected.
When issuing
setlocale
for a mixed
locale
, if a category override fails (for example, if the locale load
module cannot be found), then for that category the
LC_ALL
category is used if it is being set at
the same time. Otherwise, a
NULL
return is issued and the category for which the locale override
was requested remains unchanged. The returned string indicates the actual
mixed locale in effect.
CAUTIONS |
A second call to
setlocale
overwrites the previous value, so you
must save the current value before calling
setlocale
again, if you need the value later. This involves determining
the string length for the locale name, allocating storage space for it, and
copying it. The following code does all three:
char *name; name = setlocale(LC_ALL, NULL); name = strsave(name);
When you want to revert to the locale saved in
name
, use the following code:
setlocale(LC_ALL, name);
IMPLEMENTATION |
Except for the
"S370"
locale, which is built-in, locale information is kept in a load
module created by compiling and linking
"S370"
source code for the locale's localization data and routines.
The load module name is created by appending up to the first four uppercased
characters of the locale's name to the
"L$CL"
prefix. For example, if the locale name is
MYLOCALE
, the load module name is
L$CLMYLO
.
The locale load module is loaded when needed (with
loadm
) during
setlocale
processing. For the exact details
and requirements on specifying localization data and routines, see User-Added Locales. Also
loadm for load module library search and
location requirements.
Mixed locale strings can be specified. In this case,
all requested locales are loaded by a single call to
setlocale
.
EXAMPLE |
#include <locale.h> main() { char *name; /* Set all portions of the current locale to */ /* the values defined by the built-in "C" locale. */ setlocale(LC_ALL, "C"); /* Set the LC_COLLATE category to the value */ /* defined by the "DBCS" locale. */ setlocale(LC_COLLATE, "DBCS"); /* Set the LC_CTYPE category to the value */ /* defined by the "DBCS" locale. */ setlocale(LC_CTYPE, "DBCS"); /* Set the LC_NUMERIC category to the value */ /* defined by the "SAMP" locale. */ setlocale(LC_NUMERIC, "SAMP"); /* Return mixed locale string. */ name = setlocale(LC_ALL, NULL); }
The following string is pointed to by
name
:
"C;LC_COLLATE=DBCS;LC_CTYPE=DBCS;LC_NUMERIC=SAMP"
This string is interpreted as if the "
C
" locale (
LC_ALL
) is in effect except for
LC_COLLATE
and
LC_CTYPE
, which have the "
DBCS
" locale in effect, and
LC_NUMERIC
, which is using "
SAMP
".
The
same results can be accomplished with a single call
to
setlocale
:
#include <locale.h> void main() { char *name; name = setlocale(LC_ALL, "C;LC_COLLATE=DBCS;LC_CTYPE=DBCS;LC_NUMERIC=SAMP"); }
Chapter Contents |
Previous |
Next |
Top of Page |
Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.