man3/strfmon.3

   1 .\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  23 .\"
  24 .TH STRFMON 3  2017-09-15 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 strfmon, strfmon_l \- convert monetary value to a string
  27 .SH SYNOPSIS
  28 .nf
  29 .B #include <monetary.h>
  30 .PP
  31 .BI "ssize_t strfmon(char *" s ", size_t " max ", const char *" format ,
  32 .B "...);"
  33 .PP
  34 .BI "ssize_t strfmon_l(char *" s ", size_t " max ", locale_t " locale ",
  35 .B const char *" format , "...);"
  36 .fi
  37 .SH DESCRIPTION
  38 The
  39 .BR strfmon ()
  40 function formats the specified monetary amount
  41 according to the current locale
  42 and format specification
  43 .I format
  44 and places the
  45 result in the character array
  46 .I s
  47 of size
  48 .IR max .
  49 .PP
  50 The
  51 .BR strfmon_l ()
  52 function performs the same task,
  53 but uses
  54 the locale specified by
  55 .IR locale .
  56 The behavior of
  57 .BR strfmon_l ()
  58 is undefined if
  59 .I locale
  60 is the special locale object
  61 .BR LC_GLOBAL_LOCALE
  62 (see
  63 .BR duplocale (3))
  64 or is not a valid locale object handle.
  65 .PP
  66 Ordinary characters in
  67 .I format
  68 are copied to
  69 .I s
  70 without conversion.
  71 Conversion specifiers are introduced by a \(aq%\(aq
  72 character.
  73 Immediately following it there can be zero or more
  74 of the following flags:
  75 .TP
  76 .BI = f
  77 The single-byte character
  78 .I f
  79 is used as the numeric fill character (to be used with
  80 a left precision, see below).
  81 When not specified, the space character is used.
  82 .TP
  83 .B ^
  84 Do not use any grouping characters that might be defined
  85 for the current locale.
  86 By default, grouping is enabled.
  87 .TP
  88 .BR ( " or " +
  89 The ( flag indicates that negative amounts should be enclosed between
  90 parentheses.
  91 The + flag indicates that signs should be handled
  92 in the default way, that is, amounts are preceded by the locale's
  93 sign indication, for example, nothing for positive, "\-" for negative.
  94 .TP
  95 .B !
  96 Omit the currency symbol.
  97 .TP
  98 .B \-
  99 Left justify all fields.
 100 The default is right justification.
 101 .PP
 102 Next, there may be a field width: a decimal digit string specifying
 103 a minimum field width in bytes.
 104 The default is 0.
 105 A result smaller than this width is padded with spaces
 106 (on the left, unless the left-justify flag was given).
 107 .PP
 108 Next, there may be a left precision of the form "#" followed by
 109 a decimal digit string.
 110 If the number of digits left of the
 111 radix character is smaller than this, the representation is
 112 padded on the left with the numeric fill character.
 113 Grouping characters are not counted in this field width.
 114 .PP
 115 Next, there may be a right precision of the form "." followed by
 116 a decimal digit string.
 117 The amount being formatted is rounded to
 118 the specified number of digits prior to formatting.
 119 The default is specified in the
 120 .I frac_digits
 121 and
 122 .I int_frac_digits
 123 items of the current locale.
 124 If the right precision is 0, no radix character is printed.
 125 (The radix character here is determined by
 126 .BR LC_MONETARY ,
 127 and may differ from that specified by
 128 .BR LC_NUMERIC .)
 129 .PP
 130 Finally, the conversion specification must be ended with a
 131 conversion character.
 132 The three conversion characters are
 133 .TP
 134 .B %
 135 (In this case, the entire specification must be exactly "%%".)
 136 Put a \(aq%\(aq character in the result string.
 137 .TP
 138 .B i
 139 One argument of type
 140 .I double
 141 is converted using the locale's international currency format.
 142 .TP
 143 .B n
 144 One argument of type
 145 .I double
 146 is converted using the locale's national currency format.
 147 .SH RETURN VALUE
 148 The
 149 .BR strfmon ()
 150 function returns the number of characters placed
 151 in the array
 152 .IR s ,
 153 not including the terminating null byte,
 154 provided the string, including the terminating null byte, fits.
 155 Otherwise, it sets
 156 .I errno
 157 to
 158 .BR E2BIG ,
 159 returns \-1, and the contents of the array is undefined.
 160 .SH ATTRIBUTES
 161 For an explanation of the terms used in this section, see
 162 .BR attributes (7).
 163 .TS
 164 allbox;
 165 lb lb lb
 166 l l l.
 167 Interface       Attribute       Value
 168 T{
 169 .BR strfmon ()
 170 T}      Thread safety   MT-Safe locale
 171 T{
 172 .BR strfmon_l ()
 173 T}      Thread safety   MT-Safe
 174 .TE
 175 .sp 1
 176 .SH CONFORMING TO
 177 POSIX.1-2001, POSIX.1-2008.
 178 .SH EXAMPLE
 179 The call
 180 .PP
 181 .in +4n
 182 .EX
 183 strfmon(buf, sizeof(buf), "[%^=*#6n] [%=*#6i]",
 184         1234.567, 1234.567);
 185 .EE
 186 .in
 187 .PP
 188 outputs
 189 .PP
 190 .in +4n
 191 .EX
 192 [€ **1234,57] [EUR **1 234,57]
 193 .EE
 194 .in
 195 .PP
 196 in the
 197 .I nl_NL
 198 locale.
 199 The
 200 .IR de_DE ,
 201 .IR de_CH ,
 202 .IR en_AU ,
 203 and
 204 .I en_GB
 205 locales yield
 206 .PP
 207 .in +4n
 208 .EX
 209 [ **1234,57 €] [ **1.234,57 EUR]
 210 [ Fr. **1234.57] [ CHF **1'234.57]
 211 [ $**1234.57] [ AUD**1,234.57]
 212 [ £**1234.57] [ GBP**1,234.57]
 213 .EE
 214 .in
 215 .SH SEE ALSO
 216 .BR duplocale (3),
 217 .BR setlocale (3),
 218 .BR sprintf (3),
 219 .BR locale (7)