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

strfmon.3p (10228B)


  1. '\" et
  2. .TH STRFMON "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. strfmon,
  12. strfmon_l
  13. \(em convert monetary value to a string
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <monetary.h>
  18. .P
  19. ssize_t strfmon(char *restrict \fIs\fP, size_t \fImaxsize\fP,
  20. const char *restrict \fIformat\fP, ...);
  21. ssize_t strfmon_l(char *restrict \fIs\fP, size_t \fImaxsize\fP,
  22. locale_t \fIlocale\fP, const char *restrict \fIformat\fP, ...);
  23. .fi
  24. .SH DESCRIPTION
  25. The
  26. \fIstrfmon\fR()
  27. function shall place characters into the array pointed to by
  28. .IR s
  29. as controlled by the string pointed to by
  30. .IR format .
  31. No more than
  32. .IR maxsize
  33. bytes are placed into the array.
  34. .P
  35. The format is a character string, beginning and ending in its
  36. initial state, if any, that contains two types of objects:
  37. \fIplain characters\fP,
  38. which are simply copied to the output stream, and \fIconversion
  39. specifications\fP,
  40. each of which shall result in the fetching of zero or more arguments
  41. which are converted and formatted. The results are undefined if there
  42. are insufficient arguments for the format. If the format is exhausted
  43. while arguments remain, the excess arguments are simply ignored.
  44. .P
  45. The application shall ensure that a conversion specification consists
  46. of the following sequence:
  47. .IP " *" 4
  48. A
  49. .BR '%'
  50. character
  51. .IP " *" 4
  52. Optional flags
  53. .IP " *" 4
  54. Optional field width
  55. .IP " *" 4
  56. Optional left precision
  57. .IP " *" 4
  58. Optional right precision
  59. .IP " *" 4
  60. A required conversion specifier character that determines the
  61. conversion to be performed
  62. .P
  63. The
  64. \fIstrfmon_l\fR()
  65. function shall be equivalent to the
  66. \fIstrfmon\fR()
  67. function, except that the locale data used is from the
  68. locale represented by
  69. .IR locale .
  70. .SS Flags
  71. .P
  72. One or more of the following optional flags can be specified to control
  73. the conversion:
  74. .IP "\fR=\fIf\fR" 8
  75. An
  76. .BR '='
  77. followed by a single character
  78. .IR f
  79. which is used as the numeric fill character. In order to work with
  80. precision or width counts, the fill character shall be a single byte
  81. character; if not, the behavior is undefined. The default numeric fill
  82. character is the
  83. <space>.
  84. This flag does not affect field width filling which always uses the
  85. <space>.
  86. This flag is ignored unless a left precision (see below) is specified.
  87. .IP "\fR^\fR" 8
  88. Do not format the currency amount with grouping characters. The
  89. default is to insert the grouping characters if defined for the current
  90. locale.
  91. .IP "\fR+\fR\ or\ \fR(\fR" 8
  92. Specify the style of representing positive and negative currency
  93. amounts. Only one of
  94. .BR '+'
  95. or
  96. .BR '('
  97. may be specified. If
  98. .BR '+'
  99. is specified, the locale's equivalent of
  100. .BR '+'
  101. and
  102. .BR '\-'
  103. are used (for example, in many locales, the empty string if positive and
  104. .BR '\-'
  105. if negative). If
  106. .BR '('
  107. is specified, negative amounts are enclosed within parentheses. If
  108. neither flag is specified, the
  109. .BR '+'
  110. style is used.
  111. .IP "\fR!\fR" 8
  112. Suppress the currency symbol from the output conversion.
  113. .IP "\fR\-\fR" 8
  114. Specify the alignment. If this flag is present the result of the
  115. conversion is left-justified (padded to the right) rather than
  116. right-justified. This flag shall be ignored unless a field width (see
  117. below) is specified.
  118. .SS "Field Width"
  119. .IP "\fIw\fP" 8
  120. A decimal digit string
  121. .IR w
  122. specifying a minimum field width in bytes in which the result of the
  123. conversion is right-justified (or left-justified if the flag
  124. .BR '\-'
  125. is specified). The default is 0.
  126. .SS "Left Precision"
  127. .IP "\fR#\fIn\fR" 8
  128. A
  129. .BR '#'
  130. followed by a decimal digit string
  131. .IR n
  132. specifying a maximum number of digits expected to be formatted to the
  133. left of the radix character. This option can be used to keep the
  134. formatted output from multiple calls to the
  135. \fIstrfmon\fR()
  136. function aligned in the same columns. It can also be used to fill
  137. unused positions with a special character as in
  138. .BR \(dq$***123.45\(dq .
  139. This option causes an amount to be formatted as if it has the number of
  140. digits specified by
  141. .IR n .
  142. If more than
  143. .IR n
  144. digit positions are required, this conversion specification is ignored.
  145. Digit positions in excess of those actually required are filled with
  146. the numeric fill character (see the \fR=\fIf\fR flag above).
  147. .RS 8
  148. .P
  149. If grouping has not been suppressed with the
  150. .BR '\(ha'
  151. flag, and it is defined for the current locale, grouping separators are
  152. inserted before the fill characters (if any) are added. Grouping
  153. separators are not applied to fill characters even if the fill
  154. character is a digit.
  155. .P
  156. To ensure alignment, any characters appearing before or after the
  157. number in the formatted output such as currency or sign symbols are
  158. padded as necessary with
  159. <space>
  160. characters to make their positive and negative formats an equal length.
  161. .RE
  162. .SS "Right Precision"
  163. .IP "\fR.\fIp\fR" 8
  164. A
  165. <period>
  166. followed by a decimal digit string
  167. .IR p
  168. specifying the number of digits after the radix character. If the
  169. value of the right precision
  170. .IR p
  171. is 0, no radix character appears. If a right precision is not
  172. included, a default specified by the current locale is used. The
  173. amount being formatted is rounded to the specified number of digits
  174. prior to formatting.
  175. .SS "Conversion Specifier Characters"
  176. .P
  177. The conversion specifier characters and their meanings are:
  178. .IP "\fRi\fP" 8
  179. The
  180. .BR double
  181. argument is formatted according to the locale's international currency
  182. format (for example, in the US: USD 1,234.56). If the argument is
  183. \(+-Inf or NaN, the result of the conversion is unspecified.
  184. .IP "\fRn\fP" 8
  185. The
  186. .BR double
  187. argument is formatted according to the locale's national currency
  188. format (for example, in the US: $1,234.56). If the argument is
  189. \(+-Inf or NaN, the result of the conversion is unspecified.
  190. .IP "\fR%\fP" 8
  191. Convert to a
  192. .BR '%' ;
  193. no argument is converted. The entire conversion specification shall be
  194. .BR %% .
  195. .SS "Locale Information"
  196. .P
  197. The
  198. .IR LC_MONETARY
  199. category of the current locale affects the behavior of this function
  200. including the monetary radix character (which may be different from the
  201. numeric radix character affected by the
  202. .IR LC_NUMERIC
  203. category), the grouping separator, the currency symbols, and formats.
  204. The international currency symbol should be conformant with the ISO\ 4217:\|2001 standard.
  205. .P
  206. If the value of
  207. .IR maxsize
  208. is greater than
  209. {SSIZE_MAX},
  210. the result is implementation-defined.
  211. .P
  212. The behavior is undefined if the
  213. .IR locale
  214. argument to
  215. \fIstrfmon_l\fR()
  216. is the special locale object LC_GLOBAL_LOCALE or is not a valid locale
  217. object handle.
  218. .SH "RETURN VALUE"
  219. If the total number of resulting bytes including the terminating null
  220. byte is not more than
  221. .IR maxsize ,
  222. these functions shall return the number of bytes placed into the array
  223. pointed to by
  224. .IR s ,
  225. not including the terminating NUL character. Otherwise, \-1 shall be
  226. returned, the contents of the array are unspecified, and
  227. .IR errno
  228. shall be set to indicate the error.
  229. .SH ERRORS
  230. These functions shall fail if:
  231. .TP
  232. .BR E2BIG
  233. Conversion stopped due to lack of space in the buffer.
  234. .LP
  235. .IR "The following sections are informative."
  236. .SH "EXAMPLES"
  237. Given a locale for the US and the values 123.45, \-123.45, and
  238. 3456.781, the following output might be produced. Square brackets (\c
  239. .BR \(dq[\|]\(dq )
  240. are used in this example to delimit the output.
  241. .sp
  242. .RS 4
  243. .nf
  244. %n [$123.45] \fRDefault formatting\fP
  245. [-$123.45]
  246. [$3,456.78]
  247. .P
  248. %11n [ $123.45] \fRRight align within an 11-character field\fP
  249. [ -$123.45]
  250. [ $3,456.78]
  251. .P
  252. %#5n [ $ 123.45] \fRAligned columns for values up to 99\|999\fP
  253. [-$ 123.45]
  254. [ $ 3,456.78]
  255. .P
  256. %=*#5n [ $***123.45] \fRSpecify a fill character\fP
  257. [-$***123.45]
  258. [ $*3,456.78]
  259. .P
  260. %=0#5n [ $000123.45] \fRFill characters do not use grouping\fP
  261. [-$000123.45] \fReven if the fill character is a digit\fP
  262. [ $03,456.78]
  263. .P
  264. %\(ha#5n [ $ 123.45] \fRDisable the grouping separator\fP
  265. [-$ 123.45]
  266. [ $ 3456.78]
  267. .P
  268. %\(ha#5.0n [ $ 123] \fRRound off to whole units\fP
  269. [-$ 123]
  270. [ $ 3457]
  271. .P
  272. %\(ha#5.4n [ $ 123.4500] \fRIncrease the precision\fP
  273. [-$ 123.4500]
  274. [ $ 3456.7810]
  275. .P
  276. %(#5n [ $ 123.45 ] \fRUse an alternative pos/neg style\fP
  277. [($ 123.45)]
  278. [ $ 3,456.78 ]
  279. .P
  280. %!(#5n [ 123.45 ] \fRDisable the currency symbol\fP
  281. [( 123.45)]
  282. [ 3,456.78 ]
  283. .P
  284. %-14#5.4n [ $ 123.4500 ] \fRLeft-justify the output\fP
  285. [-$ 123.4500 ]
  286. [ $ 3,456.7810 ]
  287. .P
  288. %14#5.4n [ $ 123.4500] \fRCorresponding right-justified output\fP
  289. [ -$ 123.4500]
  290. [ $ 3,456.7810]
  291. .fi
  292. .P
  293. .RE
  294. .P
  295. See also the EXAMPLES section in
  296. \fIfprintf\fR().
  297. .SH "APPLICATION USAGE"
  298. None.
  299. .SH RATIONALE
  300. None.
  301. .SH "FUTURE DIRECTIONS"
  302. Lowercase conversion characters are reserved for future standards use
  303. and uppercase for implementation-defined use.
  304. .SH "SEE ALSO"
  305. .IR "\fIfprintf\fR\^(\|)",
  306. .IR "\fIlocaleconv\fR\^(\|)"
  307. .P
  308. The Base Definitions volume of POSIX.1\(hy2017,
  309. .IR "\fB<monetary.h>\fP"
  310. .\"
  311. .SH COPYRIGHT
  312. Portions of this text are reprinted and reproduced in electronic form
  313. from IEEE Std 1003.1-2017, Standard for Information Technology
  314. -- Portable Operating System Interface (POSIX), The Open Group Base
  315. Specifications Issue 7, 2018 Edition,
  316. Copyright (C) 2018 by the Institute of
  317. Electrical and Electronics Engineers, Inc and The Open Group.
  318. In the event of any discrepancy between this version and the original IEEE and
  319. The Open Group Standard, the original IEEE and The Open Group Standard
  320. is the referee document. The original Standard can be obtained online at
  321. http://www.opengroup.org/unix/online.html .
  322. .PP
  323. Any typographical or formatting errors that appear
  324. in this page are most likely
  325. to have been introduced during the conversion of the source files to
  326. man page format. To report such errors, see
  327. https://www.kernel.org/doc/man-pages/reporting_bugs.html .