setlocale man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

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  classifica‐
	      tion,
				  and  conversion  functions  (see  ctype(3C),
				  wctype(3C), wconv(3C),  conv(3C),  and  reg‐
				  exp(5)).   The  category  also  affects  the
				  behavior 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
				  responses  (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
       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 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
				  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  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
				  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 pro‐
				  gram'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 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
       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 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
       future  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.

       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
       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 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 on PA-RISC sys‐
       tems, 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),	 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 CONFORMANCE
								 setlocale(3C)
[top]

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net