mirror of https://github.com/mkerrisk/man-pages
169 lines
4.9 KiB
Groff
169 lines
4.9 KiB
Groff
.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl)
|
|
.\"
|
|
.\" This is free documentation; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU General Public License as
|
|
.\" published by the Free Software Foundation; either version 2 of
|
|
.\" the License, or (at your option) any later version.
|
|
.\"
|
|
.\" The GNU General Public License's references to "object code"
|
|
.\" and "executables" are to be interpreted as the output of any
|
|
.\" document formatting or typesetting system, including
|
|
.\" intermediate and printed output.
|
|
.\"
|
|
.\" This manual is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
.\" GNU General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public
|
|
.\" License along with this manual; if not, write to the Free
|
|
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
|
|
.\" USA.
|
|
.\"
|
|
.TH STRFMON 3 2000-12-05 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
strfmon \- convert monetary value to a string
|
|
.SH SYNOPSIS
|
|
.B #include <monetary.h>
|
|
.sp
|
|
.BI "ssize_t strfmon(char *" s ", size_t " max ", const char *" format ,
|
|
.B "...);"
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR strfmon ()
|
|
function formats the specified amounts
|
|
according to the format specification \fIformat\fP and places the
|
|
result in the character array \fIs\fP of size \fImax\fP.
|
|
.PP
|
|
Ordinary characters in \fIformat\fP are copied to \fIs\fP
|
|
without conversion.
|
|
Conversion specifiers are introduced by a \(aq%\(aq
|
|
character.
|
|
Immediately following it there can be zero or more
|
|
of the following flags:
|
|
.TP
|
|
.BI = f
|
|
The single-byte character
|
|
.I 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.
|
|
.TP
|
|
.B ^
|
|
Do not use any grouping characters that might be defined
|
|
for the current locale.
|
|
By default, grouping is enabled.
|
|
.TP
|
|
.BR ( " 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.
|
|
.TP
|
|
.B !
|
|
Omit the currency symbol.
|
|
.TP
|
|
.B \-
|
|
Left justify all fields.
|
|
The default is right justification.
|
|
.LP
|
|
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).
|
|
.LP
|
|
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.
|
|
.LP
|
|
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
|
|
.I frac_digits
|
|
and
|
|
.I 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
|
|
.BR LC_MONETARY ,
|
|
and may differ from that specified by
|
|
.BR LC_NUMERIC .)
|
|
.LP
|
|
Finally, the conversion specification must be ended with a
|
|
conversion character.
|
|
The three conversion characters are
|
|
.TP
|
|
.B %
|
|
(In this case the entire specification must be exactly "%%".)
|
|
Put a \(aq%\(aq character in the result string.
|
|
.TP
|
|
.B i
|
|
One argument of type
|
|
.I double
|
|
is converted using the locale's international currency format.
|
|
.TP
|
|
.B n
|
|
One argument of type
|
|
.I double
|
|
is converted using the locale's national currency format.
|
|
.SH "RETURN VALUE"
|
|
The
|
|
.BR strfmon ()
|
|
function returns the number of characters placed
|
|
in the array \fIs\fP, not including the terminating null byte,
|
|
provided the string, including the terminating null byte, fits.
|
|
Otherwise, it sets
|
|
.I errno
|
|
to
|
|
.BR E2BIG ,
|
|
returns \-1, and the contents of the array is undefined.
|
|
.SH "CONFORMING TO"
|
|
Not in POSIX.1-2001.
|
|
Present on several other systems.
|
|
.SH EXAMPLE
|
|
The call
|
|
.in +4n
|
|
.nf
|
|
|
|
strfmon(buf, sizeof(buf), "[%^=*#6n] [%=*#6i]",
|
|
1234.567, 1234.567);
|
|
|
|
.fi
|
|
.in
|
|
outputs
|
|
.in +4n
|
|
|
|
[ fl **1234,57] [ NLG **1 234,57]
|
|
|
|
.in
|
|
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
|
|
.in +4n
|
|
|
|
[ L. **1235] [ ITL **1.235]
|
|
.br
|
|
[ $**1234.57] [ AUD **1,234.57]
|
|
.br
|
|
[Fr. **1234,57] [CHF **1.234,57]
|
|
.br
|
|
[ **1234$57Esc] [ **1.234$57PTE ]
|
|
.in
|
|
.SH "SEE ALSO"
|
|
.BR setlocale (3),
|
|
.BR sprintf (3),
|
|
.BR locale (7)
|