duplocale(3)

1duplocale(3)               Library Functions Manual               duplocale(3)
2
3
4

NAME

6       duplocale - duplicate a locale object
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

32       On success, duplocale() returns a handle for the new locale object.  On
33       error, it returns (locale_t) 0, and sets errno to indicate the error.
34

ERRORS

36       ENOMEM Insufficient memory to create the duplicate locale object.
37

STANDARDS

39       POSIX.1-2008.
40

HISTORY

42       glibc 2.3.
43

NOTES

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

EXAMPLES

67       The  program below uses uselocale(3) and duplocale() to obtain a handle
68       for the current locale which is then passed to toupper_l(3).  The  pro‐
69       gram  takes  one  command-line argument, a string of characters that is
70       converted to uppercase and displayed on standard output.  An example of
71       its use is the following:
72
73           $ ./a.out abc
74           ABC
75
76   Program source
77
78       #define _XOPEN_SOURCE 700
79       #include <ctype.h>
80       #include <locale.h>
81       #include <stdio.h>
82       #include <stdlib.h>
83
84       #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
85                               } while (0)
86
87       int
88       main(int argc, char *argv[])
89       {
90           locale_t loc, nloc;
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 (char *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