1.\" Copyright (c) 2011 The FreeBSD Foundation 2.\" 3.\" This documentation was written by David Chisnall under sponsorship from 4.\" the FreeBSD Foundation. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd September 17, 2011 30.Dt XLOCALE 3 31.Os 32.Sh NAME 33.Nm xlocale 34.Nd Thread-safe extended locale support 35.Sh LIBRARY 36.Lb libc 37.Sh SYNOPSIS 38.In xlocale.h 39.Sh DESCRIPTION 40The extended locale support includes a set of functions for setting 41thread-local locales, 42as well convenience functions for performing locale-aware 43calls with a specified locale. 44.Pp 45The core of the xlocale API is the 46.Fa locale_t 47type. 48This is an opaque type encapsulating a locale. 49Instances of this can be either set as the locale for a specific thread or 50passed directly to the 51.Fa _l 52suffixed variants of various standard C functions. 53Two special 54.Fa locale_t 55values are available: 56.Bl -bullet -offset indent 57.It 58NULL refers to the current locale for the thread, 59or to the global locale if no locale has been set for this thread. 60.It 61LC_GLOBAL_LOCALE refers to the global locale. 62.El 63.Pp 64The global locale is the locale set with the 65.Xr setlocale 3 66function. 67.Sh SEE ALSO 68.Xr duplocale 3 , 69.Xr freelocale 3 , 70.Xr localeconv 3 , 71.Xr newlocale 3 , 72.Xr querylocale 3 , 73.Xr uselocale 3 74.Sh CONVENIENCE FUNCTIONS 75The xlocale API includes a number of 76.Fa _l 77suffixed convenience functions. 78These are variants of standard C functions 79that have been modified to take an explicit 80.Fa locale_t 81parameter as the final argument or, in the case of variadic functions, 82as an additional argument directly before the format string. 83Each of these functions accepts either NULL or LC_GLOBAL_LOCALE. 84In these functions, NULL refers to the C locale, 85rather than the thread's current locale. 86If you wish to use the thread's current locale, 87then use the unsuffixed version of the function. 88.Pp 89These functions are exposed by including 90.In xlocale.h 91.Em after 92including the relevant headers for the standard variant. 93For example, the 94.Xr strtol_l 3 95function is exposed by including 96.In xlocale.h 97after 98.In stdlib.h , 99which defines 100.Xr strtol 3 . 101.Pp 102For reference, 103a complete list of the locale-aware functions that are available in this form, 104along with the headers that expose them, is provided here: 105.Bl -tag -width "<monetary.h> " 106.It In wctype.h 107.Xr iswalnum_l 3 , 108.Xr iswalpha_l 3 , 109.Xr iswcntrl_l 3 , 110.Xr iswctype_l 3 , 111.Xr iswdigit_l 3 , 112.Xr iswgraph_l 3 , 113.Xr iswlower_l 3 , 114.Xr iswprint_l 3 , 115.Xr iswpunct_l 3 , 116.Xr iswspace_l 3 , 117.Xr iswupper_l 3 , 118.Xr iswxdigit_l 3 , 119.Xr towlower_l 3 , 120.Xr towupper_l 3 , 121.Xr wctype_l 3 , 122.It In ctype.h 123.Xr digittoint_l 3 , 124.Xr isalnum_l 3 , 125.Xr isalpha_l 3 , 126.Xr isblank_l 3 , 127.Xr iscntrl_l 3 , 128.Xr isdigit_l 3 , 129.Xr isgraph_l 3 , 130.Xr ishexnumber_l 3 , 131.Xr isideogram_l 3 , 132.Xr islower_l 3 , 133.Xr isnumber_l 3 , 134.Xr isphonogram_l 3 , 135.Xr isprint_l 3 , 136.Xr ispunct_l 3 , 137.Xr isrune_l 3 , 138.Xr isspace_l 3 , 139.Xr isspecial_l 3 , 140.Xr isupper_l 3 , 141.Xr isxdigit_l 3 , 142.Xr tolower_l 3 , 143.Xr toupper_l 3 144.It In inttypes.h 145.Xr strtoimax_l 3 , 146.Xr strtoumax_l 3 , 147.Xr wcstoimax_l 3 , 148.Xr wcstoumax_l 3 149.It In langinfo.h 150.Xr nl_langinfo_l 3 151.It In monetary.h 152.Xr strfmon_l 3 153.It In stdio.h 154.Xr asprintf_l 3 , 155.Xr fprintf_l 3 , 156.Xr fscanf_l 3 , 157.Xr printf_l 3 , 158.Xr scanf_l 3 , 159.Xr snprintf_l 3 , 160.Xr sprintf_l 3 , 161.Xr sscanf_l 3 , 162.Xr vasprintf_l 3 , 163.Xr vfprintf_l 3 , 164.Xr vfscanf_l 3 , 165.Xr vprintf_l 3 , 166.Xr vscanf_l 3 , 167.Xr vsnprintf_l 3 , 168.Xr vsprintf_l 3 , 169.Xr vsscanf_l 3 170.It In stdlib.h 171.Xr atof_l 3 , 172.Xr atoi_l 3 , 173.Xr atol_l 3 , 174.Xr atoll_l 3 , 175.Xr mblen_l 3 , 176.Xr mbstowcs_l 3 , 177.Xr mbtowc_l 3 , 178.Xr strtod_l 3 , 179.Xr strtof_l 3 , 180.Xr strtol_l 3 , 181.Xr strtold_l 3 , 182.Xr strtoll_l 3 , 183.Xr strtoq_l 3 , 184.Xr strtoul_l 3 , 185.Xr strtoull_l 3 , 186.Xr strtouq_l 3 , 187.Xr wcstombs_l 3 , 188.Xr wctomb_l 3 189.It In string.h 190.Xr strcoll_l 3 , 191.Xr strxfrm_l 3 , 192.Xr strcasecmp_l 3 , 193.Xr strcasestr_l 3 , 194.Xr strncasecmp_l 3 195.It In time.h 196.Xr strftime_l 3 197.Xr strptime_l 3 198.It In wchar.h 199.Xr btowc_l 3 , 200.Xr fgetwc_l 3 , 201.Xr fgetws_l 3 , 202.Xr fputwc_l 3 , 203.Xr fputws_l 3 , 204.Xr fwprintf_l 3 , 205.Xr fwscanf_l 3 , 206.Xr getwc_l 3 , 207.Xr getwchar_l 3 , 208.Xr mbrlen_l 3 , 209.Xr mbrtowc_l 3 , 210.Xr mbsinit_l 3 , 211.Xr mbsnrtowcs_l 3 , 212.Xr mbsrtowcs_l 3 , 213.Xr putwc_l 3 , 214.Xr putwchar_l 3 , 215.Xr swprintf_l 3 , 216.Xr swscanf_l 3 , 217.Xr ungetwc_l 3 , 218.Xr vfwprintf_l 3 , 219.Xr vfwscanf_l 3 , 220.Xr vswprintf_l 3 , 221.Xr vswscanf_l 3 , 222.Xr vwprintf_l 3 , 223.Xr vwscanf_l 3 , 224.Xr wcrtomb_l 3 , 225.Xr wcscoll_l 3 , 226.Xr wcsftime_l 3 , 227.Xr wcsnrtombs_l 3 , 228.Xr wcsrtombs_l 3 , 229.Xr wcstod_l 3 , 230.Xr wcstof_l 3 , 231.Xr wcstol_l 3 , 232.Xr wcstold_l 3 , 233.Xr wcstoll_l 3 , 234.Xr wcstoul_l 3 , 235.Xr wcstoull_l 3 , 236.Xr wcswidth_l 3 , 237.Xr wcsxfrm_l 3 , 238.Xr wctob_l 3 , 239.Xr wcwidth_l 3 , 240.Xr wprintf_l 3 , 241.Xr wscanf_l 3 242.It In wctype.h 243.Xr iswblank_l 3 , 244.Xr iswhexnumber_l 3 , 245.Xr iswideogram_l 3 , 246.Xr iswnumber_l 3 , 247.Xr iswphonogram_l 3 , 248.Xr iswrune_l 3 , 249.Xr iswspecial_l 3 , 250.Xr nextwctype_l 3 , 251.Xr towctrans_l 3 , 252.Xr wctrans_l 3 253.It In xlocale.h 254.Xr localeconv_l 3 255.El 256.Sh STANDARDS 257The functions 258conform to 259.St -p1003.1-2008 . 260.Sh HISTORY 261The xlocale APIs first appeared in Darwin 8.0. 262This implementation was written by David Chisnall, 263under sponsorship from the FreeBSD Foundation and first appeared in 264.Fx 9.1 . 265.Sh CAVEATS 266The 267.Xr setlocale 3 268function, and others in the family, refer to the global locale. 269Other functions that depend on the locale, however, 270will take the thread-local locale if one has been set. 271This means that the idiom of setting the locale using 272.Xr setlocale 3 , 273calling a locale-dependent function, 274and then restoring the locale will not 275have the expected behavior if the current thread has had a locale set using 276.Xr uselocale 3 . 277You should avoid this idiom and prefer to use the 278.Fa _l 279suffixed versions instead. 280