pd.if.org Git - pdclib.old/blob - man3/posix_locale.3

   1 .\" This file is part of the Public Domain C Library (PDCLib).\r
   2 .\" Permission is granted to use, modify, and / or redistribute at will.\r
   3 .\"\r
   4 .Dd\r
   5 .Dt posix_locale 3\r
   6 .Os\r
   7 .\"\r
   8 .Sh NAME\r
   9 .Nm posix_locale\r
  10 .Nd POSIX extended locale functions\r
  11 .\"\r
  12 .Sh SYNOPSIS\r
  13 .Sy #define _POSIX_C_SOURCE >= 200112L\r
  14 .In locale.h\r
  15 .Vt typedef <anonymous> locale_t;\r
  16 .br\r
  17 #define \r
  18 .Va LC_GLOBAL_LOCALE\r
  19 <constant of type locale_t>;\r
  20 .Fn "locale_t uselocale" "locale_t newlocale"\r
  21 .Fn "locale_t duplocale" "locale_t loc"\r
  22 .Fn "locale_t newlocale" "int category_mask" "const char *locale" "locale_t base"\r
  23 .Fn "void freelocale" "locale_t loc"\r
  24 .\"\r
  25 .Sh DESCRIPTION\r
  26 The ISO C standard defines the\r
  27 .Xr setlocale 3\r
  28 function, which can be used for modifying the application global locale. In \r
  29 multithreaded programs, it can sometimes be useful to allow a thread to, either\r
  30 temporarily or permanently, assume a different locale from the rest of the \r
  31 application. POSIX defines extended locale functions which permit this.\r
  32 .\"\r
  33 .Pp\r
  34 The function\r
  35 .Fn uselocale\r
  36 is used to change the locale of the current thread. If \r
  37 .Fa newlocale\r
  38 is the symbolic constant\r
  39 .Dv LC_GLOBAL_LOCALE ,\r
  40 then the thread locale will be set to the application global locale. If\r
  41 .Fa newlocale\r
  42 is\r
  43 .Dv NULL ,\r
  44 then the locale will not be changed. Otherwise, \r
  45 .Fa newlocale\r
  46 should be a value returned from either of the\r
  47 .Fn newlocale\r
  48 or\r
  49 .Fn duplocale\r
  50 functions. The return value will be the previous thread locale; or \r
  51 .Dv LC_GLOBAL_LOCALE\r
  52 if the thread has no current locale.\r
  53 .Pp\r
  54 .\"\r
  55 The function\r
  56 .Fn duplocale\r
  57 is used to make an exact copy of an existing locale. The passed locale object \r
  58 must have been returned from a call to either\r
  59 .Fn duplocale\r
  60 or\r
  61 .Fn newlocale .\r
  62 .Pp\r
  63 .\"\r
  64 The function\r
  65 .Fn newlocale\r
  66 is used to modify an existing locale or create a new locale. The returned locale\r
  67 will have the properties defined by\r
  68 .Fa category_mask\r
  69 set to the values from\r
  70 .Fa locale\r
  71 as per \r
  72 .Xr setlocale 3 ,\r
  73 with the remainder being taken from either\r
  74 .Fa base\r
  75 (which must be a locale object previously returned by\r
  76 .Fn duplocale\r
  77 or\r
  78 .Fn newlocale )\r
  79 if it is specified, or otherwise from the "C" locale.\r
  80 .Pp\r
  81 It is undefined if \r
  82 .Fn newlocale\r
  83 modifies\r
  84 .Fa base\r
  85 or frees it and creates a new locale.\r
  86 .Pp\r
  87 .\"\r
  88 The \r
  89 .Fn freelocale\r
  90 function is used to free a locale previously created via\r
  91 .Fn duplocale\r
  92 or\r
  93 .Fn newlocale .\r
  94 .\"\r
  95 .\"\r
  96 .Sh ERRORS\r
  97 For uselocale,\r
  98 .Er EINVAL\r
  99 may be returned if\r
 100 .Fa locale\r
 101 is not a valid locale.\r
 102 .Pp\r
 103 .\"\r
 104 For \r
 105 .Fn duplocale ,\r
 106 .Bl -tag -width 8\r
 107 .It Er EINVAL\r
 108 may be returned if\r
 109 .Fa locale\r
 110 is not a valid locale\r
 111 .It Er ENOMEM\r
 112 shall be returned if the system had insufficient memory to satisfy the request.\r
 113 .El\r
 114 .Pp\r
 115 .\"\r
 116 For \r
 117 .Fn newlocale ,\r
 118 .Bl -tag -width 8\r
 119 .It Er EINVAL\r
 120 shall be returned if \r
 121 .Fa category_mask\r
 122 contains a bit which does not correspond to a valid category, and may be \r
 123 returned if\r
 124 .Fa locale\r
 125 is not a valid locale object.\r
 126 .It Er ENOMEM\r
 127 shall be returned if the system did not have enough memory to allocate a new \r
 128 locale object or read the locale data\r
 129 .It Er ENOENT\r
 130 shall be returned if the locale specified does not contain data for all the \r
 131 specified categories\r
 132 .El\r
 133 .Pp\r
 134 .\"\r
 135 .Fn freelocale\r
 136 has no errors\r
 137 .\"\r
 138 .Sh IMPLEMENTATION NOTES\r
 139 None\r
 140 .\"\r
 141 .Sh SEE ALSO\r
 142 .Xr lconv 3\r
 143 .Xr setlocale 3\r
 144 .\"\r
 145 .Sh STANDARDS\r
 146 Conforming to\r
 147 .St -p1003.1-2008 .