stdlib/strfmon.3

   1 .\" Copyright (c) 2001 Jeroen Ruigrok van der Werven <asmodai@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/lib/libc/stdlib/strfmon.3,v 1.7 2003/01/06 06:21:25 tjr Exp $
  26 .\"
  27 .Dd October 12, 2002
  28 .Dt STRFMON 3
  29 .Os
  30 .Sh NAME
  31 .Nm strfmon ,
  32 .Nm strfmon_l
  33 .Nd convert monetary value to string
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In monetary.h
  38 .Ft ssize_t
  39 .Fo strfmon
  40 .Fa "char *restrict s"
  41 .Fa "size_t maxsize"
  42 .Fa "const char *restrict format"
  43 .Fa "..."
  44 .Fc
  45 .In monetary.h
  46 .In xlocale.h
  47 .Ft ssize_t
  48 .Fo strfmon_l
  49 .Fa "char *restrict s"
  50 .Fa "size_t maxsize"
  51 .Fa "locale_t loc"
  52 .Fa "const char *restrict format"
  53 .Fa "..."
  54 .Fc
  55 .Sh DESCRIPTION
  56 The
  57 .Fn strfmon
  58 function places characters into the array pointed to by
  59 .Fa s ,
  60 as controlled by the string pointed to by
  61 .Fa format .
  62 No more than
  63 .Fa maxsize
  64 bytes are placed into the array.
  65 .Pp
  66 While the
  67 .Fn strfmon
  68 function uses the current locale, the
  69 .Fn strfmon_l
  70 function may be passed a locale directly. See
  71 .Xr xlocale 3
  72 for more information.
  73 .Pp
  74 The format string is composed of zero or more directives:
  75 ordinary characters (not
  76 .Cm % ) ,
  77 which are copied unchanged to the output stream; and conversion
  78 specifications, each of which results in fetching zero or more subsequent
  79 arguments.
  80 Each conversion specification is introduced by the
  81 .Cm %
  82 character.
  83 After the
  84 .Cm % ,
  85 the following appear in sequence:
  86 .Bl -bullet
  87 .It
  88 Zero or more of the following flags:
  89 .Bl -tag -width "XXX"
  90 .It Cm = Ns Ar f
  91 A
  92 .Sq Cm =
  93 character followed by another character
  94 .Ar f
  95 which is used as the numeric fill character.
  96 .It Cm ^
  97 Do not use grouping characters, regardless of the current locale default.
  98 .It Cm +
  99 Represent positive values by prefixing them with a positive sign,
 100 and negative values by prefixing them with a negative sign.
 101 This is the default.
 102 .It Cm \&(
 103 Enclose negative values in parentheses.
 104 .It Cm \&!
 105 Do not include a currency symbol in the output.
 106 .It Cm \-
 107 Left justify the result.
 108 Only valid when a field width is specified.
 109 .El
 110 .It
 111 An optional minimum field width as a decimal number.
 112 By default, there is no minimum width.
 113 .It
 114 A
 115 .Sq Cm #
 116 sign followed by a decimal number specifying the maximum
 117 expected number of digits after the radix character.
 118 .It
 119 A
 120 .Sq Cm \&.
 121 character followed by a decimal number specifying the number
 122 the number of digits after the radix character.
 123 .It
 124 One of the following conversion specifiers:
 125 .Bl -tag -width "XXX"
 126 .It Cm i
 127 The
 128 .Vt double
 129 argument is formatted as an international monetary amount.
 130 .It Cm n
 131 The
 132 .Vt double
 133 argument is formatted as a national monetary amount.
 134 .It Cm %
 135 A
 136 .Sq Li %
 137 character is written.
 138 .El
 139 .El
 140 .Sh RETURN VALUES
 141 If the total number of resulting bytes, including the terminating
 142 .Dv NULL
 143 byte, is not more than
 144 .Fa maxsize ,
 145 .Fn strfmon
 146 returns the number of bytes placed into the array pointed to by
 147 .Fa s ,
 148 not including the terminating
 149 .Dv NULL
 150 byte.
 151 Otherwise, \-1 is returned,
 152 the contents of the array are indeterminate,
 153 and
 154 .Va errno
 155 is set to indicate the error.
 156 .Sh ERRORS
 157 The
 158 .Fn strfmon
 159 function will fail if:
 160 .Bl -tag -width Er
 161 .It Bq Er E2BIG
 162 Conversion stopped due to lack of space in the buffer.
 163 .It Bq Er EINVAL
 164 The format string is invalid.
 165 .It Bq Er ENOMEM
 166 Not enough memory for temporary buffers.
 167 .El
 168 .Sh SEE ALSO
 169 .Xr localeconv 3 ,
 170 .Xr xlocale 3
 171 .Sh STANDARDS
 172 The
 173 .Fn strfmon
 174 function
 175 conforms to
 176 .St -p1003.1-2001 .
 177 .Sh AUTHORS
 178 .An -nosplit
 179 The
 180 .Fn strfmon
 181 function was implemented by
 182 .An Alexey Zelkin Aq phantom@FreeBSD.org .
 183 .Pp
 184 This manual page was written by
 185 .An Jeroen Ruigrok van der Werven Aq asmodai@FreeBSD.org
 186 based on the standards' text.
 187 .Sh BUGS
 188 The
 189 .Fn strfmon
 190 function does not correctly handle multibyte characters in the
 191 .Fa format
 192 argument.