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 error.
31

ERRORS

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

VERSIONS

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

CONFORMING TO

40       POSIX.1-2008.
41

NOTES

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

EXAMPLES

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

COLOPHON

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