Debian Codegraph @

upstream/debian-unstable/man3/strfmon.3

raw
1 '\" t
2 .\" Copyright 2000, Andries E. Brouwer <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH strfmon 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 strfmon, strfmon_l \- convert monetary value to a string
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <monetary.h>
16 .P
17 .BR "ssize_t strfmon(" "size_t size;"
18 .BI " char " s "[restrict " size "], size_t " size ,
19 .BI " const char *restrict " format ", ...);"
20 .BR "ssize_t strfmon_l(" "size_t size;"
21 .BI " char " s "[restrict " size "], size_t " size ", locale_t " l ,
22 .BI " const char *restrict " format ", ...);"
23 .fi
24 .SH DESCRIPTION
25 The
26 .BR strfmon ()
27 function formats the specified monetary amount
28 according to the current locale
29 and format specification
30 .I format
31 and places the
32 result in the character array
33 .I s
34 of
35 .I size
36 bytes.
37 .P
38 The
39 .BR strfmon_l ()
40 function performs the same task,
41 but uses
42 the locale specified by
43 .IR l .
44 The behavior of
45 .BR strfmon_l ()
46 is undefined if
47 .I l
48 is the special locale object
49 .B LC_GLOBAL_LOCALE
50 (see
51 .BR duplocale (3))
52 or is not a valid locale object handle.
53 .P
54 Ordinary characters in
55 .I format
56 are copied to
57 .I s
58 without conversion.
59 Conversion specifiers are introduced by a \[aq]%\[aq]
60 character.
61 Immediately following it there can be zero or more
62 of the following flags:
63 .TP
64 .BI = f
65 The single-byte character
66 .I f
67 is used as the numeric fill character (to be used with
68 a left precision, see below).
69 When not specified, the space character is used.
70 .TP
71 .B \[ha]
72 Do not use any grouping characters that might be defined
73 for the current locale.
74 By default, grouping is enabled.
75 .TP
76 .BR ( " or " +
77 The ( flag indicates that negative amounts should be enclosed between
78 parentheses.
79 The + flag indicates that signs should be handled
80 in the default way, that is, amounts are preceded by the locale's
81 sign indication, for example, nothing for positive, "\-" for negative.
82 .TP
83 .B !
84 Omit the currency symbol.
85 .TP
86 .B \-
87 Left justify all fields.
88 The default is right justification.
89 .P
90 Next, there may be a field width: a decimal digit string specifying
91 a minimum field width in bytes.
92 The default is 0.
93 A result smaller than this width is padded with spaces
94 (on the left, unless the left-justify flag was given).
95 .P
96 Next, there may be a left precision of the form "#" followed by
97 a decimal digit string.
98 If the number of digits left of the
99 radix character is smaller than this, the representation is
100 padded on the left with the numeric fill character.
101 Grouping characters are not counted in this field width.
102 .P
103 Next, there may be a right precision of the form "." followed by
104 a decimal digit string.
105 The amount being formatted is rounded to
106 the specified number of digits prior to formatting.
107 The default is specified in the
108 .I frac_digits
109 and
110 .I int_frac_digits
111 items of the current locale.
112 If the right precision is 0, no radix character is printed.
113 (The radix character here is determined by
114 .BR LC_MONETARY ,
115 and may differ from that specified by
116 .BR LC_NUMERIC .)
117 .P
118 Finally, the conversion specification must be ended with a
119 conversion character.
120 The three conversion characters are
121 .TP
122 .B %
123 (In this case, the entire specification must be exactly "%%".)
124 Put a \[aq]%\[aq] character in the result string.
125 .TP
126 .B i
127 One argument of type
128 .I double
129 is converted using the locale's international currency format.
130 .TP
131 .B n
132 One argument of type
133 .I double
134 is converted using the locale's national currency format.
135 .SH RETURN VALUE
136 The
137 .BR strfmon ()
138 function returns the number of characters placed
139 in the array
140 .IR s ,
141 not including the terminating null byte,
142 provided the string, including the terminating null byte, fits.
143 Otherwise, it sets
144 .I errno
145 to
146 .BR E2BIG ,
147 returns \-1, and the contents of the array is undefined.
148 .SH ATTRIBUTES
149 For an explanation of the terms used in this section, see
150 .BR attributes (7).
151 .TS
152 allbox;
153 lbx lb lb
154 l l l.
155 Interface Attribute Value
156 T{
157 .na
158 .nh
159 .BR strfmon ()
160 T} Thread safety MT-Safe locale
161 T{
162 .na
163 .nh
164 .BR strfmon_l ()
165 T} Thread safety MT-Safe
166 .TE
167 .SH STANDARDS
168 POSIX.1-2008.
169 .SH HISTORY
170 POSIX.1-2001.
171 .SH EXAMPLES
172 The call
173 .P
174 .in +4n
175 .EX
176 strfmon(buf, sizeof(buf), "[%\[ha]=*#6n] [%=*#6i]",
177 1234.567, 1234.567);
178 .EE
179 .in
180 .P
181 outputs
182 .P
183 .in +4n
184 .EX
185 [€ **1234,57] [EUR **1 234,57]
186 .EE
187 .in
188 .P
189 in the
190 .I nl_NL
191 locale.
192 The
193 .IR de_DE ,
194 .IR de_CH ,
195 .IR en_AU ,
196 and
197 .I en_GB
198 locales yield
199 .P
200 .in +4n
201 .EX
202 [ **1234,57 €] [ **1.234,57 EUR]
203 [ Fr.\& **1234.57] [ CHF **1\[aq]234.57]
204 [ $**1234.57] [ AUD**1,234.57]
205 [ £**1234.57] [ GBP**1,234.57]
206 .EE
207 .in
208 .SH SEE ALSO
209 .BR duplocale (3),
210 .BR setlocale (3),
211 .BR sprintf (3),
212 .BR locale (7)