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

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