share/man/man3c/newlocale.3c

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