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
23       referred 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
38       library.
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 EXAMPLE, below.
61
62       Each locale object created by duplocale() should be  deallocated  using
63       freelocale(3).
64

EXAMPLE

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           char *p;
91
92           if (argc != 2) {
93               fprintf(stderr, "Usage: %s string\n", argv[0]);
94               exit(EXIT_FAILURE);
95           }
96
97           /* This sequence is necessary, because uselocale() might return
98              the value LC_GLOBAL_LOCALE, which can't be passed as an
99              argument to toupper_l() */
100
101           loc = uselocale((locale_t) 0);
102           if (loc == (locale_t) 0)
103               errExit("uselocale");
104
105           nloc = duplocale(loc);
106           if (nloc == (locale_t) 0)
107               errExit("duplocale");
108
109           for (p = argv[1]; *p; p++)
110               putchar(toupper_l(*p, nloc));
111
112           printf("\n");
113
114           freelocale(nloc);
115
116           exit(EXIT_SUCCESS);
117       }
118

COLOPHON

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