Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 lo-
       cale 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  de-
       fined:

	      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  classifica-
	      tion,
				  and conversion functions (see	ctype(3C), wc-
				  type(3C),  wconv(3C),	 conv(3C),  and	  reg-
				  exp(5)).   The category also affects the be-
				  havior of all	routines that  process	multi-
				  byte characters (see multibyte(3C)).

	      Affects the language in which messages are displayed and the
				  processing  of  affirmative and negative re-
				  sponses  (see	  catopen(3C)	and   nl_lang-
				  info(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 str-
				  tod(3C)).  also affects the  numeric	values
				  found	in the localeconv structure.

	      Affects the behavior of time conversion functions	(see
				  getdate(3C),	  strftime(3C),	   and	 strp-
				  time(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 en-
       sure 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 environ-
				  ment 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  de-
				  fined	for the	locale (see lang(5)).  The lo-
				  cale 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  environ-
				  ment	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  associ-
				  ated	with  the category to the value	speci-
				  fied 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 vari-
				  able is set to a valid  language  name  (see
				  lang(5)).  In	this case the value of the en-
				  vironment 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 pro-
				  gram's locale	being set according to the 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 con-
       tain  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 information.

   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 charac-
       ters,  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 en-
       vironment 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 defi-
       nition, the category items would	be set to correspond to	 the  language
       definition  for	collation  and	the category items would be set	corre-
       sponding	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	 vari-
       able:

       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	 exam-
       ple:

WARNINGS
       The format of the return	string from is implementation specific,	is not
       standardized across vendor's platforms, and is subject to change	in fu-
       ture  releases.	 The  return  string is	valid only for the life	of the
       process invoking	the and	should only be used for	restoring a previously
       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  pro-
       gram's  locale  based  upon the setting of the user's environment vari-
       ables 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.

       call does not support usage of  obsoleted  9.x  HP  proprietary	locale
       names  for which	support	was removed in 10.0 release of HP-UX.  Use the
       new ISO locale names (listed in the Release Notes).

       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	exist-
       ing DCE applications. New multithreaded applications should use and

       Any  program  that calls	before with the	oflag parameter	set to may be-
       have 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 fol-
       lows:

       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, please note that
       has a dependency	on that	will require a change to the compile/link com-
       mand.

       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),	 wcsf-
       time(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 COMPLIANCE
								 setlocale(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | WARNINGS | AUTHOR | FILES | SEE ALSO | STANDARDS COMPLIANCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=setlocale&sektion=3c&manpath=HP-UX+11.22>

home | help