1STRFMON(3P)                POSIX Programmer's Manual               STRFMON(3P)
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       strfmon - convert monetary value to a string
13

SYNOPSIS

15       #include <monetary.h>
16
17       ssize_t strfmon(char *restrict s, size_t maxsize,
18              const char *restrict format, ...);
19
20

DESCRIPTION

22       The strfmon() function shall place characters into the array pointed to
23       by  s  as  controlled  by the string pointed to by format. No more than
24       maxsize bytes are placed into the array.
25
26       The format is a character string, beginning and ending in  its  initial
27       state,  if  any,  that contains two types of objects: plain characters,
28       which are simply copied to the output stream, and conversion specifica‐
29       tions, each of which shall result in the fetching of zero or more argu‐
30       ments which are converted and formatted. The results are  undefined  if
31       there  are  insufficient  arguments  for  the  format. If the format is
32       exhausted while arguments  remain,  the  excess  arguments  are  simply
33       ignored.
34
35       The  application  shall ensure that a conversion specification consists
36       of the following sequence:
37
38        * A '%' character
39
40        * Optional flags
41
42        * Optional field width
43
44        * Optional left precision
45
46        * Optional right precision
47
48        * A required conversion specifier character that determines  the  con‐
49          version to be performed
50
51   Flags
52       One or more of the following optional flags can be specified to control
53       the conversion:
54
55       =f     An '=' followed by a single character f which  is  used  as  the
56              numeric fill character. In order to work with precision or width
57              counts, the fill character shall be a single byte character;  if
58              not, the behavior is undefined. The default numeric fill charac‐
59              ter is the <space>. This flag does not affect field width  fill‐
60              ing  which always uses the <space>.  This flag is ignored unless
61              a left precision (see below) is specified.
62
63       ^      Do not format the currency amount with grouping characters.  The
64              default  is to insert the grouping characters if defined for the
65              current locale.
66
67       + or ( Specify the style of representing positive and negative currency
68              amounts.   Only  one  of  '+' or '(' may be specified. If '+' is
69              specified, the locale's equivalent of '+' and '-' are used  (for
70              example,  in  the  U.S., the empty string if positive and '-' if
71              negative). If '(' is specified, negative  amounts  are  enclosed
72              within  parentheses. If neither flag is specified, the '+' style
73              is used.
74
75       !      Suppress the currency symbol from the output conversion.
76
77       -      Specify the alignment. If this flag is present the result of the
78              conversion  is  left-justified (padded to the right) rather than
79              right-justified. This flag shall be ignored unless a field width
80              (see below) is specified.
81
82
83   Field Width
84       w      A  decimal  digit  string  w specifying a minimum field width in
85              bytes in which the result of the conversion  is  right-justified
86              (or  left-justified  if the flag '-' is specified).  The default
87              is 0.
88
89
90   Left Precision
91       #n     A '#' followed by a decimal digit string n specifying a  maximum
92              number  of  digits  expected  to be formatted to the left of the
93              radix character. This option can be used to keep  the  formatted
94              output  from multiple calls to the strfmon() function aligned in
95              the same columns. It can also be used to fill  unused  positions
96              with a special character as in "$***123.45" . This option causes
97              an amount to be formatted as if it  has  the  number  of  digits
98              specified  by  n.  If  more than n digit positions are required,
99              this conversion specification is  ignored.  Digit  positions  in
100              excess  of  those  actually required are filled with the numeric
101              fill character (see the =f flag above).
102
103       If grouping has not been suppressed  with  the  '^'  flag,  and  it  is
104       defined for the current locale, grouping separators are inserted before
105       the fill characters (if any) are added.  Grouping  separators  are  not
106       applied to fill characters even if the fill character is a digit.
107
108       To  ensure alignment, any characters appearing before or after the num‐
109       ber in the formatted output such as currency or sign symbols are padded
110       as  necessary with <space>s to make their positive and negative formats
111       an equal length.
112
113
114   Right Precision
115       .p     A period followed by a decimal digit  string  p  specifying  the
116              number  of digits after the radix character. If the value of the
117              right precision p is 0, no radix character appears. If  a  right
118              precision  is  not  included, a default specified by the current
119              locale is used. The amount being formatted  is  rounded  to  the
120              specified number of digits prior to formatting.
121
122
123   Conversion Specifier Characters
124       The conversion specifier characters and their meanings are:
125
126       i      The  double  argument  is  formatted  according  to the locale's
127              international currency format (for example,  in  the  U.S.:  USD
128              1,234.56).  If  the  argument  is ±Inf or NaN, the result of the
129              conversion is unspecified.
130
131       n      The double argument  is  formatted  according  to  the  locale's
132              national  currency format (for example, in the U.S.: $1,234.56).
133              If the argument is ±Inf or NaN, the result of the conversion  is
134              unspecified.
135
136       %      Convert  to a '%' ; no argument is converted. The entire conver‐
137              sion specification shall be %% .
138
139
140   Locale Information
141       The LC_MONETARY category of the program's locale affects  the  behavior
142       of  this  function including the monetary radix character (which may be
143       different from the numeric radix character affected by  the  LC_NUMERIC
144       category),  the  grouping separator, the currency symbols, and formats.
145       The  international  currency  symbol  should  be  conformant  with  the
146       ISO 4217:1995 standard.
147
148       If  the  value  of  maxsize  is greater than {SSIZE_MAX}, the result is
149       implementation-defined.
150

RETURN VALUE

152       If the total number of resulting bytes including the  terminating  null
153       byte  is  not  more  than maxsize, strfmon() shall return the number of
154       bytes placed into the array pointed to by s, not including  the  termi‐
155       nating  null byte. Otherwise, -1 shall be returned, the contents of the
156       array are unspecified, and errno shall be set to indicate the error.
157

ERRORS

159       The strfmon() function shall fail if:
160
161       E2BIG  Conversion stopped due to lack of space in the buffer.
162
163
164       The following sections are informative.
165

EXAMPLES

167       Given a locale for  the  U.S.  and  the  values  123.45,  -123.45,  and
168       3456.781,  the  following  output  might be produced. Square brackets (
169       "[]" ) are used in this example to delimit the output.
170
171
172              %n         [$123.45]         Default formatting
173                         [-$123.45]
174                         [$3,456.78]
175
176
177              %11n       [    $123.45]     Right align within an 11-character field
178                         [   -$123.45]
179                         [  $3,456.78]
180
181
182              %#5n       [ $   123.45]     Aligned columns for values up to 99999
183                         [-$   123.45]
184                         [ $ 3,456.78]
185
186
187              %=*#5n     [ $***123.45]     Specify a fill character
188                         [-$***123.45]
189                         [ $*3,456.78]
190
191
192              %=0#5n     [ $000123.45]     Fill characters do not use grouping
193                         [-$000123.45]     even if the fill character is a digit
194                         [ $03,456.78]
195
196
197              %^#5n      [ $  123.45]      Disable the grouping separator
198                         [-$  123.45]
199                         [ $ 3456.78]
200
201
202              %^#5.0n    [ $  123]         Round off to whole units
203                         [-$  123]
204                         [ $ 3457]
205
206
207              %^#5.4n    [ $  123.4500]    Increase the precision
208                         [-$  123.4500]
209                         [ $ 3456.7810]
210
211
212              %(#5n      [$   123.45]      Use an alternative pos/neg style
213                         [($   123.45)]
214                         [$ 3,456.78]
215
216
217              %!(#5n     [   123.45]       Disable the currency symbol
218                         [(   123.45)]
219                         [ 3,456.78]
220
221
222              %-14#5.4n  [ $   123.4500 ]  Left-justify the output
223                         [-$   123.4500 ]
224                         [ $ 3,456.7810 ]
225
226
227              %14#5.4n   [  $   123.4500]  Corresponding right-justified output
228                         [ -$   123.4500]
229                         [  $ 3,456.7810]
230
231       See also the EXAMPLES section in fprintf().
232

APPLICATION USAGE

234       None.
235

RATIONALE

237       None.
238

FUTURE DIRECTIONS

240       Lowercase conversion characters are reserved for future  standards  use
241       and uppercase for implementation-defined use.
242

SEE ALSO

244       fprintf(),    localeconv(),    the    Base    Definitions   volume   of
245       IEEE Std 1003.1-2001, <monetary.h>
246
248       Portions of this text are reprinted and reproduced in  electronic  form
249       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
250       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
251       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
252       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
253       event of any discrepancy between this version and the original IEEE and
254       The Open Group Standard, the original IEEE and The Open Group  Standard
255       is  the  referee document. The original Standard can be obtained online
256       at http://www.opengroup.org/unix/online.html .
257
258
259
260IEEE/The Open Group                  2003                          STRFMON(3P)
Impressum