man3/duplocale.3

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