man3/newlocale.3

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