]> git.ipfire.org Git - thirdparty/man-pages.git/blob - man3/duplocale.3
err.3: EXAMPLES: use EXIT_FAILURE rather than 1 as exit status
[thirdparty/man-pages.git] / man3 / duplocale.3
1 '\" t
2 .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\"
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
8 .\"
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
13 .\"
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
20 .\" professionally.
21 .\"
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
24 .\" %%%LICENSE_END
25 .\"
26 .TH DUPLOCALE 3 2019-03-06 "Linux" "Linux Programmer's Manual"
27 .SH NAME
28 duplocale \- duplicate a locale object
29 .SH SYNOPSIS
30 .nf
31 .B #include <locale.h>
32 .PP
33 .BI "locale_t duplocale(locale_t " locobj );
34 .fi
35 .PP
36 .in -4n
37 Feature Test Macro Requirements for glibc (see
38 .BR feature_test_macros (7)):
39 .in
40 .PP
41 .BR duplocale ():
42 .PD 0
43 .RS 4
44 .TP
45 Since glibc 2.10:
46 _XOPEN_SOURCE\ >=\ 700
47 .TP
48 Before glibc 2.10:
49 _GNU_SOURCE
50 .RE
51 .PD
52 .SH DESCRIPTION
53 The
54 .BR duplocale ()
55 function creates a duplicate of the locale object referred to by
56 .IR locobj .
57 .PP
58 If
59 .I locobj
60 is
61 .BR LC_GLOBAL_LOCALE ,
62 .BR duplocale ()
63 creates a locale object containing a copy of the global locale
64 determined by
65 .BR setlocale (3).
66 .SH RETURN VALUE
67 On success,
68 .BR duplocale ()
69 returns a handle for the new locale object.
70 On error, it returns
71 .IR "(locale_t)\ 0",
72 and sets
73 .I errno
74 to indicate the cause of the error.
75 .SH ERRORS
76 .TP
77 .B ENOMEM
78 Insufficient memory to create the duplicate locale object.
79 .SH VERSIONS
80 The
81 .BR duplocale ()
82 function first appeared in version 2.3 of the GNU C library.
83 .SH CONFORMING TO
84 POSIX.1-2008.
85 .SH NOTES
86 Duplicating a locale can serve the following purposes:
87 .IP * 3
88 To create a copy of a locale object in which one of more categories
89 are to be modified (using
90 .BR newlocale (3)).
91 .IP *
92 To obtain a handle for the current locale which can used in
93 other functions that employ a locale handle, such as
94 .BR toupper_l (3).
95 This is done by applying
96 .BR duplocale ()
97 to the value returned by the following call:
98 .IP
99 loc = uselocale((locale_t) 0);
100 .IP
101 This technique is necessary, because the above
102 .BR uselocale (3)
103 call may return the value
104 .BR LC_GLOBAL_LOCALE ,
105 which results in undefined behavior if passed to functions such as
106 .BR toupper_l (3).
107 Calling
108 .BR duplocale ()
109 can be used to ensure that the
110 .BR LC_GLOBAL_LOCALE
111 value is converted into a usable locale object.
112 See EXAMPLE, below.
113 .PP
114 Each locale object created by
115 .BR duplocale ()
116 should be deallocated using
117 .BR freelocale (3).
118 .SH EXAMPLES
119 The program below uses
120 .BR uselocale (3)
121 and
122 .BR duplocale ()
123 to obtain a handle for the current locale which is then passed to
124 .BR toupper_l (3).
125 The program takes one command-line argument,
126 a string of characters that is converted to uppercase and
127 displayed on standard output.
128 An example of its use is the following:
129 .PP
130 .in +4n
131 .EX
132 $ \fB./a.out abc\fP
133 ABC
134 .EE
135 .in
136 .SS Program source
137 \&
138 .EX
139 #define _XOPEN_SOURCE 700
140 #include <ctype.h>
141 #include <stdio.h>
142 #include <stdlib.h>
143 #include <locale.h>
144
145 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
146 } while (0)
147
148 int
149 main(int argc, char *argv[])
150 {
151 locale_t loc, nloc;
152 char *p;
153
154 if (argc != 2) {
155 fprintf(stderr, "Usage: %s string\en", argv[0]);
156 exit(EXIT_FAILURE);
157 }
158
159 /* This sequence is necessary, because uselocale() might return
160 the value LC_GLOBAL_LOCALE, which can\(aqt be passed as an
161 argument to toupper_l() */
162
163 loc = uselocale((locale_t) 0);
164 if (loc == (locale_t) 0)
165 errExit("uselocale");
166
167 nloc = duplocale(loc);
168 if (nloc == (locale_t) 0)
169 errExit("duplocale");
170
171 for (p = argv[1]; *p; p++)
172 putchar(toupper_l(*p, nloc));
173
174 printf("\en");
175
176 freelocale(nloc);
177
178 exit(EXIT_SUCCESS);
179 }
180 .EE
181 .SH SEE ALSO
182 .BR freelocale (3),
183 .BR newlocale (3),
184 .BR setlocale (3),
185 .BR uselocale (3),
186 .BR locale (5),
187 .BR locale (7)