]>
Commit | Line | Data |
---|---|---|
2af53d0c MK |
1 | .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" | |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
2af53d0c | 4 | .\" |
1d767b55 | 5 | .TH DUPLOCALE 3 2021-03-22 "Linux" "Linux Programmer's Manual" |
2af53d0c MK |
6 | .SH NAME |
7 | duplocale \- duplicate a locale object | |
b813014f AC |
8 | .SH LIBRARY |
9 | Standard C library | |
10 | .RI ( libc ", " \-lc ) | |
2af53d0c MK |
11 | .SH SYNOPSIS |
12 | .nf | |
13 | .B #include <locale.h> | |
f90f031e | 14 | .PP |
2af53d0c MK |
15 | .BI "locale_t duplocale(locale_t " locobj ); |
16 | .fi | |
68e4db0a | 17 | .PP |
d39ad78f | 18 | .RS -4 |
2af53d0c MK |
19 | Feature Test Macro Requirements for glibc (see |
20 | .BR feature_test_macros (7)): | |
d39ad78f | 21 | .RE |
68e4db0a | 22 | .PP |
2af53d0c | 23 | .BR duplocale (): |
9d2adbae MK |
24 | .nf |
25 | Since glibc 2.10: | |
5c10d2c5 | 26 | _XOPEN_SOURCE >= 700 |
9d2adbae MK |
27 | Before glibc 2.10: |
28 | _GNU_SOURCE | |
29 | .fi | |
2af53d0c MK |
30 | .SH DESCRIPTION |
31 | The | |
32 | .BR duplocale () | |
33 | function creates a duplicate of the locale object referred to by | |
34 | .IR locobj . | |
847e0d88 | 35 | .PP |
2af53d0c MK |
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 | |
855d489a | 52 | to indicate the error. |
2af53d0c MK |
53 | .SH ERRORS |
54 | .TP | |
55 | .B ENOMEM | |
56 | Insufficient memory to create the duplicate locale object. | |
57 | .SH VERSIONS | |
58 | The | |
59 | .BR duplocale () | |
60 | function first appeared in version 2.3 of the GNU C library. | |
61 | .SH CONFORMING TO | |
62 | POSIX.1-2008. | |
63 | .SH NOTES | |
64 | Duplicating a locale can serve the following purposes: | |
65 | .IP * 3 | |
66 | To create a copy of a locale object in which one of more categories | |
67 | are to be modified (using | |
68 | .BR newlocale (3)). | |
69 | .IP * | |
70 | To obtain a handle for the current locale which can used in | |
71 | other functions that employ a locale handle, such as | |
72 | .BR toupper_l (3). | |
73 | This is done by applying | |
74 | .BR duplocale () | |
75 | to the value returned by the following call: | |
847e0d88 | 76 | .IP |
1ae6b2c7 AC |
77 | .in +4n |
78 | .EX | |
79 | loc = uselocale((locale_t) 0); | |
80 | .EE | |
81 | .in | |
2af53d0c MK |
82 | .IP |
83 | This technique is necessary, because the above | |
84 | .BR uselocale (3) | |
85 | call may return the value | |
86 | .BR LC_GLOBAL_LOCALE , | |
87 | which results in undefined behavior if passed to functions such as | |
88 | .BR toupper_l (3). | |
89 | Calling | |
90 | .BR duplocale () | |
91 | can be used to ensure that the | |
1ae6b2c7 | 92 | .B LC_GLOBAL_LOCALE |
2af53d0c | 93 | value is converted into a usable locale object. |
78da9b6b | 94 | See EXAMPLES, below. |
2af53d0c MK |
95 | .PP |
96 | Each locale object created by | |
97 | .BR duplocale () | |
98 | should be deallocated using | |
99 | .BR freelocale (3). | |
a14af333 | 100 | .SH EXAMPLES |
2af53d0c MK |
101 | The program below uses |
102 | .BR uselocale (3) | |
103 | and | |
104 | .BR duplocale () | |
105 | to obtain a handle for the current locale which is then passed to | |
106 | .BR toupper_l (3). | |
2654d1a8 | 107 | The program takes one command-line argument, |
efaef3da | 108 | a string of characters that is converted to uppercase and |
2af53d0c MK |
109 | displayed on standard output. |
110 | An example of its use is the following: | |
e646a1ba | 111 | .PP |
2af53d0c | 112 | .in +4n |
e646a1ba | 113 | .EX |
2af53d0c MK |
114 | $ \fB./a.out abc\fP |
115 | ABC | |
b8302363 | 116 | .EE |
2af53d0c MK |
117 | .in |
118 | .SS Program source | |
c7885256 | 119 | \& |
e7d0bb47 | 120 | .EX |
2af53d0c MK |
121 | #define _XOPEN_SOURCE 700 |
122 | #include <ctype.h> | |
123 | #include <stdio.h> | |
124 | #include <stdlib.h> | |
125 | #include <locale.h> | |
126 | ||
d1a71985 | 127 | #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e |
2af53d0c MK |
128 | } while (0) |
129 | ||
130 | int | |
131 | main(int argc, char *argv[]) | |
132 | { | |
133 | locale_t loc, nloc; | |
2af53d0c MK |
134 | |
135 | if (argc != 2) { | |
d1a71985 | 136 | fprintf(stderr, "Usage: %s string\en", argv[0]); |
2af53d0c MK |
137 | exit(EXIT_FAILURE); |
138 | } | |
139 | ||
140 | /* This sequence is necessary, because uselocale() might return | |
141 | the value LC_GLOBAL_LOCALE, which can\(aqt be passed as an | |
46b20ca1 | 142 | argument to toupper_l(). */ |
2af53d0c MK |
143 | |
144 | loc = uselocale((locale_t) 0); | |
145 | if (loc == (locale_t) 0) | |
146 | errExit("uselocale"); | |
147 | ||
148 | nloc = duplocale(loc); | |
149 | if (nloc == (locale_t) 0) | |
150 | errExit("duplocale"); | |
89851a00 | 151 | |
88893a77 | 152 | for (char *p = argv[1]; *p; p++) |
2af53d0c MK |
153 | putchar(toupper_l(*p, nloc)); |
154 | ||
d1a71985 | 155 | printf("\en"); |
2af53d0c MK |
156 | |
157 | freelocale(nloc); | |
158 | ||
159 | exit(EXIT_SUCCESS); | |
160 | } | |
e7d0bb47 | 161 | .EE |
2af53d0c MK |
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) |