locale/xlocale.3

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