Debian Codegraph @

upstream/debian-unstable/man3/duplocale.3

raw
1 .\" Copyright 2014, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH duplocale 3 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 duplocale \- duplicate a locale object
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <locale.h>
15 .P
16 .BI "locale_t duplocale(locale_t " locobj );
17 .fi
18 .P
19 .RS -4
20 Feature Test Macro Requirements for glibc (see
21 .BR feature_test_macros (7)):
22 .RE
23 .P
24 .BR duplocale ():
25 .nf
26 Since glibc 2.10:
27 _XOPEN_SOURCE >= 700
28 Before glibc 2.10:
29 _GNU_SOURCE
30 .fi
31 .SH DESCRIPTION
32 The
33 .BR duplocale ()
34 function creates a duplicate of the locale object referred to by
35 .IR locobj .
36 .P
37 If
38 .I locobj
39 is
40 .BR LC_GLOBAL_LOCALE ,
41 .BR duplocale ()
42 creates a locale object containing a copy of the global locale
43 determined by
44 .BR setlocale (3).
45 .SH RETURN VALUE
46 On success,
47 .BR duplocale ()
48 returns a handle for the new locale object.
49 On error, it returns
50 .IR "(locale_t)\ 0",
51 and sets
52 .I errno
53 to indicate the error.
54 .SH ERRORS
55 .TP
56 .B ENOMEM
57 Insufficient memory to create the duplicate locale object.
58 .SH STANDARDS
59 POSIX.1-2008.
60 .SH HISTORY
61 glibc 2.3.
62 .SH NOTES
63 Duplicating a locale can serve the following purposes:
64 .IP \[bu] 3
65 To create a copy of a locale object in which one of more categories
66 are to be modified (using
67 .BR newlocale (3)).
68 .IP \[bu]
69 To obtain a handle for the current locale which can used in
70 other functions that employ a locale handle, such as
71 .BR toupper_l (3).
72 This is done by applying
73 .BR duplocale ()
74 to the value returned by the following call:
75 .IP
76 .in +4n
77 .EX
78 loc = uselocale((locale_t) 0);
79 .EE
80 .in
81 .IP
82 This technique is necessary, because the above
83 .BR uselocale (3)
84 call may return the value
85 .BR LC_GLOBAL_LOCALE ,
86 which results in undefined behavior if passed to functions such as
87 .BR toupper_l (3).
88 Calling
89 .BR duplocale ()
90 can be used to ensure that the
91 .B LC_GLOBAL_LOCALE
92 value is converted into a usable locale object.
93 See EXAMPLES, below.
94 .P
95 Each locale object created by
96 .BR duplocale ()
97 should be deallocated using
98 .BR freelocale (3).
99 .SH EXAMPLES
100 The program below uses
101 .BR uselocale (3)
102 and
103 .BR duplocale ()
104 to obtain a handle for the current locale which is then passed to
105 .BR toupper_l (3).
106 The program takes one command-line argument,
107 a string of characters that is converted to uppercase and
108 displayed on standard output.
109 An example of its use is the following:
110 .P
111 .in +4n
112 .EX
113 .RB $ " ./a.out abc" ;
114 ABC
115 .EE
116 .in
117 .SS Program source
118 \&
119 .\" SRC BEGIN (duplocale.c)
120 .EX
121 #define _XOPEN_SOURCE 700
122 #include <ctype.h>
123 #include <err.h>
124 #include <locale.h>
125 #include <stdio.h>
126 #include <stdlib.h>
127 \&
128 int
129 main(int argc, char *argv[])
130 {
131 locale_t loc, nloc;
132 \&
133 if (argc != 2) {
134 fprintf(stderr, "Usage: %s string\[rs]n", argv[0]);
135 exit(EXIT_FAILURE);
136 }
137 \&
138 /* This sequence is necessary, because uselocale() might return
139 the value LC_GLOBAL_LOCALE, which can\[aq]t be passed as an
140 argument to toupper_l(). */
141 \&
142 loc = uselocale((locale_t) 0);
143 if (loc == (locale_t) 0)
144 err(EXIT_FAILURE, "uselocale");
145 \&
146 nloc = duplocale(loc);
147 if (nloc == (locale_t) 0)
148 err(EXIT_FAILURE, "duplocale");
149 \&
150 for (char *p = argv[1]; *p; p++)
151 putchar(toupper_l(*p, nloc));
152 \&
153 printf("\[rs]n");
154 \&
155 freelocale(nloc);
156 \&
157 exit(EXIT_SUCCESS);
158 }
159 .EE
160 .\" SRC END
161 .SH SEE ALSO
162 .BR freelocale (3),
163 .BR newlocale (3),
164 .BR setlocale (3),
165 .BR uselocale (3),
166 .BR locale (5),
167 .BR locale (7)