strfmon - convert monetary value to a string


SYNOPSIS

       #include <monetary.h>

       ssize_t strfmon(char *s, size_t max, const char *format,
       ...);


DESCRIPTION

       The  strfmon()  function  formats  the  specified  amounts
       according to the format specification  format  and  places
       the result in the character array s of size max.

       Ordinary characters in format are copied to s without con­
       version.  Conversion specifiers are introduced  by  a  `%'
       character.  Immediately  following it there can be zero or
       more of the following flags:

       =f     The single-byte character f is used as the  numeric
              fill  character  (to be used with a left precision,
              see below).  When not specified, the space  charac­
              ter is used.

       ^      Do  not  use  any grouping characters that might be
              defined for the current locale. By default,  group­
              ing is enabled.

       ( or + The  (  flag indicates that negative amounts should
              be enclosed between parentheses. The +  flag  indi­
              cates  that  signs should be handled in the default
              way, that is, amounts are preceded by the  locale's
              sign  indication,  e.g.,  nothing for positive, "-"
              for negative.

       !      Omit the currency symbol.

       -      Left justify all fields. The default is right  jus­
              tification.

       Next,  there  may be a field width: a decimal digit string
       specifying a minimum field width in bytes. The default  is
       0.  A result smaller than this width is padded with spaces
       (on the left, unless the left-justify flag was given).

       Next, there may be a left precision of the form  "#"  fol­
       lowed  by  a decimal digit string. If the number of digits
       left of the radix character is smaller than this, the rep­
       resentation  is  padded  on the left with the numeric fill
       character.  Grouping characters are not  counted  in  this
       field width.

       Next,  there may be a right precision of the form "." fol­
       lowed  by  a  decimal  digit  string.  The  amount   being

       prior to formatting.  The  default  is  specified  in  the
       frac_digits  and  int_frac_digits  items  of  the  current
       locale.  If the right precision is 0, no  radix  character
       is  printed.   (The  radix character here is determined by
       LC_MONETARY,  and  may  differ  from  that  specified   by
       LC_NUMERIC.)

       Finally, the conversion specification must be ended with a
       conversion character. The three conversion characters are

       %      (In this case  the  entire  specification  must  be
              exactly  "%%".)   Put a `%' character in the result
              string.

       i      One argument of type double is converted using  the
              locale's international currency format.

       n      One  argument of type double is converted using the
              locale's national currency format.


RETURN VALUE

       The strfmon() function returns the  number  of  characters
       placed  in  the array s, not including the terminating NUL
       character, provided the string, including the  terminating
       NUL, fits.  Otherwise, it sets errno to E2BIG, returns -1,
       and the contents of the array is undefined.


EXAMPLE

       The call
              strfmon(buf, sizeof(buf), "[%^=*#6n] [%=*#6i]",
                      1234.567, 1234.567);
       outputs
              [ fl **1234,57] [ NLG  **1 234,57]
       in the Dutch locale (with fl for "florijnen" and  NLG  for
       Netherlands  Guilders).   The  grouping  character is very
       ugly because it takes as much space as a digit,  while  it
       should  not  take  more  than half that, and will no doubt
       cause confusion.  Surprisingly, the "fl" is  preceded  and
       followed by a space, and "NLG" is preceded by one and fol­
       lowed by two spaces.  This may be  a  bug  in  the  locale
       files.  The  Italian,  Australian,  Swiss  and  Portuguese
       locales yield
              [ L. **1235] [ ITL  **1.235]
              [ $**1234.57] [ AUD **1,234.57]
              [Fr. **1234,57] [CHF  **1.234,57]
              [ **1234$57Esc] [ **1.234$57PTE ]


SEE ALSO

       setlocale(3), sprintf(3), locale(7)


Man(1) output converted with man2html