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)