SETLOCALE(3)                    Domain/OS BSD                     SETLOCALE(3)



NAME
     setlocale - Changes or queries the program's locale

SYNOPSIS
     #include <locale.h>

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

DESCRIPTION
     The setlocale function selects the appropriate portion of the program's
     locale as specified by the category and locale arguments.  The setlocale
     function can be used to change or query the program's entire current
     locale or portions thereof.

     The category argument specifies a value from the locale.h header file
     that names the program's entire locale or a portion thereof. The locale
     argument points to a string defining the locale.

     The LC_ALL value for the category argument names the entire locale; the
     other values name only a portion of the program locale, as follows:

     LC_COLLATE
               Affects the behavior of regular expressions and the string
               collation functions (strcoll and strxfrm); see string(3).

     LC_CTYPE  Affects the behavior of the character conversion and character
               handling functions (except for the isdigit and isxdigit
               functions; see ctype(3)).

     LC_MONETARY
               Affects the monetary formatting information returned by the
               localeconv(3) function.

     LC_NUMERIC
               Affects the radix character for the formatted input/output
               functions and the string conversion functions, as well as the
               nonmonetary formatting information returned by the
               localeconv(3) function.

     LC_TIME   Affects the behavior of the strftime function; see ctime(3)

     The behavior of the language information function defined in the
     nl_langinfo(3C) function is also affected by settings of the category
     argument.

     The locale argument points to a character string containing the required
     setting of the category argument.  The following preset values of locale
     are defined for all settings of category:

     "C"     Specifies the minimal environment for C-language translation.  If
             setlocale is not invoked, the "C" locale is the default.
             Operational behavior within the "C" locale is defined separately
             for each interface function that is affected by the locale
             string.

     ``''    Specifies a native environment, corresponding to the value of the
             associated environment variables.

             In all cases, the setlocale function first checks the value of

             the corresponding environment variable and if valid, setlocale
             sets the specified category of the international environment to
             that value and returns the string corresponding to the locale set
             (that is, the value of the environment variable, not "").  If the
             value is invalid, setlocale returns a null pointer and the
             international environment is not changed by this function call.
             If the environment variable corresponding to the specified
             category is not set or is set to the empty string, and the LANG
             environment variable is set and valid, then setlocale sets the
             category to the corresponding value of LANG. If the LANG
             environment variable is not set, the setlocale function uses a
             system-wide default, and corresponds to the "C" locale.

             To set all categories in the international environment, the
             setlocale function is invoked in the following manner:
                  setlocale (LC_ALL, "");

             To satisfy this request, the setlocale function first checks all
             the environment variables.  If any environment variable is
             invalid, setlocale returns a null pointer and the international
             environment is not changed by this function call.  If all the
             relevant environment variables are valid, setlocale sets the
             international environment to reflect the values of the
             environment variables.  The categories are set in the following
             order:
                  LC_CTYPE
                  LC_COLLATE
                  LC_TIME
                  LC_NUMERIC
                  LC_MONETARY

             Using this scheme, the categories corresponding to the
             environment variables will override the value of the LANG
             environment variable for a particular category.

     NULL    Used to direct setlocale to query the current internationalized
             environment and return the name of the locale.

     "POSIX" Provides the same environment as the "C" locale.

DIAGNOSTICS
     If a pointer to a string is given for the locale argument and the
     selection can be honored, the setlocale function returns the string
     associated with the specified category argument for the new locale.  If
     the selection cannot be honored, a null pointer is returned and the
     program's locale is unchanged.

     A null pointer for the locale argument causes the setlocale function to
     return the string associated with the category argument for the program
     current locale, and the program locale is unchanged.

     The string returned by the setlocale function is such that a subsequent
     call with that string and its associated category restores that part of
     the program locale.  The string returned is not modified by the program,
     but can be overwritten by a subsequent call to the setlocale function.

SEE ALSO
     atof(3), ctype(3), isalpha(3), isascii(3), nl_langinfo(3), printf(3),
     scanf(3), strcat(3), strchr(3), strcmp(3), strcoll(3), strcpy(3),
     strftime(3), strlen(3), strpbrk(3), strtok(3), strtod(3), strxrfm(3),
     <locale.h>, <langinfo.h>