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  2021-03-22 "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 *restrict " s ", size_t " max ,
  32 .BI "                const char *restrict " format ", ...);"
  33 .BI "ssize_t strfmon_l(char *restrict " s ", size_t " max ", locale_t " locale ,
  34 .BI "                const char *restrict " format ", ...);"
  35 .fi
  36 .SH DESCRIPTION
  37 The
  38 .BR strfmon ()
  39 function formats the specified monetary amount
  40 according to the current locale
  41 and format specification
  42 .I format
  43 and places the
  44 result in the character array
  45 .I s
  46 of size
  47 .IR max .
  48 .PP
  49 The
  50 .BR strfmon_l ()
  51 function performs the same task,
  52 but uses
  53 the locale specified by
  54 .IR locale .
  55 The behavior of
  56 .BR strfmon_l ()
  57 is undefined if
  58 .I locale
  59 is the special locale object
  60 .BR LC_GLOBAL_LOCALE
  61 (see
  62 .BR duplocale (3))
  63 or is not a valid locale object handle.
  64 .PP
  65 Ordinary characters in
  66 .I format
  67 are copied to
  68 .I s
  69 without conversion.
  70 Conversion specifiers are introduced by a \(aq%\(aq
  71 character.
  72 Immediately following it there can be zero or more
  73 of the following flags:
  74 .TP
  75 .BI = f
  76 The single-byte character
  77 .I f
  78 is used as the numeric fill character (to be used with
  79 a left precision, see below).
  80 When not specified, the space character is used.
  81 .TP
  82 .B \(ha
  83 Do not use any grouping characters that might be defined
  84 for the current locale.
  85 By default, grouping is enabled.
  86 .TP
  87 .BR ( " or " +
  88 The ( flag indicates that negative amounts should be enclosed between
  89 parentheses.
  90 The + flag indicates that signs should be handled
  91 in the default way, that is, amounts are preceded by the locale's
  92 sign indication, for example, nothing for positive, "\-" for negative.
  93 .TP
  94 .B !
  95 Omit the currency symbol.
  96 .TP
  97 .B \-
  98 Left justify all fields.
  99 The default is right justification.
 100 .PP
 101 Next, there may be a field width: a decimal digit string specifying
 102 a minimum field width in bytes.
 103 The default is 0.
 104 A result smaller than this width is padded with spaces
 105 (on the left, unless the left-justify flag was given).
 106 .PP
 107 Next, there may be a left precision of the form "#" followed by
 108 a decimal digit string.
 109 If the number of digits left of the
 110 radix character is smaller than this, the representation is
 111 padded on the left with the numeric fill character.
 112 Grouping characters are not counted in this field width.
 113 .PP
 114 Next, there may be a right precision of the form "." followed by
 115 a decimal digit string.
 116 The amount being formatted is rounded to
 117 the specified number of digits prior to formatting.
 118 The default is specified in the
 119 .I frac_digits
 120 and
 121 .I int_frac_digits
 122 items of the current locale.
 123 If the right precision is 0, no radix character is printed.
 124 (The radix character here is determined by
 125 .BR LC_MONETARY ,
 126 and may differ from that specified by
 127 .BR LC_NUMERIC .)
 128 .PP
 129 Finally, the conversion specification must be ended with a
 130 conversion character.
 131 The three conversion characters are
 132 .TP
 133 .B %
 134 (In this case, the entire specification must be exactly "%%".)
 135 Put a \(aq%\(aq character in the result string.
 136 .TP
 137 .B i
 138 One argument of type
 139 .I double
 140 is converted using the locale's international currency format.
 141 .TP
 142 .B n
 143 One argument of type
 144 .I double
 145 is converted using the locale's national currency format.
 146 .SH RETURN VALUE
 147 The
 148 .BR strfmon ()
 149 function returns the number of characters placed
 150 in the array
 151 .IR s ,
 152 not including the terminating null byte,
 153 provided the string, including the terminating null byte, fits.
 154 Otherwise, it sets
 155 .I errno
 156 to
 157 .BR E2BIG ,
 158 returns \-1, and the contents of the array is undefined.
 159 .SH ATTRIBUTES
 160 For an explanation of the terms used in this section, see
 161 .BR attributes (7).
 162 .ad l
 163 .nh
 164 .TS
 165 allbox;
 166 lbx lb lb
 167 l l l.
 168 Interface       Attribute       Value
 169 T{
 170 .BR strfmon ()
 171 T}      Thread safety   MT-Safe locale
 172 T{
 173 .BR strfmon_l ()
 174 T}      Thread safety   MT-Safe
 175 .TE
 176 .hy
 177 .ad
 178 .sp 1
 179 .SH CONFORMING TO
 180 POSIX.1-2001, POSIX.1-2008.
 181 .SH EXAMPLES
 182 The call
 183 .PP
 184 .in +4n
 185 .EX
 186 strfmon(buf, sizeof(buf), "[%\(ha=*#6n] [%=*#6i]",
 187         1234.567, 1234.567);
 188 .EE
 189 .in
 190 .PP
 191 outputs
 192 .PP
 193 .in +4n
 194 .EX
 195 [€ **1234,57] [EUR **1 234,57]
 196 .EE
 197 .in
 198 .PP
 199 in the
 200 .I nl_NL
 201 locale.
 202 The
 203 .IR de_DE ,
 204 .IR de_CH ,
 205 .IR en_AU ,
 206 and
 207 .I en_GB
 208 locales yield
 209 .PP
 210 .in +4n
 211 .EX
 212 [ **1234,57 €] [ **1.234,57 EUR]
 213 [ Fr. **1234.57] [ CHF **1\(aq234.57]
 214 [ $**1234.57] [ AUD**1,234.57]
 215 [ £**1234.57] [ GBP**1,234.57]
 216 .EE
 217 .in
 218 .SH SEE ALSO
 219 .BR duplocale (3),
 220 .BR setlocale (3),
 221 .BR sprintf (3),
 222 .BR locale (7)