strfmon(3C)strfmon(3C)NAMEstrfmon - convert monetary value to string
SYNOPSIS
Remarks
The ANSI C "" construct denotes a variable length argument list whose
optional [or required] members are given in the associated comment
DESCRIPTION
The function places characters into the array pointed to by s as con‐
trolled by the string pointed to by format. No more than maxsize bytes
are placed into the array.
The format is a character string that contains two types of objects:
plain characters, which are simply copied to the output, and conversion
specifications, each of which results in the fetching of zero or more
arguments that are converted and formatted. The arguments are of type
see the section for details. 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 is the string
flag]...[field_width][right_precision] conversion_character
Each element of the sequence is specified as follows:
Flags
One or more of the following optional flags can be specified to control
the conversion:
An (equal sign) followed by a single character f which is used
as the numeric fill character. The fill character must be
representable in a single byte in order to work with preci‐
sion and width counts. The default numeric fill character is
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 (see below) 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 for representing positive and negative currency
amounts.
Only one of or (plus sign or left parenthesis) may be speci‐
fied. If is specified, the locale's equivalent of + and −
are used (for example, in the locale: an empty string if pos‐
itive and − if negative). If is specified, negative amounts
are enclosed within parentheses. If neither flag is speci‐
fied, the style is used.
Suppress the currency symbol from the output conversion.
A minus sign specifying the alignment.
If this flag is present all fields are left-justified (padded
to the right) rather than right-justified.
Field Width
w A decimal digit string w specifying a minimum field width in
bytes in which the result of the conversion is right-justi‐
fied (or left-justified if the flag − is specified). The
default is zero.
Left Precision
A followed by a decimal digit string n specifying a maximum
number of digits expected to be formatted to the left of the
radix character. This option can be used to keep the format‐
ted output from multiple calls to the aligned in the same
columns. It can also be used 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 numeric
fill character (see the flag above).
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.
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.
Right Precision
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 char‐
acter appears If a right precision is not included, a default
specified by the current locale is used The amount being for‐
matted is rounded to the specified number of digits prior to
formatting.
Conversion Characters
The conversion characters and their meanings are:
The argument is formatted according to the locale's international
currency format (for example, in the locale:
The argument is formatted according to the locale's national cur‐
rency format (for example, in the locale:
Convert to a
no argument is converted. The entire conversion specifica‐
tion must be %%.
Notes
The behavior of the function in a UNIX 2003 conforming application dif‐
fers from its behavior in a non-conforming application. With the con‐
version character the function uses the fourth character of the string
defined in of the current locale instead of a space as a separator for
separating different items in a monetary quantity as dictated by the
values of and Only the first three characters will be taken as the cur‐
rency symbol. As a result, the formatting of internationally formatted
monetary quantities may change.
EXTERNAL INFLUENCES
Locale
The category of the program's locale affects the behavior of this func‐
tion including the monetary radix character (which may be different
from the numeric radix character affected by the category), the group‐
ing separator, the currency symbols and formats.
RETURN VALUE
If the total number of resulting bytes including the terminating null
byte is not more than maxsize, the function returns the number of bytes
placed into the array pointed to by s, not including the terminating
null byte Otherwise, −1 is returned, the contents of the array are
indeterminate, and errno is set to indicate the error.
ERRORS
The function will fail if:
Conversion stopped due to lack of space in the buffer.
EXAMPLES
The following program segment formats the monetary value using the
locale with a left precision of and as the fill character.
char string[31];
double amt = -4321.123;
setlocale(LC_MONETARY, "en_US.roman8");
strfmon(string, 31, "The amount is %=*#5n.", amt);
The string array will contain:
The amount is -$*4,321.12.
As an other example, given the locale of and the values and
───────────────────────────────────────────────────────────────────────────
Conversion Output Comments
Specification
───────────────────────────────────────────────────────────────────────────
%n $123.45 default formatting
-$123.45
$3,456.78
───────────────────────────────────────────────────────────────────────────
%11n $123.45 right align within an 11 character field
-$123.45
$3,456.78
───────────────────────────────────────────────────────────────────────────
%#5n $ 123.45 align columns for values up to 99,999
-$ 123.45
$ 3,456.78
───────────────────────────────────────────────────────────────────────────
%=*#5n $***123.45 specify a fill character
-$***123.45
$*3,456.78
───────────────────────────────────────────────────────────────────────────
%=0#5n $000123.45 fill characters do not use grouping
-$000123.45 even if the fill character is a digit
$03,456.78
───────────────────────────────────────────────────────────────────────────
%^#5n $ 123.45 disable the grouping separator
-$ 123.45
$ 3456.78
───────────────────────────────────────────────────────────────────────────
%^#5.0n $ 123 round off to whole units
-$ 123
$ 3457
───────────────────────────────────────────────────────────────────────────
%^#5.4n $ 123.4500 increase the precision
-$ 123.4500
$ 3456.7810
───────────────────────────────────────────────────────────────────────────
%(#5n $ 123.45 use an alternative positive/negative style
($ 123.45)
$ 3,456.78
───────────────────────────────────────────────────────────────────────────
%!(#5n 123.45 disable the currency symbol
( 123.45)
3,456.78
───────────────────────────────────────────────────────────────────────────
AUTHOR
was developed by HP.
SEE ALSOlocaleconv(3C), thread_safety(5).
STANDARDS CONFORMANCEstrfmon(3C)
