strfmon(3C) strfmon(3C)
NAME
strfmon - convert monetary value to string
SYNOPSIS
#include <monetary.h>
ssize_t *strfmon(char *s, size_t max, const char *format, . .
.);
DESCRIPTION
strfmon is part of the X/Open Portability Guide Issue 4
optional Enhanced Internationalization feature group.
strfmon places characters into the array pointed to by s as
controlled by the string pointed to by format. No more than
max bytes are placed into the array.
format contains plain characters that are copied to the output
stream, and conversion specifications, that result in the
fetching of zero or more arguments which are converted and
formatted. The results are undefined if there are insufficient
arguments for the format. If the format is exhausted while
arguments remain, the excess arguments are ignored.
A conversion specification consists of the following:
% character
optional flags
optional field width
optional precision
optional left precision
a conversion character that determines the conversion to
be performed.
Options
The following flags can be specified to control the
conversion:
=f An = followed by a single byte character f which is used
as the numeric fill character. You must represent the
fill character in a single byte to work with precision
and width counts. The default numeric fill character is
Copyright 1994 Novell, Inc. Page 1
strfmon(3C) strfmon(3C)
the space character. This flag does not affect field
width filling which always uses the space character.
This flag is ignored unless a left precision is
specified.
^ Do not format the currency amount with grouping
characters. The default is to insert the grouping
characters if defined for the current locale.
+ Specify the style of representing positive and negative
amounts. You can only specify one of these. If + is
specified, the locale's equivalent of + and - are used.
If ( is specified, negative amounts are enclosed within
parentheses. + is the default.
! Suppress the currency symbol from the output conversion.
- Specify the alignment. If this flag is present all
fields are left-justified rather than right-justified.
w A decimal digit string w specifying a minimum field
width in bytes in which the result of the conversion is
right-justified, or left-justified if the - flag is
specified. The default is zero.
#n a # followed by a decimal digit string n specifying the
maximum number of digits expect to be formatted to the
left of the radix character. Use this option to keep
the formatted output from multiple calls to the strfmon
aligned in the same column. You can also use it to fill
unused positions with a special character as in
$***123.45. This option causes an amount to be
formatted as if it has the number of digits specified by
n. If more than n digit positions are required, this
conversion specification is ignored. Digit positions in
excess of those actually required are filled with the
numeric fill character.
If grouping has not been suppressed with the ^ flag, and
it is defined for the current locale, grouping
separators are inserted before the fill characters (if
any) are added. Grouping separators are not applied to
fill characters even if the fill character is a digit.
Copyright 1994 Novell, Inc. Page 2
strfmon(3C) strfmon(3C)
To ensure alignment, any characters appearing before or
after the number in the formatted output such as
currency or sign symbols are padded as necessary with
space characters to make their positive and negative
formats an equal length.
.p A period followed by a decimal digit string p specifying
the number of digits after the radix character. If the
value of the right precision p is zero, no radix
character appears. If the right precision is not
included, a default specified by the current locale is
used. The amount being formatted is rounded to the
specified number of digits before formatting.
The conversion characters and their meanings are:
i The double argument is formatted according to the
locale's international currency format, for example, USD
1,234.56 for the USA.
n The double argument is formatted according to the
locale's national currency format, for example, USD
$1,234.56 for the USA.
% Convert to a %. No argument is converted. The entire
conversion specification must be %%.
USAGE
The LC_MONETARY category of the program's locale affects the
behavior of this function including the monetary radix
character which may be different from the numeric radix
character affected by this category. It also affects the
grouping separator, the currency symbols, and formats. The
international currency symbols used conform to ISO 4217:1987
standard.
Return Values
strfmon returns -1 and sets errno to ENOSYS.
Errors
In the following conditions, strfmon fails and sets errno to:
ENOSYS The function is not supported
Copyright 1994 Novell, Inc. Page 3
strfmon(3C) strfmon(3C)
E2BIG Conversion stopped because of lack of space in the
buffer.
REFERENCES
monetary(5)
Copyright 1994 Novell, Inc. Page 4