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

localeconv.3p (11219B)


  1. '\" et
  2. .TH LOCALECONV "3P" 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. localeconv
  12. \(em return locale-specific information
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <locale.h>
  17. .P
  18. struct lconv *localeconv(void);
  19. .fi
  20. .SH DESCRIPTION
  21. The functionality described on this reference page is aligned with the
  22. ISO\ C standard. Any conflict between the requirements described here and the
  23. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  24. .P
  25. The
  26. \fIlocaleconv\fR()
  27. function shall set the components of an object with the type
  28. .BR "struct lconv"
  29. with the values appropriate for the formatting of numeric quantities
  30. (monetary and otherwise) according to the rules of the current locale.
  31. .P
  32. The members of the structure with type
  33. .BR "char *"
  34. are pointers to strings, any of which (except
  35. .BR decimal_point )
  36. can point to
  37. .BR \(dq\^\(dq ,
  38. to indicate that the value is not available in the current locale or is
  39. of zero length. The members with type
  40. .BR char
  41. are non-negative numbers, any of which can be
  42. {CHAR_MAX}
  43. to indicate that the value is not available in the current locale.
  44. .P
  45. The members include the following:
  46. .IP "\fBchar\ *decimal_point\fP" 6
  47. .br
  48. The radix character used to format non-monetary quantities.
  49. .IP "\fBchar\ *thousands_sep\fP" 6
  50. .br
  51. The character used to separate groups of digits before the
  52. decimal-point character in formatted non-monetary quantities.
  53. .IP "\fBchar\ *grouping\fP" 6
  54. .br
  55. A string whose elements taken as one-byte integer values indicate the
  56. size of each group of digits in formatted non-monetary quantities.
  57. .IP "\fBchar\ *int_curr_symbol\fP" 6
  58. .br
  59. The international currency symbol applicable to the current locale.
  60. The first three characters contain the alphabetic international
  61. currency symbol in accordance with those specified in the ISO\ 4217:\|2001 standard. The
  62. fourth character (immediately preceding the null byte) is the character
  63. used to separate the international currency symbol from the monetary
  64. quantity.
  65. .IP "\fBchar\ *currency_symbol\fP" 6
  66. .br
  67. The local currency symbol applicable to the current locale.
  68. .IP "\fBchar\ *mon_decimal_point\fP" 6
  69. .br
  70. The radix character used to format monetary quantities.
  71. .IP "\fBchar\ *mon_thousands_sep\fP" 6
  72. .br
  73. The separator for groups of digits before the decimal-point in
  74. formatted monetary quantities.
  75. .IP "\fBchar\ *mon_grouping\fP" 6
  76. .br
  77. A string whose elements taken as one-byte integer values indicate the
  78. size of each group of digits in formatted monetary quantities.
  79. .IP "\fBchar\ *positive_sign\fP" 6
  80. .br
  81. The string used to indicate a non-negative valued formatted monetary
  82. quantity.
  83. .IP "\fBchar\ *negative_sign\fP" 6
  84. .br
  85. The string used to indicate a negative valued formatted monetary
  86. quantity.
  87. .IP "\fBchar\ int_frac_digits\fP" 6
  88. .br
  89. The number of fractional digits (those after the decimal-point) to be
  90. displayed in an internationally formatted monetary quantity.
  91. .IP "\fBchar\ frac_digits\fP" 6
  92. .br
  93. The number of fractional digits (those after the decimal-point) to be
  94. displayed in a formatted monetary quantity.
  95. .IP "\fBchar\ p_cs_precedes\fP" 6
  96. .br
  97. Set to 1 if the
  98. .BR currency_symbol
  99. precedes the value for a non-negative formatted monetary quantity. Set
  100. to 0 if the symbol succeeds the value.
  101. .IP "\fBchar\ p_sep_by_space\fP" 6
  102. .br
  103. Set to a value indicating the separation of the
  104. .BR currency_symbol ,
  105. the sign string, and the value for a non-negative formatted monetary
  106. quantity.
  107. .IP "\fBchar\ n_cs_precedes\fP" 6
  108. .br
  109. Set to 1 if the
  110. .BR currency_symbol
  111. precedes the value for a negative formatted monetary quantity. Set
  112. to 0 if the symbol succeeds the value.
  113. .IP "\fBchar\ n_sep_by_space\fP" 6
  114. .br
  115. Set to a value indicating the separation of the
  116. .BR currency_symbol ,
  117. the sign string, and the value for a negative formatted monetary
  118. quantity.
  119. .IP "\fBchar\ p_sign_posn\fP" 6
  120. .br
  121. Set to a value indicating the positioning of the
  122. .BR positive_sign
  123. for a non-negative formatted monetary quantity.
  124. .IP "\fBchar\ n_sign_posn\fP" 6
  125. .br
  126. Set to a value indicating the positioning of the
  127. .BR negative_sign
  128. for a negative formatted monetary quantity.
  129. .IP "\fBchar\ int_p_cs_precedes\fP" 6
  130. .br
  131. Set to 1 or 0 if the
  132. .BR int_curr_symbol
  133. respectively precedes or succeeds the value for a non-negative
  134. internationally formatted monetary quantity.
  135. .IP "\fBchar\ int_n_cs_precedes\fP" 6
  136. .br
  137. Set to 1 or 0 if the
  138. .BR int_curr_symbol
  139. respectively precedes or succeeds the value for a negative
  140. internationally formatted monetary quantity.
  141. .IP "\fBchar\ int_p_sep_by_space\fP" 6
  142. .br
  143. Set to a value indicating the separation of the
  144. .BR int_curr_symbol ,
  145. the sign string, and the value for a non-negative internationally
  146. formatted monetary quantity.
  147. .IP "\fBchar\ int_n_sep_by_space\fP" 6
  148. .br
  149. Set to a value indicating the separation of the
  150. .BR int_curr_symbol ,
  151. the sign string, and the value for a negative internationally formatted
  152. monetary quantity.
  153. .IP "\fBchar\ int_p_sign_posn\fP" 6
  154. .br
  155. Set to a value indicating the positioning of the
  156. .BR positive_sign
  157. for a non-negative internationally formatted monetary quantity.
  158. .IP "\fBchar\ int_n_sign_posn\fP" 6
  159. .br
  160. Set to a value indicating the positioning of the
  161. .BR negative_sign
  162. for a negative internationally formatted monetary quantity.
  163. .P
  164. The elements of
  165. .BR grouping
  166. and
  167. .BR mon_grouping
  168. are interpreted according to the following:
  169. .IP {CHAR_MAX} 12
  170. No further grouping is to be performed.
  171. .IP 0 12
  172. The previous element is to be repeatedly used for the remainder of the
  173. digits.
  174. .IP "\fIother\fP" 12
  175. The integer value is the number of digits that comprise the current
  176. group. The next element is examined to determine the size of the next
  177. group of digits before the current group.
  178. .P
  179. The values of
  180. .BR p_sep_by_space ,
  181. .BR n_sep_by_space ,
  182. .BR int_p_sep_by_space ,
  183. and
  184. .BR int_n_sep_by_space
  185. are interpreted according to the following:
  186. .IP 0 6
  187. No space separates the currency symbol and value.
  188. .IP 1 6
  189. If the currency symbol and sign string are adjacent, a space separates
  190. them from the value; otherwise, a space separates the currency symbol
  191. from the value.
  192. .IP 2 6
  193. If the currency symbol and sign string are adjacent, a space separates
  194. them; otherwise, a space separates the sign string from the value.
  195. .P
  196. For
  197. .BR int_p_sep_by_space
  198. and
  199. .BR int_n_sep_by_space ,
  200. the fourth character of
  201. .BR int_curr_symbol
  202. is used instead of a space.
  203. .P
  204. The values of
  205. .BR p_sign_posn ,
  206. .BR n_sign_posn ,
  207. .BR int_p_sign_posn ,
  208. and
  209. .BR int_n_sign_posn
  210. are interpreted according to the following:
  211. .IP 0 6
  212. Parentheses surround the quantity and
  213. .BR currency_symbol
  214. or
  215. .BR int_curr_symbol .
  216. .IP 1 6
  217. The sign string precedes the quantity and
  218. .BR currency_symbol
  219. or
  220. .BR int_curr_symbol .
  221. .IP 2 6
  222. The sign string succeeds the quantity and
  223. .BR currency_symbol
  224. or
  225. .BR int_curr_symbol .
  226. .IP 3 6
  227. The sign string immediately precedes the
  228. .BR currency_symbol
  229. or
  230. .BR int_curr_symbol .
  231. .IP 4 6
  232. The sign string immediately succeeds the
  233. .BR currency_symbol
  234. or
  235. .BR int_curr_symbol .
  236. .P
  237. The implementation shall behave as if no function in this volume of POSIX.1\(hy2017 calls
  238. \fIlocaleconv\fR().
  239. .P
  240. The
  241. \fIlocaleconv\fR()
  242. function need not be thread-safe.
  243. .SH "RETURN VALUE"
  244. The
  245. \fIlocaleconv\fR()
  246. function shall return a pointer to the filled-in object. The application
  247. shall not modify the structure to which the return value points,
  248. nor any storage areas pointed to by pointers within the structure. The
  249. returned pointer, and pointers within the structure, might be
  250. invalidated or
  251. the structure
  252. or the storage areas
  253. might be overwritten by a subsequent call to
  254. \fIlocaleconv\fR().
  255. In addition,
  256. the returned pointer, and pointers within the structure, might be
  257. invalidated or
  258. the structure
  259. or the storage areas
  260. might be overwritten by subsequent calls to
  261. \fIsetlocale\fR()
  262. with the categories LC_ALL, LC_MONETARY, or LC_NUMERIC,
  263. or by calls to
  264. \fIuselocale\fR()
  265. which change the categories LC_MONETARY or LC_NUMERIC. The returned
  266. pointer, pointers within the structure, the structure, and the
  267. storage areas might also be invalidated if the calling thread is
  268. terminated.
  269. .SH ERRORS
  270. No errors are defined.
  271. .LP
  272. .IR "The following sections are informative."
  273. .SH EXAMPLES
  274. None.
  275. .SH "APPLICATION USAGE"
  276. The following table illustrates the rules which may be used by four
  277. countries to format monetary quantities.
  278. .TS
  279. center box tab(!);
  280. cB | cB | cB | cB
  281. l | l | l | l.
  282. Country!Positive Format!Negative Format!International Format
  283. _
  284. Italy!\(eu.1.230!\-\(eu.1.230!EUR.1.230
  285. Netherlands!\(eu 1.234,56!\(eu \-1.234,56!EUR 1.234,56
  286. Norway!kr1.234,56!kr1.234,56\-!NOK 1.234,56
  287. Switzerland!SFrs.1,234.56!SFrs.1,234.56C!CHF 1,234.56
  288. .TE
  289. .P
  290. For these four countries, the respective values for the monetary
  291. members of the structure returned by
  292. \fIlocaleconv\fR()
  293. are:
  294. .TS
  295. center box tab(!);
  296. cB | cB | cB | cB | cB
  297. lb | cf5 | cf5 | cf5 | cf5.
  298. !Italy!Netherlands!Norway!Switzerland
  299. _
  300. int_curr_symbol!"EUR."!"EUR "!"NOK "!"CHF "
  301. currency_symbol!"\(eu."!"\(eu"!"kr"!"SFrs."
  302. mon_decimal_point!""!","!","!"."
  303. mon_thousands_sep!"."!"."!"."!","
  304. mon_grouping!"\e3"!"\e3"!"\e3"!"\e3"
  305. positive_sign!""!""!""!""
  306. negative_sign!"-"!"-"!"-"!"C"
  307. int_frac_digits!0!2!2!2
  308. frac_digits!0!2!2!2
  309. p_cs_precedes!1!1!1!1
  310. p_sep_by_space!0!1!0!0
  311. n_cs_precedes!1!1!1!1
  312. n_sep_by_space!0!1!0!0
  313. p_sign_posn!1!1!1!1
  314. n_sign_posn!1!4!2!2
  315. int_p_cs_precedes!1!1!1!1
  316. int_n_cs_precedes!1!1!1!1
  317. int_p_sep_by_space!0!0!0!0
  318. int_n_sep_by_space!0!0!0!0
  319. int_p_sign_posn!1!1!1!1
  320. int_n_sign_posn!1!4!4!2
  321. .TE
  322. .SH RATIONALE
  323. None.
  324. .SH "FUTURE DIRECTIONS"
  325. None.
  326. .SH "SEE ALSO"
  327. .IR "\fIfprintf\fR\^(\|)",
  328. .IR "\fIfscanf\fR\^(\|)",
  329. .IR "\fIisalpha\fR\^(\|)",
  330. .IR "\fIisascii\fR\^(\|)",
  331. .IR "\fInl_langinfo\fR\^(\|)",
  332. .IR "\fIsetlocale\fR\^(\|)",
  333. .IR "\fIstrcat\fR\^(\|)",
  334. .IR "\fIstrchr\fR\^(\|)",
  335. .IR "\fIstrcmp\fR\^(\|)",
  336. .IR "\fIstrcoll\fR\^(\|)",
  337. .IR "\fIstrcpy\fR\^(\|)",
  338. .IR "\fIstrftime\fR\^(\|)",
  339. .IR "\fIstrlen\fR\^(\|)",
  340. .IR "\fIstrpbrk\fR\^(\|)",
  341. .IR "\fIstrspn\fR\^(\|)",
  342. .IR "\fIstrtok\fR\^(\|)",
  343. .IR "\fIstrxfrm\fR\^(\|)",
  344. .IR "\fIstrtod\fR\^(\|)",
  345. .IR "\fIuselocale\fR\^(\|)"
  346. .P
  347. The Base Definitions volume of POSIX.1\(hy2017,
  348. .IR "\fB<langinfo.h>\fP",
  349. .IR "\fB<locale.h>\fP"
  350. .\"
  351. .SH COPYRIGHT
  352. Portions of this text are reprinted and reproduced in electronic form
  353. from IEEE Std 1003.1-2017, Standard for Information Technology
  354. -- Portable Operating System Interface (POSIX), The Open Group Base
  355. Specifications Issue 7, 2018 Edition,
  356. Copyright (C) 2018 by the Institute of
  357. Electrical and Electronics Engineers, Inc and The Open Group.
  358. In the 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 at
  361. http://www.opengroup.org/unix/online.html .
  362. .PP
  363. Any typographical or formatting errors that appear
  364. in this page are most likely
  365. to have been introduced during the conversion of the source files to
  366. man page format. To report such errors, see
  367. https://www.kernel.org/doc/man-pages/reporting_bugs.html .