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