original/man3/duplocale.3

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