logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

locale.1p (14497B)


  1. '\" et
  2. .TH LOCALE "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. locale
  12. \(em get locale-specific information
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. locale \fB[\fR-a|-m\fB]\fR
  17. .P
  18. locale \fB[\fR-ck\fB] \fIname\fR...
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. .IR locale
  23. utility shall write information about the current locale environment,
  24. or all public locales, to the standard output. For the purposes of
  25. this section, a
  26. .IR "public locale"
  27. is one provided by the implementation that is accessible to the
  28. application.
  29. .P
  30. When
  31. .IR locale
  32. is invoked without any arguments, it shall summarize the current locale
  33. environment for each locale category as determined by the settings of
  34. the environment variables defined in the Base Definitions volume of POSIX.1\(hy2017,
  35. .IR "Chapter 7" ", " "Locale".
  36. .P
  37. When invoked with operands, it shall write values that have been
  38. assigned to the keywords in the locale categories, as follows:
  39. .IP " *" 4
  40. Specifying a keyword name shall select the named keyword and the
  41. category containing that keyword.
  42. .IP " *" 4
  43. Specifying a category name shall select the named category and all
  44. keywords in that category.
  45. .SH OPTIONS
  46. The
  47. .IR locale
  48. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  49. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  50. .P
  51. The following options shall be supported:
  52. .IP "\fB\-a\fP" 10
  53. Write information about all available public locales. The available
  54. locales shall include
  55. .BR POSIX ,
  56. representing the POSIX locale. The manner in which the implementation
  57. determines what other locales are available is
  58. implementation-defined.
  59. .IP "\fB\-c\fP" 10
  60. Write the names of selected locale categories; see the STDOUT section.
  61. The
  62. .BR \-c
  63. option increases readability when more than one category is selected
  64. (for example, via more than one keyword name or via a category name).
  65. It is valid both with and without the
  66. .BR \-k
  67. option.
  68. .IP "\fB\-k\fP" 10
  69. Write the names and values of selected keywords. The implementation
  70. may omit values for some keywords; see the OPERANDS section.
  71. .IP "\fB\-m\fP" 10
  72. Write names of available charmaps; see the Base Definitions volume of POSIX.1\(hy2017,
  73. .IR "Section 6.1" ", " "Portable Character Set".
  74. .SH OPERANDS
  75. The following operand shall be supported:
  76. .IP "\fIname\fR" 10
  77. The name of a locale category as defined in the Base Definitions volume of POSIX.1\(hy2017,
  78. .IR "Chapter 7" ", " "Locale",
  79. the name of a keyword in a locale category, or the reserved name
  80. .BR charmap .
  81. The named category or keyword shall be selected for output. If a
  82. single
  83. .IR name
  84. represents both a locale category name and a keyword name in the
  85. current locale, the results are unspecified. Otherwise, both category
  86. and keyword names can be specified as
  87. .IR name
  88. operands, in any sequence. It is implementation-defined whether any
  89. keyword values are written for the categories
  90. .IR LC_CTYPE
  91. and
  92. .IR LC_COLLATE .
  93. .SH STDIN
  94. Not used.
  95. .SH "INPUT FILES"
  96. None.
  97. .SH "ENVIRONMENT VARIABLES"
  98. The following environment variables shall affect the execution of
  99. .IR locale :
  100. .IP "\fILANG\fP" 10
  101. Provide a default value for the internationalization variables that are
  102. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  103. .IR "Section 8.2" ", " "Internationalization Variables"
  104. for the precedence of internationalization variables used to determine
  105. the values of locale categories.)
  106. .IP "\fILC_ALL\fP" 10
  107. If set to a non-empty string value, override the values of all the
  108. other internationalization variables.
  109. .IP "\fILC_CTYPE\fP" 10
  110. Determine the locale for the interpretation of sequences of bytes of
  111. text data as characters (for example, single-byte as opposed to
  112. multi-byte characters in arguments and input files).
  113. .IP "\fILC_MESSAGES\fP" 10
  114. .br
  115. Determine the locale that should be used to affect the format and
  116. contents of diagnostic messages written to standard error.
  117. .IP "\fINLSPATH\fP" 10
  118. Determine the location of message catalogs for the processing of
  119. .IR LC_MESSAGES .
  120. .P
  121. The application shall ensure that the
  122. .IR LANG ,
  123. .IR LC_* ,
  124. and
  125. .IR NLSPATH
  126. environment variables specify the current locale environment to be
  127. written out; they shall be used if the
  128. .BR \-a
  129. option is not specified.
  130. .SH "ASYNCHRONOUS EVENTS"
  131. Default.
  132. .SH STDOUT
  133. The
  134. .IR LANG
  135. variable shall be written first using the format:
  136. .sp
  137. .RS 4
  138. .nf
  139. "LANG=%s\en", <\fIvalue\fR>
  140. .fi
  141. .P
  142. .RE
  143. .P
  144. If
  145. .IR LANG
  146. is not set or is an empty string, the value is the empty string.
  147. .P
  148. If
  149. .IR locale
  150. is invoked without any options or operands, the names and values of the
  151. .IR LC_*
  152. environment variables described in this volume of POSIX.1\(hy2017 shall be written to the
  153. standard output, one variable per line, and each line using the
  154. following format. Only those variables set in the environment and not
  155. overridden by
  156. .IR LC_ALL
  157. shall be written using this format:
  158. .sp
  159. .RS 4
  160. .nf
  161. "%s=%s\en", <\fIvariable_name\fR>, <\fIvalue\fR>
  162. .fi
  163. .P
  164. .RE
  165. .P
  166. The names of those
  167. .IR LC_*
  168. variables associated with locale categories defined in this volume of POSIX.1\(hy2017 that are
  169. not set in the environment or are overridden by
  170. .IR LC_ALL
  171. shall be written in the following format:
  172. .sp
  173. .RS 4
  174. .nf
  175. "%s=\e"%s\e"\en", <\fIvariable_name\fR>, <\fIimplied value\fR>
  176. .fi
  177. .P
  178. .RE
  179. .P
  180. The <\fIimplied\ value\fP> shall be the name of the locale that has
  181. been selected for that category by the implementation, based on the
  182. values in
  183. .IR LANG
  184. and
  185. .IR LC_ALL ,
  186. as described in the Base Definitions volume of POSIX.1\(hy2017,
  187. .IR "Chapter 8" ", " "Environment Variables".
  188. .P
  189. The <\fIvalue\fP> and <\fIimplied\ value\fP> shown above shall be
  190. properly quoted for possible later reentry to the shell. The
  191. <\fIvalue\fP> shall not be quoted using double-quotes (so that it can
  192. be distinguished by the user from the <\fIimplied\ value\fP> case,
  193. which always requires double-quotes).
  194. .P
  195. The
  196. .IR LC_ALL
  197. variable shall be written last, using the first format shown above. If
  198. it is not set, it shall be written as:
  199. .sp
  200. .RS 4
  201. .nf
  202. "LC_ALL=\en"
  203. .fi
  204. .P
  205. .RE
  206. .P
  207. If any arguments are specified:
  208. .IP " 1." 4
  209. If the
  210. .BR \-a
  211. option is specified, the names of all the public locales shall be
  212. written, each in the following format:
  213. .RS 4
  214. .sp
  215. .RS 4
  216. .nf
  217. "%s\en", <\fIlocale\ name\fR>
  218. .fi
  219. .P
  220. .RE
  221. .RE
  222. .IP " 2." 4
  223. If the
  224. .BR \-c
  225. option is specified, the names of all selected categories shall be
  226. written, each in the following format:
  227. .RS 4
  228. .sp
  229. .RS 4
  230. .nf
  231. "%s\en", <\fIcategory\ name\fR>
  232. .fi
  233. .P
  234. .RE
  235. .P
  236. If keywords are also selected for writing (see following items), the
  237. category name output shall precede the keyword output for that
  238. category.
  239. .P
  240. If the
  241. .BR \-c
  242. option is not specified, the names of the categories shall not be
  243. written; only the keywords, as selected by the <\fIname\fP> operand,
  244. shall be written.
  245. .RE
  246. .IP " 3." 4
  247. If the
  248. .BR \-k
  249. option is specified, the names and values of selected keywords shall be
  250. written. If a value is non-numeric and is not a compound keyword
  251. value, it shall be written in the following format:
  252. .RS 4
  253. .sp
  254. .RS 4
  255. .nf
  256. "%s=\e"%s\e"\en", <\fIkeyword name\fR>, <\fIkeyword value\fR>
  257. .fi
  258. .P
  259. .RE
  260. .P
  261. If a value is a non-numeric compound keyword value, it shall either be
  262. written in the format:
  263. .sp
  264. .RS 4
  265. .nf
  266. "%s=\e"%s\e"\en", <\fIkeyword name\fR>, <\fIkeyword value\fR>
  267. .fi
  268. .P
  269. .RE
  270. .P
  271. where the <\fIkeyword value\fR> is a single string of values separated by
  272. <semicolon>
  273. characters, or it shall be written in the format:
  274. .sp
  275. .RS 4
  276. .nf
  277. "%s=%s\en", <\fIkeyword name\fR>, <\fIkeyword value\fR>
  278. .fi
  279. .P
  280. .RE
  281. .P
  282. where the <\fIkeyword value\fP> is encoded as a set of strings, each
  283. enclosed in double-quotation-marks, separated by
  284. <semicolon>
  285. characters.
  286. .P
  287. If the keyword was
  288. .BR charmap ,
  289. the name of the charmap (if any) that was specified via the
  290. .IR localedef
  291. .BR \-f
  292. option when the locale was created shall be written, with the word
  293. .BR charmap
  294. as <\fIkeyword\ name\fP>.
  295. .P
  296. If a value is numeric, it shall be written in one of the following
  297. formats:
  298. .sp
  299. .RS 4
  300. .nf
  301. "%s=%d\en", <\fIkeyword name\fR>, <\fIkeyword value\fR>
  302. .P
  303. "%s=%c%o\en", <\fIkeyword name\fR>, <\fIescape character\fR>, <\fIkeyword value\fR>
  304. .P
  305. "%s=%cx%x\en", <\fIkeyword name\fR>, <\fIescape character\fR>, <\fIkeyword value\fR>
  306. .fi
  307. .P
  308. .RE
  309. .P
  310. where the <\fIescape\ character\fP> is that identified by the
  311. .BR escape_char
  312. keyword in the current locale; see the Base Definitions volume of POSIX.1\(hy2017,
  313. .IR "Section 7.3" ", " "Locale Definition".
  314. .P
  315. Compound keyword values (list entries) shall be separated in the output by
  316. <semicolon>
  317. characters. When included in keyword values, the
  318. <semicolon>,
  319. <backslash>,
  320. double-quote, and any control character shall be preceded (escaped)
  321. with the escape character.
  322. .RE
  323. .IP " 4." 4
  324. If the
  325. .BR \-k
  326. option is not specified, selected keyword values shall be written, each
  327. in the following format:
  328. .RS 4
  329. .sp
  330. .RS 4
  331. .nf
  332. "%s\en", <\fIkeyword value\fR>
  333. .fi
  334. .P
  335. .RE
  336. .P
  337. If the keyword was
  338. .BR charmap ,
  339. the name of the charmap (if any) that was specified via the
  340. .IR localedef
  341. .BR \-f
  342. option when the locale was created shall be written.
  343. .RE
  344. .IP " 5." 4
  345. If the
  346. .BR \-m
  347. option is specified, then a list of all available charmaps shall be
  348. written, each in the format:
  349. .RS 4
  350. .sp
  351. .RS 4
  352. .nf
  353. "%s\en", <\fIcharmap\fR>
  354. .fi
  355. .P
  356. .RE
  357. .P
  358. where <\fIcharmap\fP> is in a format suitable for use as the
  359. option-argument to the
  360. .IR localedef
  361. .BR \-f
  362. option.
  363. .RE
  364. .SH STDERR
  365. The standard error shall be used only for diagnostic messages.
  366. .SH "OUTPUT FILES"
  367. None.
  368. .SH "EXTENDED DESCRIPTION"
  369. None.
  370. .SH "EXIT STATUS"
  371. The following exit values shall be returned:
  372. .IP "\00" 6
  373. All the requested information was found and output successfully.
  374. .IP >0 6
  375. An error occurred.
  376. .SH "CONSEQUENCES OF ERRORS"
  377. Default.
  378. .LP
  379. .IR "The following sections are informative."
  380. .SH "APPLICATION USAGE"
  381. If the
  382. .IR LANG
  383. environment variable is not set or set to an empty value, or one of the
  384. .IR LC_*
  385. environment variables is set to an unrecognized value, the actual
  386. locales assumed (if any) are implementation-defined as described in the Base Definitions volume of POSIX.1\(hy2017,
  387. .IR "Chapter 8" ", " "Environment Variables".
  388. .P
  389. Implementations are not required to write out the actual values for
  390. keywords in the categories
  391. .IR LC_CTYPE
  392. and
  393. .IR LC_COLLATE ;
  394. however, they must write out the categories (allowing an application to
  395. determine, for example, which character classes are available).
  396. .SH EXAMPLES
  397. In the following examples, the assumption is that locale environment
  398. variables are set as follows:
  399. .sp
  400. .RS 4
  401. .nf
  402. LANG=locale_x
  403. LC_COLLATE=locale_y
  404. .fi
  405. .P
  406. .RE
  407. .P
  408. The command
  409. .IR locale
  410. would result in the following output:
  411. .sp
  412. .RS 4
  413. .nf
  414. LANG=locale_x
  415. LC_CTYPE="locale_x"
  416. LC_COLLATE=locale_y
  417. LC_TIME="locale_x"
  418. LC_NUMERIC="locale_x"
  419. LC_MONETARY="locale_x"
  420. LC_MESSAGES="locale_x"
  421. LC_ALL=
  422. .fi
  423. .P
  424. .RE
  425. .P
  426. The order of presentation of the categories is not specified by this volume of POSIX.1\(hy2017.
  427. .P
  428. The command:
  429. .sp
  430. .RS 4
  431. .nf
  432. LC_ALL=POSIX locale -ck decimal_point
  433. .fi
  434. .P
  435. .RE
  436. .P
  437. would produce:
  438. .sp
  439. .RS 4
  440. .nf
  441. LC_NUMERIC
  442. decimal_point="."
  443. .fi
  444. .P
  445. .RE
  446. .P
  447. The following command shows an application of
  448. .IR locale
  449. to determine whether a user-supplied response is affirmative:
  450. .sp
  451. .RS 4
  452. .nf
  453. printf \(aqPrompt for response: \(aq
  454. read response
  455. if printf "%s\en$response" | grep -- -Eq "$(locale yesexpr)"
  456. then
  457. affirmative processing goes here
  458. else
  459. non-affirmative processing goes here
  460. fi
  461. .fi
  462. .P
  463. .RE
  464. .SH RATIONALE
  465. The output for categories
  466. .IR LC_CTYPE
  467. and
  468. .IR LC_COLLATE
  469. has been made implementation-defined because there is a questionable
  470. value in having a shell script receive an entire array of characters.
  471. It is also difficult to return a logical collation description, short
  472. of returning a complete
  473. .IR localedef
  474. source.
  475. .P
  476. The
  477. .BR \-m
  478. option was included to allow applications to query for the existence of
  479. charmaps.
  480. The output is a list of the charmaps (implementation-supplied and
  481. user-supplied, if any) on the system.
  482. .P
  483. The
  484. .BR \-c
  485. option was included for readability when more than one category is
  486. selected (for example, via more than one keyword name or via a category
  487. name). It is valid both with and without the
  488. .BR \-k
  489. option.
  490. .P
  491. The
  492. .BR charmap
  493. keyword, which returns the name of the charmap (if any) that was used
  494. when the current locale was created, was included to allow applications
  495. needing the information to retrieve it.
  496. .P
  497. According to the Base Definitions volume of POSIX.1\(hy2017,
  498. .IR "Section 6.1" ", " "Portable Character Set",
  499. the standard requires that all supported locales must have the same
  500. encoding for
  501. <period>
  502. and
  503. <slash>,
  504. because these two characters are used within the locale-independent
  505. pathname resolution sequence. Therefore, it would be an error if
  506. .IR locale
  507. .BR \-a
  508. listed both ASCII and EBCDIC-based locales, since those two encodings
  509. do not share the same representation for either
  510. <period>
  511. or
  512. <slash>.
  513. Any system that supports both environments would be expected to provide two
  514. POSIX locales, one in either codeset, where only the locales appropriate
  515. to the current environment can be visible at a time. In an XSI-compliant
  516. implementation, the
  517. .IR dd
  518. utility is the only portable means for performing conversions between
  519. the two character sets.
  520. .SH "FUTURE DIRECTIONS"
  521. None.
  522. .SH "SEE ALSO"
  523. .IR "\fIlocaledef\fR\^"
  524. .P
  525. The Base Definitions volume of POSIX.1\(hy2017,
  526. .IR "Section 6.1" ", " "Portable Character Set",
  527. .IR "Chapter 7" ", " "Locale",
  528. .IR "Chapter 8" ", " "Environment Variables",
  529. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  530. .\"
  531. .SH COPYRIGHT
  532. Portions of this text are reprinted and reproduced in electronic form
  533. from IEEE Std 1003.1-2017, Standard for Information Technology
  534. -- Portable Operating System Interface (POSIX), The Open Group Base
  535. Specifications Issue 7, 2018 Edition,
  536. Copyright (C) 2018 by the Institute of
  537. Electrical and Electronics Engineers, Inc and The Open Group.
  538. In the event of any discrepancy between this version and the original IEEE and
  539. The Open Group Standard, the original IEEE and The Open Group Standard
  540. is the referee document. The original Standard can be obtained online at
  541. http://www.opengroup.org/unix/online.html .
  542. .PP
  543. Any typographical or formatting errors that appear
  544. in this page are most likely
  545. to have been introduced during the conversion of the source files to
  546. man page format. To report such errors, see
  547. https://www.kernel.org/doc/man-pages/reporting_bugs.html .