1SETLOCALE(3P) POSIX Programmer's Manual SETLOCALE(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 setlocale — set program locale
13
15 #include <locale.h>
16 char *setlocale(int category, const char *locale);
18
20 The functionality described on this reference page is aligned with the
21 ISO C standard. Any conflict between the requirements described here
22 and the ISO C standard is unintentional. This volume of POSIX.1‐2017
23 defers to the ISO C standard.
24 The setlocale() function selects the appropriate piece of the global
26 locale, as specified by the category and locale arguments, and can be
27 used to change or query the entire global locale or portions thereof.
28 The value LC_ALL for category names the entire global locale; other
29 values for category name only a part of the global locale:
30 LC_COLLATE Affects the behavior of regular expressions and the colla‐
32 tion functions.
33 LC_CTYPE Affects the behavior of regular expressions, character
35 classification, character conversion functions, and wide-
36 character functions.
37 LC_MESSAGES Affects the affirmative and negative response expressions
39 returned by nl_langinfo() and the way message catalogs are
40 located. It may also affect the behavior of functions that
41 return or write message strings.
42 LC_MONETARY Affects the behavior of functions that handle monetary val‐
44 ues.
45 LC_NUMERIC Affects the behavior of functions that handle numeric val‐
47 ues.
48 LC_TIME Affects the behavior of the time conversion functions.
50 The locale argument is a pointer to a character string containing the
52 required setting of category. The contents of this string are imple‐
53 mentation-defined. In addition, the following preset values of locale
54 are defined for all settings of category:
55 "POSIX" Specifies the minimal environment for C-language transla‐
57 tion called the POSIX locale. The POSIX locale is the
58 default global locale at entry to main().
59 "C" Equivalent to "POSIX".
61 "" Specifies an implementation-defined native environment.
63 The determination of the name of the new locale for the
64 specified category depends on the value of the associated
65 environment variables, LC_* and LANG; see the Base Defini‐
66 tions volume of POSIX.1‐2017, Chapter 7, Locale and Chapter
67 8, Environment Variables.
68 A null pointer
70 Directs setlocale() to query the current global locale set‐
71 ting and return the name of the locale if category is not
72 LC_ALL, or a string which encodes the locale name(s) for
73 all of the individual categories if category is LC_ALL.
74 Setting all of the categories of the global locale is similar to suc‐
76 cessively setting each individual category of the global locale, except
77 that all error checking is done before any actions are performed. To
78 set all the categories of the global locale, setlocale() can be invoked
79 as:
80 setlocale(LC_ALL, "");
83 In this case, setlocale() shall first verify that the values of all the
85 environment variables it needs according to the precedence rules
86 (described in the Base Definitions volume of POSIX.1‐2017, Chapter 8,
87 Environment Variables) indicate supported locales. If the value of any
88 of these environment variable searches yields a locale that is not sup‐
89 ported (and non-null), setlocale() shall return a null pointer and the
90 global locale shall not be changed. If all environment variables name
91 supported locales, setlocale() shall proceed as if it had been called
92 for each category, using the appropriate value from the associated
93 environment variable or from the implementation-defined default if
94 there is no such value.
95 The global locale established using setlocale() shall only be used in
97 threads for which no current locale has been set using uselocale() or
98 whose current locale has been set to the global locale using uselo‐
99 cale(LC_GLOBAL_LOCALE).
100 The implementation shall behave as if no function defined in this vol‐
102 ume of POSIX.1‐2017 calls setlocale().
103 The setlocale() function need not be thread-safe.
105
107 Upon successful completion, setlocale() shall return the string associ‐
108 ated with the specified category for the new locale. Otherwise, setlo‐
109 cale() shall return a null pointer and the global locale shall not be
110 changed.
111 A null pointer for locale shall cause setlocale() to return a pointer
113 to the string associated with the specified category for the current
114 global locale. The global locale shall not be changed.
115 The string returned by setlocale() is such that a subsequent call with
117 that string and its associated category shall restore that part of the
118 global locale. The application shall not modify the string returned.
119 The returned string pointer might be invalidated or the string content
120 might be overwritten by a subsequent call to setlocale(). The returned
121 pointer might also be invalidated if the calling thread is terminated.
122
124 No errors are defined.
125 The following sections are informative.
127
129 None.
130
132 The following code illustrates how a program can initialize the inter‐
133 national environment for one language, while selectively modifying the
134 global locale such that regular expressions and string operations can
135 be applied to text recorded in a different language:
136 setlocale(LC_ALL, "De");
139 setlocale(LC_COLLATE, "Fr@dict");
140 Internationalized programs can initiate language operation according to
142 environment variable settings (see the Base Definitions volume of
143 POSIX.1‐2017, Section 8.2, Internationalization Variables) by calling
144 setlocale() as follows:
145 setlocale(LC_ALL, "");
148 Changing the setting of LC_MESSAGES has no effect on catalogs that have
150 already been opened by calls to catopen().
151 In order to make use of different locale settings while multiple
153 threads are running, applications should use uselocale() in preference
154 to setlocale().
155
157 References to the international environment or locale in the following
158 text relate to the global locale for the process. This can be overrid‐
159 den for individual threads using uselocale().
160 The ISO C standard defines a collection of functions to support inter‐
162 nationalization. One of the most significant aspects of these func‐
163 tions is a facility to set and query the international environment.
164 The international environment is a repository of information that
165 affects the behavior of certain functionality, namely:
166 1. Character handling
168 2. Collating
170 3. Date/time formatting
172 4. Numeric editing
174 5. Monetary formatting
176 6. Messaging
178 The setlocale() function provides the application developer with the
180 ability to set all or portions, called categories, of the international
181 environment. These categories correspond to the areas of functionality
182 mentioned above. The syntax for setlocale() is as follows:
183 char *setlocale(int category, const char *locale);
186 where category is the name of one of following categories, namely:
188 LC_COLLATE LC_CTYPE LC_MESSAGES LC_MONETARY LC_NUMERIC LC_TIME
190 In addition, a special value called LC_ALL directs setlocale() to set
192 all categories.
193 There are two primary uses of setlocale():
195 1. Querying the international environment to find out what it is set
197 to
198 2. Setting the international environment, or locale, to a specific
200 value
201 The behavior of setlocale() in these two areas is described below.
203 Since it is difficult to describe the behavior in words, examples are
204 used to illustrate the behavior of specific uses.
205 To query the international environment, setlocale() is invoked with a
207 specific category and the null pointer as the locale. The null pointer
208 is a special directive to setlocale() that tells it to query rather
209 than set the international environment. The following syntax is used
210 to query the name of the international environment:
211 setlocale({LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, \
214 LC_NUMERIC, LC_TIME},(char *) NULL);
215 The setlocale() function shall return the string corresponding to the
217 current international environment. This value may be used by a subse‐
218 quent call to setlocale() to reset the international environment to
219 this value. However, it should be noted that the return value from set‐
220 locale() may be a pointer to a static area within the function and is
221 not guaranteed to remain unchanged (that is, it may be modified by a
222 subsequent call to setlocale()). Therefore, if the purpose of calling
223 setlocale() is to save the value of the current international environ‐
224 ment so it can be changed and reset later, the return value should be
225 copied to an array of char in the calling program.
226 There are three ways to set the international environment with setlo‐
228 cale():
229 setlocale(category, string)
231 This usage sets a specific category in the international environ‐
232 ment to a specific value corresponding to the value of the
233 string. A specific example is provided below:
234 setlocale(LC_ALL, "fr_FR.ISO-8859-1");
237 In this example, all categories of the international environment
239 are set to the locale corresponding to the string
240 "fr_FR.ISO-8859-1", or to the French language as spoken in France
241 using the ISO/IEC 8859‐1:1998 standard codeset.
242 If the string does not correspond to a valid locale, setlocale()
244 shall return a null pointer and the international environment is
245 not changed. Otherwise, setlocale() shall return the name of the
246 locale just set.
247 setlocale(category, "C")
249 The ISO C standard states that one locale must exist on all con‐
250 forming implementations. The name of the locale is C and corre‐
251 sponds to a minimal international environment needed to support
252 the C programming language.
253 setlocale(category, "")
255 This sets a specific category to an implementation-defined
256 default. This corresponds to the value of the environment vari‐
257 ables.
258
260 None.
261
263 catopen(), exec, fprintf(), fscanf(), isalnum(), isalpha(), isblank(),
264 iscntrl(), isdigit(), isgraph(), islower(), isprint(), ispunct(), iss‐
265 pace(), isupper(), iswalnum(), iswalpha(), iswblank(), iswcntrl(),
266 iswctype(), iswdigit(), iswgraph(), iswlower(), iswprint(), iswpunct(),
267 iswspace(), iswupper(), iswxdigit(), isxdigit(), localeconv(), mblen(),
268 mbstowcs(), mbtowc(), newlocale(), nl_langinfo(), perror(), psiginfo(),
269 strcoll(), strerror(), strfmon(), strsignal(), strtod(), strxfrm(),
270 tolower(), toupper(), towlower(), towupper(), uselocale(), wcscoll(),
271 wcstod(), wcstombs(), wcsxfrm(), wctomb()
272 The Base Definitions volume of POSIX.1‐2017, Chapter 7, Locale, Chapter
274 8, Environment Variables, <langinfo.h>, <locale.h>
275
277 Portions of this text are reprinted and reproduced in electronic form
278 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
279 table Operating System Interface (POSIX), The Open Group Base Specifi‐
280 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
281 Electrical and Electronics Engineers, Inc and The Open Group. In the
282 event of any discrepancy between this version and the original IEEE and
283 The Open Group Standard, the original IEEE and The Open Group Standard
284 is the referee document. The original Standard can be obtained online
285 at http://www.opengroup.org/unix/online.html .
286 Any typographical or formatting errors that appear in this page are
288 most likely to have been introduced during the conversion of the source
289 files to man page format. To report such errors, see https://www.ker‐
290 nel.org/doc/man-pages/reporting_bugs.html .
291IEEE/The Open Group 2017 SETLOCALE(3P)