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 (date) "Linux man-pages (unreleased)"
   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 were added in glibc 2.3.
  61 .SH STANDARDS
  62 POSIX.1-2008.
  63 .SH NOTES
  64 Duplicating a locale can serve the following purposes:
  65 .IP \[bu] 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 \[bu]
  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 .\" SRC BEGIN (duplocale.c)
 121 .EX
 122 #define _XOPEN_SOURCE 700
 123 #include <ctype.h>
 124 #include <locale.h>
 125 #include <stdio.h>
 126 #include <stdlib.h>
 127
 128 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 129                         } while (0)
 130
 131 int
 132 main(int argc, char *argv[])
 133 {
 134     locale_t loc, nloc;
 135
 136     if (argc != 2) {
 137         fprintf(stderr, "Usage: %s string\en", argv[0]);
 138         exit(EXIT_FAILURE);
 139     }
 140
 141     /* This sequence is necessary, because uselocale() might return
 142        the value LC_GLOBAL_LOCALE, which can\[aq]t be passed as an
 143        argument to toupper_l(). */
 144
 145     loc = uselocale((locale_t) 0);
 146     if (loc == (locale_t) 0)
 147         errExit("uselocale");
 148
 149     nloc = duplocale(loc);
 150     if (nloc == (locale_t) 0)
 151         errExit("duplocale");
 152
 153     for (char *p = argv[1]; *p; p++)
 154         putchar(toupper_l(*p, nloc));
 155
 156     printf("\en");
 157
 158     freelocale(nloc);
 159
 160     exit(EXIT_SUCCESS);
 161 }
 162 .EE
 163 .\" SRC END
 164 .SH SEE ALSO
 165 .BR freelocale (3),
 166 .BR newlocale (3),
 167 .BR setlocale (3),
 168 .BR uselocale (3),
 169 .BR locale (5),
 170 .BR locale (7)