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
13 setlocale — set program locale
14
16 #include <locale.h>
17 char *setlocale(int category, const char *locale);
19
21 The functionality described on this reference page is aligned with the
22 ISO C standard. Any conflict between the requirements described here
23 and the ISO C standard is unintentional. This volume of POSIX.1‐2008
24 defers to the ISO C standard.
25 The setlocale() function selects the appropriate piece of the global
27 locale, as specified by the category and locale arguments, and can be
28 used to change or query the entire global locale or portions thereof.
29 The value LC_ALL for category names the entire global locale; other
30 values for category name only a part of the global locale:
31 LC_COLLATE Affects the behavior of regular expressions and the colla‐
33 tion functions.
34 LC_CTYPE Affects the behavior of regular expressions, character
36 classification, character conversion functions, and wide-
37 character functions.
38 LC_MESSAGES Affects the affirmative and negative response expressions
40 returned by nl_langinfo() and the way message catalogs are
41 located. It may also affect the behavior of functions that
42 return or write message strings.
43 LC_MONETARY Affects the behavior of functions that handle monetary val‐
45 ues.
46 LC_NUMERIC Affects the behavior of functions that handle numeric val‐
48 ues.
49 LC_TIME Affects the behavior of the time conversion functions.
51 The locale argument is a pointer to a character string containing the
53 required setting of category. The contents of this string are imple‐
54 mentation-defined. In addition, the following preset values of locale
55 are defined for all settings of category:
56 "POSIX" Specifies the minimal environment for C-language transla‐
58 tion called the POSIX locale. The POSIX locale is the
59 default global locale at entry to main().
60 "C" Equivalent to "POSIX".
62 "" Specifies an implementation-defined native environment.
64 The determination of the name of the new locale for the
65 specified category depends on the value of the associated
66 environment variables, LC_* and LANG; see the Base Defini‐
67 tions volume of POSIX.1‐2008, Chapter 7, Locale and Chapter
68 8, Environment Variables.
69 A null pointer
71 Directs setlocale() to query the current global locale set‐
72 ting and return the name of the locale if category is not
73 LC_ALL, or a string which encodes the locale name(s) for
74 all of the individual categories if category is LC_ALL.
75 Setting all of the categories of the global locale is similar to suc‐
77 cessively setting each individual category of the global locale, except
78 that all error checking is done before any actions are performed. To
79 set all the categories of the global locale, setlocale() can be invoked
80 as:
81 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‐2008, 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‐2008 calls setlocale().
103
105 Upon successful completion, setlocale() shall return the string associ‐
106 ated with the specified category for the new locale. Otherwise, setlo‐
107 cale() shall return a null pointer and the global locale shall not be
108 changed.
109 A null pointer for locale shall cause setlocale() to return a pointer
111 to the string associated with the specified category for the current
112 global locale. The global locale shall not be changed.
113 The string returned by setlocale() is such that a subsequent call with
115 that string and its associated category shall restore that part of the
116 global locale. The application shall not modify the string returned.
117 The returned string pointer might be invalidated or the string content
118 might be overwritten by a subsequent call to setlocale().
119
121 No errors are defined.
122 The following sections are informative.
124
126 None.
127
129 The following code illustrates how a program can initialize the inter‐
130 national environment for one language, while selectively modifying the
131 global locale such that regular expressions and string operations can
132 be applied to text recorded in a different language:
133 setlocale(LC_ALL, "De");
135 setlocale(LC_COLLATE, "Fr@dict");
136 Internationalized programs can initiate language operation according to
138 environment variable settings (see the Base Definitions volume of
139 POSIX.1‐2008, Section 8.2, Internationalization Variables) by calling
140 setlocale() as follows:
141 setlocale(LC_ALL, "");
143 Changing the setting of LC_MESSAGES has no effect on catalogs that have
145 already been opened by calls to catopen().
146 In order to make use of different locale settings while multiple
148 threads are running, applications should use uselocale() in preference
149 to setlocale().
150
152 References to the international environment or locale in the following
153 text relate to the global locale for the process. This can be overrid‐
154 den for individual threads using uselocale().
155 The ISO C standard defines a collection of functions to support inter‐
157 nationalization. One of the most significant aspects of these func‐
158 tions is a facility to set and query the international environment.
159 The international environment is a repository of information that
160 affects the behavior of certain functionality, namely:
161 1. Character handling
163 2. Collating
165 3. Date/time formatting
167 4. Numeric editing
169 5. Monetary formatting
171 6. Messaging
173 The setlocale() function provides the application developer with the
175 ability to set all or portions, called categories, of the international
176 environment. These categories correspond to the areas of functionality
177 mentioned above. The syntax for setlocale() is as follows:
178 char *setlocale(int category, const char *locale);
180 where category is the name of one of following categories, namely:
182 LC_COLLATE LC_CTYPE LC_MESSAGES LC_MONETARY LC_NUMERIC LC_TIME
184 In addition, a special value called LC_ALL directs setlocale() to set
186 all categories.
187 There are two primary uses of setlocale():
189 1. Querying the international environment to find out what it is set
191 to
192 2. Setting the international environment, or locale, to a specific
194 value
195 The behavior of setlocale() in these two areas is described below.
197 Since it is difficult to describe the behavior in words, examples are
198 used to illustrate the behavior of specific uses.
199 To query the international environment, setlocale() is invoked with a
201 specific category and the null pointer as the locale. The null pointer
202 is a special directive to setlocale() that tells it to query rather
203 than set the international environment. The following syntax is used
204 to query the name of the international environment:
205 setlocale({LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, \
207 LC_NUMERIC, LC_TIME},(char *) NULL);
208 The setlocale() function shall return the string corresponding to the
210 current international environment. This value may be used by a subse‐
211 quent call to setlocale() to reset the international environment to
212 this value. However, it should be noted that the return value from set‐
213 locale() may be a pointer to a static area within the function and is
214 not guaranteed to remain unchanged (that is, it may be modified by a
215 subsequent call to setlocale()). Therefore, if the purpose of calling
216 setlocale() is to save the value of the current international environ‐
217 ment so it can be changed and reset later, the return value should be
218 copied to an array of char in the calling program.
219 There are three ways to set the international environment with setlo‐
221 cale():
222 setlocale(category, string)
224 This usage sets a specific category in the international environ‐
225 ment to a specific value corresponding to the value of the
226 string. A specific example is provided below:
227 setlocale(LC_ALL, "fr_FR.ISO-8859-1");
229 In this example, all categories of the international environment
231 are set to the locale corresponding to the string
232 "fr_FR.ISO-8859-1", or to the French language as spoken in France
233 using the ISO/IEC 8859‐1:1998 standard codeset.
234 If the string does not correspond to a valid locale, setlocale()
236 shall return a null pointer and the international environment is
237 not changed. Otherwise, setlocale() shall return the name of the
238 locale just set.
239 setlocale(category, "C")
241 The ISO C standard states that one locale must exist on all con‐
242 forming implementations. The name of the locale is C and corre‐
243 sponds to a minimal international environment needed to support
244 the C programming language.
245 setlocale(category, "")
247 This sets a specific category to an implementation-defined
248 default. This corresponds to the value of the environment vari‐
249 ables.
250
252 None.
253
255 catopen(), exec, fprintf(), fscanf(), isalnum(), isalpha(), isblank(),
256 iscntrl(), isdigit(), isgraph(), islower(), isprint(), ispunct(), iss‐
257 pace(), isupper(), iswalnum(), iswalpha(), iswblank(), iswcntrl(),
258 iswctype(), iswdigit(), iswgraph(), iswlower(), iswprint(), iswpunct(),
259 iswspace(), iswupper(), iswxdigit(), isxdigit(), localeconv(), mblen(),
260 mbstowcs(), mbtowc(), nl_langinfo(), perror(), psiginfo(), setlocale(),
261 strcoll(), strerror(), strfmon(), strsignal(), strtod(), strxfrm(),
262 tolower(), toupper(), towlower(), towupper(), uselocale(), wcscoll(),
263 wcstod(), wcstombs(), wcsxfrm(), wctomb()
264 The Base Definitions volume of POSIX.1‐2008, Chapter 7, Locale, Chapter
266 8, Environment Variables, <langinfo.h>, <locale.h>
267
269 Portions of this text are reprinted and reproduced in electronic form
270 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
271 -- Portable Operating System Interface (POSIX), The Open Group Base
272 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
273 cal and Electronics Engineers, Inc and The Open Group. (This is
274 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
275 event of any discrepancy between this version and the original IEEE and
276 The Open Group Standard, the original IEEE and The Open Group Standard
277 is the referee document. The original Standard can be obtained online
278 at http://www.unix.org/online.html .
279 Any typographical or formatting errors that appear in this page are
281 most likely to have been introduced during the conversion of the source
282 files to man page format. To report such errors, see https://www.ker‐
283 nel.org/doc/man-pages/reporting_bugs.html .
284IEEE/The Open Group 2013 SETLOCALE(3P)