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
11

NAME

13       strfmon, strfmon_l — convert monetary value to a string
14

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

158       If  the  total number of resulting bytes including the terminating null
159       byte is not more than maxsize, these functions shall return the  number
160       of  bytes placed into the array pointed to by s, not including the ter‐
161       minating NUL character. Otherwise, −1 shall be returned,  the  contents
162       of  the  array  are unspecified, and errno shall be set to indicate the
163       error.
164

ERRORS

166       These functions shall fail if:
167
168       E2BIG  Conversion stopped due to lack of space in the buffer.
169
170       The following sections are informative.
171

EXAMPLES

173       Given a locale for the US and the values 123.45, −123.45, and 3456.781,
174       the following output might be produced. Square brackets ("[]") are used
175       in this example to delimit the output.
176
177           %n         [$123.45]         Default formatting
178                      [-$123.45]
179                      [$3,456.78]
180
181           %11n       [    $123.45]     Right align within an 11-character field
182                      [   -$123.45]
183                      [  $3,456.78]
184
185           %#5n       [ $   123.45]     Aligned columns for values up to 99999
186                      [-$   123.45]
187                      [ $ 3,456.78]
188
189           %=*#5n     [ $***123.45]     Specify a fill character
190                      [-$***123.45]
191                      [ $*3,456.78]
192
193           %=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
197           %^#5n      [ $  123.45]      Disable the grouping separator
198                      [-$  123.45]
199                      [ $ 3456.78]
200
201           %^#5.0n    [ $  123]         Round off to whole units
202                      [-$  123]
203                      [ $ 3457]
204
205           %^#5.4n    [ $  123.4500]    Increase the precision
206                      [-$  123.4500]
207                      [ $ 3456.7810]
208
209           %(#5n      [ $   123.45 ]    Use an alternative pos/neg style
210                      [($   123.45)]
211                      [ $ 3,456.78 ]
212
213           %!(#5n     [    123.45 ]     Disable the currency symbol
214                      [(   123.45)]
215                      [  3,456.78 ]
216
217           %-14#5.4n  [ $   123.4500 ]  Left-justify the output
218                      [-$   123.4500 ]
219                      [ $ 3,456.7810 ]
220
221           %14#5.4n   [  $   123.4500]  Corresponding right-justified output
222                      [ -$   123.4500]
223                      [  $ 3,456.7810]
224
225       See also the EXAMPLES section in fprintf().
226

APPLICATION USAGE

228       None.
229

RATIONALE

231       None.
232

FUTURE DIRECTIONS

234       Lowercase conversion characters are reserved for future  standards  use
235       and uppercase for implementation-defined use.
236

SEE ALSO

238       fprintf(), localeconv()
239
240       The Base Definitions volume of POSIX.1‐2008, <monetary.h>
241
243       Portions  of  this text are reprinted and reproduced in electronic form
244       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
245       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
246       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
247       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
248       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
249       event of any discrepancy between this version and the original IEEE and
250       The Open Group Standard, the original IEEE and The Open Group  Standard
251       is  the  referee document. The original Standard can be obtained online
252       at http://www.unix.org/online.html .
253
254       Any typographical or formatting errors that appear  in  this  page  are
255       most likely to have been introduced during the conversion of the source
256       files to man page format. To report such errors,  see  https://www.ker
257       nel.org/doc/man-pages/reporting_bugs.html .
258
259
260
261IEEE/The Open Group                  2013                          STRFMON(3P)
Impressum