setlocale(3C)                                                    setlocale(3C)


NAME
     setlocale - modify and query a program's locale

SYNOPSIS
     #include <locale.h>

     char *setlocale (int category, const char *locale);

DESCRIPTION
     setlocale selects the appropriate piece of the program's locale as
     specified by the category and locale arguments.  The category argument
     may have the following values: LC_CTYPE, LC_NUMERIC, LC_TIME, LC_COLLATE,
     LC_MONETARY, LC_MESSAGES and LC_ALL.  These names are defined in the
     locale.h header file.  LC_CTYPE affects the behavior of the character
     handling functions (isalpha, tolower, etc.) and the multibyte character
     functions (such as mbtowc and wctomb).  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 localeconv [see localeconv(3C)].  LC_TIME affects the
     behavior of ascftime, cftime, getdate, and strftime.  LC_COLLATE affects
     the behavior of strcoll and strxfrm.  LC_MONETARY affects the monetary
     formatted information returned by localeconv.  LC_MESSAGES affects the
     behavior of gettxt, catopen, catclose, and catgets [see catopen(3C) and
     catgets(3C)].  LC_ALL names the program's entire locale.

     Each category corresponds to a set of databases that contain the relevant
     information for each defined locale.  The location of a database is given
     by the following path, /usr/lib/locale/locale/category, where locale and
     category are the names of locale and category, respectively.  For
     example, the database for the LC_CTYPE category for the "german" locale
     would be found in /usr/lib/locale/german/LC_CTYPE.

     A value of "C" for locale specifies the default environment.

     A value of "" for locale specifies that the locale should be taken from
     environment variables.  The order in which the environment variables are
     checked for the various categories is given below:
               Category       1st Env. Var.   2nd Env. Var
               ___________________________________________
               LC_CTYPE:      LC_CTYPE        LANG
               LC_COLLATE:    LC_COLLATE      LANG
               LC_TIME:       LC_TIME         LANG
               LC_NUMERIC:    LC_NUMERIC      LANG
               LC_MONETARY:   LC_MONETARY     LANG
               LC_MESSAGES:   LC_MESSAGES     LANG

     At program startup, the equivalent of

          setlocale(LC_ALL, "C")


     is executed.  This has the effect of initializing each category to the
     locale described by the environment "C".

     If a pointer to a string is given for locale, setlocale attempts to set
     the locale for the given category to locale.  If setlocale succeeds,
     locale is returned.  If setlocale fails, a null pointer is returned and
     the program's locale is not changed.

     For category LC_ALL, the behavior is slightly different.  If a pointer to
     a string is given for locale and LC_ALL is given for category, setlocale
     attempts to set the locale for all the categories to locale.  The locale
     may be a simple locale, consisting of a single locale, or a composite
     locale.  A composite locale is a string returned by a previous call to
     setlocale with LC_ALL for which the locale did not consist of identical
     category values.  If setlocale fails to set the locale for any category,
     a null pointer is returned and the program's locale for all categories is
     not changed.  Otherwise, a description of the new locale is returned.

     A null pointer for locale causes setlocale to return the current locale
     associated with the category.  The program's locale is not changed.

FILES
     /usr/lib/locale/C/LC_CTYPE          LC_CTYPE database for the C locale
     /usr/lib/locale/C/LC_NUMERIC        LC_NUMERIC database for the C locale
     /usr/lib/locale/C/LC_TIME           LC_TIME database for the C locale
     /usr/lib/locale/C/LC_COLLATE        LC_COLLATE database for the C locale
     /usr/lib/locale/C/LC_MESSAGES       LC_MESSAGES database for the C locale
     /usr/lib/locale/locale/category     files containing the locale-specific
                                         information for each locale and
                                         category

SEE ALSO
     ctime(3C), ctype(3C), getdate(3C), gettxt(3G), localeconv(3C),
     mbchar(3C), mbstring, strcoll(3C), strftime(3C), strtod(3C), strxfrm(3C),
     printf(3S), environ(5).

BUGS
     Because setlocale() may call dlopen(3), and because dlopen(3) calls are
     forbidden from init sections of DSO's, setlocale() should not be called
     from such sections.  See DSO(5) for more information.


                                                                        Page 2