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

FreeBSD Manual Pages


home | help
setlocale(3C)		 Standard C Library Functions		 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_CTIME:      | LC_ALL		|LC_CTIME	 |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.

	     locale database directory for locale

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

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

       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)

       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 anywhere in a  mul-
       tithreaded application.

       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 can-
       not be represented in the "C" locale's ASCII codeset.

       Internationalization functions by setlocale() are supported  only  when
       the  dynamic  linking version of	libc has been linked with the applica-
       tion. If	the static linking version of libc has been  linked  with  the
       application, setlocale()	can handle only	C and POSIX locales.

SunOS 5.9			  20 Dec 1996			 setlocale(3C)


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

home | help