]>
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 | .\" |
4c1c5274 | 5 | .TH duplocale 3 (date) "Linux man-pages (unreleased)" |
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> | |
c6d039a3 | 14 | .P |
2af53d0c MK |
15 | .BI "locale_t duplocale(locale_t " locobj ); |
16 | .fi | |
c6d039a3 | 17 | .P |
d39ad78f | 18 | .RS -4 |
2af53d0c MK |
19 | Feature Test Macro Requirements for glibc (see |
20 | .BR feature_test_macros (7)): | |
d39ad78f | 21 | .RE |
c6d039a3 | 22 | .P |
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 . | |
c6d039a3 | 35 | .P |
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. | |
3113c7f3 | 57 | .SH STANDARDS |
2af53d0c | 58 | POSIX.1-2008. |
4131356c AC |
59 | .SH HISTORY |
60 | glibc 2.3. | |
2af53d0c MK |
61 | .SH NOTES |
62 | Duplicating a locale can serve the following purposes: | |
cdede5cd | 63 | .IP \[bu] 3 |
2af53d0c MK |
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)). | |
cdede5cd | 67 | .IP \[bu] |
2af53d0c MK |
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: | |
847e0d88 | 74 | .IP |
1ae6b2c7 AC |
75 | .in +4n |
76 | .EX | |
77 | loc = uselocale((locale_t) 0); | |
78 | .EE | |
79 | .in | |
2af53d0c MK |
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 | |
1ae6b2c7 | 90 | .B LC_GLOBAL_LOCALE |
2af53d0c | 91 | value is converted into a usable locale object. |
78da9b6b | 92 | See EXAMPLES, below. |
c6d039a3 | 93 | .P |
2af53d0c MK |
94 | Each locale object created by |
95 | .BR duplocale () | |
96 | should be deallocated using | |
97 | .BR freelocale (3). | |
a14af333 | 98 | .SH EXAMPLES |
2af53d0c MK |
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). | |
2654d1a8 | 105 | The program takes one command-line argument, |
efaef3da | 106 | a string of characters that is converted to uppercase and |
2af53d0c MK |
107 | displayed on standard output. |
108 | An example of its use is the following: | |
c6d039a3 | 109 | .P |
2af53d0c | 110 | .in +4n |
e646a1ba | 111 | .EX |
2af53d0c MK |
112 | $ \fB./a.out abc\fP |
113 | ABC | |
b8302363 | 114 | .EE |
2af53d0c MK |
115 | .in |
116 | .SS Program source | |
c7885256 | 117 | \& |
b0b6ab4e | 118 | .\" SRC BEGIN (duplocale.c) |
e7d0bb47 | 119 | .EX |
2af53d0c MK |
120 | #define _XOPEN_SOURCE 700 |
121 | #include <ctype.h> | |
ad3868f0 | 122 | #include <locale.h> |
2af53d0c MK |
123 | #include <stdio.h> |
124 | #include <stdlib.h> | |
fe5dba13 | 125 | \& |
d1a71985 | 126 | #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e |
2af53d0c | 127 | } while (0) |
fe5dba13 | 128 | \& |
2af53d0c MK |
129 | int |
130 | main(int argc, char *argv[]) | |
131 | { | |
132 | locale_t loc, nloc; | |
fe5dba13 | 133 | \& |
2af53d0c | 134 | if (argc != 2) { |
d1a71985 | 135 | fprintf(stderr, "Usage: %s string\en", argv[0]); |
2af53d0c MK |
136 | exit(EXIT_FAILURE); |
137 | } | |
fe5dba13 | 138 | \& |
2af53d0c | 139 | /* This sequence is necessary, because uselocale() might return |
b957f81f | 140 | the value LC_GLOBAL_LOCALE, which can\[aq]t be passed as an |
46b20ca1 | 141 | argument to toupper_l(). */ |
fe5dba13 | 142 | \& |
2af53d0c MK |
143 | loc = uselocale((locale_t) 0); |
144 | if (loc == (locale_t) 0) | |
145 | errExit("uselocale"); | |
fe5dba13 | 146 | \& |
2af53d0c MK |
147 | nloc = duplocale(loc); |
148 | if (nloc == (locale_t) 0) | |
149 | errExit("duplocale"); | |
fe5dba13 | 150 | \& |
88893a77 | 151 | for (char *p = argv[1]; *p; p++) |
2af53d0c | 152 | putchar(toupper_l(*p, nloc)); |
fe5dba13 | 153 | \& |
d1a71985 | 154 | printf("\en"); |
fe5dba13 | 155 | \& |
2af53d0c | 156 | freelocale(nloc); |
fe5dba13 | 157 | \& |
2af53d0c MK |
158 | exit(EXIT_SUCCESS); |
159 | } | |
e7d0bb47 | 160 | .EE |
b0b6ab4e | 161 | .\" SRC END |
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) |