man3/newlocale.3

   1 .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH NEWLOCALE 3 2021-03-22 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 newlocale, freelocale \- create, modify, and free a locale object
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <locale.h>
  31 .PP
  32 .BI "locale_t newlocale(int " category_mask ", const char *" locale ,
  33 .BI "                   locale_t " base );
  34 .BI "void freelocale(locale_t " locobj );
  35 .fi
  36 .PP
  37 .RS -4
  38 Feature Test Macro Requirements for glibc (see
  39 .BR feature_test_macros (7)):
  40 .RE
  41 .PP
  42 .BR newlocale (),
  43 .BR freelocale ():
  44 .nf
  45     Since glibc 2.10:
  46         _XOPEN_SOURCE >= 700
  47     Before glibc 2.10:
  48         _GNU_SOURCE
  49 .fi
  50 .SH DESCRIPTION
  51 The
  52 .BR newlocale ()
  53 function creates a new locale object, or modifies an existing object,
  54 returning a reference to the new or modified object as the function result.
  55 Whether the call creates a new object or modifies an existing object
  56 is determined by the value of
  57 .IR base :
  58 .IP * 3
  59 If
  60 .I base
  61 is
  62 .IR "(locale_t)\ 0" ,
  63 a new object is created.
  64 .IP *
  65 If
  66 .I base
  67 refers to valid existing locale object
  68 (i.e., an object returned by a previous call to
  69 .BR newlocale ()
  70 or
  71 .BR duplocale (3)),
  72 then that object is modified by the call.
  73 If the call is successful, the contents of
  74 .I base
  75 are unspecified (in particular, the object referred to by
  76 .I base
  77 may be freed, and a new object created).
  78 Therefore, the caller should ensure that it stops using
  79 .I base
  80 before the call to
  81 .BR newlocale (),
  82 and should subsequently refer to the modified object via the
  83 reference returned as the function result.
  84 If the call fails, the contents of
  85 .I base
  86 remain valid and unchanged.
  87 .PP
  88 If
  89 .I base
  90 is the special locale object
  91 .BR LC_GLOBAL_LOCALE
  92 (see
  93 .BR duplocale (3)),
  94 or is not
  95 .IR "(locale_t)\ 0"
  96 and is not a valid locale object handle,
  97 the behavior is undefined.
  98 .PP
  99 The
 100 .I category_mask
 101 argument is a bit mask that specifies the locale categories
 102 that are to be set in a newly created locale object
 103 or modified in an existing object.
 104 The mask is constructed by a bitwise OR of the constants
 105 .BR LC_ADDRESS_MASK ,
 106 .BR LC_CTYPE_MASK ,
 107 .BR LC_COLLATE_MASK ,
 108 .BR LC_IDENTIFICATION_MASK ,
 109 .BR LC_MEASUREMENT_MASK ,
 110 .BR LC_MESSAGES_MASK ,
 111 .BR LC_MONETARY_MASK ,
 112 .BR LC_NUMERIC_MASK ,
 113 .BR LC_NAME_MASK ,
 114 .BR LC_PAPER_MASK ,
 115 .BR LC_TELEPHONE_MASK ,
 116 and
 117 .BR LC_TIME_MASK .
 118 Alternatively, the mask can be specified as
 119 .BR LC_ALL_MASK ,
 120 which is equivalent to ORing all of the preceding constants.
 121 .PP
 122 For each category specified in
 123 .IR category_mask ,
 124 the locale data from
 125 .I locale
 126 will be used in the object returned by
 127 .BR newlocale ().
 128 If a new locale object is being created,
 129 data for all categories not specified in
 130 .IR category_mask
 131 is taken from the default ("POSIX") locale.
 132 .PP
 133 The following preset values of
 134 .I locale
 135 are defined for all categories that can be specified in
 136 .IR category_mask :
 137 .TP
 138 "POSIX"
 139 A minimal locale environment for C language programs.
 140 .TP
 141 "C"
 142 Equivalent to "POSIX".
 143 .TP
 144 ""
 145 An implementation-defined native environment
 146 corresponding to the values of the
 147 .BR LC_*
 148 and
 149 .B LANG
 150 environment variables (see
 151 .BR locale (7)).
 152 .SS freelocale()
 153 The
 154 .BR freelocale ()
 155 function deallocates the resources associated with
 156 .IR locobj ,
 157 a locale object previously returned by a call to
 158 .BR newlocale ()
 159 or
 160 .BR duplocale (3).
 161 If
 162 .I locobj
 163 is
 164 .BR LC_GLOBAL_LOCALE
 165 or is not valid locale object handle, the results are undefined.
 166 .PP
 167 Once a locale object has been freed,
 168 the program should make no further use of it.
 169 .SH RETURN VALUE
 170 On success,
 171 .BR newlocale ()
 172 returns a handle that can be used in calls to
 173 .BR duplocale (3),
 174 .BR freelocale (),
 175 and other functions that take a
 176 .I locale_t
 177 argument.
 178 On error,
 179 .BR newlocale ()
 180 returns
 181 .IR "(locale_t)\ 0",
 182 and sets
 183 .I errno
 184 to indicate the error.
 185 .SH ERRORS
 186 .TP
 187 .B EINVAL
 188 One or more bits in
 189 .I category_mask
 190 do not correspond to a valid locale category.
 191 .TP
 192 .B EINVAL
 193 .I locale
 194 is NULL.
 195 .TP
 196 .B ENOENT
 197 .I locale
 198 is not a string pointer referring to a valid locale.
 199 .TP
 200 .B ENOMEM
 201 Insufficient memory to create a locale object.
 202 .SH VERSIONS
 203 The
 204 .BR newlocale ()
 205 and
 206 .BR freelocale ()
 207 functions first appeared in version 2.3 of the GNU C library.
 208 .SH CONFORMING TO
 209 POSIX.1-2008.
 210 .SH NOTES
 211 Each locale object created by
 212 .BR newlocale ()
 213 should be deallocated using
 214 .BR freelocale ().
 215 .SH EXAMPLES
 216 The program below takes up to two command-line arguments,
 217 which each identify locales.
 218 The first argument is required, and is used to set the
 219 .B LC_NUMERIC
 220 category in a locale object created using
 221 .BR newlocale ().
 222 The second command-line argument is optional;
 223 if it is present, it is used to set the
 224 .B LC_TIME
 225 category of the locale object.
 226 .PP
 227 Having created and initialized the locale object,
 228 the program then applies it using
 229 .BR uselocale (3),
 230 and then tests the effect of the locale changes by:
 231 .IP 1. 3
 232 Displaying a floating-point number with a fractional part.
 233 This output will be affected by the
 234 .B LC_NUMERIC
 235 setting.
 236 In many European-language locales,
 237 the fractional part of the number is separated from the integer part
 238 using a comma, rather than a period.
 239 .IP 2.
 240 Displaying the date.
 241 The format and language of the output will be affected by the
 242 .B LC_TIME
 243 setting.
 244 .PP
 245 The following shell sessions show some example runs of this program.
 246 .PP
 247 Set the
 248 .B LC_NUMERIC
 249 category to
 250 .IR fr_FR
 251 (French):
 252 .PP
 253 .in +4n
 254 .EX
 255 $ \fB./a.out fr_FR\fP
 256 123456,789
 257 Fri Mar  7 00:25:08 2014
 258 .EE
 259 .in
 260 .PP
 261 Set the
 262 .B LC_NUMERIC
 263 category to
 264 .IR fr_FR
 265 (French),
 266 and the
 267 .B LC_TIME
 268 category to
 269 .IR it_IT
 270 (Italian):
 271 .PP
 272 .in +4n
 273 .EX
 274 $ \fB./a.out fr_FR it_IT\fP
 275 123456,789
 276 ven 07 mar 2014 00:26:01 CET
 277 .EE
 278 .in
 279 .PP
 280 Specify the
 281 .B LC_TIME
 282 setting as an empty string,
 283 which causes the value to be taken from environment variable settings
 284 (which, here, specify
 285 .IR mi_NZ ,
 286 New Zealand Māori):
 287 .PP
 288 .in +4n
 289 .EX
 290 $ LC_ALL=mi_NZ ./a.out fr_FR ""
 291 123456,789
 292 Te Paraire, te 07 o Poutū\-te\-rangi, 2014 00:38:44 CET
 293 .EE
 294 .in
 295 .SS Program source
 296 .EX
 297 #define _XOPEN_SOURCE 700
 298 #include <stdio.h>
 299 #include <stdlib.h>
 300 #include <locale.h>
 301 #include <time.h>
 302
 303 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 304                         } while (0)
 305
 306 int
 307 main(int argc, char *argv[])
 308 {
 309     char buf[100];
 310     time_t t;
 311     size_t s;
 312     struct tm *tm;
 313     locale_t loc, nloc;
 314
 315     if (argc < 2) {
 316         fprintf(stderr, "Usage: %s locale1 [locale2]\en", argv[0]);
 317         exit(EXIT_FAILURE);
 318     }
 319
 320     /* Create a new locale object, taking the LC_NUMERIC settings
 321        from the locale specified in argv[1]. */
 322
 323     loc = newlocale(LC_NUMERIC_MASK, argv[1], (locale_t) 0);
 324     if (loc == (locale_t) 0)
 325         errExit("newlocale");
 326
 327     /* If a second command\-line argument was specified, modify the
 328        locale object to take the LC_TIME settings from the locale
 329        specified in argv[2]. We assign the result of this newlocale()
 330        call to \(aqnloc\(aq rather than \(aqloc\(aq, since in some cases, we might
 331        want to preserve \(aqloc\(aq if this call fails. */
 332
 333     if (argc > 2) {
 334         nloc = newlocale(LC_TIME_MASK, argv[2], loc);
 335         if (nloc == (locale_t) 0)
 336             errExit("newlocale");
 337         loc = nloc;
 338     }
 339
 340     /* Apply the newly created locale to this thread. */
 341
 342     uselocale(loc);
 343
 344     /* Test effect of LC_NUMERIC. */
 345
 346     printf("%8.3f\en", 123456.789);
 347
 348     /* Test effect of LC_TIME. */
 349
 350     t = time(NULL);
 351     tm = localtime(&t);
 352     if (tm == NULL)
 353         errExit("time");
 354
 355     s = strftime(buf, sizeof(buf), "%c", tm);
 356     if (s == 0)
 357         errExit("strftime");
 358
 359     printf("%s\en", buf);
 360
 361     /* Free the locale object. */
 362
 363     uselocale(LC_GLOBAL_HANDLE);    /* So \(aqloc\(aq is no longer in use */
 364     freelocale(loc);
 365
 366     exit(EXIT_SUCCESS);
 367 }
 368 .EE
 369 .SH SEE ALSO
 370 .BR locale (1),
 371 .BR duplocale (3),
 372 .BR setlocale (3),
 373 .BR uselocale (3),
 374 .BR locale (5),
 375 .BR locale (7)