man3/duplocale.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 DUPLOCALE 3 2021-03-22 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 duplocale \- duplicate a locale object
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <locale.h>
  31 .PP
  32 .BI "locale_t duplocale(locale_t " locobj );
  33 .fi
  34 .PP
  35 .RS -4
  36 Feature Test Macro Requirements for glibc (see
  37 .BR feature_test_macros (7)):
  38 .RE
  39 .PP
  40 .BR duplocale ():
  41 .nf
  42     Since glibc 2.10:
  43         _XOPEN_SOURCE >= 700
  44     Before glibc 2.10:
  45         _GNU_SOURCE
  46 .fi
  47 .SH DESCRIPTION
  48 The
  49 .BR duplocale ()
  50 function creates a duplicate of the locale object referred to by
  51 .IR locobj .
  52 .PP
  53 If
  54 .I locobj
  55 is
  56 .BR LC_GLOBAL_LOCALE ,
  57 .BR duplocale ()
  58 creates a locale object containing a copy of the global locale
  59 determined by
  60 .BR setlocale (3).
  61 .SH RETURN VALUE
  62 On success,
  63 .BR duplocale ()
  64 returns a handle for the new locale object.
  65 On error, it returns
  66 .IR "(locale_t)\ 0",
  67 and sets
  68 .I errno
  69 to indicate the error.
  70 .SH ERRORS
  71 .TP
  72 .B ENOMEM
  73 Insufficient memory to create the duplicate locale object.
  74 .SH VERSIONS
  75 The
  76 .BR duplocale ()
  77 function first appeared in version 2.3 of the GNU C library.
  78 .SH CONFORMING TO
  79 POSIX.1-2008.
  80 .SH NOTES
  81 Duplicating a locale can serve the following purposes:
  82 .IP * 3
  83 To create a copy of a locale object in which one of more categories
  84 are to be modified (using
  85 .BR newlocale (3)).
  86 .IP *
  87 To obtain a handle for the current locale which can used in
  88 other functions that employ a locale handle, such as
  89 .BR toupper_l (3).
  90 This is done by applying
  91 .BR duplocale ()
  92 to the value returned by the following call:
  93 .IP
  94     loc = uselocale((locale_t) 0);
  95 .IP
  96 This technique is necessary, because the above
  97 .BR uselocale (3)
  98 call may return the value
  99 .BR LC_GLOBAL_LOCALE ,
 100 which results in undefined behavior if passed to functions such as
 101 .BR toupper_l (3).
 102 Calling
 103 .BR duplocale ()
 104 can be used to ensure that the
 105 .BR LC_GLOBAL_LOCALE
 106 value is converted into a usable locale object.
 107 See EXAMPLES, below.
 108 .PP
 109 Each locale object created by
 110 .BR duplocale ()
 111 should be deallocated using
 112 .BR  freelocale (3).
 113 .SH EXAMPLES
 114 The program below uses
 115 .BR uselocale (3)
 116 and
 117 .BR duplocale ()
 118 to obtain a handle for the current locale which is then passed to
 119 .BR toupper_l (3).
 120 The program takes one command-line argument,
 121 a string of characters that is converted to uppercase and
 122 displayed on standard output.
 123 An example of its use is the following:
 124 .PP
 125 .in +4n
 126 .EX
 127 $ \fB./a.out abc\fP
 128 ABC
 129 .EE
 130 .in
 131 .SS Program source
 132 \&
 133 .EX
 134 #define _XOPEN_SOURCE 700
 135 #include <ctype.h>
 136 #include <stdio.h>
 137 #include <stdlib.h>
 138 #include <locale.h>
 139
 140 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 141                         } while (0)
 142
 143 int
 144 main(int argc, char *argv[])
 145 {
 146     locale_t loc, nloc;
 147
 148     if (argc != 2) {
 149         fprintf(stderr, "Usage: %s string\en", argv[0]);
 150         exit(EXIT_FAILURE);
 151     }
 152
 153     /* This sequence is necessary, because uselocale() might return
 154        the value LC_GLOBAL_LOCALE, which can\(aqt be passed as an
 155        argument to toupper_l(). */
 156
 157     loc = uselocale((locale_t) 0);
 158     if (loc == (locale_t) 0)
 159         errExit("uselocale");
 160
 161     nloc = duplocale(loc);
 162     if (nloc == (locale_t) 0)
 163         errExit("duplocale");
 164
 165     for (char *p = argv[1]; *p; p++)
 166         putchar(toupper_l(*p, nloc));
 167
 168     printf("\en");
 169
 170     freelocale(nloc);
 171
 172     exit(EXIT_SUCCESS);
 173 }
 174 .EE
 175 .SH SEE ALSO
 176 .BR freelocale (3),
 177 .BR newlocale (3),
 178 .BR setlocale (3),
 179 .BR uselocale (3),
 180 .BR locale (5),
 181 .BR locale (7)