1.Dd March 11, 2005 2.Dt XLOCALE 3 3.Os 4.Sh NAME 5.Nm xlocale 6.Nd Extended locale support. 7.Sh LIBRARY 8.Lb libc 9.Sh DESCRIPTION 10Include 11.Aq xlocale.h 12for extended locale support. 13It can be used alone or with the POSIX locale API in 14.Aq locale.h . 15.Pp 16The extended locale, or "xlocale" API consists of five basic routines, 17which are documented separately: 18.Xr duplocale 3 , 19.Xr freelocale 3 , 20.Xr newlocale 3 , 21.Xr querylocale 3 , 22and 23.Xr uselocale 3 . 24For each of these routines, if a NULL 25.Vt locale_t 26is given, the current locale is used. 27.Pp 28In addition, 29.Aq xlocale.h 30defines a few macros: 31.Pp 32.Bl -dash 33.It 34LC_GLOBAL_LOCALE - A special 35.Vt locale_t 36value that corresponds to the global, process-wide locale. 37.It 38MB_CUR_MAX - This macro is traditionally defined as an integer 39containing the value of the longest multi-byte string 40that a single-wide character in the global locale can translate into. 41With extended locales, this macro is replaced with a function 42that returns the value of the longest multi-byte string 43that a single-wide character in the current locale (per-thread or global) 44can translate into. 45.It 46MB_CUR_MAX_L(loc) - This macro is equivalent to MB_CUR_MAX, 47except that it may be passed a specific locale directly. 48.El 49.Sh CAVEATS 50The POSIX 51.Xr setlocale 3 52function only affects the global locale, 53so using it when a per-thread locale is in effect 54will not change locale behavior for that thread. 55However, it will change behavior for threads 56with no per-thread locale in effect. 57#ifdef UNIFDEF_LEGACY_RUNE_APIS 58.Pp 59The routines defined in 60.Aq rune.h 61are deprecated, and may not be fully consistent with the xlocale API. 62Of particular note is 63.Fn setinvalidrune , 64which would normally modify the value in the global locale. 65Since this value resides in a sub-structure of 66.Vt locale_t 67and sub-structures may be shared by multiple locales, 68.Fn setinvalidrune 69has been modified to make a copy of the sub-structure. 70This prevents it from affecting other locales. 71#endif /* UNIFDEF_LEGACY_RUNE_APIS */ 72.Sh SEE ALSO 73.Xr duplocale 3 , 74.Xr freelocale 3 , 75.Xr localeconv 3 , 76.Xr newlocale 3 , 77.Xr querylocale 3 , 78.Xr uselocale 3 79.Sh CONVENIENCE FUNCTIONS 80The xlocale API also includes "convenience functions": 81functions that can be executed using a given locale, 82rather than the current locale. 83These functions all take one extra 84.Vt locale_t 85argument at the end of the traditional argument list, 86except in the case of variable-argument functions, 87in which case the extra argument comes before the format string. 88If a NULL 89.Vt locale_t 90is passed, the C locale will be used. 91.Pp 92For completeness, 93the convenience functions are listed here 94(organized by the header file that contains the original function). 95.Pp 96.Bl -tag -width monetary.h 97.It Aq _wctype.h 98.Xr iswalnum_l 3 , 99.Xr iswalpha_l 3 , 100.Xr iswcntrl_l 3 , 101.Xr iswctype_l 3 , 102.Xr iswdigit_l 3 , 103.Xr iswgraph_l 3 , 104.Xr iswlower_l 3 , 105.Xr iswprint_l 3 , 106.Xr iswpunct_l 3 , 107.Xr iswspace_l 3 , 108.Xr iswupper_l 3 , 109.Xr iswxdigit_l 3 , 110.Xr towlower_l 3 , 111.Xr towupper_l 3 , 112.Xr wctype_l 3 113.It Aq ctype.h 114.Xr digittoint_l 3 , 115.Xr isalnum_l 3 , 116.Xr isalpha_l 3 , 117.Xr isblank_l 3 , 118.Xr iscntrl_l 3 , 119.Xr isdigit_l 3 , 120.Xr isgraph_l 3 , 121.Xr ishexnumber_l 3 , 122.Xr isideogram_l 3 , 123.Xr islower_l 3 , 124.Xr isnumber_l 3 , 125.Xr isphonogram_l 3 , 126.Xr isprint_l 3 , 127.Xr ispunct_l 3 , 128.Xr isrune_l 3 , 129.Xr isspace_l 3 , 130.Xr isspecial_l 3 , 131.Xr isupper_l 3 , 132.Xr isxdigit_l 3 , 133.Xr tolower_l 3 , 134.Xr toupper_l 3 135.It Aq inttypes.h 136.Xr strtoimax_l 3 , 137.Xr strtoumax_l 3 , 138.Xr wcstoimax_l 3 , 139.Xr wcstoumax_l 3 140.It Aq langinfo.h 141.Xr nl_langinfo_l 3 142.It Aq monetary.h 143.Xr strfmon_l 3 144.It Aq stdio.h 145.Xr asprintf_l 3 , 146.Xr fprintf_l 3 , 147.Xr fscanf_l 3 , 148.Xr printf_l 3 , 149.Xr scanf_l 3 , 150.Xr snprintf_l 3 , 151.Xr sprintf_l 3 , 152.Xr sscanf_l 3 , 153.Xr vasprintf_l 3 , 154.Xr vfprintf_l 3 , 155.Xr vfscanf_l 3 , 156.Xr vprintf_l 3 , 157.Xr vscanf_l 3 , 158.Xr vsnprintf_l 3 , 159.Xr vsprintf_l 3 , 160.Xr vsscanf_l 3 161.It Aq stdlib.h 162.Xr atof_l 3 , 163.Xr atoi_l 3 , 164.Xr atol_l 3 , 165.Xr atoll_l 3 , 166.Xr mblen_l 3 , 167.Xr mbstowcs_l 3 , 168.Xr mbtowc_l 3 , 169.Xr strtod_l 3 , 170.Xr strtof_l 3 , 171.Xr strtol_l 3 , 172.Xr strtold_l 3 , 173.Xr strtoll_l 3 , 174.Xr strtoq_l 3 , 175.Xr strtoul_l 3 , 176.Xr strtoull_l 3 , 177.Xr strtouq_l 3 , 178.Xr wcstombs_l 3 , 179.Xr wctomb_l 3 180.It Aq string.h 181.Xr strcoll_l 3 , 182.Xr strxfrm_l 3 , 183.Xr strcasecmp_l 3 , 184.Xr strcasestr_l 3 , 185.Xr strncasecmp_l 3 186.It Aq time.h 187.Xr strftime_l 3 , 188.Xr strptime_l 3 189.It Aq wchar.h 190.Xr btowc_l 3 , 191.Xr fgetwc_l 3 , 192.Xr *fgetws_l 3 , 193.Xr fputwc_l 3 , 194.Xr fputws_l 3 , 195.Xr fwprintf_l 3 , 196.Xr fwscanf_l 3 , 197.Xr getwc_l 3 , 198.Xr getwchar_l 3 , 199.Xr mbrlen_l 3 , 200.Xr mbrtowc_l 3 , 201.Xr mbsinit_l 3 , 202.Xr mbsnrtowcs_l 3 , 203.Xr mbsrtowcs_l 3 , 204.Xr putwc_l 3 , 205.Xr putwchar_l 3 , 206.Xr swprintf_l 3 , 207.Xr swscanf_l 3 , 208.Xr ungetwc_l 3 , 209.Xr vfwprintf_l 3 , 210.Xr vfwscanf_l 3 , 211.Xr vswprintf_l 3 , 212.Xr vswscanf_l 3 , 213.Xr vwprintf_l 3 , 214.Xr vwscanf_l 3 , 215.Xr wcrtomb_l 3 , 216.Xr wcscoll_l 3 , 217.Xr wcsftime_l 3 , 218.Xr wcsnrtombs_l 3 , 219.Xr wcsrtombs_l 3 , 220.Xr wcstod_l 3 , 221.Xr wcstof_l 3 , 222.Xr wcstol_l 3 , 223.Xr wcstold_l 3 , 224.Xr wcstoll_l 3 , 225.Xr wcstoul_l 3 , 226.Xr wcstoull_l 3 , 227.Xr wcswidth_l 3 , 228.Xr wcsxfrm_l 3 , 229.Xr wctob_l 3 , 230.Xr wcwidth_l 3 , 231.Xr wprintf_l 3 , 232.Xr wscanf_l 3 233.It Aq wctype.h 234.Xr iswblank_l 3 , 235.Xr iswhexnumber_l 3 , 236.Xr iswideogram_l 3 , 237.Xr iswnumber_l 3 , 238.Xr iswphonogram_l 3 , 239.Xr iswrune_l 3 , 240.Xr iswspecial_l 3 , 241.Xr nextwctype_l 3 , 242.Xr towctrans_l 3 , 243.Xr wctrans_l 3 244.It Aq xlocale.h 245.Xr localeconv_l 3 246.El 247