man3/newlocale.3

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