1STRFMON(3P) POSIX Programmer's Manual STRFMON(3P)
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 strfmon, strfmon_l — convert monetary value to a string
13
15 #include <monetary.h>
16 ssize_t strfmon(char *restrict s, size_t maxsize,
18 const char *restrict format, ...);
19 ssize_t strfmon_l(char *restrict s, size_t maxsize,
20 locale_t locale, const char *restrict format, ...);
21
23 The strfmon() function shall place characters into the array pointed to
24 by s as controlled by the string pointed to by format. No more than
25 maxsize bytes are placed into the array.
26 The format is a character string, beginning and ending in its initial
28 state, if any, that contains two types of objects: plain characters,
29 which are simply copied to the output stream, and conversion specifica‐
30 tions, each of which shall result in the fetching of zero or more argu‐
31 ments which are converted and formatted. The results are undefined if
32 there are insufficient arguments for the format. If the format is
33 exhausted while arguments remain, the excess arguments are simply
34 ignored.
35 The application shall ensure that a conversion specification consists
37 of the following sequence:
38 * A '%' character
40 * Optional flags
42 * Optional field width
44 * Optional left precision
46 * Optional right precision
48 * A required conversion specifier character that determines the con‐
50 version to be performed
51 The strfmon_l() function shall be equivalent to the strfmon() function,
53 except that the locale data used is from the locale represented by
54 locale.
55 Flags
57 One or more of the following optional flags can be specified to control
58 the conversion:
59 =f An '=' followed by a single character f which is used as the
61 numeric fill character. In order to work with precision or
62 width counts, the fill character shall be a single byte charac‐
63 ter; if not, the behavior is undefined. The default numeric
64 fill character is the <space>. This flag does not affect field
65 width filling which always uses the <space>. This flag is
66 ignored unless a left precision (see below) is specified.
67 ^ Do not format the currency amount with grouping characters. The
69 default is to insert the grouping characters if defined for the
70 current locale.
71 + or ( Specify the style of representing positive and negative cur‐
73 rency amounts. Only one of '+' or '(' may be specified. If '+'
74 is specified, the locale's equivalent of '+' and '-' are used
75 (for example, in many locales, the empty string if positive and
76 '-' if negative). If '(' is specified, negative amounts are
77 enclosed within parentheses. If neither flag is specified, the
78 '+' style is used.
79 ! Suppress the currency symbol from the output conversion.
81 - Specify the alignment. If this flag is present the result of
83 the conversion is left-justified (padded to the right) rather
84 than right-justified. This flag shall be ignored unless a field
85 width (see below) is specified.
86 Field Width
88 w A decimal digit string w specifying a minimum field width in
89 bytes in which the result of the conversion is right-justified
90 (or left-justified if the flag '-' is specified). The default
91 is 0.
92 Left Precision
94 #n A '#' followed by a decimal digit string n specifying a maximum
95 number of digits expected to be formatted to the left of the
96 radix character. This option can be used to keep the formatted
97 output from multiple calls to the strfmon() function aligned in
98 the same columns. It can also be used to fill unused positions
99 with a special character as in "$***123.45". This option
100 causes an amount to be formatted as if it has the number of
101 digits specified by n. If more than n digit positions are
102 required, this conversion specification is ignored. Digit
103 positions in excess of those actually required are filled with
104 the numeric fill character (see the =f flag above).
105 If grouping has not been suppressed with the '^' flag, and it
107 is defined for the current locale, grouping separators are
108 inserted before the fill characters (if any) are added. Group‐
109 ing separators are not applied to fill characters even if the
110 fill character is a digit.
111 To ensure alignment, any characters appearing before or after
113 the number in the formatted output such as currency or sign
114 symbols are padded as necessary with <space> characters to make
115 their positive and negative formats an equal length.
116 Right Precision
118 .p A <period> followed by a decimal digit string p specifying the
119 number of digits after the radix character. If the value of the
120 right precision p is 0, no radix character appears. If a right
121 precision is not included, a default specified by the current
122 locale is used. The amount being formatted is rounded to the
123 specified number of digits prior to formatting.
124 Conversion Specifier Characters
126 The conversion specifier characters and their meanings are:
127 i The double argument is formatted according to the locale's
129 international currency format (for example, in the US: USD
130 1,234.56). If the argument is ±Inf or NaN, the result of the
131 conversion is unspecified.
132 n The double argument is formatted according to the locale's
134 national currency format (for example, in the US: $1,234.56).
135 If the argument is ±Inf or NaN, the result of the conversion is
136 unspecified.
137 % Convert to a '%'; no argument is converted. The entire conver‐
139 sion specification shall be %%.
140 Locale Information
142 The LC_MONETARY category of the current locale affects the behavior of
143 this function including the monetary radix character (which may be dif‐
144 ferent from the numeric radix character affected by the LC_NUMERIC cat‐
145 egory), the grouping separator, the currency symbols, and formats. The
146 international currency symbol should be conformant with the
147 ISO 4217:2001 standard.
148 If the value of maxsize is greater than {SSIZE_MAX}, the result is
150 implementation-defined.
151 The behavior is undefined if the locale argument to strfmon_l() is the
153 special locale object LC_GLOBAL_LOCALE or is not a valid locale object
154 handle.
155
157 If the total number of resulting bytes including the terminating null
158 byte is not more than maxsize, these functions shall return the number
159 of bytes placed into the array pointed to by s, not including the ter‐
160 minating NUL character. Otherwise, -1 shall be returned, the contents
161 of the array are unspecified, and errno shall be set to indicate the
162 error.
163
165 These functions shall fail if:
166 E2BIG Conversion stopped due to lack of space in the buffer.
168 The following sections are informative.
170
172 Given a locale for the US and the values 123.45, -123.45, and 3456.781,
173 the following output might be produced. Square brackets ("[]") are used
174 in this example to delimit the output.
175 %n [$123.45] Default formatting
178 [-$123.45]
179 [$3,456.78]
180 %11n [ $123.45] Right align within an 11-character field
182 [ -$123.45]
183 [ $3,456.78]
184 %#5n [ $ 123.45] Aligned columns for values up to 99999
186 [-$ 123.45]
187 [ $ 3,456.78]
188 %=*#5n [ $***123.45] Specify a fill character
190 [-$***123.45]
191 [ $*3,456.78]
192 %=0#5n [ $000123.45] Fill characters do not use grouping
194 [-$000123.45] even if the fill character is a digit
195 [ $03,456.78]
196 %^#5n [ $ 123.45] Disable the grouping separator
198 [-$ 123.45]
199 [ $ 3456.78]
200 %^#5.0n [ $ 123] Round off to whole units
202 [-$ 123]
203 [ $ 3457]
204 %^#5.4n [ $ 123.4500] Increase the precision
206 [-$ 123.4500]
207 [ $ 3456.7810]
208 %(#5n [ $ 123.45 ] Use an alternative pos/neg style
210 [($ 123.45)]
211 [ $ 3,456.78 ]
212 %!(#5n [ 123.45 ] Disable the currency symbol
214 [( 123.45)]
215 [ 3,456.78 ]
216 %-14#5.4n [ $ 123.4500 ] Left-justify the output
218 [-$ 123.4500 ]
219 [ $ 3,456.7810 ]
220 %14#5.4n [ $ 123.4500] Corresponding right-justified output
222 [ -$ 123.4500]
223 [ $ 3,456.7810]
224 See also the EXAMPLES section in fprintf().
226
228 None.
229
231 None.
232
234 Lowercase conversion characters are reserved for future standards use
235 and uppercase for implementation-defined use.
236
238 fprintf(), localeconv()
239 The Base Definitions volume of POSIX.1‐2017, <monetary.h>
241
243 Portions of this text are reprinted and reproduced in electronic form
244 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
245 table Operating System Interface (POSIX), The Open Group Base Specifi‐
246 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
247 Electrical and Electronics Engineers, Inc and The Open Group. In the
248 event of any discrepancy between this version and the original IEEE and
249 The Open Group Standard, the original IEEE and The Open Group Standard
250 is the referee document. The original Standard can be obtained online
251 at http://www.opengroup.org/unix/online.html .
252 Any typographical or formatting errors that appear in this page are
254 most likely to have been introduced during the conversion of the source
255 files to man page format. To report such errors, see https://www.ker‐
256 nel.org/doc/man-pages/reporting_bugs.html .
257IEEE/The Open Group 2017 STRFMON(3P)