setlocale(3C)															     setlocale(3C)

NAME

       setlocale(), getlocale() - set and get the locale of a program

SYNOPSIS

   Obsolescent Interfaces
DESCRIPTION

       The  function  sets,  queries, or restores the aspect of a program's locale that is specified by the category argument.	A program's locale
       refers to those areas of the program's Native Language Support (NLS) environment for which the  following  values  of  category	have  been
       defined:

	      Affects behavior of all categories below, as well as all
				  nl_langinfo(3C) items.

	      Affects behavior of regular expressions and the NLS
				  string collation functions (see string(3C), and regexp(5)).

	      Affects behavior of regular expressions, character classification,
				  and  conversion  functions  (see  ctype(3C), wctype(3C), wconv(3C), conv(3C), and regexp(5)).  The category also
				  affects the behavior of all routines that process multibyte characters (see multibyte(3C)).

	      Affects the language in which messages are displayed and the
				  processing of affirmative and negative responses (see catopen(3C) and nl_langinfo(3C)).

	      Affects behavior of functions that handle monetary values (see
				  localeconv(3C) and strfmon(3C)).

	      Affects handling of the radix character in the formatted
				  input/output functions (see printf(3S), scanf(3S) and vprintf(3S)) and  the  string  conversion  functions  (see
				  ecvt(3C) and strtod(3C)).  also affects the numeric values found in the localeconv structure.

	      Affects the behavior of time conversion functions (see
				  getdate(3C), strftime(3C), and strptime(3C)).

       All nl_langinfo(3C) items are affected by the setting of one of the categories listed above.  See langinfo(5) to determine which categories
       affect each item.

       The value of the locale argument determines the action taken by locale is a pointer to a character string.

       Note that while can be called concurrently from multiple threads, the locale data structures that get updated  are  not	protected  against
       reads by other threads.	Hence it is up to the application developer to ensure proper synchronization when changing locales.

   Setting the Locale of a Program
       To  set	the program's locale for category, accepts one of the following values as the locale argument: locale name, or (the empty string).
       The actions prescribed by these values are as follows:

	      locale name	  If locale is a valid locale name (see lang(5)), sets that part of the NLS environment associated  with  category
				  as defined for that locale.

	      If the value of	  locale  is  set to sets that part of the NLS environment associated with category as defined for the locale (see
				  lang(5)).  The locale is the default prior to successfully calling

	      Same as

	      If the value of	  locale is the empty string, the setting of that part of the NLS environment  associated  with  category  depends
				  upon the setting of the following environment variables in the user's environment (see environ(5)):

				  If  category	is  any  defined value other than sets that category as specified by the value of the environment.
				  This is also the case if is not set to the corresponding environment variable.  If the environment  variable	is
				  not  set or is set to the empty string, sets the category as specified by the value of the environment variable.
				  If is not set or is set to the empty string, then sets the category to the locale.  For example,

				  sets the program's NLS environment associated with the category to the value specified by the user's environment
				  variable.  All other aspects of the NLS environment are unaffected.

				  If category is then all categories are set corresponding to the value of if is set, or if is not set, except for
				  those categories in which the corresponding environment variable is set to a valid language name (see  lang(5)).
				  In this case the value of the environment variable overrides the values of and for that category.  If the values
				  of both and are not set or are set to the empty string, then the locale is used.

				  The following usage of results in the program's locale being set according to the user's language requirements:

   Querying the Locale of a Program
       queries the current NLS environment pertaining to category, if the value of locale is NULL.  The query operation does not change the  envi-
       ronment.   The  purpose of performing a query is to save that aspect of the user's current NLS environment associated with category, in the
       value returned by such that it can be restored with a subsequent call to

   Restoring the Locale of a Program
       To restore a category within the program locale, a call is made with the same category argument and the return string of the previous  call
       given as the locale argument.

       returns a pointer to a structure (see The members of the structure contain information about the setting of each category.  type determines
       what information is contained in the structure.	The only supported value of type is:

	      The structure member corresponding to each category contains a string
				    with the name of the locale currently set for that category.  The string does not  include	modifier  informa-
				    tion.

   Obsolescent Interfaces
       and set and get the locale of a program..

RETURN VALUE

       If  the	pointer  to a string is given for locale and the selection can be honored, the function returns a pointer to the string associated
       with the specified category for the new locale.	The maximum length of this string is bytes (see If the selection cannot  be  honored,  the
       function returns a null pointer and the program's locale is not changed.

       A null pointer for locale causes to return a string associated with the category for the program's current locale.

       The  string  returned  by  is such that a subsequent call with that string as the locale argument and its associated category restores that
       part of the program's locale.

ERRORS

       If a language name given through the locale argument does not identify a valid language name, or if the language  name  is  more  than  256
       characters,  or	if  the language is not available on the system (see lang(5)), then a null pointer is returned and the program's locale is
       not changed.  The same behavior occurs when the call:

       is made and any category related environment variable in the user's environment identifies an invalid language name or a language  that	is
       not available on the system.

       If the category argument is not a defined category value, a null pointer is returned and the program's locale is not changed.

       returns	a  string that reflects the current setting of that aspect of the NLS environment corresponding to the category argument.  If this
       return string is used in a subsequent call and the category arguments of the two calls do not match, the locale	remains  unchanged  and  a
       null pointer is returned.

EXAMPLES

       To set a program's entire locale based on the language requirements specified via the user's environment variables:

       If in the example the user's environment variables were set as follows:

       the and category items would be set to correspond to the language definition, the category items would be set to correspond to the language
       definition for collation and the category items would be set corresponding to the language definition.

       Using the same example, if the following call was made:

       the contents of would be:

       The next example shows the precedence of the environment variable:

       with the following settings in the user's environment:

       All categories will be loaded with

       Another example showing the precedence of the environment variable:

       with the following settings in the user's environment:

       All categories will be loaded with

       Another example with the environment variable:

       with the following settings in the user's environment:

       The category will be set to but all other categories will be set to

       To set the date/time formats to

       To set the collating sequence to the locale:

       To set monetary handling to the value of the user's environment variable:

       Note that if the environment variable is not set or is empty, the value of the user's environment variable is used.

       To query a user's locale:

       To restore the locale saved in the above example:

       To query only the part of the user's locale pertaining to the category:

       To restore the category of the user's locale saved in the above example:

WARNINGS

       The format of the return string from is implementation specific, is not standardized across vendor's platforms, and is subject to change in
       future  releases.   The return string is valid only for the life of the process invoking the and should only be used for restoring a previ-
       ously stored locale setting within the same process.

       Using as the locale argument is not recommended.  An example of such incorrect usage is:

       returns a character string which can be a language name, an empty string, or a null pointer; depending on the setting of the  user's  envi-
       ronment	variable.   Each  of  these  values  as  the locale argument define a specific action to be taken by Therefore the action taken by
       depends upon the value returned from the call.  To ensure that sets the program's locale based upon the setting of the  user's  environment
       variables the following usage is recommended:

       The  value  returned  by points to an area that is overwritten during the next call to Be sure to copy these values to another area if they
       are to be used after a subsequent call.

       is an HP proprietary interface, which will be in a future release, and is not portable to other vendor's platforms.

       The structure returned through a call to is overwritten during the next call to Be sure to save these values if they are to be used after a
       subsequent call.

       It should be noted that the locale state is common to  all threads within a process.

       and are obsolescent interfaces supported for compatibility with existing DCE applications. New multithreaded applications should use and

       Any  program  that calls before with the oflag parameter set to may behave differently in this release than in previous releases because of
       the addition of to In the past, was directed to the desired language by Now, with the oflag parameter set to is controlled  by  can  modify
       the category.  For example, if the environment variables are set as follows:

       and the following call to is made:

       followed by a call to then will open the message catalogs for rather than

       If you use and compile/link your application archive on PA-RISC systems, please note that has a dependency on that will require a change to
       the compile/link command.

       Compile:

       Or compile with and

       The option is positionally dependent and should occur at the beginning of the compile line.  For optimum compatibility in future  releases,
       avoid using archive with other shared libraries except for as needed above.

AUTHOR

       and were developed by OSF and HP.

FILES

SEE ALSO

       locale(1),  localedef(1M), conv(3C), ctype(3C), ecvt(3C), getdate(3C), multibyte(3C), nl_langinfo(3C), regcomp(3C), string(3C), perror(3C),
       strfmon(3C), strftime(3C), string(3C), strptime(3C), strtod(3C), wcsftime(3C), wcstring(3C), printf(3S), scanf(3S), vprintf(3S), wconv(3C),
       wctype(3C), wcstod(3C), wcstol(3C), environ(5), lang(5), langinfo(5), thread_safety(5).

STANDARDS CONFORMANCE

																     setlocale(3C)