1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright (c) 2014 Joyent, Inc.  All rights reserved.
  13 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  14 .\"
  15 .Dd "Jul 23, 2014"
  16 .Dt NEWLOCALE 3C
  17 .Os
  18 .Sh NAME
  19 .Nm duplocale ,
  20 .Nm freelocale ,
  21 .Nm newlocale
  22 .Nd create, duplicate, and destroy locale objects
  23 .Sh SYNOPSIS
  24 .In locale.h
  25 .
  26 .Ft locale_t
  27 .Fo newlocale
  28 .Fa "int category_mask"
  29 .Fa "const char *locale"
  30 .Fa "locale_t base"
  31 .Fc
  32 .
  33 .Ft locale_t
  34 .Fo duplocale
  35 .Fa "locale_t loc"
  36 .Fc
  37 .
  38 .Ft void
  39 .Fo freelocale
  40 .Fa "locale_t loc"
  41 .Fc
  42 .Sh DESCRIPTION
  43 These functions manipulate locale objects that can be used with
  44 .Xr uselocale 3C
  45 and functions that take arguments of type
  46 .Vt locale_t .
  47 .Lp
  48 The
  49 .Fn newlocale
  50 function
  51 can be used to create a new locale object. It can also be used to modify an
  52 existing locale object; the new locale object will be a replacement for the
  53 modified locale object. To create a new locale, the argument
  54 .Fa base
  55 should be passed the special argument
  56 .Po Vt locale_t Pc 0.
  57 This will use a copy of the current global locale as a starting point. To modify
  58 an existing locale object, it should be passed in as the argument
  59 .Fa base .
  60 The new locale object is constructed by taking the categories specified in
  61 .Fa category_mask
  62 from the locale specified by the string
  63 .Fa locale ,
  64 and filling in the remaining categories from the locale
  65 .Fa base .
  66 When
  67 .Fn newlocale
  68 returns, callers must no longer use
  69 .Fa base .
  70 They should assume that
  71 .Fn freelocale
  72 has been called on it.
  73 .Lp
  74 In addition to locales defined on the system, the
  75 following three locales may always be passed in as the string
  76 .Fa locale :
  77 .Bl -tag -offset indent -width Dq
  78 .It \\"C\\"
  79 Specifies the traditional UNIX system behavior.
  80 .It \\"POSIX\\"
  81 An alternate name fo the locale "C".
  82 .It \\"\\"
  83 Indicates that the locale should be processed based in the values in the
  84 environment. See
  85 .Xr setlocale 3C
  86 and
  87 .Xr environ 5
  88 for more information.
  89 .El
  90 .Lp
  91 The value of
  92 .Fa category_mask
  93 is a bitwise-inclusive or of the following macros which correspond to categories
  94 as defined in
  95 .Xr locale 5
  96 and
  97 .Xr environ 5 :
  98 .Bl -tag -offset indent -width Dv
  99 .It Dv LC_CTYPE_MASK
 100 Character classification and case conversion.
 101 .It Dv LC_NUMERIC_MASK
 102 Numeric formatting.
 103 .It Dv LC_TIME_MASK
 104 Date and time formatting.
 105 .It Dv LC_COLLATE_MASK
 106 Collation order.
 107 .It Dv LC_MONETARY_MASK
 108 Monetary formatting.
 109 .It Dv LC_MESSAGES_MASK
 110 Formats of informative and diagnostic messages and interactive responses.
 111 .It Dv LC_ALL_MASK
 112 Mask of all categories.
 113 .El
 114 .Lp
 115 The
 116 .Fn duplocale
 117 function duplicates the locale object specified by
 118 .Fa loc .
 119 If the locale object passed is
 120 .Dv LC_GLOBAL_LOCALE ,
 121 .Fn duplocale
 122 creates a copy of the current global locale as defined through calls to
 123 .Xr setlocale 3C .
 124 .Lp
 125 The
 126 .Fn freelocale
 127 function removes and releases all resources associated with the locale object
 128 .Fa loc .
 129 Programs must not call
 130 .Fn freelocale
 131 on
 132 .Dv LC_GLOBAL_LOCALE .
 133 .Sh RETURN VALUES
 134 On success, the functions
 135 .Fn newlocale
 136 and
 137 .Fn duplocale
 138 return a new locale object that can be used with functions that take a
 139 .Vt locale_t .
 140 Locale objects created this way should be freed with
 141 .Fn freelocale .
 142 On error, the functions
 143 .Fn newlocale
 144 and
 145 .Fn duplocale
 146 return
 147 .Po Vt locale_t Pc 0
 148 and
 149 .Va errno
 150 is set to indicate the error. The
 151 .Fn freelocale
 152 function does not set
 153 .Va errno .
 154 .Sh ERRORS
 155 The
 156 .Fn newlocale
 157 and
 158 .Fn duplocale
 159 functions will fail if:
 160 .Bl -tag -width Er
 161 .It Er ENOMEM
 162 Insufficient memory was available to create the locale object or to load the
 163 requested locale data.
 164 .El
 165 .Lp
 166 The
 167 .Fn newlocale
 168 function will fail if:
 169 .Bl -tag -width Er
 170 .It Er EINVAL
 171 An unknown bit is specified in
 172 .Fa category_mask .
 173 .It Er ENOENT
 174 Locale data was not found for a category specified in
 175 .Fa category_mask .
 176 .El
 177 .Sh INTERFACE STABILITY
 178 .Sy Standard .
 179 .Sh MT-LEVEL
 180 .Sy MT-Safe .
 181 .Sh SEE ALSO
 182 .Xr locale 1 ,
 183 .Xr setlocale 3C ,
 184 .Xr uselocale 3C ,
 185 .Xr locale.h 3HEAD  ,
 186 .Xr environ 5 ,
 187 .Xr locale 5
 188 .Sh STANDARDS
 189 The
 190 .Fn newlocale ,
 191 .Fn duplocale ,
 192 and
 193 .Fn freelocale
 194 functions were introduced in
 195 .St -p1003.1-2008 .