Debian Codegraph @

upstream/debian-trixie/man3/duplocale.3

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