NAME

       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 conversion.  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 character is used.

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

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

       !      Omit the currency symbol.

       -      Left justify all fields.  The default is right justification.

       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 "#" followed by a decimal digit string.  If the number of
       digits left of the radix character is smaller than this, the representation 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 "." followed by a decimal digit string.  The amount
       being formatted is rounded to the specified number  of  digits  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 null byte, provided the string, including the terminating null  byte,  fits.   Otherwise,  it
       sets errno to E2BIG, returns -1, and the contents of the array is undefined.

CONFORMING TO

       Not in POSIX.1-2001.  Present on several other systems.

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 followed 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)

COLOPHON

       This  page  is  part  of  release 3.54 of the Linux man-pages project.  A description of the project, and
       information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.