1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  13 .\"
  14 .TH STRFMON 3C "Jun 23, 2014"
  15 .SH NAME
  16 strfmon, strfmon_l \- convert monetary values to string
  17 .SH SYNOPSIS
  18 .LP
  19 .nf
  20 #include <monetary.h>
  21 
  22 \fBssize_t\fR \fBstrfmon\fR(\fBchar *restrict\fR \fIs\fR, \fBsize_t\fR \fImaxsize\fR,
  23     \fBconst char *restrict\fR \fIformat\fR, ...);
  24 .fi
  25 .LP
  26 .nf
  27 \fBssize_t\fR \fBstrfmon\fR(\fBchar *restrict\fR \fIs\fR, \fBsize_t\fR \fImaxsize\fR,
  28     \fBlocale_t\fR \fIloc\fR, \fBconst char *restrict\fR \fIformat\fR, ...);
  29 .fi
  30 .SH DESCRIPTION
  31 These functions are used to format strings containing numeric quantities using
  32 rules that are specific to a given locale.  For example, in the United States,
  33 currencies are formatted using the dollar sign
  34 .RB ( $ )
  35 and include two decimal digits (cents).
  36 .LP
  37 Each character from the
  38 .I format
  39 is copied to the output buffer supplied by
  40 .IR s .
  41 Furthermore, when a percent
  42 .RB ( % )
  43 character is encountered, this triggers an expansion, as follows:
  44 .LP
  45 Immediately following the
  46 .B %
  47 character there shall be zero or more flags, as indicated below:
  48 .TP
  49 .BI = f
  50 An equals sign followed by a character
  51 .I f
  52 is the numeric fill
  53 character, which must be a single byte.  The default fill character is <space>.
  54 .TP
  55 .B ^
  56 The carat suppresses the use of grouping characters, even if the
  57 locale indicates their use.
  58 .TP
  59 .B +
  60 The plus sign indicates that positive and negative numbers should use the
  61 locale's positive and negative signs.  This may not be used with the open
  62 parenthesis. This behavior is default.
  63 .TP
  64 .B (
  65 The open parenthesis indicates that negative numbers should be enclosed
  66 within parenthesis, and no special formatting should be applied to positive
  67 values.  This may not be supplied with the plus sign flag.
  68 .TP
  69 .B !
  70 The exclamation point suppresses the output of any currency symbol.
  71 .TP
  72 .B -
  73 The dash specifies that numeric values should be left-justified
  74 within a field width, if a field width is specified.
  75 .LP
  76 Next there may appear an optional minimum field width, specified as a string of
  77 decimal digits, indicating a minimum width in bytes of this fields.
  78 .LP
  79 Next there may appear a left precision, as
  80 .RI # p ,
  81 indicating the maximum
  82 number of digits expected to appear left of the radix character.  (If a numeric
  83 value does not require this many places, including grouping separators, then
  84 the numeric fill character is used to pad the value to this many places.)
  85 .LP
  86 Next there may appear a right precision, as
  87 .RI . p ,
  88 indicating the minimum
  89 number of digits to appear to to the right of the radix character.  If the
  90 value of
  91 .I p
  92 is zero, then the radix character is also suppressed.
  93 .LP
  94 Finally there shall appear one of the following conversion specifier
  95 characters:
  96 .TP
  97 .B i
  98 The next available argument (assumed to be
  99 .BR double )
 100 is formatted, using
 101 the locale's international currency format.  For example, in the United States,
 102 the output might look like "USD 1,234.56".
 103 .TP
 104 .B n
 105 The next available argument (assumed to be
 106 .BR double )
 107 is formatted, using
 108 the locale's national currency format.  For example, in the United States, the
 109 output might look like "$1,234.56".
 110 .TP
 111 .B %
 112 A single percent character is emitted.  In this case, the entire specifier
 113 shall be
 114 .BR %% .
 115 .LP
 116 Whereas the
 117 .B strfmon()
 118 function uses the current locale, the
 119 .B strfmon_l()
 120 function uses the supplied locale
 121 .IR loc .
 122 .SH RETURN VALUES
 123 .LP
 124 If the conversion was successfully performed, and the entire result (including
 125 the terminating null character) fits in
 126 .I maxsize
 127 bytes, then the number of
 128 bytes placed in the buffer (excluding the terminating null character) is
 129 returned.
 130 .LP
 131 If the result of expansion exceeds
 132 .I maxsize
 133 bytes, then the value \(mi1 is returned, and
 134 .I errno
 135 is set to
 136 .BR E2BIG .
 137 .SH NOTES
 138 The result of formatting a value that is not a rational number (e.g. +NaN) is
 139 unspecified.
 140 .SH ATTRIBUTES
 141 .LP
 142 See
 143 .BR attributes (5)
 144 for descriptions of the following attributes:
 145 .TS
 146 box;
 147 c | c
 148 l | l .
 149 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 150 _
 151 CSI     Enabled
 152 _
 153 Interface Stability     Standard
 154 _
 155 MT-Level        MT-Safe
 156 .TE
 157 
 158 .SH SEE ALSO
 159 .BR setlocale (3C),
 160 .BR uselocale (3C),
 161 .BR locale (3HEAD),
 162 .BR attributes (5),
 163 .BR standards (5)
 164