setlocale(3)						     Library Functions Manual						      setlocale(3)

NAME

       setlocale - Changes or queries the program's current locale

LIBRARY

       Standard C Library (libc)

SYNOPSIS

       #include <locale.h>

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

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       setlocale(): XSH5.0

       Refer to the standards(5) reference page for more information about industry standards and associated tags.

PARAMETERS

       Specifies  the  category  of  the  locale  to  set  or  query.  The category can be LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY,
       LC_NUMERIC, or LC_TIME.	Points to a string that specifies the locale.

DESCRIPTION

       The setlocale() function sets or queries the appropriate portion of the program's locale as specified by the category  and  locale  parame-
       ters.   The LC_ALL value for the category parameter names the entire locale; the other values name only a portion of the program locale, as
       follows: Affects the behavior of collation functions and regular expressions.  Affects the behavior of character classification	functions,
       character  conversion  functions, and regular expressions.  Affects the language used to display application program and utilities messages
       (when translations of the messages are available) and the strings expected as affirmative and negative responses.  Affects the behavior	of
       functions  that	handle	monetary  values.   Affects the radix character for the formatted input/output functions and the string conversion
       functions.  Affects the behavior of the time conversion functions.

       The behavior of the language information function defined in the nl_langinfo() function is also affected by settings of the category param-
       eter.

       The  locale parameter points to a character string that identifies the locale that is to be used to set the category parameter.	The locale
       parameter can specify either the name of a locale, such as fr_CA.ISO8859-1, or one of the following: Sets the  locale  to  be  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.	 Equivalent  to  C.   Specifies  that  the
       locale should be set based on the user's current values for the locale environment variables.  Queries the program's current locale setting
       and returns the name of the locale; does not change the current setting.

       If the locale parameter is set to the empty string (""), setlocale() checks the user's environment variables in the following order:  First
       it  checks  the value of the LC_ALL environment variable.  If it is set, setlocale() sets the specified category of the international envi-
       ronment to that value and returns the string corresponding to the locale set (that is, the value of the environment variable, not  "",  the
       null string).  If the environment variable LC_ALL is not set or is set to the empty string, setlocale() next checks the corresponding envi-
       ronment variable for the category specified.  If the environment variable for the category is set, setlocale() sets the specified  category
       of  the	international environment to that value.  If the environment variable corresponding to the specified category is not set or is set
       to the empty string, then setlocale() checks the LANG environment variable.  If the LANG environment variable is set, then setlocale() sets
       the  category  to  the locale specified by the LANG environment variable.  Lastly, if the LANG environment variable is not set or is set to
       the empty string, the setlocale() function sets the category to the POSIX (C) locale.

       If the locale parameter is a pointer to NULL, the setlocale() function returns the name of the program's current locale for  the  specified
       category but does not change the locale.

       If  the locale specified by the locale parameter or by the environment variable is invalid, setlocale() returns a null pointer and does not
       change the program's locale.

EXAMPLES

       The following example sets all categories in the international environment based on the user's environment variables:

	      (void)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 rel-
	      evant environment variables are valid, setlocale() sets the international environment to reflect the values of the environment vari-
	      ables.  The following example sets a specific category in the international environment to an explicit locale.

	      (void)setlocale(LC_MESSAGES,"fr_FR.ISO8859-1");  The following subroutine queries and saves the current program locale, then explic-
	      itly sets the locale to the C locale, performs some operations in the C locale, and finally, restores the locale to one  saved.  The
	      main  program  typically	uses setlocale() to set the program's locale to the one specified by the user's environment. However, if a
	      subroutine needs to execute in a specific locale, the subroutine must save and later restore the setting made by the main program.

	      #include <locale.h> #include <string.h>

	      void Do_stuff(void) {	 char *test_l, *saved_l;

		   test_l=setlocale(LC_ALL,NULL);      saved_l=strdup(test_l);

		   test_l=setlocale(LC_ALL,"C");      /* Perform operations in the C locale */

		   /* Restore the original locale */	  test_l=setlocale(LC_ALL,saved_l);	 return; }

NOTES

       There is only one locale per process and the locale state is common to all threads within that process.	A threaded application should call
       setlocale() in the main part of the application before any threads are created.

       If  a  call  to	setlocale() changes the setting of the LC_MESSAGES category, this operation has no effect on any message catalogs that are
       currently open.

RETURN VALUES

       If the setlocale() function succeeds in setting the program's locale to the one specified by the locale parameter, the function returns the
       string  associated  with  the  specified category parameter for the new locale.	Note that the locale parameter can specify the locale name
       explicitly or, if locale is an empty string, the locale is specified by the value of the corresponding environment variable.  If the setlo-
       cale()  function  cannot  set  the  program's  locale  as  requested,  the  function returns a null pointer and leaves the program's locale
       unchanged.

       If the category parameter has a value of LC_ALL, the return value is a series of locale names separated by spaces. The locale names  corre-
       spond to the categories in the following order: LC_COLLATE LC_CTYPE LC_MONETARY LC_NUMERIC LC_TIME LC_MESSAGES

       If  the locale parameter is a null pointer, the setlocale() function returns the string associated with the category parameter for the pro-
       gram's current locale, and leaves the program's locale 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's locale.  The string returned must not be modified by the program, but is overwritten by a subsequent call to the set-
       locale() function.

RELATED INFORMATION

       Functions: atof(3), catclose(3), catgets(3), catopen(3), ctype(3), localeconv(3), nl_langinfo(3), printf(3),  scanf(3),	strfmon(3),  strf-
       time(3), string(3), wctype(3), wprintf(3), wscanf(3)

       Files: locale(4)

       Others: i18n_intro(5), l10n_intro(5), standards(5)

       Writing Software for the International Market delim off

																      setlocale(3)