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