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
20 The locale utility shall write information about the current locale
21 environment, or all public locales, to the standard output. For the
22 purposes of this section, a public locale is one provided by the imple‐
23 mentation that is accessible to the application.
24 When locale is invoked without any arguments, it shall summarize the
26 current locale environment for each locale category as determined by
27 the settings of the environment variables defined in the Base Defini‐
28 tions volume of POSIX.1‐2017, Chapter 7, Locale.
29 When invoked with operands, it shall write values that have been
31 assigned to the keywords in the locale categories, as follows:
32 * Specifying a keyword name shall select the named keyword and the
34 category containing that keyword.
35 * Specifying a category name shall select the named category and all
37 keywords in that category.
38
40 The locale utility shall conform to the Base Definitions volume of
41 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
42 The following options shall be supported:
44 -a Write information about all available public locales. The
46 available locales shall include POSIX, representing the POSIX
47 locale. The manner in which the implementation determines
48 what other locales are available is implementation-defined.
49 -c Write the names of selected locale categories; see the STDOUT
51 section. The -c option increases readability when more than
52 one category is selected (for example, via more than one key‐
53 word name or via a category name). It is valid both with and
54 without the -k option.
55 -k Write the names and values of selected keywords. The imple‐
57 mentation may omit values for some keywords; see the OPERANDS
58 section.
59 -m Write names of available charmaps; see the Base Definitions
61 volume of POSIX.1‐2017, Section 6.1, Portable Character Set.
62
64 The following operand shall be supported:
65 name The name of a locale category as defined in the Base Defini‐
67 tions volume of POSIX.1‐2017, Chapter 7, Locale, the name of
68 a keyword in a locale category, or the reserved name charmap.
69 The named category or keyword shall be selected for output.
70 If a single name represents both a locale category name and a
71 keyword name in the current locale, the results are unspeci‐
72 fied. Otherwise, both category and keyword names can be spec‐
73 ified as name operands, in any sequence. It is implementa‐
74 tion-defined whether any keyword values are written for the
75 categories LC_CTYPE and LC_COLLATE.
76
78 Not used.
79
81 None.
82
84 The following environment variables shall affect the execution of
85 locale:
86 LANG Provide a default value for the internationalization vari‐
88 ables that are unset or null. (See the Base Definitions vol‐
89 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
90 ables for the precedence of internationalization variables
91 used to determine the values of locale categories.)
92 LC_ALL If set to a non-empty string value, override the values of
94 all the other internationalization variables.
95 LC_CTYPE Determine the locale for the interpretation of sequences of
97 bytes of text data as characters (for example, single-byte as
98 opposed to multi-byte characters in arguments and input
99 files).
100 LC_MESSAGES
102 Determine the locale that should be used to affect the format
103 and contents of diagnostic messages written to standard
104 error.
105 NLSPATH Determine the location of message catalogs for the processing
107 of LC_MESSAGES.
108 The application shall ensure that the LANG, LC_*, and NLSPATH environ‐
110 ment variables specify the current locale environment to be written
111 out; they shall be used if the -a option is not specified.
112
114 Default.
115
117 The LANG variable shall be written first using the format:
118 "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‐2017 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>
134 The names of those LC_* variables associated with locale categories
136 defined in this volume of POSIX.1‐2017 that are not set in the environ‐
137 ment or are overridden by LC_ALL shall be written in the following for‐
138 mat:
139 "%s=\"%s\"\n", <variable_name>, <implied value>
142 The <implied value> shall be the name of the locale that has been
144 selected for that category by the implementation, based on the values
145 in LANG and LC_ALL, as described in the Base Definitions volume of
146 POSIX.1‐2017, Chapter 8, Environment Variables.
147 The <value> and <implied value> shown above shall be properly quoted
149 for possible later reentry to the shell. The <value> shall not be
150 quoted using double-quotes (so that it can be distinguished by the user
151 from the <implied value> case, which always requires double-quotes).
152 The LC_ALL variable shall be written last, using the first format shown
154 above. If it is not set, it shall be written as:
155 "LC_ALL=\n"
158 If any arguments are specified:
160 1. If the -a option is specified, the names of all the public locales
162 shall be written, each in the following format:
163 "%s\n", <locale name>
166 2. If the -c option is specified, the names of all selected categories
168 shall be written, each in the following format:
169 "%s\n", <category name>
172 If keywords are also selected for writing (see following items),
174 the category name output shall precede the keyword output for that
175 category.
176 If the -c option is not specified, the names of the categories
178 shall not be written; only the keywords, as selected by the <name>
179 operand, shall be written.
180 3. If the -k option is specified, the names and values of selected
182 keywords shall be written. If a value is non-numeric and is not a
183 compound keyword value, it shall be written in the following for‐
184 mat:
185 "%s=\"%s\"\n", <keyword name>, <keyword value>
188 If a value is a non-numeric compound keyword value, it shall either
190 be written in the format:
191 "%s=\"%s\"\n", <keyword name>, <keyword value>
194 where the <keyword value> is a single string of values separated by
196 <semicolon> characters, or it shall be written in the format:
197 "%s=%s\n", <keyword name>, <keyword value>
200 where the <keyword value> is encoded as a set of strings, each
202 enclosed in double-quotation-marks, separated by <semicolon> char‐
203 acters.
204 If the keyword was charmap, the name of the charmap (if any) that
206 was specified via the localedef -f option when the locale was cre‐
207 ated shall be written, with the word charmap as <keyword name>.
208 If a value is numeric, it shall be written in one of the following
210 formats:
211 "%s=%d\n", <keyword name>, <keyword value>
214 "%s=%c%o\n", <keyword name>, <escape character>, <keyword value>
216 "%s=%cx%x\n", <keyword name>, <escape character>, <keyword value>
218 where the <escape character> is that identified by the escape_char
220 keyword in the current locale; see the Base Definitions volume of
221 POSIX.1‐2017, Section 7.3, Locale Definition.
222 Compound keyword values (list entries) shall be separated in the
224 output by <semicolon> characters. When included in keyword values,
225 the <semicolon>, <backslash>, double-quote, and any control charac‐
226 ter shall be preceded (escaped) with the escape character.
227 4. If the -k option is not specified, selected keyword values shall be
229 written, each in the following format:
230 "%s\n", <keyword value>
233 If the keyword was charmap, the name of the charmap (if any) that
235 was specified via the localedef -f option when the locale was cre‐
236 ated shall be written.
237 5. If the -m option is specified, then a list of all available
239 charmaps shall be written, each in the format:
240 "%s\n", <charmap>
243 where <charmap> is in a format suitable for use as the option-argu‐
245 ment to the localedef -f option.
246
248 The standard error shall be used only for diagnostic messages.
249
251 None.
252
254 None.
255
257 The following exit values shall be returned:
258 0 All the requested information was found and output successfully.
260 >0 An error occurred.
262
264 Default.
265 The following sections are informative.
267
269 If the LANG environment variable is not set or set to an empty value,
270 or one of the LC_* environment variables is set to an unrecognized
271 value, the actual locales assumed (if any) are implementation-defined
272 as described in the Base Definitions volume of POSIX.1‐2017, Chapter 8,
273 Environment Variables.
274 Implementations are not required to write out the actual values for
276 keywords in the categories LC_CTYPE and LC_COLLATE; however, they must
277 write out the categories (allowing an application to determine, for
278 example, which character classes are available).
279
281 In the following examples, the assumption is that locale environment
282 variables are set as follows:
283 LANG=locale_x
286 LC_COLLATE=locale_y
287 The command locale would result in the following output:
289 LANG=locale_x
292 LC_CTYPE="locale_x"
293 LC_COLLATE=locale_y
294 LC_TIME="locale_x"
295 LC_NUMERIC="locale_x"
296 LC_MONETARY="locale_x"
297 LC_MESSAGES="locale_x"
298 LC_ALL=
299 The order of presentation of the categories is not specified by this
301 volume of POSIX.1‐2017.
302 The command:
304 LC_ALL=POSIX locale -ck decimal_point
307 would produce:
309 LC_NUMERIC
312 decimal_point="."
313 The following command shows an application of locale to determine
315 whether a user-supplied response is affirmative:
316 printf 'Prompt for response: '
319 read response
320 if printf "%s\n$response" | grep -- -Eq "$(locale yesexpr)"
321 then
322 affirmative processing goes here
323 else
324 non-affirmative processing goes here
325 fi
326
328 The output for categories LC_CTYPE and LC_COLLATE has been made imple‐
329 mentation-defined because there is a questionable value in having a
330 shell script receive an entire array of characters. It is also diffi‐
331 cult to return a logical collation description, short of returning a
332 complete localedef source.
333 The -m option was included to allow applications to query for the exis‐
335 tence of charmaps. The output is a list of the charmaps (implementa‐
336 tion-supplied and user-supplied, if any) on the system.
337 The -c option was included for readability when more than one category
339 is selected (for example, via more than one keyword name or via a cate‐
340 gory name). It is valid both with and without the -k option.
341 The charmap keyword, which returns the name of the charmap (if any)
343 that was used when the current locale was created, was included to
344 allow applications needing the information to retrieve it.
345 According to the Base Definitions volume of POSIX.1‐2017, Section 6.1,
347 Portable Character Set, the standard requires that all supported
348 locales must have the same encoding for <period> and <slash>, because
349 these two characters are used within the locale-independent pathname
350 resolution sequence. Therefore, it would be an error if locale -a
351 listed both ASCII and EBCDIC-based locales, since those two encodings
352 do not share the same representation for either <period> or <slash>.
353 Any system that supports both environments would be expected to provide
354 two POSIX locales, one in either codeset, where only the locales appro‐
355 priate to the current environment can be visible at a time. In an XSI-
356 compliant implementation, the dd utility is the only portable means for
357 performing conversions between the two character sets.
358
360 None.
361
363 localedef
364 The Base Definitions volume of POSIX.1‐2017, Section 6.1, Portable
366 Character Set, Chapter 7, Locale, Chapter 8, Environment Variables,
367 Section 12.2, Utility Syntax Guidelines
368
370 Portions of this text are reprinted and reproduced in electronic form
371 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
372 table Operating System Interface (POSIX), The Open Group Base Specifi‐
373 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
374 Electrical and Electronics Engineers, Inc and The Open Group. In the
375 event of any discrepancy between this version and the original IEEE and
376 The Open Group Standard, the original IEEE and The Open Group Standard
377 is the referee document. The original Standard can be obtained online
378 at http://www.opengroup.org/unix/online.html .
379 Any typographical or formatting errors that appear in this page are
381 most likely to have been introduced during the conversion of the source
382 files to man page format. To report such errors, see https://www.ker‐
383 nel.org/doc/man-pages/reporting_bugs.html .
384IEEE/The Open Group 2017 LOCALE(1P)