duplocale(3)

1DUPLOCALE(3)               Linux Programmer's Manual              DUPLOCALE(3)
2
3
4

NAME

6       duplocale - duplicate a locale object
7

SYNOPSIS

9       #include <locale.h>
10
11       locale_t duplocale(locale_t locobj);
12
13   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
14
15       duplocale():
16           Since glibc 2.10:
17                  _XOPEN_SOURCE >= 700
18           Before glibc 2.10:
19                  _GNU_SOURCE
20

DESCRIPTION

22       The  duplocale()  function creates a duplicate of the locale object re‐
23       ferred to by locobj.
24
25       If locobj is LC_GLOBAL_LOCALE, duplocale() creates a locale object con‐
26       taining a copy of the global locale determined by setlocale(3).
27

RETURN VALUE

29       On success, duplocale() returns a handle for the new locale object.  On
30       error, it returns (locale_t) 0, and sets errno to indicate the cause of
31       the error.
32

ERRORS

34       ENOMEM Insufficient memory to create the duplicate locale object.
35

VERSIONS

37       The duplocale() function first appeared in version 2.3 of the GNU C li‐
38       brary.
39

CONFORMING TO

41       POSIX.1-2008.
42

NOTES

44       Duplicating a locale can serve the following purposes:
45
46       *  To create a copy of a locale object in which one of more  categories
47          are to be modified (using newlocale(3)).
48
49       *  To  obtain  a  handle for the current locale which can used in other
50          functions that employ a locale handle, such as  toupper_l(3).   This
51          is done by applying duplocale() to the value returned by the follow‐
52          ing call:
53
54              loc = uselocale((locale_t) 0);
55
56          This technique is necessary, because the above uselocale(3) call may
57          return the value LC_GLOBAL_LOCALE, which results in undefined behav‐
58          ior if passed to functions such  as  toupper_l(3).   Calling  duplo‐
59          cale() can be used to ensure that the LC_GLOBAL_LOCALE value is con‐
60          verted into a usable locale object.  See EXAMPLES, below.
61
62       Each locale object created by duplocale() should be  deallocated  using
63       freelocale(3).
64

EXAMPLES

66       The  program below uses uselocale(3) and duplocale() to obtain a handle
67       for the current locale which is then passed to toupper_l(3).  The  pro‐
68       gram  takes  one  command-line argument, a string of characters that is
69       converted to uppercase and displayed on standard output.  An example of
70       its use is the following:
71
72           $ ./a.out abc
73           ABC
74
75   Program source
76
77       #define _XOPEN_SOURCE 700
78       #include <ctype.h>
79       #include <stdio.h>
80       #include <stdlib.h>
81       #include <locale.h>
82
83       #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
84                               } while (0)
85
86       int
87       main(int argc, char *argv[])
88       {
89           locale_t loc, nloc;
90
91           if (argc != 2) {
92               fprintf(stderr, "Usage: %s string\n", argv[0]);
93               exit(EXIT_FAILURE);
94           }
95
96           /* This sequence is necessary, because uselocale() might return
97              the value LC_GLOBAL_LOCALE, which can't be passed as an
98              argument to toupper_l() */
99
100           loc = uselocale((locale_t) 0);
101           if (loc == (locale_t) 0)
102               errExit("uselocale");
103
104           nloc = duplocale(loc);
105           if (nloc == (locale_t) 0)
106               errExit("duplocale");
107
108           for (char *p = argv[1]; *p; p++)
109               putchar(toupper_l(*p, nloc));
110
111           printf("\n");
112
113           freelocale(nloc);
114
115           exit(EXIT_SUCCESS);
116       }
117

COLOPHON

123       This page is part of release 5.10 of the Linux  man-pages  project.   A
124       description  of  the project, information about reporting bugs, and the
125       latest    version    of    this    page,    can     be     found     at
126       https://www.kernel.org/doc/man-pages/.
127
128
129
130Linux                             2020-11-01                      DUPLOCALE(3)