]>
Commit | Line | Data |
---|---|---|
2af53d0c MK |
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 | .\" | |
4b8c67d9 | 26 | .TH DUPLOCALE 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
2af53d0c MK |
27 | .SH NAME |
28 | duplocale \- duplicate a locale object | |
29 | .SH SYNOPSIS | |
30 | .nf | |
31 | .B #include <locale.h> | |
f90f031e | 32 | .PP |
2af53d0c MK |
33 | .BI "locale_t duplocale(locale_t " locobj ); |
34 | .fi | |
68e4db0a | 35 | .PP |
2af53d0c MK |
36 | .in -4n |
37 | Feature Test Macro Requirements for glibc (see | |
38 | .BR feature_test_macros (7)): | |
39 | .in | |
68e4db0a | 40 | .PP |
2af53d0c MK |
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 . | |
847e0d88 | 57 | .PP |
2af53d0c MK |
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: | |
847e0d88 | 98 | .IP |
2af53d0c | 99 | loc = uselocale((locale_t) 0); |
2af53d0c MK |
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 EXAMPLE | |
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). | |
2654d1a8 | 125 | The program takes one command-line argument, |
efaef3da | 126 | a string of characters that is converted to uppercase and |
2af53d0c MK |
127 | displayed on standard output. |
128 | An example of its use is the following: | |
e646a1ba | 129 | .PP |
2af53d0c | 130 | .in +4n |
e646a1ba | 131 | .EX |
2af53d0c MK |
132 | $ \fB./a.out abc\fP |
133 | ABC | |
b8302363 | 134 | .EE |
2af53d0c MK |
135 | .in |
136 | .SS Program source | |
c7885256 | 137 | \& |
e7d0bb47 | 138 | .EX |
2af53d0c MK |
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); \\ | |
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\\n", 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"); | |
89851a00 | 170 | |
2af53d0c MK |
171 | for (p = argv[1]; *p; p++) |
172 | putchar(toupper_l(*p, nloc)); | |
173 | ||
174 | printf("\\n"); | |
175 | ||
176 | freelocale(nloc); | |
177 | ||
178 | exit(EXIT_SUCCESS); | |
179 | } | |
e7d0bb47 | 180 | .EE |
2af53d0c MK |
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) |