1setlocale(3C) Standard C Library Functions setlocale(3C)
2
3
4
6 setlocale - modify and query a program's locale
7
9 #include <locale.h>
10
11 char *setlocale(int category, const char *locale);
12
13
15 The setlocale() function selects the appropriate piece of the program's
16 locale as specified by the category and locale arguments. The category
17 argument may have the following values: LC_CTYPE, LC_NUMERIC, LC_TIME,
18 LC_COLLATE, LC_MONETARY, LC_MESSAGES, and LC_ALL. These names are
19 defined in the <locale.h> header. The LC_ALL variable names all of a
20 program's locale categories.
21
22
23 The LC_CTYPE variable affects the behavior of character handling func‐
24 tions such as isdigit(3C) and tolower(3C), and multibyte character
25 functions such as mbtowc(3C) and wctomb(3C).
26
27
28 The LC_NUMERIC variable affects the decimal point character and thou‐
29 sands separator character for the formatted input/output functions and
30 string conversion functions.
31
32
33 The LC_TIME variable affects the date and time format as delivered by
34 ascftime(3C), cftime(3C), getdate(3C), strftime(3C), and strptime(3C).
35
36
37 The LC_COLLATE variable affects the sort order produced by collating
38 functions such as strcoll(3C) and strxfrm(3C).
39
40
41 The LC_MONETARY variable affects the monetary formatted information
42 returned by localeconv(3C).
43
44
45 The LC_MESSAGES variable affects the behavior of messaging functions
46 such as dgettext(3C), gettext(3C), and gettxt(3C).
47
48
49 A value of "C" for locale specifies the traditional UNIX system behav‐
50 ior. At program startup, the equivalent of
51
52
53 setlocale(LC_ALL, "C")
54
55
56 is executed. This has the effect of initializing each category to the
57 locale described by the environment "C".
58
59
60 A value of "" for locale specifies that the locale should be taken from
61 environment variables. The order in which the environment variables are
62 checked for the various categories is given below:
63
64
65
66
67 ┌───────────────┬────────────────┬────────────────┬───────────────┐
68 │ Category │ 1st Env Var │ 2nd Env Var │ 3rd Env Var │
69 ├───────────────┼────────────────┼────────────────┼───────────────┤
70 │LC_CTYPE: │ LC_ALL │ LC_CTYPE │LANG │
71 ├───────────────┼────────────────┼────────────────┼───────────────┤
72 │LC_COLLATE: │ LC_ALL │ LC_COLLATE │LANG │
73 ├───────────────┼────────────────┼────────────────┼───────────────┤
74 │LC_TIME: │ LC_ALL │ LC_TIME │LANG │
75 ├───────────────┼────────────────┼────────────────┼───────────────┤
76 │LC_NUMERIC: │ LC_ALL │ LC_NUMERIC │LANG │
77 ├───────────────┼────────────────┼────────────────┼───────────────┤
78 │LC_MONETARY: │ LC_ALL │ LC_MONETARY │LANG │
79 ├───────────────┼────────────────┼────────────────┼───────────────┤
80 │LC_MESSAGES: │ LC_ALL │ LC_MESSAGES │LANG │
81 └───────────────┴────────────────┴────────────────┴───────────────┘
82
83
84 If a pointer to a string is given for locale, setlocale() attempts to
85 set the locale for the given category to locale. If setlocale() suc‐
86 ceeds, locale is returned. If setlocale() fails, a null pointer is
87 returned and the program's locale is not changed.
88
89
90 For category LC_ALL, the behavior is slightly different. If a pointer
91 to a string is given for locale and LC_ALL is given for category, set‐
92 locale() attempts to set the locale for all the categories to locale.
93 The locale may be a simple locale, consisting of a single locale, or a
94 composite locale. If the locales for all the categories are the same
95 after all the attempted locale changes, setlocale() will return a
96 pointer to the common simple locale. If there is a mixture of locales
97 among the categories, setlocale() will return a composite locale.
98
100 Upon successful completion, setlocale() returns the string associated
101 with the specified category for the new locale. Otherwise, setlocale()
102 returns a null pointer and the program's locale is not changed.
103
104
105 A null pointer for locale causes setlocale() to return a pointer to the
106 string associated with the category for the program's current locale.
107 The program's locale is not changed.
108
109
110 The string returned by setlocale() is such that a subsequent call with
111 that string and its associated category will restore that part of the
112 program's locale. The string returned must not be modified by the pro‐
113 gram, but may be overwritten by a subsequent call to setlocale().
114
116 No errors are defined.
117
119 /usr/lib/locale/locale locale database directory for locale
120
121
123 See attributes(5) for descriptions of the following attributes:
124
125
126
127
128 ┌─────────────────────────────┬─────────────────────────────┐
129 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
130 ├─────────────────────────────┼─────────────────────────────┤
131 │CSI │Enabled │
132 ├─────────────────────────────┼─────────────────────────────┤
133 │Interface Stability │Standard │
134 ├─────────────────────────────┼─────────────────────────────┤
135 │MT-Level │MT-Safe with exceptions │
136 └─────────────────────────────┴─────────────────────────────┘
137
139 locale(1), ctype(3C), getdate(3C) gettext(3C), gettxt(3C), isdigit(3C),
140 libc(3LIB), localeconv(3C), mbtowc(3C), strcoll(3C), strftime(3C),
141 strptime(3C) strxfrm(3C) tolower(3C), wctomb(3C), attributes(5), envi‐
142 ron(5), locale(5), standards(5)
143
145 It is unsafe for any thread to change locale (by calling setlocale()
146 with a non-null locale argument) in a multithreaded application while
147 any other thread in the application is using any locale-sensitive rou‐
148 tine. To change locale in a multithreaded application, setlocale()
149 should be called prior to using any locale-sensitive routine. Using
150 setlocale() to query the current locale is safe and can be used any‐
151 where in a multithreaded application except when some other thread is
152 changing locale.
153
154
155 It is the user's responsibility to ensure that mixed locale categories
156 are compatible. For example, setting LC_CTYPE=C and LC_TIME=ja (where
157 ja indicates Japanese) will not work, because Japanese time cannot be
158 represented in the "C" locale's ASCII codeset.
159
160
161
162SunOS 5.11 19 Sep 2005 setlocale(3C)