diff options
Diffstat (limited to 'man/man3/strfmon.3')
| -rw-r--r-- | man/man3/strfmon.3 | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/man/man3/strfmon.3 b/man/man3/strfmon.3 new file mode 100644 index 0000000..c3a9cb2 --- /dev/null +++ b/man/man3/strfmon.3 @@ -0,0 +1,209 @@ +'\" t +.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH strfmon 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strfmon, strfmon_l \- convert monetary value to a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <monetary.h> +.P +.BI "ssize_t strfmon(char " s "[restrict ." max "], size_t " max , +.BI " const char *restrict " format ", ...);" +.BI "ssize_t strfmon_l(char " s "[restrict ." max "], size_t " max ", \ +locale_t " locale , +.BI " const char *restrict " format ", ...);" +.fi +.SH DESCRIPTION +The +.BR strfmon () +function formats the specified monetary amount +according to the current locale +and format specification +.I format +and places the +result in the character array +.I s +of size +.IR max . +.P +The +.BR strfmon_l () +function performs the same task, +but uses +the locale specified by +.IR locale . +The behavior of +.BR strfmon_l () +is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.P +Ordinary characters in +.I format +are copied to +.I s +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 \[ha] +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. +.P +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). +.P +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. +.P +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 .) +.P +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 +.IR s , +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 ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strfmon () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR strfmon_l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +The call +.P +.in +4n +.EX +strfmon(buf, sizeof(buf), "[%\[ha]=*#6n] [%=*#6i]", + 1234.567, 1234.567); +.EE +.in +.P +outputs +.P +.in +4n +.EX +[€ **1234,57] [EUR **1 234,57] +.EE +.in +.P +in the +.I nl_NL +locale. +The +.IR de_DE , +.IR de_CH , +.IR en_AU , +and +.I en_GB +locales yield +.P +.in +4n +.EX +[ **1234,57 €] [ **1.234,57 EUR] +[ Fr. **1234.57] [ CHF **1\[aq]234.57] +[ $**1234.57] [ AUD**1,234.57] +[ £**1234.57] [ GBP**1,234.57] +.EE +.in +.SH SEE ALSO +.BR duplocale (3), +.BR setlocale (3), +.BR sprintf (3), +.BR locale (7) |