setlocale(3C)						   Standard C Library Functions 					     setlocale(3C)

NAME

       setlocale - modify and query a program's locale

SYNOPSIS

       #include <locale.h>

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

DESCRIPTION

       The setlocale() function selects the appropriate piece of the program's locale as specified by the category and locale arguments. The cate-
       gory 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.  The LC_ALL variable names all of a program's locale categories.

       The  LC_CTYPE  variable	affects  the behavior of character handling functions such as isdigit(3C) and tolower(3C), and multibyte character
       functions such as  mbtowc(3C) and wctomb(3C).

       The LC_NUMERIC variable affects the decimal point character and thousands separator character for the formatted input/output functions  and
       string conversion functions.

       The  LC_TIME  variable  affects	the  date  and	time format as delivered by ascftime(3C), cftime(3C), getdate(3C), strftime(3C), and strp-
       time(3C).

       The LC_COLLATE variable affects the sort order produced by collating functions such as strcoll(3C) and strxfrm(3C).

       The LC_MONETARY variable affects the monetary formatted information returned by localeconv(3C).

       The LC_MESSAGES variable affects the behavior of messaging functions such as dgettext(3C), gettext(3C), and gettxt(3C).

       A value of "C" for locale specifies the traditional UNIX system behavior. 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".

       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	 | 3rd Env Var	 |
       +---------------+----------------+----------------+---------------+
       |LC_CTYPE:      | LC_ALL 	| LC_CTYPE	 |LANG		 |
       +---------------+----------------+----------------+---------------+
       |LC_COLLATE:    | LC_ALL 	| LC_COLLATE	 |LANG		 |
       +---------------+----------------+----------------+---------------+
       |LC_TIME:       | LC_ALL 	| LC_TIME	 |LANG		 |
       +---------------+----------------+----------------+---------------+
       |LC_NUMERIC:    | LC_ALL 	| LC_NUMERIC	 |LANG		 |
       +---------------+----------------+----------------+---------------+
       |LC_MONETARY:   | LC_ALL 	| LC_MONETARY	 |LANG		 |
       +---------------+----------------+----------------+---------------+
       |LC_MESSAGES:   | LC_ALL 	| LC_MESSAGES	 |LANG		 |
       +---------------+----------------+----------------+---------------+

       If  a pointer to a string is given for locale, setlocale() attempts to set the locale for the given category to locale. If setlocale() suc-
       ceeds, 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. If the locales for all the categories are the same after all the attempted locale changes, setlocale() will return a
       pointer to the common simple locale. If there is a mixture of locales among the categories, setlocale() will return a composite locale.

RETURN VALUES

       Upon  successful  completion,  setlocale()  returns the string associated with the specified category for the new locale. Otherwise, setlo-
       cale() returns a null pointer and the program's locale is not changed.

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

       The  string  returned  by setlocale() is such that a subsequent call with that string and its associated category will restore that part of
       the program's locale. The string returned must not be modified by the program, but may be overwritten by a subsequent call to setlocale().

ERRORS

       No errors are defined.

FILES

       /usr/lib/locale/locale	 locale database directory for locale

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |CSI			     |Enabled			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe with exceptions	   |
       +-----------------------------+-----------------------------+

SEE ALSO

       locale(1), ctype(3C), getdate(3C) gettext(3C), gettxt(3C), isdigit(3C), libc(3LIB), localeconv(3C), mbtowc(3C), strcoll(3C),  strftime(3C),
       strptime(3C) strxfrm(3C) tolower(3C), wctomb(3C), attributes(5), environ(5), locale(5), standards(5)

NOTES

       It  is unsafe for any thread to change locale (by calling setlocale() with a non-null locale argument) in a multithreaded application while
       any other thread in the application is using any locale-sensitive routine. To change locale in  a  multithreaded  application,  setlocale()
       should  be  called  prior to using any locale-sensitive routine. Using setlocale() to query the current locale is safe and can be used any-
       where in a multithreaded application except when some other thread is changing locale.

       It is the user's responsibility to ensure that mixed locale categories are compatible.  For  example,  setting  LC_CTYPE=C  and	LC_TIME=ja
       (where ja indicates Japanese) will not work, because Japanese time cannot be represented in the "C" locale's ASCII codeset.

SunOS 5.11							    19 Sep 2005 						     setlocale(3C)