]>
Commit | Line | Data |
---|---|---|
bf5a7247 MK |
1 | .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) |
2 | .\" and Copyright 1999 by Bruno Haible (haible@clisp.cons.org) | |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
c08df37a | 25 | .\" |
fea681da MK |
26 | .\" Modified Sat Jul 24 18:20:12 1993 by Rik Faith (faith@cs.unc.edu) |
27 | .\" Modified Tue Jul 15 16:49:10 1997 by Andries Brouwer (aeb@cwi.nl) | |
28 | .\" Modified Sun Jul 4 14:52:16 1999 by Bruno Haible (haible@clisp.cons.org) | |
29 | .\" Modified Tue Aug 24 17:11:01 1999 by Andries Brouwer (aeb@cwi.nl) | |
30 | .\" Modified Tue Feb 6 03:31:55 2001 by Andries Brouwer (aeb@cwi.nl) | |
31 | .\" | |
4b8c67d9 | 32 | .TH SETLOCALE 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
fea681da MK |
33 | .SH NAME |
34 | setlocale \- set the current locale | |
35 | .SH SYNOPSIS | |
36 | .nf | |
37 | .B #include <locale.h> | |
68e4db0a | 38 | .PP |
fea681da MK |
39 | .BI "char *setlocale(int " category ", const char *" locale ); |
40 | .fi | |
41 | .SH DESCRIPTION | |
c13182ef | 42 | The |
63aa9df0 | 43 | .BR setlocale () |
fea681da MK |
44 | function is used to set or query the program's current locale. |
45 | .PP | |
46 | If | |
47 | .I locale | |
8478ee02 | 48 | is not NULL, |
fea681da MK |
49 | the program's current locale is modified according to the arguments. |
50 | The argument | |
51 | .I category | |
52 | determines which parts of the program's current locale should be modified. | |
348aab37 MK |
53 | .TS |
54 | lB lB | |
55 | lB l. | |
56 | Category Governs | |
57 | LC_ALL All of the locale | |
58 | LC_ADDRESS T{ | |
59 | Formatting of addresses and | |
60 | .br | |
61 | geography-related items (*) | |
62 | T} | |
63 | LC_COLLATE String collation | |
64 | LC_CTYPE Character classification | |
65 | LC_IDENTIFICATION Metadata describing the locale (*) | |
66 | LC_MEASUREMENT T{ | |
67 | Settings related to measurements | |
68 | .br | |
69 | (metric versus US customary) (*) | |
70 | T} | |
71 | LC_MESSAGES Localizable natural-language messages | |
72 | LC_MONETARY Formatting of monetary values | |
73 | LC_NAME Formatting of salutations for persons (*) | |
74 | LC_NUMERIC Formatting of nonmonetary numeric values | |
75 | LC_PAPER Settings related to the standard paper size (*) | |
76 | LC_TELEPHONE Formats to be used with telephone services (*) | |
77 | LC_TIME Formatting of date and time values | |
78 | .TE | |
79 | .PP | |
80 | The categories marked with an asterisk in the above table | |
81 | are GNU extensions. | |
82 | For further information on these locale categories, see | |
83 | .BR locale (7). | |
fea681da MK |
84 | .PP |
85 | The argument | |
86 | .I locale | |
87 | is a pointer to a character string containing the | |
88 | required setting of | |
89 | .IR category . | |
90 | Such a string is either a well-known constant like "C" or "da_DK" | |
91 | (see below), or an opaque string that was returned by another call of | |
e511ffb6 | 92 | .BR setlocale (). |
fea681da MK |
93 | .PP |
94 | If | |
95 | .I locale | |
e0396d76 | 96 | is an empty string, |
fea681da MK |
97 | .BR """""" , |
98 | each part of the locale that should be modified is set according to the | |
c13182ef | 99 | environment variables. |
a43eed0c | 100 | The details are implementation-dependent. |
97aec57c | 101 | For glibc, first (regardless of |
fea681da | 102 | .IR category ), |
2f0af33b MK |
103 | the environment variable |
104 | .B LC_ALL | |
105 | is inspected, | |
fea681da | 106 | next the environment variable with the same name as the category |
348aab37 | 107 | (see the table above), |
2f0af33b MK |
108 | and finally the environment variable |
109 | .BR LANG . | |
fea681da MK |
110 | The first existing environment variable is used. |
111 | If its value is not a valid locale specification, the locale | |
112 | is unchanged, and | |
e511ffb6 | 113 | .BR setlocale () |
fea681da | 114 | returns NULL. |
fea681da MK |
115 | .PP |
116 | The locale | |
117 | .B """C""" | |
118 | or | |
119 | .B """POSIX""" | |
9ce8a1e0 MM |
120 | is a portable locale; |
121 | it exists on all conforming systems. | |
fea681da MK |
122 | .PP |
123 | A locale name is typically of the form | |
124 | .IR language "[_" territory "][." codeset "][@" modifier "]," | |
125 | where | |
126 | .I language | |
127 | is an ISO 639 language code, | |
128 | .I territory | |
129 | is an ISO 3166 country code, and | |
130 | .I codeset | |
131 | is a character set or encoding identifier like | |
132 | .B "ISO-8859-1" | |
133 | or | |
134 | .BR "UTF-8" . | |
9ab7f611 BR |
135 | For a list of all supported locales, try "locale \-a" (see |
136 | .BR locale (1)). | |
fea681da MK |
137 | .PP |
138 | If | |
139 | .I locale | |
8478ee02 | 140 | is NULL, the current locale is only queried, not modified. |
fea681da MK |
141 | .PP |
142 | On startup of the main program, the portable | |
143 | .B """C""" | |
144 | locale is selected as default. | |
001bbe30 | 145 | A program may be made portable to all locales by calling: |
408731d4 MK |
146 | .PP |
147 | .in +4n | |
148 | .EX | |
149 | setlocale(LC_ALL, ""); | |
150 | .EE | |
151 | .in | |
152 | .PP | |
cfadad46 | 153 | after program initialization, by using the values returned |
fea681da | 154 | from a |
fb186734 | 155 | .BR localeconv (3) |
fea681da | 156 | call |
ae03dc66 | 157 | for locale-dependent information, by using the multibyte and wide |
fea681da MK |
158 | character functions for text processing if |
159 | .BR "MB_CUR_MAX > 1" , | |
160 | and by using | |
1368e847 | 161 | .BR strcoll (3), |
fb186734 | 162 | .BR wcscoll (3) |
c13182ef | 163 | or |
fb186734 MK |
164 | .BR strxfrm (3), |
165 | .BR wcsxfrm (3) | |
fea681da | 166 | to compare strings. |
47297adb | 167 | .SH RETURN VALUE |
fea681da | 168 | A successful call to |
63aa9df0 | 169 | .BR setlocale () |
fea681da MK |
170 | returns an opaque string that corresponds to the locale set. |
171 | This string may be allocated in static storage. | |
172 | The string returned is such that a subsequent call with that string | |
173 | and its associated category will restore that part of the process's | |
c13182ef | 174 | locale. |
8478ee02 | 175 | The return value is NULL if the request cannot be honored. |
b3eedd06 ZL |
176 | .SH ATTRIBUTES |
177 | For an explanation of the terms used in this section, see | |
178 | .BR attributes (7). | |
179 | .TS | |
180 | allbox; | |
181 | lb lb lbw26 | |
182 | l l l. | |
183 | Interface Attribute Value | |
184 | T{ | |
185 | .BR setlocale () | |
186 | T} Thread safety MT-Unsafe const:locale env | |
187 | .TE | |
847e0d88 | 188 | .sp 1 |
47297adb | 189 | .SH CONFORMING TO |
3a6e9ca5 | 190 | POSIX.1-2001, POSIX.1-2008, C89, C99. |
2050975e MK |
191 | .PP |
192 | The C standards specify only the categories | |
193 | .BR LC_ALL , | |
194 | .BR LC_COLLATE , | |
195 | .BR LC_CTYPE , | |
196 | .BR LC_MONETARY , | |
197 | .BR LC_NUMERIC , | |
198 | and | |
199 | .BR LC_TIME . | |
200 | POSIX.1 adds | |
201 | .BR LC_MESSAGES . | |
202 | The remaining categories are GNU extensions. | |
47297adb | 203 | .SH SEE ALSO |
fea681da MK |
204 | .BR locale (1), |
205 | .BR localedef (1), | |
206 | .BR isalpha (3), | |
207 | .BR localeconv (3), | |
0087e7c4 | 208 | .BR nl_langinfo (3), |
aa52d776 | 209 | .BR rpmatch (3), |
fea681da MK |
210 | .BR strcoll (3), |
211 | .BR strftime (3), | |
17a1234f | 212 | .BR charsets (7), |
fea681da | 213 | .BR locale (7) |