original/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 2014-03-12 "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
  33 .BI "locale_t newlocale(int " category_mask ", const char *" locale ",
  34 .BI "                   locale_t " base );
  35
  36 .BI "void freelocale(locale_t " locobj );
  37 .fi
  38 .sp
  39 .in -4n
  40 Feature Test Macro Requirements for glibc (see
  41 .BR feature_test_macros (7)):
  42 .in
  43 .sp
  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
 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_CTYPE_MASK ,
 112 .BR LC_COLLATE_MASK ,
 113 .BR LC_MESSAGES_MASK ,
 114 .BR LC_MONETARY_MASK ,
 115 .BR LC_NUMERIC_MASK ,
 116 and
 117 .BR LC_TIME_MASK .
 118
 119 For each category specified in
 120 .IR category_mask ,
 121 the locale data from
 122 .I locale
 123 will be used in the object returned by
 124 .BR newlocale ().
 125 If a new locale object is being created,
 126 data for all categories not specified in
 127 .IR category_mask
 128 is taken from the default ("POSIX") locale.
 129
 130 The following preset values of
 131 .I locale
 132 are defined for all categories that can be specified in
 133 .IR category_mask :
 134 .TP
 135 "POSIX"
 136 A minimal locale environment for C language programs.
 137 .TP
 138 "C"
 139 Equivalent to "POSIX".
 140 .TP
 141 ""
 142 An implementation-defined native environment
 143 corresponding to the values of the
 144 .BR LC_*
 145 and
 146 .B LANG
 147 environment variables (see
 148 .BR locale (7)).
 149 .SS freelocale()
 150 The
 151 .BR freelocale ()
 152 function deallocates the resources associated with
 153 .IR locobj ,
 154 a locale object previously returned by a call to
 155 .BR newlocale ()
 156 or
 157 .BR duplocale (3).
 158 If
 159 .I locobj
 160 is
 161 .BR LC_GLOBAL_LOCALE
 162 or is not valid locale object handle, the results are undefined.
 163
 164 Once a locale object has been freed,
 165 the program should make no further use of it.
 166 .SH RETURN VALUE
 167 On success,
 168 .BR newlocale ()
 169 returns a handle that can be used in calls to
 170 .BR duplocale (3),
 171 .BR freelocale (),
 172 and other functions that take a
 173 .I locale_t
 174 argument.
 175 On error,
 176 .BR newlocale ()
 177 returns
 178 .IR "(locale_t)\ 0",
 179 and sets
 180 .I errno
 181 to indicate the cause of the error.
 182 .SH ERRORS
 183 .TP
 184 .B EINVAL
 185 One or more bits in
 186 .I category_mask
 187 do not correspond to a valid locale category.
 188 .TP
 189 .B EINVAL
 190 .I locale
 191 is NULL.
 192 .TP
 193 .B ENOENT
 194 .I locale
 195 is not a string pointer referring to a valid locale.
 196 .TP
 197 .B ENOMEM
 198 Insufficient memory to create a locale object.
 199 .SH VERSIONS
 200 The
 201 .BR newlocale ()
 202 and
 203 .BR freelocale ()
 204 functions first appeared in version 2.3 of the GNU C library.
 205 .SH CONFORMING TO
 206 POSIX.1-2008.
 207 .SH NOTES
 208 Each locale object created by
 209 .BR newlocale ()
 210 should be deallocated using
 211 .BR freelocale (3).
 212 .SH EXAMPLE
 213 The program below takes up to two command-line arguments,
 214 which each identify locales.
 215 The first argument is required, and is used to set the
 216 .B LC_NUMERIC
 217 category in a locale object created using
 218 .BR newlocale ().
 219 The second command-line argument is optional;
 220 if it is present, it is used to set the
 221 .B LC_TIME
 222 category of the locale object.
 223
 224 Having created and initialized the locale object,
 225 the program then applies it using
 226 .BR uselocale (3),
 227 and then tests the effect of the locale changes by:
 228 .IP 1. 3
 229 Displaying a floating-point number with a fractional part.
 230 This output will be affected by the
 231 .B LC_NUMERIC
 232 setting.
 233 In many European-language locales,
 234 the fractional part of the number is separated from the integer part
 235 using a comma, rather than a period.
 236 .IP 2.
 237 Displaying the date.
 238 The format and language of the output will be affected by the
 239 .B LC_TIME
 240 setting.
 241
 242 .PP
 243 The following shell sessions show some example runs of this program.
 244
 245 Set the
 246 .B LC_NUMERIC
 247 category to
 248 .IR fr_FR
 249 (French):
 250 .in +4n
 251 .nf
 252
 253 $ \fB./a.out fr_FR\fP
 254 123456,789
 255 Fri Mar  7 00:25:08 2014
 256 .fi
 257 .in
 258
 259 Set the
 260 .B LC_NUMERIC
 261 category to
 262 .IR fr_FR
 263 (French),
 264 and the
 265 .B LC_TIME
 266 category to
 267 .IR it_IT
 268 (Italian):
 269 .in +4n
 270 .nf
 271
 272 $ \fB./a.out fr_FR it_IT\fP
 273 123456,789
 274 ven 07 mar 2014 00:26:01 CET
 275 .fi
 276 .in
 277
 278 Specify the
 279 .B LC_TIME
 280 setting as an empty string,
 281 which causes the value to be taken from environment variable settings
 282 (which, here, specify
 283 .IR mi_NZ ,
 284 New Zealand Māori):
 285 .in +4n
 286 .nf
 287
 288 $ LC_ALL=mi_NZ ./a.out fr_FR ""
 289 123456,789
 290 Te Paraire, te 07 o Poutū-te-rangi, 2014 00:38:44 CET
 291 .fi
 292 .SS Program source
 293 .nf
 294 #define _XOPEN_SOURCE 700
 295 #include <stdio.h>
 296 #include <stdlib.h>
 297 #include <locale.h>
 298 #include <time.h>
 299
 300 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \\
 301                         } while (0)
 302
 303 int
 304 main(int argc, char *argv[])
 305 {
 306     char buf[100];
 307     time_t t;
 308     size_t s;
 309     struct tm *tm;
 310     locale_t loc, nloc;
 311
 312     if (argc < 2) {
 313         fprintf(stderr, "Usage: %s locale1 [locale2]\\n", argv[0]);
 314         exit(EXIT_FAILURE);
 315     }
 316
 317     /* Create a new locale object, taking the LC_NUMERIC settings
 318        from the locale specified in argv[1] */
 319
 320     loc = newlocale(LC_NUMERIC_MASK, argv[1], (locale_t) 0);
 321     if (loc == (locale_t) 0)
 322         errExit("newlocale");
 323
 324     /* If a second command\-line argument was specified, modify the
 325        locale object to take the LC_TIME settings from the locale
 326        specified in argv[2]. We assign the result of this newlocale()
 327        call to 'nloc' rather than 'loc', since in some cases, we might
 328        want to preserve 'loc' if this call fails. */
 329
 330     if (argc > 2) {
 331         nloc = newlocale(LC_TIME_MASK, argv[2], loc);
 332         if (nloc == (locale_t) 0)
 333             errExit("newlocale");
 334         loc = nloc;
 335     }
 336
 337     /* Apply the newly created locale to this thread */
 338
 339     uselocale(loc);
 340
 341     /* Test effect of LC_NUMERIC */
 342
 343     printf("%8.3f\\n", 123456.789);
 344
 345     /* Test effect of LC_TIME */
 346
 347     t = time(NULL);
 348     tm = localtime(&t);
 349     if (tm == NULL)
 350         errExit("time");
 351
 352     s = strftime(buf, sizeof(buf), "%c", tm);
 353     if (s == 0)
 354         errExit("strftime");
 355
 356     printf("%s\\n", buf);
 357
 358     /* Free the locale object */
 359
 360     freelocale(loc);
 361
 362     exit(EXIT_SUCCESS);
 363 }
 364 .fi
 365 .SH SEE ALSO
 366 .BR locale (1),
 367 .BR duplocale (3),
 368 .BR setlocale (3),
 369 .BR uselocale (3),
 370 .BR locale (5),
 371 .BR locale (7)
 372 .SH COLOPHON
 373 This page is part of release 3.67 of the Linux
 374 .I man-pages
 375 project.
 376 A description of the project,
 377 information about reporting bugs,
 378 and the latest version of this page,
 379 can be found at
 380 \%http://www.kernel.org/doc/man\-pages/.