1LOCALE(1P)                 POSIX Programmer's Manual                LOCALE(1P)
2
3
4

PROLOG

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

NAME

12       locale — get locale-specific information
13

SYNOPSIS

15       locale [-a|-m]
16
17       locale [-ck] name...
18

DESCRIPTION

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
25       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
30       When invoked with operands,  it  shall  write  values  that  have  been
31       assigned to the keywords in the locale categories, as follows:
32
33        *  Specifying  a  keyword  name shall select the named keyword and the
34           category containing that keyword.
35
36        *  Specifying a category name shall select the named category and  all
37           keywords in that category.
38

OPTIONS

40       The  locale  utility  shall  conform  to the Base Definitions volume of
41       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
42
43       The following options shall be supported:
44
45       -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
50       -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
56       -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
60       -m        Write  names  of available charmaps; see the Base Definitions
61                 volume of POSIX.1‐2017, Section 6.1, Portable Character Set.
62

OPERANDS

64       The following operand shall be supported:
65
66       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

STDIN

78       Not used.
79

INPUT FILES

81       None.
82

ENVIRONMENT VARIABLES

84       The  following  environment  variables  shall  affect  the execution of
85       locale:
86
87       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
93       LC_ALL    If set to a non-empty string value, override  the  values  of
94                 all the other internationalization variables.
95
96       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
101       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
106       NLSPATH   Determine the location of message catalogs for the processing
107                 of LC_MESSAGES.
108
109       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

ASYNCHRONOUS EVENTS

114       Default.
115

STDOUT

117       The LANG variable shall be written first using the format:
118
119
120           "LANG=%s\n", <value>
121
122       If  LANG  is  not  set  or  is  an empty string, the value is the empty
123       string.
124
125       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
132
133           "%s=%s\n", <variable_name>, <value>
134
135       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
140
141           "%s=\"%s\"\n", <variable_name>, <implied value>
142
143       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
148       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
153       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
156
157           "LC_ALL=\n"
158
159       If any arguments are specified:
160
161        1. If  the -a option is specified, the names of all the public locales
162           shall be written, each in the following format:
163
164
165               "%s\n", <locale name>
166
167        2. If the -c option is specified, the names of all selected categories
168           shall be written, each in the following format:
169
170
171               "%s\n", <category name>
172
173           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
177           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
181        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
186
187               "%s=\"%s\"\n", <keyword name>, <keyword value>
188
189           If a value is a non-numeric compound keyword value, it shall either
190           be written in the format:
191
192
193               "%s=\"%s\"\n", <keyword name>, <keyword value>
194
195           where the <keyword value> is a single string of values separated by
196           <semicolon> characters, or it shall be written in the format:
197
198
199               "%s=%s\n", <keyword name>, <keyword value>
200
201           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
205           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
209           If a value is numeric, it shall be written in one of the  following
210           formats:
211
212
213               "%s=%d\n", <keyword name>, <keyword value>
214
215               "%s=%c%o\n", <keyword name>, <escape character>, <keyword value>
216
217               "%s=%cx%x\n", <keyword name>, <escape character>, <keyword value>
218
219           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
223           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
228        4. If the -k option is not specified, selected keyword values shall be
229           written, each in the following format:
230
231
232               "%s\n", <keyword value>
233
234           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
238        5. If  the  -m  option  is  specified,  then  a  list of all available
239           charmaps shall be written, each in the format:
240
241
242               "%s\n", <charmap>
243
244           where <charmap> is in a format suitable for use as the option-argu‐
245           ment to the localedef -f option.
246

STDERR

248       The standard error shall be used only for diagnostic messages.
249

OUTPUT FILES

251       None.
252

EXTENDED DESCRIPTION

254       None.
255

EXIT STATUS

257       The following exit values shall be returned:
258
259        0    All the requested information was found and output successfully.
260
261       >0    An error occurred.
262

CONSEQUENCES OF ERRORS

264       Default.
265
266       The following sections are informative.
267

APPLICATION USAGE

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
275       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

EXAMPLES

281       In the following examples, the assumption is  that  locale  environment
282       variables are set as follows:
283
284
285           LANG=locale_x
286           LC_COLLATE=locale_y
287
288       The command locale would result in the following output:
289
290
291           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
300       The  order  of  presentation of the categories is not specified by this
301       volume of POSIX.1‐2017.
302
303       The command:
304
305
306           LC_ALL=POSIX locale -ck decimal_point
307
308       would produce:
309
310
311           LC_NUMERIC
312           decimal_point="."
313
314       The following command shows  an  application  of  locale  to  determine
315       whether a user-supplied response is affirmative:
316
317
318           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

RATIONALE

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
334       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
338       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
342       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
346       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

FUTURE DIRECTIONS

360       None.
361

SEE ALSO

363       localedef
364
365       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
380       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 .
384
385
386
387IEEE/The Open Group                  2017                           LOCALE(1P)
Impressum