Debian Codegraph @

upstream/debian-trixie/man3/setlocale.3

raw
1 '\" t
2 .\" Copyright (c) 1993 by Thomas Koenig ([email protected])
3 .\" and Copyright 1999 by Bruno Haible ([email protected])
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\" Modified Sat Jul 24 18:20:12 1993 by Rik Faith ([email protected])
8 .\" Modified Tue Jul 15 16:49:10 1997 by Andries Brouwer ([email protected])
9 .\" Modified Sun Jul 4 14:52:16 1999 by Bruno Haible ([email protected])
10 .\" Modified Tue Aug 24 17:11:01 1999 by Andries Brouwer ([email protected])
11 .\" Modified Tue Feb 6 03:31:55 2001 by Andries Brouwer ([email protected])
12 .\"
13 .TH setlocale 3 2024-05-02 "Linux man-pages 6.9.1"
14 .SH NAME
15 setlocale \- set the current locale
16 .SH LIBRARY
17 Standard C library
18 .RI ( libc ", " \-lc )
19 .SH SYNOPSIS
20 .nf
21 .B #include <locale.h>
22 .P
23 .BI "char *setlocale(int " category ", const char *" locale );
24 .fi
25 .SH DESCRIPTION
26 The
27 .BR setlocale ()
28 function is used to set or query the program's current locale.
29 .P
30 If
31 .I locale
32 is not NULL,
33 the program's current locale is modified according to the arguments.
34 The argument
35 .I category
36 determines which parts of the program's current locale should be modified.
37 .TS
38 lB lB
39 lB lx.
40 Category Governs
41 LC_ALL All of the locale
42 LC_ADDRESS T{
43 Formatting of addresses and
44 geography-related items (*)
45 T}
46 LC_COLLATE String collation
47 LC_CTYPE Character classification
48 LC_IDENTIFICATION T{
49 Metadata describing the locale (*)
50 T}
51 LC_MEASUREMENT T{
52 Settings related to measurements
53 (metric versus US customary) (*)
54 T}
55 LC_MESSAGES T{
56 Localizable natural-language messages
57 T}
58 LC_MONETARY T{
59 Formatting of monetary values
60 T}
61 LC_NAME T{
62 Formatting of salutations for persons (*)
63 T}
64 LC_NUMERIC T{
65 Formatting of nonmonetary numeric values
66 T}
67 LC_PAPER T{
68 Settings related to the standard paper size (*)
69 T}
70 LC_TELEPHONE T{
71 Formats to be used with telephone services (*)
72 T}
73 LC_TIME T{
74 Formatting of date and time values
75 T}
76 .TE
77 .P
78 The categories marked with an asterisk in the above table
79 are GNU extensions.
80 For further information on these locale categories, see
81 .BR locale (7).
82 .P
83 The argument
84 .I locale
85 is a pointer to a character string containing the
86 required setting of
87 .IR category .
88 Such a string is either a well-known constant like "C" or "da_DK"
89 (see below), or an opaque string that was returned by another call of
90 .BR setlocale ().
91 .P
92 If
93 .I locale
94 is an empty string,
95 .BR \[dq]\[dq] ,
96 each part of the locale that should be modified is set according to the
97 environment variables.
98 The details are implementation-dependent.
99 For glibc, first (regardless of
100 .IR category ),
101 the environment variable
102 .B LC_ALL
103 is inspected,
104 next the environment variable with the same name as the category
105 (see the table above),
106 and finally the environment variable
107 .BR LANG .
108 The first existing environment variable is used.
109 If its value is not a valid locale specification, the locale
110 is unchanged, and
111 .BR setlocale ()
112 returns NULL.
113 .P
114 The locale
115 .B \[dq]C\[dq]
116 or
117 .B \[dq]POSIX\[dq]
118 is a portable locale;
119 it exists on all conforming systems.
120 .P
121 A locale name is typically of the form
122 .IR language "[_" territory "][." codeset "][@" modifier "],"
123 where
124 .I language
125 is an ISO\~639 language code,
126 .I territory
127 is an ISO\~3166 country code, and
128 .I codeset
129 is a character set or encoding identifier like
130 .B "ISO\-8859\-1"
131 or
132 .BR "UTF\-8" .
133 For a list of all supported locales, try "locale \-a" (see
134 .BR locale (1)).
135 .P
136 If
137 .I locale
138 is NULL, the current locale is only queried, not modified.
139 .P
140 On startup of the main program, the portable
141 .B \[dq]C\[dq]
142 locale is selected as default.
143 A program may be made portable to all locales by calling:
144 .P
145 .in +4n
146 .EX
147 setlocale(LC_ALL, "");
148 .EE
149 .in
150 .P
151 after program initialization, and then:
152 .IP \[bu] 3
153 using the values returned from a
154 .BR localeconv (3)
155 call for locale-dependent information;
156 .IP \[bu]
157 using the multibyte and wide character functions for text processing if
158 .BR "MB_CUR_MAX > 1" ;
159 .IP \[bu]
160 using
161 .BR strcoll (3)
162 and
163 .BR strxfrm (3)
164 to compare strings; and
165 .IP \[bu]
166 using
167 .BR wcscoll (3)
168 and
169 .BR wcsxfrm (3)
170 to compare wide-character strings.
171 .SH RETURN VALUE
172 A successful call to
173 .BR setlocale ()
174 returns an opaque string that corresponds to the locale set.
175 This string may be allocated in static storage.
176 The string returned is such that a subsequent call with that string
177 and its associated category will restore that part of the process's
178 locale.
179 The return value is NULL if the request cannot be honored.
180 .SH ATTRIBUTES
181 For an explanation of the terms used in this section, see
182 .BR attributes (7).
183 .TS
184 allbox;
185 lbx lb lb
186 l l l.
187 Interface Attribute Value
188 T{
189 .na
190 .nh
191 .BR setlocale ()
192 T} Thread safety MT-Unsafe const:locale env
193 .TE
194 .SH STANDARDS
195 C11, POSIX.1-2008.
196 .SS Categories
197 .TP
198 .B LC_ALL
199 .TQ
200 .B LC_COLLATE
201 .TQ
202 .B LC_CTYPE
203 .TQ
204 .B LC_MONETARY
205 .TQ
206 .B LC_NUMERIC
207 .TQ
208 .B LC_TIME
209 C11, POSIX.1-2008.
210 .TP
211 .B LC_MESSAGES
212 POSIX.1-2008.
213 .TP
214 Others:
215 GNU.
216 .SH HISTORY
217 POSIX.1-2001, C89.
218 .SS Categories
219 .TP
220 .B LC_ALL
221 .TQ
222 .B LC_COLLATE
223 .TQ
224 .B LC_CTYPE
225 .TQ
226 .B LC_MONETARY
227 .TQ
228 .B LC_NUMERIC
229 .TQ
230 .B LC_TIME
231 C89, POSIX.1-2001.
232 .TP
233 .B LC_MESSAGES
234 POSIX.1-2001.
235 .TP
236 Others:
237 GNU.
238 .SH SEE ALSO
239 .BR locale (1),
240 .BR localedef (1),
241 .BR isalpha (3),
242 .BR localeconv (3),
243 .BR nl_langinfo (3),
244 .BR rpmatch (3),
245 .BR strcoll (3),
246 .BR strftime (3),
247 .BR charsets (7),
248 .BR locale (7)