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
21 The setlocale() function selects the appropriate piece of the program's
22 locale, as specified by the category and locale arguments, and may be
23 used to change or query the program's entire locale or portions
24 thereof. The value LC_ALL for category names the program's entire
25 locale; other values for category name only a part of the program's
26 locale:
27 LC_COLLATE
29 Affects the behavior of regular expressions and the collation
30 functions.
31 LC_CTYPE
33 Affects the behavior of regular expressions, character classifi‐
34 cation, character conversion functions, and wide-character func‐
35 tions.
36 LC_MESSAGES
38 Affects what strings are expected by commands and utilities as
39 affirmative or negative responses.
40 It also affects what strings are given by commands and utilities as
42 affirmative or negative responses, and the content of messages.
43 LC_MONETARY
45 Affects the behavior of functions that handle monetary values.
46 LC_NUMERIC
48 Affects the behavior of functions that handle numeric values.
49 LC_TIME
51 Affects the behavior of the time conversion functions.
52 The locale argument is a pointer to a character string containing the
55 required setting of category. The contents of this string are implemen‐
56 tation-defined. In addition, the following preset values of locale are
57 defined for all settings of category:
58 "POSIX"
60 Specifies the minimal environment for C-language translation
61 called the POSIX locale. If setlocale() is not invoked, the
62 POSIX locale is the default at entry to main().
63 "C" Equivalent to "POSIX" .
65 "" Specifies an implementation-defined native environment. This
67 corresponds to the value of the associated environment vari‐
68 ables, LC_* and LANG ; see the Base Definitions volume of
69 IEEE Std 1003.1-2001, Chapter 7, Locale and the Base Definitions
70 volume of IEEE Std 1003.1-2001, Chapter 8, Environment Vari‐
71 ables.
72 A null pointer
74 Used to direct setlocale() to query the current international‐
75 ized environment and return the name of the locale.
76 The locale state is common to all threads within a process.
79
81 Upon successful completion, setlocale() shall return the string associ‐
82 ated with the specified category for the new locale. Otherwise, setlo‐
83 cale() shall return a null pointer and the program's locale is not
84 changed.
85 A null pointer for locale causes setlocale() to return a pointer to the
87 string associated with the category for the program's current locale.
88 The program's locale shall not be changed.
89 The string returned by setlocale() is such that a subsequent call with
91 that string and its associated category shall restore that part of the
92 program's locale. The application shall not modify the string returned
93 which may be overwritten by a subsequent call to setlocale().
94
96 No errors are defined.
97 The following sections are informative.
99
101 None.
102
104 The following code illustrates how a program can initialize the inter‐
105 national environment for one language, while selectively modifying the
106 program's locale such that regular expressions and string operations
107 can be applied to text recorded in a different language:
108 setlocale(LC_ALL, "De");
111 setlocale(LC_COLLATE, "Fr@dict");
112 Internationalized programs must call setlocale() to initiate a specific
114 language operation. This can be done by calling setlocale() as follows:
115 setlocale(LC_ALL, "");
118 Changing the setting of LC_MESSAGES has no effect on catalogs that have
120 already been opened by calls to catopen().
121
123 The ISO C standard defines a collection of functions to support inter‐
124 nationalization. One of the most significant aspects of these func‐
125 tions is a facility to set and query the international environment. The
126 international environment is a repository of information that affects
127 the behavior of certain functionality, namely:
128 1. Character handling
130 2. Collating
132 3. Date/time formatting
134 4. Numeric editing
136 5. Monetary formatting
138 6. Messaging
140 The setlocale() function provides the application developer with the
142 ability to set all or portions, called categories, of the international
143 environment. These categories correspond to the areas of functionality
144 mentioned above. The syntax for setlocale() is as follows:
145 char *setlocale(int category, const char *locale);
148 where category is the name of one of following categories, namely:
150 LC_COLLATE
153 LC_CTYPE
155 LC_MESSAGES
157 LC_MONETARY
159 LC_NUMERIC
161 LC_TIME
163 In addition, a special value called LC_ALL directs setlocale() to set
166 all categories.
167 There are two primary uses of setlocale():
169 1. Querying the international environment to find out what it is set
171 to
172 2. Setting the international environment, or locale, to a specific
174 value
175 The behavior of setlocale() in these two areas is described below.
177 Since it is difficult to describe the behavior in words, examples are
178 used to illustrate the behavior of specific uses.
179 To query the international environment, setlocale() is invoked with a
181 specific category and the NULL pointer as the locale. The NULL pointer
182 is a special directive to setlocale() that tells it to query rather
183 than set the international environment. The following syntax is used to
184 query the name of the international environment:
185 setlocale({LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, \
188 LC_NUMERIC, LC_TIME},(char *) NULL);
189 The setlocale() function shall return the string corresponding to the
191 current international environment. This value may be used by a subse‐
192 quent call to setlocale() to reset the international environment to
193 this value. However, it should be noted that the return value from set‐
194 locale() may be a pointer to a static area within the function and is
195 not guaranteed to remain unchanged (that is, it may be modified by a
196 subsequent call to setlocale()). Therefore, if the purpose of calling
197 setlocale() is to save the value of the current international environ‐
198 ment so it can be changed and reset later, the return value should be
199 copied to an array of char in the calling program.
200 There are three ways to set the international environment with setlo‐
202 cale():
203 setlocale(category, string)
205 This usage sets a specific category in the international envi‐
207 ronment to a specific value corresponding to the value of the
208 string. A specific example is provided below:
209 setlocale(LC_ALL, "fr_FR.ISO-8859-1");
212 In this example, all categories of the international environment are
214 set to the locale corresponding to the string "fr_FR.ISO-8859-1", or to
215 the French language as spoken in France using the ISO/IEC 8859-1:1998
216 standard codeset.
217 If the string does not correspond to a valid locale, setlocale() shall
219 return a NULL pointer and the international environment is not changed.
220 Otherwise, setlocale() shall return the name of the locale just set.
221 setlocale(category, "C")
223 The ISO C standard states that one locale must exist on all con‐
225 forming implementations. The name of the locale is C and corre‐
226 sponds to a minimal international environment needed to support
227 the C programming language.
228 setlocale(category, "")
230 This sets a specific category to an implementation-defined
232 default. This corresponds to the value of the environment vari‐
233 ables.
234
237 None.
238
240 exec(), isalnum(), isalpha(), isblank(), iscntrl(), isdigit(),
241 isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(),
242 iswalnum(), iswalpha(), iswblank(), iswcntrl(), iswctype(), iswdigit(),
243 iswgraph(), iswlower(), iswprint(), iswpunct(), iswspace(), iswupper(),
244 iswxdigit(), isxdigit(), localeconv(), mblen(), mbstowcs(), mbtowc(),
245 nl_langinfo(), printf(), scanf(), setlocale, strcoll(), strerror(),
246 strfmon() , strtod(), strxfrm(), tolower(), toupper(), towlower(),
247 towupper(), wcscoll(), wcstod(), wcstombs(), wcsxfrm(), wctomb(), the
248 Base Definitions volume of IEEE Std 1003.1-2001, <langinfo.h>,
249 <locale.h>
250
252 Portions of this text are reprinted and reproduced in electronic form
253 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
254 -- Portable Operating System Interface (POSIX), The Open Group Base
255 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
256 Electrical and Electronics Engineers, Inc and The Open Group. In the
257 event of any discrepancy between this version and the original IEEE and
258 The Open Group Standard, the original IEEE and The Open Group Standard
259 is the referee document. The original Standard can be obtained online
260 at http://www.opengroup.org/unix/online.html .
261IEEE/The Open Group 2003 SETLOCALE(3P)