1SETLOCALE(3P)              POSIX Programmer's Manual             SETLOCALE(3P)
2
3
4

PROLOG

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

NAME

12       setlocale — set program locale
13

SYNOPSIS

15       #include <locale.h>
16
17       char *setlocale(int category, const char *locale);
18

DESCRIPTION

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
25       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
31       LC_COLLATE  Affects  the behavior of regular expressions and the colla‐
32                   tion functions.
33
34       LC_CTYPE    Affects the  behavior  of  regular  expressions,  character
35                   classification,  character  conversion functions, and wide-
36                   character functions.
37
38       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
43       LC_MONETARY Affects the behavior of functions that handle monetary val‐
44                   ues.
45
46       LC_NUMERIC  Affects the behavior of functions that handle numeric  val‐
47                   ues.
48
49       LC_TIME     Affects the behavior of the time conversion functions.
50
51       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
56       "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
60       "C"         Equivalent to "POSIX".
61
62       ""          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
69       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
75       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
81
82           setlocale(LC_ALL, "");
83
84       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
96       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
101       The  implementation shall behave as if no function defined in this vol‐
102       ume of POSIX.1‐2017 calls setlocale().
103
104       The setlocale() function need not be thread-safe.
105

RETURN VALUE

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
112       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
116       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

ERRORS

124       No errors are defined.
125
126       The following sections are informative.
127

EXAMPLES

129       None.
130

APPLICATION USAGE

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
137
138           setlocale(LC_ALL, "De");
139           setlocale(LC_COLLATE, "Fr@dict");
140
141       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
146
147           setlocale(LC_ALL, "");
148
149       Changing the setting of LC_MESSAGES has no effect on catalogs that have
150       already been opened by calls to catopen().
151
152       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

RATIONALE

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
161       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
167        1. Character handling
168
169        2. Collating
170
171        3. Date/time formatting
172
173        4. Numeric editing
174
175        5. Monetary formatting
176
177        6. Messaging
178
179       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
184
185           char *setlocale(int category, const char *locale);
186
187       where category is the name of one of following categories, namely:
188
189              LC_COLLATE LC_CTYPE LC_MESSAGES LC_MONETARY LC_NUMERIC LC_TIME
190
191       In addition, a special value called LC_ALL directs setlocale()  to  set
192       all categories.
193
194       There are two primary uses of setlocale():
195
196        1. Querying  the  international environment to find out what it is set
197           to
198
199        2. Setting the international environment, or  locale,  to  a  specific
200           value
201
202       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
206       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
212
213           setlocale({LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, \
214               LC_NUMERIC, LC_TIME},(char *) NULL);
215
216       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
227       There are three ways to set the international environment  with  setlo‐
228       cale():
229
230       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
235
236                 setlocale(LC_ALL, "fr_FR.ISO-8859-1");
237
238             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
243             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
248       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
254       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

FUTURE DIRECTIONS

260       None.
261

SEE ALSO

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
273       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
287       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 .
291
292
293
294IEEE/The Open Group                  2017                        SETLOCALE(3P)
Impressum