man3/strfmon.3

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