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
13 locale — get locale-specific information
14
16 locale [−a|−m]
17 locale [−ck] name...
19
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 POSIX.1‐2008, 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 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
43 The following options shall be supported:
45 −a Write information about all available public locales. The
47 available locales shall include POSIX, representing the POSIX
48 locale. The manner in which the implementation determines
49 what other 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
53 one category is selected (for example, via more than one key‐
54 word name or via a category name). It is valid both with and
55 without the −k option.
56 −k Write the names and values of selected keywords. The imple‐
58 mentation may omit values for some keywords; see the OPERANDS
59 section.
60 −m Write names of available charmaps; see the Base Definitions
62 volume of POSIX.1‐2008, Section 6.1, Portable Character Set.
63
65 The following operand shall be supported:
66 name The name of a locale category as defined in the Base Defini‐
68 tions volume of POSIX.1‐2008, Chapter 7, Locale, the name of
69 a keyword in a locale category, or the reserved name charmap.
70 The named category or keyword shall be selected for output.
71 If a single name represents both a locale category name and a
72 keyword name in the current locale, the results are unspeci‐
73 fied. Otherwise, both category and keyword names can be spec‐
74 ified as name operands, in any sequence. It is implementa‐
75 tion-defined whether any keyword values are written for the
76 categories LC_CTYPE and LC_COLLATE.
77
79 Not used.
80
82 None.
83
85 The following environment variables shall affect the execution of
86 locale:
87 LANG Provide a default value for the internationalization vari‐
89 ables that are unset or null. (See the Base Definitions vol‐
90 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
91 ables for the precedence of internationalization variables
92 used to determine the values of locale categories.)
93 LC_ALL If set to a non-empty string value, override the values of
95 all the other internationalization variables.
96 LC_CTYPE Determine the locale for the interpretation of sequences of
98 bytes of text data as characters (for example, single-byte as
99 opposed to multi-byte characters in arguments and input
100 files).
101 LC_MESSAGES
103 Determine the locale that should be used to affect the format
104 and contents of diagnostic messages written to standard
105 error.
106 NLSPATH Determine the location of message catalogs for the processing
108 of LC_MESSAGES.
109 The application shall ensure that the LANG, LC_*, and NLSPATH environ‐
111 ment variables specify the current locale environment to be written
112 out; they shall be used if the −a option is not specified.
113
115 Default.
116
118 The LANG variable shall be written first using the format:
119 "LANG=%s\n", <value>
121 If LANG is not set or is an empty string, the value is the empty
123 string.
124 If locale is invoked without any options or operands, the names and
126 values of the LC_* environment variables described in this volume of
127 POSIX.1‐2008 shall be written to the standard output, one variable per
128 line, and each line using the following format. Only those variables
129 set in the environment and not overridden by LC_ALL shall be written
130 using this format:
131 "%s=%s\n", <variable_name>, <value>
133 The names of those LC_* variables associated with locale categories
135 defined in this volume of POSIX.1‐2008 that are not set in the environ‐
136 ment or are overridden by LC_ALL shall be written in the following for‐
137 mat:
138 "%s=\"%s\"\n", <variable_name>, <implied value>
140 The <implied value> shall be the name of the locale that has been
142 selected for that category by the implementation, based on the values
143 in LANG and LC_ALL, as described in the Base Definitions volume of
144 POSIX.1‐2008, Chapter 8, Environment Variables.
145 The <value> and <implied value> shown above shall be properly quoted
147 for possible later reentry to the shell. The <value> shall not be
148 quoted using double-quotes (so that it can be distinguished by the user
149 from the <implied value> case, which always requires double-quotes).
150 The LC_ALL variable shall be written last, using the first format shown
152 above. If it is not set, it shall be written as:
153 "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>
162 2. If the −c option is specified, the names of all selected categories
164 shall be written, each in the following format:
165 "%s\n", <category name>
167 If keywords are also selected for writing (see following items),
169 the category name output shall precede the keyword output for that
170 category.
171 If the −c option is not specified, the names of the categories
173 shall not be written; only the keywords, as selected by the <name>
174 operand, shall be written.
175 3. If the −k option is specified, the names and values of selected
177 keywords shall be written. If a value is non-numeric and is not a
178 compound keyword value, it shall be written in the following for‐
179 mat:
180 "%s=\"%s\"\n", <keyword name>, <keyword value>
182 If a value is a non-numeric compound keyword value, it shall either
184 be written in the format:
185 "%s=\"%s\"\n", <keyword name>, <keyword value>
187 where the <keyword value> is a single string of values separated by
189 <semicolon> characters, or it shall be written in the format:
190 "%s=%s\n", <keyword name>, <keyword value>
192 where the <keyword value> is encoded as a set of strings, each
194 enclosed in double-quotation-marks, separated by <semicolon> char‐
195 acters.
196 If the keyword was charmap, the name of the charmap (if any) that
198 was specified via the localedef −f option when the locale was cre‐
199 ated shall be written, with the word charmap as <keyword name>.
200 If a value is numeric, it shall be written in one of the following
202 formats:
203 "%s=%d\n", <keyword name>, <keyword value>
205 "%s=%c%o\n", <keyword name>, <escape character>, <keyword value>
207 "%s=%cx%x\n", <keyword name>, <escape character>, <keyword value>
209 where the <escape character> is that identified by the escape_char
211 keyword in the current locale; see the Base Definitions volume of
212 POSIX.1‐2008, Section 7.3, Locale Definition.
213 Compound keyword values (list entries) shall be separated in the
215 output by <semicolon> characters. When included in keyword values,
216 the <semicolon>, <backslash>, double-quote, and any control charac‐
217 ter shall be preceded (escaped) with the escape character.
218 4. If the −k option is not specified, selected keyword values shall be
220 written, each in the following format:
221 "%s\n", <keyword value>
223 If the keyword was charmap, the name of the charmap (if any) that
225 was specified via the localedef −f option when the locale was cre‐
226 ated shall be written.
227 5. If the −m option is specified, then a list of all available
229 charmaps shall be written, each in the format:
230 "%s\n", <charmap>
232 where <charmap> is in a format suitable for use as the option-argu‐
234 ment to the localedef −f option.
235
237 The standard error shall be used only for diagnostic messages.
238
240 None.
241
243 None.
244
246 The following exit values shall be returned:
247 0 All the requested information was found and output successfully.
249 >0 An error occurred.
251
253 Default.
254 The following sections are informative.
256
258 If the LANG environment variable is not set or set to an empty value,
259 or one of the LC_* environment variables is set to an unrecognized
260 value, the actual locales assumed (if any) are implementation-defined
261 as described in the Base Definitions volume of POSIX.1‐2008, Chapter 8,
262 Environment Variables.
263 Implementations are not required to write out the actual values for
265 keywords in the categories LC_CTYPE and LC_COLLATE; however, they must
266 write out the categories (allowing an application to determine, for
267 example, which character classes are available).
268
270 In the following examples, the assumption is that locale environment
271 variables are set as follows:
272 LANG=locale_x
274 LC_COLLATE=locale_y
275 The command locale would result in the following output:
277 LANG=locale_x
279 LC_CTYPE="locale_x"
280 LC_COLLATE=locale_y
281 LC_TIME="locale_x"
282 LC_NUMERIC="locale_x"
283 LC_MONETARY="locale_x"
284 LC_MESSAGES="locale_x"
285 LC_ALL=
286 The order of presentation of the categories is not specified by this
288 volume of POSIX.1‐2008.
289 The command:
291 LC_ALL=POSIX locale −ck decimal_point
293 would produce:
295 LC_NUMERIC
297 decimal_point="."
298 The following command shows an application of locale to determine
300 whether a user-supplied response is affirmative:
301 if printf "%s\n$response" | grep −Eq "$(locale yesexpr)"
303 then
304 affirmative processing goes here
305 else
306 non-affirmative processing goes here
307 fi
308
310 The output for categories LC_CTYPE and LC_COLLATE has been made imple‐
311 mentation-defined because there is a questionable value in having a
312 shell script receive an entire array of characters. It is also diffi‐
313 cult to return a logical collation description, short of returning a
314 complete localedef source.
315 The −m option was included to allow applications to query for the exis‐
317 tence of charmaps. The output is a list of the charmaps (implementa‐
318 tion-supplied and user-supplied, if any) on the system.
319 The −c option was included for readability when more than one category
321 is selected (for example, via more than one keyword name or via a cate‐
322 gory name). It is valid both with and without the −k option.
323 The charmap keyword, which returns the name of the charmap (if any)
325 that was used when the current locale was created, was included to
326 allow applications needing the information to retrieve it.
327 According to the Base Definitions volume of POSIX.1‐2008, Section 6.1,
329 Portable Character Set, the standard requires that all supported
330 locales must have the same encoding for <period> and <slash>, because
331 these two characters are used within the locale-independent pathname
332 resolution sequence. Therefore, it would be an error if locale −a
333 listed both ASCII and EBCDIC-based locales, since those two encodings
334 do not share the same representation for either <period> or <slash>.
335 Any system that supports both environments would be expected to provide
336 two POSIX locales, one in either codeset, where only the locales appro‐
337 priate to the current environment can be visible at a time. In an XSI-
338 compliant implementation, the dd utility is the only portable means for
339 performing conversions between the two character sets.
340
342 None.
343
345 localedef
346 The Base Definitions volume of POSIX.1‐2008, Section 6.1, Portable
348 Character Set, Chapter 7, Locale, Chapter 8, Environment Variables,
349 Section 12.2, Utility Syntax Guidelines
350
352 Portions of this text are reprinted and reproduced in electronic form
353 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
354 -- Portable Operating System Interface (POSIX), The Open Group Base
355 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
356 cal and Electronics Engineers, Inc and The Open Group. (This is
357 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
358 event of any discrepancy between this version and the original IEEE and
359 The Open Group Standard, the original IEEE and The Open Group Standard
360 is the referee document. The original Standard can be obtained online
361 at http://www.unix.org/online.html .
362 Any typographical or formatting errors that appear in this page are
364 most likely to have been introduced during the conversion of the source
365 files to man page format. To report such errors, see https://www.ker‐
366 nel.org/doc/man-pages/reporting_bugs.html .
367IEEE/The Open Group 2013 LOCALE(1P)