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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
XLOCALE(3)	       FreeBSD Library Functions Manual		    XLOCALE(3)

NAME
     xlocale --	Thread-safe extended locale support.

LIBRARY
     Standard C	Library	(libc, -lc)

SYNOPSIS
     #include <xlocale.h>

DESCRIPTION
     The extended locale support includes a set	of functions for setting
     thread-local locales, as well convenience functions for performing
     locale-aware calls	with a specified locale.

     The core of the xlocale API is the	locale_t type.	This is	an opaque type
     encapsulating a locale.  Instances	of this	can be either set as the
     locale for	a specific thread or passed directly to	the _l suffixed	vari-
     ants of various standard C	functions.  Two	special	locale_t values	are
     available:

	   +o   NULL refers to the current locale for the thread, or to the
	       global locale if	no locale has been set for this	thread.

	   +o   LC_GLOBAL_LOCALE	refers to the global locale.

     The global	locale is the locale set with the setlocale(3) function.

CAVEATS
     The setlocale(3) function,	and others in the family, refer	to the global
     locale.  Other functions that depend on the locale, however, will take
     the thread-local locale if	one has	been set.  This	means that the idiom
     of	setting	the locale using setlocale(3), calling a locale-dependent
     function, and then	restoring the locale will not have the expected	behav-
     ior if the	current	thread has had a locale	set using uselocale(3).	 You
     should avoid this idiom and prefer	to use the _l suffixed versions
     instead.

SEE ALSO
     duplocale(3), freelocale(3), localeconv(3), newlocale(3), querylocale(3),
     uselocale(3),

CONVENIENCE FUNCTIONS
     The xlocale API includes a	number of _l suffixed convenience functions.
     These are variants	of standard C functions	that have been modified	to
     take an explicit locale_t parameter as the	final argument or, in the case
     of	variadic functions, as an additional argument directly before the for-
     mat string.  Each of these	functions accepts either NULL or
     LC_GLOBAL_LOCALE.	In these functions, NULL refers	to the C locale,
     rather than the thread's current locale.  If you wish to use the thread's
     current locale, then use the unsuffixed version of	the function.

     These functions are exposed by including <xlocale.h> after	including the
     relevant headers for the standard variant.	 For example, the strtol_l(3)
     function is exposed by including <xlocale.h> after	<stdlib.h>, which
     defines strtol(3).

     For reference, a complete list of the locale-aware	functions that are
     available in this form, along with	the headers that expose	them, is pro-
     vided here:

     <wctype.h>	    iswalnum_l(3), iswalpha_l(3), iswcntrl_l(3),
		    iswctype_l(3), iswdigit_l(3), iswgraph_l(3),
		    iswlower_l(3), iswprint_l(3), iswpunct_l(3),
		    iswspace_l(3), iswupper_l(3), iswxdigit_l(3),
		    towlower_l(3), towupper_l(3), wctype_l(3),

     <ctype.h>	    digittoint_l(3), isalnum_l(3), isalpha_l(3), isblank_l(3),
		    iscntrl_l(3), isdigit_l(3),	isgraph_l(3),
		    ishexnumber_l(3), isideogram_l(3), islower_l(3),
		    isnumber_l(3), isphonogram_l(3), isprint_l(3),
		    ispunct_l(3), isrune_l(3), isspace_l(3), isspecial_l(3),
		    isupper_l(3), isxdigit_l(3), tolower_l(3), toupper_l(3)

     <inttypes.h>   strtoimax_l(3), strtoumax_l(3), wcstoimax_l(3),
		    wcstoumax_l(3)

     <langinfo.h>   nl_langinfo_l(3)

     <monetary.h>   strfmon_l(3)

     <stdio.h>	    asprintf_l(3), fprintf_l(3), fscanf_l(3), printf_l(3),
		    scanf_l(3),	snprintf_l(3), sprintf_l(3), sscanf_l(3),
		    vasprintf_l(3), vfprintf_l(3), vfscanf_l(3), vprintf_l(3),
		    vscanf_l(3), vsnprintf_l(3), vsprintf_l(3),	vsscanf_l(3)

     <stdlib.h>	    atof_l(3), atoi_l(3), atol_l(3), atoll_l(3), mblen_l(3),
		    mbstowcs_l(3), mbtowc_l(3),	strtod_l(3), strtof_l(3),
		    strtol_l(3), strtold_l(3), strtoll_l(3), strtoq_l(3),
		    strtoul_l(3), strtoull_l(3), strtouq_l(3), wcstombs_l(3),
		    wctomb_l(3)

     <string.h>	    strcoll_l(3), strxfrm_l(3),	strcasecmp_l(3),
		    strcasestr_l(3), strncasecmp_l(3)

     <time.h>	    strftime_l(3) strptime_l(3)

     <wchar.h>	    btowc_l(3),	fgetwc_l(3), fgetws_l(3), fputwc_l(3),
		    fputws_l(3), fwprintf_l(3),	fwscanf_l(3), getwc_l(3),
		    getwchar_l(3), mbrlen_l(3),	mbrtowc_l(3), mbsinit_l(3),
		    mbsnrtowcs_l(3), mbsrtowcs_l(3), putwc_l(3),
		    putwchar_l(3), swprintf_l(3), swscanf_l(3),	ungetwc_l(3),
		    vfwprintf_l(3), vfwscanf_l(3), vswprintf_l(3),
		    vswscanf_l(3), vwprintf_l(3), vwscanf_l(3),	wcrtomb_l(3),
		    wcscoll_l(3), wcsftime_l(3), wcsnrtombs_l(3),
		    wcsrtombs_l(3), wcstod_l(3), wcstof_l(3), wcstol_l(3),
		    wcstold_l(3), wcstoll_l(3),	wcstoul_l(3), wcstoull_l(3),
		    wcswidth_l(3), wcsxfrm_l(3), wctob_l(3), wcwidth_l(3),
		    wprintf_l(3), wscanf_l(3)

     <wctype.h>	    iswblank_l(3), iswhexnumber_l(3), iswideogram_l(3),
		    iswnumber_l(3), iswphonogram_l(3), iswrune_l(3),
		    iswspecial_l(3), nextwctype_l(3), towctrans_l(3),
		    wctrans_l(3)

     <xlocale.h>    localeconv_l(3)

STANDARDS
     The functions conform to IEEE Std 1003.1-2008 (``POSIX.1'').

HISTORY
     The xlocale APIs first appeared in	Darwin 8.0.  This implementation was
     written by	David Chisnall,	under sponsorship from the FreeBSD Foundation
     and first appeared	in FreeBSD 9.1.

FreeBSD	9.2		       September 17 2011		   FreeBSD 9.2

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | CAVEATS | SEE ALSO | CONVENIENCE FUNCTIONS | STANDARDS | HISTORY

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=xlocale&sektion=3&manpath=FreeBSD+9.1-RELEASE>

home | help