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

FreeBSD Manual Pages


home | help
setlocale(3C)							 setlocale(3C)

       setlocale - modify and query a program's	locale

       #include	<locale.h>

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

       The setlocale() function	selects	the appropriate	piece of the program's
       locale as specified by the category and locale arguments. The  category
       argument	 may have the following	values:	LC_CTYPE, LC_NUMERIC, LC_TIME,
       LC_COLLATE, LC_MONETARY,	LC_MESSAGES, and LC_ALL. These names  are  de-
       fined in	the <locale.h> header.
	The LC_ALL variable names all of a program's locale categories.

       The  LC_CTYPE variable affects the behavior of character	handling func-
       tions such as isdigit(3C)  and  tolower(3C),  and  multibyte  character
       functions such as  mbtowc(3C) and wctomb(3C).

       The  LC_NUMERIC	variable affects the decimal point character and thou-
       sands separator character for the formatted input/output	functions  and
       string conversion functions.

       The  LC_TIME  variable affects the date and time	format as delivered by
       ascftime(3C) cftime(3C) getdate(3C) strftime(3C)	and strptime(3C)

       The LC_COLLATE variable affects the sort	order  produced	 by  collating
       functions such as strcoll(3C) and strxfrm(3C)

       The LC_MONETARY variable	affects	the monetary formatted information re-
       turned by localeconv(3C).

       The LC_MESSAGES variable	affects	the behavior  of  messaging  functions
       such as dgettext(3C), gettext(3C), and gettxt(3C).

       A  value	of "C" for locale specifies the	traditional UNIX system	behav-
       ior. At program startup,	the equivalent of

	      setlocale(LC_ALL,	"C")

       is executed. This has the effect	of initializing	each category  to  the
       locale described	by the environment "C".

       A value of "" for locale	specifies that the locale should be taken from
       environment variables. The order	in which the environment variables are
       checked for the various categories is given below:

       |Category       | 1st Env Var	|2nd Env Var	 |3rd Env Var	 |
       |LC_CTYPE:      | LC_ALL		|LC_CTYPE	 |LANG		 |
       |LC_COLLATE:    | LC_ALL		|LC_COLLATE	 |LANG		 |
       |LC_TIME:       | LC_ALL		|LC_TIME	 |LANG		 |
       |LC_NUMERIC:    | LC_ALL		|LC_NUMERIC	 |LANG		 |

       If  a  pointer to a string is given for locale, setlocale() attempts to
       set the locale for the given category to	locale.	 If  setlocale()  suc-
       ceeds,  locale is returned. If setlocale() fails, a null	pointer	is re-
       turned and the program's	locale is not changed.

       For category LC_ALL, the	behavior is slightly different.	If  a  pointer
       to  a string is given for locale	and LC_ALL is given for	category, set-
       locale()	attempts to set	the locale for all the categories  to  locale.
       The  locale may be a simple locale, consisting of a single locale, or a
       composite locale. If the	locales	for all	the categories	are  the  same
       after  all  the	attempted  locale  changes,  setlocale() will return a
       pointer to the common simple locale.  If	there is a mixture of  locales
       among the categories, setlocale() will return a composite locale.

       Upon  successful	 completion, setlocale() returns the string associated
       with the	specified category for the new locale. Otherwise,  setlocale()
       returns a null pointer and the program's	locale is not changed.

       A null pointer for locale causes	setlocale() to return a	pointer	to the
       string associated with the category for the program's  current  locale.
       The program's locale is not changed.

       The  string returned by setlocale() is such that	a subsequent call with
       that string and its associated category will restore that part  of  the
       program's  locale. The string returned must not be modified by the pro-
       gram, but may be	overwritten by a subsequent call to setlocale().

       No errors are defined.

       /usr/lib/locale/locale	       locale database directory for locale

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |CSI			     |Enabled			   |
       |Interface Stability	     |Standard			   |
       |MT-Level		     |MT-Safe with exceptions	   |

       locale(1), ctype(3C), getdate(3C) gettext(3C), gettxt(3C), isdigit(3C),
       localeconv(3C),	mbtowc(3C),  strcoll(3C),  strftime(3C),  strptime(3C)
       strxfrm(3C) tolower(3C),	wctomb(3C), libc(3LIB),	 attributes(5),	 envi-
       ron(5), locale(5), standards(5)

       It  is  unsafe  for any thread to change	locale (by calling setlocale()
       with a non-null locale argument)	in a multithreaded  application	 while
       any  other thread in the	application is using any locale-sensitive rou-
       tine. To	change locale  in  a  multithreaded  application,  setlocale()
       should  be  called  prior  to using any locale-sensitive	routine. Using
       setlocale() to query the	current	locale is safe and can	be  used  any-
       where  in  a multithreaded application except when some other thread is
       changing	locale.

       It is the user's	responsibility to ensure that mixed locale  categories
       are  compatible.	 For example, setting LC_CTYPE=C and LC_TIME=ja	(where
       ja indicates Japanese) will not work, because Japanese time  cannot  be
       represented in the "C" locale's ASCII codeset.

				  19 Sep 2005			 setlocale(3C)


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

home | help