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

FreeBSD Manual Pages


home | help

       setlocale, nl_init - set	international environment

       #include	<locale.h>

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

       int nl_init(lang)
       char *lang;

       setlocale()  selects  the  appropriate piece of the program's locale as
       specified by category, and may be used to change	or query the program's
       international environment.  The entire locale may be changed by calling
       setlocale() with	category set to	LC_ALL.	 The other possible values for
       category	query or change	only a part of the program's complete interna-
       tional locale:

	      Affects the behavior of the character classification and conver-
	      sion functions.  See ctype(3V), and mblen(3).

	      Affects  the  behavior of	the string collation functions strcoll
	      (3) and strxfrm(3V).

	      Affects the behavior of  the  time  conversion  functions.   See
	      printf(3V),  scanf(3V), strtod(3), and ctime(3V) for strftime(),
	      strptime(), and ctime().

	      Affects the radix	character for the formatted input/output func-
	      tions and	the string conversion functions, gcvt(3V), printf(3V),
	      strtod(3),   gconvert(),	  sgconvert()	 (see	 econvert(3)),
	      file_to_decimal(),  and  func_to_decimal()  (see string_to_deci-
	      mal(3)).	Also affects the non-monetary  formatting  information
	      returned by the localeconv() function.

	      Affects  the monetary formatting information returned by the lo-
	      caleconv() function.

	      Affects the behavior of functions	that present messages,	namely
	      gettext(), and textdomain().

       The  locale  argument is	a pointer to a character string	containing the
       required	setting	of category.  The following preset  values  of	locale
       are defined for all settings of category:

       "C"    Specifies	 the minimal environment for C translation.  If	setlo-
	      cale() is	not invoked, the "C" locale is	the  default.	Opera-
	      tional  behavior within the "C" locale is	defined	separately for
	      each interface function.

       At program startup, the equivalent of:

       ""     In this case, setlocale()	will first check the value of the cor-
	      responding  environment  variable	(for example, LC_CTYPE for the
	      LC_CTYPE category) and if	valid (that is,	points to the name  of
	      a	 valid locale),	setlocale() sets the specified category	of the
	      international environment	to that	value and returns  the	string
	      corresponding to the locale set (that is,	the value of the envi-
	      ronment variable,	not "").  If the value is invalid, setlocale()
	      returns  a NULL pointer and the international environment	is not
	      changed by this call.

	      If the environment variable corresponding	to the specified cate-
	      gory  is not set or is set to the	empty string, setlocale() will
	      examine the LANG environment variable.  If both the  LANG	 envi-
	      ronment  variable, and the environment variable corresponding to
	      the specified category are not set  or  are  set	to  the	 empty
	      string,  then  the  LC_default environment variable is examined.
	      If this contains a valid setting,	then the category  is  set  to
	      the  value  of  LC_default.  If the LANG environment variable is
	      set and valid this will set the category	to  the	 corresponding
	      value  of	 LANG.	If LC_default is not set, then setlocale() re-
	      turns that category to the default "C" locale.

       To set all categories in	the international environment, setlocale()  is
       invoked in the following	manner:

	      setlocale	(LC_ALL,  "" );

       To  satisfy this	request, setlocale() first checks all the relevant en-
       vironment variables LC_CTYPE, LC_COLLATE, LC_TIME, LC_NUMERIC, LC_MONE-
       TARY,  LC_MESSAGES.  If any one of these	relevant environment variables
       is invalid, this	call to	setlocale() will return	a  NULL	 pointer,  and
       the international environment will not be changed.  If all the relevant
       environment variables are valid,	setlocale() sets the international en-
       vironment to reflect the	values of the environment variables.  The cat-
       egories are set in the following	order:


       Using this scheme, the  categories  corresponding  to  the  environment
       variables  will	override the value of the LANG and LC_default environ-
       ment variables for a particular category.

       nl_init() is equivalent to

	      setlocale(LC_ALL,	"");

       and is supplied for compatibility with X/Open XPG2.

       If a valid string is given for the locale parameter, and	the  selection
       can  be	honored,  setlocale()  returns	the string associated with the
       specified category for the new locale.  If the selection	cannot be hon-
       ored,  setlocale()  returns  a null pointer and the program's locale is
       not changed.

       A NULL pointer for locale causes	setlocale() to return the string asso-
       ciated  with  the  category  for	the program's current locale; the pro-
       gram's locale is	not changed.  The string contains information relating
       to  each	 piece	part of	the whole international	environment.  This in-
       quiry can fail by returning a null pointer if any category is invalid.

       The string returned by such a setlocale() call is such  that  a	subse-
       quent  call  with  the  string and its associated category will restore
       that part of the	program's locale.  The string returned by:

	      ptr = setlocale(LC_ALL, (char *) 0);

       is such that in a subsequent call:

	      setlocale(LC_ALL,	ptr);

       will reset each and every category to the state	when  the  string  was
       first  returned.	  The string returned must not be modified by the pro-
       gram, but will be overwritten by	a subsequent call to setlocale().

			   locale is  the  directory  that  contains  numerous
			   files (categories), each relating to	a single cate-
			   gory	of a valid locale as selected by category  ar-
			   gument  to  setlocale().  Generally this is classed
			   as a	private	directory.  This directory is searched
			   by setlocale(), prior to searching:
			   locale  is  the  directory  that  contains numerous
			   files (categories), each relating to	a single cate-
			   gory	 of a valid locale as selected by category ar-
			   gument to  setlocale().   Generally	this  data  is
			   classed as global and sharable.

       setlocale()  returns  a null pointer if a relevant environment variable
       has an invalid setting.	setlocale() also returns  a  null  pointer  if
       category	is invalid.

				21 January 1990			 SETLOCALE(3V)


Want to link to this manual page? Use this URL:

home | help