setlocale(S)                   6 January 1993                   setlocale(S)


 Name

    setlocale - set or read international environment

 Syntax


    cc  . . .  -lc


    #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 follow-
    ing categories (defined in <locale.h>) are recognised:


    LCALL          Set all categories in the international environment.

    LCCOLLATE      Set only the category that contains collating informa-
                    tion.

    LCCTYPE        Set only the category that contains character classifica-
                    tion and case conversion information.

    LCNUMERIC      Set only the category that contains numeric formatting
                    information.

    LCMESSAGES     Set only the category that contains message language in-
                    formation.

    LCMONETARY     Set only the category that contains currency formatting
                    information.

    LCTIME         Set only the category that contains date and time format-
                    ting 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.
    ""           (Null string) Specifies that the locale
                 is set to be the implementation-defined
                 native environment which may be affected
                 by the /etc/defaults/lang file, the LANG
                 environment variable, or any of the LC
                 environment variables.  (See
                 environ(M)).
    (char *) 0   (Null pointer) Used to query the current
                 locale for a specific category.

    Other strings use the same format as the user environment variables (see
    environ(M)).

    If the program was compiled in default or -svid mode, then 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. If the program was compiled in -ansi, -posix, or -
    xpg3 mode, then the equivalent of the following call is executed at
    startup:

       setlocale(LC_ALL, "C");

    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
    (that is, (char *)0) as the locale argument.  setlocale() returns 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 pro-
    gram startup, the effect is as if the previous locale was "C".  If the
    failing call was for the category LCALL, 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 LCALL, 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
    restores 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 dis-
    played:

       libc: setlocale: xxxx: no LANG= line in /etc/default/lang

    where xxxx is one of the environment variables found in environ(M).  For
    example, LCCTYPE.

    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, LCCTYPE.

 Notes

    The return values from setlocale() are pointers to static data, the con-
    tent of which is overwritten with each call.

 See also

    strcoll(S), ctime(S), ctype(S), environ(M), locale(M)

 Standards conformance

    setlocale() is conformant with:
    ANSI X3.159-1989 Programming Language -- C;
    IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C
    Language] (ISO/IEC 9945-1);
    and NIST FIPS 151-1.