SETLOCALE(3,L) AIX Technical Reference SETLOCALE(3,L)
-------------------------------------------------------------------------------
setlocale
PURPOSE
Sets program's locale.
SYNTAX
#include <locale.h>
char *setlocale (int category, const char *locale);
DESCRIPTION
The setlocale subroutine selects the appropriate portion of the program's
locale as specified by the category and locale arguments. The setlocale
subroutine 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. LC_COLLATE affects the behavior of the strcoll and strxfrm
subroutines. LC_CTYPE affects the behavior of the character handling
subroutines and the multibyte functions. LC_MONETARY affects the monetary
formatting information returned by the localeconv subroutine. LC_NUMERIC
affects the decimal-point character for the formatted input/output subroutines
and the string conversion subroutines, as well as the non-monetary formatting
information returned by the localeconv subroutine. LC_TIME affects the
behavior of the strftime subroutine.
A value of C for locale specifies the minimal environment for C translation; a
value of " " for locale specifies the implementation defined native
environment. 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 implementation will behave as if no library subroutine calls the setlocale
subroutine.
OPTIONS AND AFFECTED AREAS
The category Option
Below is the list of parameters which setlocale understands.
Processed November 7, 1990 SETLOCALE(3,L) 1
SETLOCALE(3,L) AIX Technical Reference SETLOCALE(3,L)
+-------------+-------------------------------------------+
|Category | Action |
+-------------+-------------------------------------------+
|LC_ALL | All the categories. |
+-------------+-------------------------------------------+
|LC_COLLATE | Loads in new collation table that |
| | determines the ordering of characters. |
+-------------+-------------------------------------------+
|LC_CTYPE | Loads in new collation table to be used |
| | for character examination functions. |
+-------------+-------------------------------------------+
|LC_MONETARY | Update the structure that hold various |
| | monetary standard information, position |
| | of sign and the characters for the |
| | monetary standards. |
+-------------+-------------------------------------------+
|LC_NUMERIC | The type of decimal point used. |
+-------------+-------------------------------------------+
|LC_TIME | The format of time and weekday and the |
| | corresponding words for them. |
+-------------+-------------------------------------------+
|LC_MESSAGE | The language in which system error |
| | messages are to be shown in. |
+-------------+-------------------------------------------+
+---------------------------------------------------------------------------+
| Functions affected as a result of calling setlocale |
+--------------+------------------------------------------------------------+
| Category | Functions affected |
+--------------+------------------------------------------------------------+
| LC_ALL | All functions mentioned below. |
+--------------+------------------------------------------------------------+
| LC_COLLATE | _NCxcol() NCcollate() strxfrm() |
| | _NLxcol() NCcoluniq() wcscmp() |
| | mbscoll() NCcolval() wcsncmp() |
| | mbscmp() NCeqvmap() wcscoll() |
| | mbsncmp() strcoll() |
+--------------+------------------------------------------------------------+
Processed November 7, 1990 SETLOCALE(3,L) 2
SETLOCALE(3,L) AIX Technical Reference SETLOCALE(3,L)
+---------------------------------------------------------------------------+
| Functions affected as a result of calling setlocale |
+--------------+------------------------------------------------------------+
| Category | Functions affected |
+--------------+------------------------------------------------------------+
| LC_CTYPE | _tolower() ispunct() iswlower() |
| | _toupper() isshift() iswprint() |
| | isalnum() isspace() iswpunct() |
| | isalpha() isupper() iswspace() |
| | iscntrl() iswalnum() iswupper() |
| | isgraph() iswalpha() iswxdigit() |
| | islower iswcntrl() mblen() |
| | isprint() iswdigit() mbsadvance() |
| | mbschr() iswgraph() mbscat() |
| | mbscmp() NCisgraph() NLstrncat() |
| | mbscpy() NCislower() NLstrncmp() |
| | mbscspn() NCisNLchar() NLstrncpy() |
| | mbsinvalid() NCisprint() NLstrpbrk() |
| | mbslen() NCispunct() NLstrrchr() |
| | mbsncat() NCisshift() NLstrspn() |
| | mbsncmp() NCisspace() NLstrtok() |
| | mbsncpy() NCisupper() NCisxdigit() |
| | mbspbrk() NCstrcat() tolower() |
| | mbsrchr() NCstrchr() toupper() |
| | mbsspn() NCstrcpy() towlower() |
| | mbstok() NCstrcspn() towupper() |
| | mbstomb() NCstrlen() wcscat() |
| | mbstowcs() NCstrncat() wcschr() |
| | mbtowc() NCstrncmp() wcscmp() |
| | NCchrlen() NCstrncpy() wcscpy() |
| | NCdec() NCstrpbrk() wcscspn() |
| | NCdechr() NCstrrchr() wcslen() |
| | NCdecode() NCstrspn() wcsncat() |
| | NCdecstr() NCstrtok() wcsncmp() |
| | NCenc() NLchrlen() wcsncpy() |
| | NCencode() NLstrcat() wcspbrk() |
| | NCencstr() NLstrchr() wcsrchr() |
| | NCisalnum() NLstrcpy() wcsspn() |
| | NCisalpha() NLstrcspn() wcstok() |
| | NCiscntrl() NLstrdlen() wctombs() |
| | NCisdigit() NLstrlen() wctomb() |
+--------------+------------------------------------------------------------+
| LC_MONETARY | localeconv. |
+--------------+------------------------------------------------------------+
| LC_NUMERIC | atof, fprintf, localeconv, printf, scanf, sprintf, sscanf. |
+--------------+------------------------------------------------------------+
| LC_TIME | NLstrtime, NLtmtime, strftime. |
+--------------+------------------------------------------------------------+
| LC_MESSAGE | All message accessing routines. |
+--------------+------------------------------------------------------------+
Processed November 7, 1990 SETLOCALE(3,L) 3
SETLOCALE(3,L) AIX Technical Reference SETLOCALE(3,L)
Note: Many of the above function/macros will affect other library routines
such as regex, but since their dependence is solely through the above
interface, they will not be mentioned separately.
The locale Option
char *setlocale (int category, char *locale);
The variable locale consists of two parts. First, the locale which is the name
of the configuration file and second, the modifier. The modifier is separated
from the filename, using the @, or "at" sign. The filename, which will follow
the standards set in the Version 3 document, is language_territory.codeset. In
reality, this is the name of a configuration file that contains keywords
corresponding to various elements of setlocale. If the filename included in
the locale variable points to an absolute path, the given absolute path will be
read. On the other hand, if the filename does not start with a "/", setlocale
will look in the environment for a variable called MBCS_CFG_DIR. This variable
will contain the path to directory in which the directory named locale.dir
resides. setlocale processes the file pointed to by
$MBCS_CFG_DIR/locale.dir/<filename> and interprets its various options. In the
event the MBCS_CFG_DIR is not set, the hard-coded default file
/usr/lib/mbcs.cfg.dir/locale.dir/<filename> is opened for reading.
The contents of the configuration file is a number of tokens indicating the
various options of the subroutines affected by the call to setlocale. The
format is as follows:
#####
# Comments et.al.
#
MBDATE=MM/DD/YY
MBSDAY=Sun:Mon:Tue:Wed:Thu:Fri:Sat
Note: Some fields such as MBSDAY contain an array of values separated by a :,
or colon; if you need a colon as a literal and not a field separator,
then it must be escaped using a backslash character. Multiple
definitions can be made on a line, provided the definitions are
separated by a semi-colon. There are no spaces between the equal equal
sign, and the variable name and its value; the double quote character,
has no special meaning and it will be interpreted as a part of the
variable name/value. If a token is defined and is not legal or does not
belong to the current category, it is ignored.
Below is a list of understood tokens, their groups and their subroutines:
Processed November 7, 1990 SETLOCALE(3,L) 4
SETLOCALE(3,L) AIX Technical Reference SETLOCALE(3,L)
+-----------------------------------------------------------------------------+
|Tokens and their respective Category |
+-------------+----------------+----------------------------------------------+
|Name | Category | Functions Effected |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBDATE | LC_TIME | |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBLANG | LC_MESSAGE | NLgetmsg, catopen |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBLDATE | LC_TIME | strftime(%x) |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBLDATIM | LC_TIME | strftime(%c) |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBLDAY | LC_TIME | strftime(%A) |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBSDAY | LC_TIME | strftime(%a) |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBLMONTH | LC_TIME | strftime(%B) |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBSMONTH | LC_TIME | strftime(%b) |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBTIME | LC_TIME | strftime(%X) |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBAM_STR | LC_TIME | strftime(%p) |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBPM_STR | LC_TIME | strftime(%p) |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBCURSTR | LC_MONETARY | nl_langinfo |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBNUMSEP | LC_NUMERIC | printf, scanf, atof |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBTMISC | LC_TIME | Unix "at" command |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
Processed November 7, 1990 SETLOCALE(3,L) 5
SETLOCALE(3,L) AIX Technical Reference SETLOCALE(3,L)
+-------------+----------------+----------------------------------------------+
|MBMONEY | LC_MONETARY | localeconv |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBTSTRS | LC_TIME | |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBNOSTR | LC_MESSAGE | |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBYESSTR | LC_MESSAGE | |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBCOLTAB | LC_COLLATE | See above for a list |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBCTYPE | LC_CTYPE | See above for a list |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
|MBCONV | LC_ALL | All wide char stdio functions |
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
+-------------+----------------+----------------------------------------------+
The modifier can be used to modify the behavior of various subroutines of
setlocale. For instance, if you wish to use the GR_SW.pc850 (German spoken in
Switzerland) locale, but you wish to use the am, pm strings belonging to the
time subroutine with different values than the ones defined in the GR_SW.pc850
locale, you may do this as follows:
setlocale (LC_ALL, "Gr_SW.pc850@MBAM_STR=am;MBPM_STR=pm");
Note that no space is used before and after the equal signs, the semicolons and
the '@' modifier when calling setlocale.
There are two other values recognized for the locale value. If locale is a
NULL pointer, the user will be given a char pointer containing all the
information about the current locale for the category inquired. This pointer
can be used at a later call to setlocale to restore the locale that was
surveyed last, provided that the contents of memory pointed to by the char
pointer, which is passed to the user, was saved (the contents of the array
could change by calling setlocale, before trying to restore the locale).
EXAMPLE
old_locale = setlocale (LC_TIME, (char *)NULL);
setlocale(LC_TIME, "Fr_FR.pc850");
setlocale(LC_TIME, old_locale);
The above example will fail. The correct format will look like this:
Processed November 7, 1990 SETLOCALE(3,L) 6
SETLOCALE(3,L) AIX Technical Reference SETLOCALE(3,L)
old_locale = setlocale(LC_TIME, (char *)NULL);
cspace = malloc(strlen(old_locale+1));
strcpy(cspace, old_locale);
setlocale(LC_TIME, "Fr_FR.pc850");
setlocale(LC_TIME, cspace);
free(cspace);
The other value recognized for setlocale is a pointer to a NULL. This means to
set the locale to the default locale. This is established by examining the
environment value for the category at hand; in other words, the program will
act as if you passed the environment variable for that category, as follows:
setlocale(LC_TIME, ""); /* is equivalent to: */
setlocale(LC_TIME, getenv("LC_TIME"));
If one calls setlocale in the form
setlocale(LC_ALL, "C");
all the options will be reset to their C locale value. This is the default
value at start-up. All programs at start-up will act if they called
setlocale(LC_ALL, "C"); this is achieved by having all the structures used by
setlocale initialized to the C locale.
The three tokens MBCONV, MBCTYPE, and MBCOLTAB are different, in the sense that
they involve loading an external collation or conversion table. setlocale has
the two hard-coded tables, one for a C locale conversion table, and a second
for a C locale collation/character type table. There are a few advantages in
having the two tables hard-coded. First, there will be no need for loading the
two collation and conversion tables at the beginning of the execution. This
increases the performance and reliability of the system, since a damage to the
C locale collation or conversion table will break all the executables relying
on tables. Second, the hard-coded tables will be a part of the text of the
executables, and in an AIX environment, executables running simultaneously
share their text.
The values of MBCONV, MBCTYPE, and MBCOTAB will be understood as filenames to
be loaded and placed in the appropriate structures, except in the case where
the value is equal to C; in this case, the assumption will be made that the
user wants the C locale, and the appropriate table pointers to their hard-coded
C locale values will be set.
RETURN VALUE
If a pointer to a string is given for locale and the selection can be honored,
the setlocale subroutine returns a pointer to the string associated with the
specified category for the new locale. If the selection cannot be honored, the
setlocale subroutine returns a null pointer and the program's locale is not
changed.
Parameters passed to setlocale update the working environment (this is not the
same as the environment variables) of that particular process, such as its
Processed November 7, 1990 SETLOCALE(3,L) 7
SETLOCALE(3,L) AIX Technical Reference SETLOCALE(3,L)
monetary representation, and some of this information is passed to the kernel.
setlocale is responsible for loading in the conversion table using mbgettabl
and the collation table.
RELATED INFORMATION
In this book: "ctype," "langinfo.h," "locale.h," "nl_langinfo," "string,"
"strcoll, strncoll, strxfrm, mbscoll, mbsncoll, wcscoll, wcsncoll," "printf,
fprintf, sprintf, NLprintf, NLfprintf, NLsprintf, wsprintf," and "scanf,
fscanf, sscanf, NLscanf, NLfscanf, NLsscanf, wsscanf."
AIX Guide to Multibyte Character Set (MBCS) Support.
Processed November 7, 1990 SETLOCALE(3,L) 8