STRFMON(3C) Standard C Library Functions STRFMON(3C)

NAME


strfmon, strfmon_l - convert monetary values to string

SYNOPSIS


#include <monetary.h>

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

ssize_t strfmon_l(char *restrict s, size_t maxsize,
locale_t loc, const char *restrict format, ...);

DESCRIPTION


These functions are used to format strings containing numeric quantities
using rules that are specific to a given locale. For example, in the
United States, currencies are formatted using the dollar sign ($) and
include two decimal digits (cents).

Each character from the format is copied to the output buffer supplied by
s. Furthermore, when a percent (%) character is encountered, this
triggers an expansion, as follows:

Immediately following the % character there shall be zero or more flags,
as indicated below:

=f An equals sign followed by a character f is the numeric fill
character, which must be a single byte. The default fill
character is <space>.

^ The carat suppresses the use of grouping characters, even if the
locale indicates their use.

+ The plus sign indicates that positive and negative numbers should
use the locale's positive and negative signs. This may not be
used with the open parenthesis. This behavior is default.

( The open parenthesis indicates that negative numbers should be
enclosed within parenthesis, and no special formatting should be
applied to positive values. This may not be supplied with the
plus sign flag.

! The exclamation point suppresses the output of any currency
symbol.

- The dash specifies that numeric values should be left-justified
within a field width, if a field width is specified.

Next there may appear an optional minimum field width, specified as a
string of decimal digits, indicating a minimum width in bytes of this
fields.

Next there may appear a left precision, as #p, indicating the maximum
number of digits expected to appear left of the radix character. (If a
numeric value does not require this many places, including grouping
separators, then the numeric fill character is used to pad the value to
this many places.)

Next there may appear a right precision, as .p, indicating the minimum
number of digits to appear to to the right of the radix character. If
the value of p is zero, then the radix character is also suppressed.

Finally there shall appear one of the following conversion specifier
characters:

i The next available argument (assumed to be double) is formatted,
using the locale's international currency format. For example, in
the United States, the output might look like "USD 1,234.56".

n The next available argument (assumed to be double) is formatted,
using the locale's national currency format. For example, in the
United States, the output might look like "$1,234.56".

% A single percent character is emitted. In this case, the entire
specifier shall be %%.

Whereas the strfmon() function uses the current locale, the strfmon_l()
function uses the supplied locale loc.

RETURN VALUES


If the conversion was successfully performed, and the entire result
(including the terminating null character) fits in maxsize bytes, then
the number of bytes placed in the buffer (excluding the terminating null
character) is returned.

If the result of expansion exceeds maxsize bytes, then the value -1 is
returned, and errno is set to E2BIG.

NOTES


The result of formatting a value that is not a rational number (e.g.
+NaN) is unspecified.

ATTRIBUTES


See attributes(7) for descriptions of the following attributes:

+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|CSI | Enabled |
+--------------------+-----------------+
|Interface Stability | Standard |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+

SEE ALSO


setlocale(3C), uselocale(3C), locale(3HEAD), attributes(7), standards(7)


illumos June 23, 2014 STRFMON(3C)