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