Debian Codegraph @

upstream/debian-unstable/man3/setlocale.3

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