1LOCALE(P) POSIX Programmer's Manual LOCALE(P)
2
6 locale - get locale-specific information
7
9 locale [-a| -m]
10 locale [-ck] name...
12
15 The locale utility shall write information about the current locale
16 environment, or all public locales, to the standard output. For the
17 purposes of this section, a public locale is one provided by the imple‐
18 mentation that is accessible to the application.
19 When locale is invoked without any arguments, it shall summarize the
21 current locale environment for each locale category as determined by
22 the settings of the environment variables defined in the Base Defini‐
23 tions volume of IEEE Std 1003.1-2001, Chapter 7, Locale.
24 When invoked with operands, it shall write values that have been
26 assigned to the keywords in the locale categories, as follows:
27 * Specifying a keyword name shall select the named keyword and the
29 category containing that keyword.
30 * Specifying a category name shall select the named category and all
32 keywords in that category.
33
35 The locale utility shall conform to the Base Definitions volume of
36 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
37 The following options shall be supported:
39 -a Write information about all available public locales. The avail‐
41 able locales shall include POSIX, representing the POSIX locale.
42 The manner in which the implementation determines what other
43 locales are available is implementation-defined.
44 -c Write the names of selected locale categories; see the STDOUT
46 section. The -c option increases readability when more than one
47 category is selected (for example, via more than one keyword
48 name or via a category name). It is valid both with and without
49 the -k option.
50 -k Write the names and values of selected keywords. The implementa‐
52 tion may omit values for some keywords; see the OPERANDS sec‐
53 tion.
54 -m Write names of available charmaps; see the Base Definitions vol‐
56 ume of IEEE Std 1003.1-2001, Section 6.1, Portable Character
57 Set.
58
61 The following operand shall be supported:
62 name The name of a locale category as defined in the Base Definitions
64 volume of IEEE Std 1003.1-2001, Chapter 7, Locale, the name of a
65 keyword in a locale category, or the reserved name charmap. The
66 named category or keyword shall be selected for output. If a
67 single name represents both a locale category name and a keyword
68 name in the current locale, the results are unspecified. Other‐
69 wise, both category and keyword names can be specified as name
70 operands, in any sequence. It is implementation-defined whether
71 any keyword values are written for the categories LC_CTYPE and
72 LC_COLLATE .
73
76 Not used.
77
79 None.
80
82 The following environment variables shall affect the execution of
83 locale:
84 LANG Provide a default value for the internationalization variables
86 that are unset or null. (See the Base Definitions volume of
87 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
88 ables for the precedence of internationalization variables used
89 to determine the values of locale categories.)
90 LC_ALL If set to a non-empty string value, override the values of all
92 the other internationalization variables.
93 LC_CTYPE
95 Determine the locale for the interpretation of sequences of
96 bytes of text data as characters (for example, single-byte as
97 opposed to multi-byte characters in arguments and input files).
98 LC_MESSAGES
100 Determine the locale that should be used to affect the format
101 and contents of diagnostic messages written to standard error.
102 NLSPATH
104 Determine the location of message catalogs for the processing of
105 LC_MESSAGES .
106 The application shall ensure that the LANG , LC_* , and NLSPATH envi‐
109 ronment variables specify the current locale environment to be written
110 out; they shall be used if the -a option is not specified.
111
113 Default.
114
116 If locale is invoked without any options or operands, the names and
117 values of the LANG and LC_* environment variables described in this
118 volume of IEEE Std 1003.1-2001 shall be written to the standard output,
119 one variable per line, with LANG first, and each line using the follow‐
120 ing format. Only those variables set in the environment and not over‐
121 ridden by LC_ALL shall be written using this format:
122 "%s=%s\n", <variable_name>, <value>
125 The names of those LC_* variables associated with locale categories
127 defined in this volume of IEEE Std 1003.1-2001 that are not set in the
128 environment or are overridden by LC_ALL shall be written in the follow‐
129 ing format:
130 "%s=\"%s\"\n", <variable_name>, <implied value>
133 The <implied value> shall be the name of the locale that has been
135 selected for that category by the implementation, based on the values
136 in LANG and LC_ALL , as described in the Base Definitions volume of
137 IEEE Std 1003.1-2001, Chapter 8, Environment Variables.
138 The <value> and <implied value> shown above shall be properly quoted
140 for possible later reentry to the shell. The <value> shall not be
141 quoted using double-quotes (so that it can be distinguished by the user
142 from the <implied value> case, which always requires double-quotes).
143 The LC_ALL variable shall be written last, using the first format shown
145 above. If it is not set, it shall be written as:
146 "LC_ALL=\n"
149 If any arguments are specified:
151 1. If the -a option is specified, the names of all the public locales
153 shall be written, each in the following format:
154 "%s\n", <locale name>
157 2. If the -c option is specified, the names of all selected categories
159 shall be written, each in the following format:
160 "%s\n", <category name>
163 If keywords are also selected for writing (see following items), the
165 category name output shall precede the keyword output for that cate‐
166 gory.
167 If the -c option is not specified, the names of the categories shall
169 not be written; only the keywords, as selected by the <name> operand,
170 shall be written.
171 3. If the -k option is specified, the names and values of selected
173 keywords shall be written. If a value is non-numeric, it shall be
174 written in the following format:
175 "%s=\"%s\"\n", <keyword name>, <keyword value>
178 If the keyword was charmap, the name of the charmap (if any) that was
180 specified via the localedef -f option when the locale was created shall
181 be written, with the word charmap as <keyword name>.
182 If a value is numeric, it shall be written in one of the following for‐
184 mats:
185 "%s=%d\n", <keyword name>, <keyword value>
188 "%s=%c%o\n", <keyword name>, <escape character>, <keyword value>
191 "%s=%cx%x\n", <keyword name>, <escape character>, <keyword value>
194 where the <escape character> is that identified by the escape_char key‐
196 word in the current locale; see the Base Definitions volume of
197 IEEE Std 1003.1-2001, Section 7.3, Locale Definition.
198 Compound keyword values (list entries) shall be separated in the output
200 by semicolons. When included in keyword values, the semicolon, the dou‐
201 ble-quote, the backslash, and any control character shall be preceded
202 (escaped) with the escape character.
203 4. If the -k option is not specified, selected keyword values shall be
205 written, each in the following format:
206 "%s\n", <keyword value>
209 If the keyword was charmap, the name of the charmap (if any) that was
211 specified via the localedef -f option when the locale was created shall
212 be written.
213 5. If the -m option is specified, then a list of all available
215 charmaps shall be written, each in the format:
216 "%s\n", <charmap>
219 where <charmap> is in a format suitable for use as the option-argument
221 to the localedef -f option.
222
224 The standard error shall be used only for diagnostic messages.
225
227 None.
228
230 None.
231
233 The following exit values shall be returned:
234 0 All the requested information was found and output successfully.
236 >0 An error occurred.
238
241 Default.
242 The following sections are informative.
244
246 If the LANG environment variable is not set or set to an empty value,
247 or one of the LC_* environment variables is set to an unrecognized
248 value, the actual locales assumed (if any) are implementation-defined
249 as described in the Base Definitions volume of IEEE Std 1003.1-2001,
250 Chapter 8, Environment Variables.
251 Implementations are not required to write out the actual values for
253 keywords in the categories LC_CTYPE and LC_COLLATE ; however, they must
254 write out the categories (allowing an application to determine, for
255 example, which character classes are available).
256
258 In the following examples, the assumption is that locale environment
259 variables are set as follows:
260 LANG=locale_x
263 LC_COLLATE=locale_y
264 The command locale would result in the following output:
266 LANG=locale_x
269 LC_CTYPE="locale_x"
270 LC_COLLATE=locale_y
271 LC_TIME="locale_x"
272 LC_NUMERIC="locale_x"
273 LC_MONETARY="locale_x"
274 LC_MESSAGES="locale_x"
275 LC_ALL=
276 The order of presentation of the categories is not specified by this
278 volume of IEEE Std 1003.1-2001.
279 The command:
281 LC_ALL=POSIX locale -ck decimal_point
284 would produce:
286 LC_NUMERIC
289 decimal_point="."
290 The following command shows an application of locale to determine
292 whether a user-supplied response is affirmative:
293 if printf "%s\n" "$response" | grep -Eq "$(locale yesexpr)"
296 then
297 affirmative processing goes here
298 else
299 non-affirmative processing goes here
300 fi
301
303 The output for categories LC_CTYPE and LC_COLLATE has been made imple‐
304 mentation-defined because there is a questionable value in having a
305 shell script receive an entire array of characters. It is also diffi‐
306 cult to return a logical collation description, short of returning a
307 complete localedef source.
308 The -m option was included to allow applications to query for the exis‐
310 tence of charmaps. The output is a list of the charmaps (implementa‐
311 tion-supplied and user-supplied, if any) on the system.
312 The -c option was included for readability when more than one category
314 is selected (for example, via more than one keyword name or via a cate‐
315 gory name). It is valid both with and without the -k option.
316 The charmap keyword, which returns the name of the charmap (if any)
318 that was used when the current locale was created, was included to
319 allow applications needing the information to retrieve it.
320
322 None.
323
325 localedef , the Base Definitions volume of IEEE Std 1003.1-2001, Sec‐
326 tion 7.3, Locale Definition
327
329 Portions of this text are reprinted and reproduced in electronic form
330 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
331 -- Portable Operating System Interface (POSIX), The Open Group Base
332 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
333 Electrical and Electronics Engineers, Inc and The Open Group. In the
334 event of any discrepancy between this version and the original IEEE and
335 The Open Group Standard, the original IEEE and The Open Group Standard
336 is the referee document. The original Standard can be obtained online
337 at http://www.opengroup.org/unix/online.html .
338IEEE/The Open Group 2003 LOCALE(P)