gdb - Local mods (compile)
[dragonfly.git] / lib / libc / stdlib / strfmon.3
CommitLineData
c6ddf9d0
SW
1.\" Copyright (c) 2001 Jeroen Ruigrok van der Werven <asmodai@FreeBSD.org>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
3d960e09 25.\" $FreeBSD: head/lib/libc/stdlib/strfmon.3 237591 2012-06-26 05:34:31Z joel $
c6ddf9d0 26.\"
94d35d83 27.Dd December 25, 2013
c6ddf9d0
SW
28.Dt STRFMON 3
29.Os
30.Sh NAME
3d960e09
SW
31.Nm strfmon ,
32.Nm strfmon_l
c6ddf9d0
SW
33.Nd convert monetary value to string
34.Sh LIBRARY
35.Lb libc
36.Sh SYNOPSIS
37.In monetary.h
38.Ft ssize_t
39.Fn strfmon "char * restrict s" "size_t maxsize" "const char * restrict format" "..."
3d960e09 40.Ft ssize_t
94d35d83 41.Fn strfmon_l "char * restrict s" "size_t maxsize" "locale_t locale" "const char * restrict format" "..."
c6ddf9d0
SW
42.Sh DESCRIPTION
43The
44.Fn strfmon
45function places characters into the array pointed to by
46.Fa s
47as controlled by the string pointed to by
48.Fa format .
49No more than
50.Fa maxsize
51bytes are placed into the array.
52.Pp
3d960e09
SW
53The
54.Fn strfmon_l
55function does the same as
56.Fn strfmon
94d35d83
SW
57but takes an explicit
58.Fa locale
59rather than using the current locale.
3d960e09 60.Pp
c6ddf9d0
SW
61The format string is composed of zero or more directives:
62ordinary characters (not
63.Cm % ) ,
64which are copied unchanged to the output stream; and conversion
65specifications, each of which results in fetching zero or more subsequent
66arguments.
67Each conversion specification is introduced by the
68.Cm %
69character.
70After the
71.Cm % ,
72the following appear in sequence:
73.Bl -bullet
74.It
75Zero or more of the following flags:
76.Bl -tag -width "XXX"
77.It Cm = Ns Ar f
78A
79.Sq Cm =
80character followed by another character
81.Ar f
82which is used as the numeric fill character.
83.It Cm ^
84Do not use grouping characters, regardless of the current locale default.
85.It Cm +
86Represent positive values by prefixing them with a positive sign,
87and negative values by prefixing them with a negative sign.
88This is the default.
89.It Cm \&(
90Enclose negative values in parentheses.
91.It Cm \&!
92Do not include a currency symbol in the output.
93.It Cm \-
94Left justify the result.
95Only valid when a field width is specified.
96.El
97.It
98An optional minimum field width as a decimal number.
99By default, there is no minimum width.
100.It
101A
102.Sq Cm #
103sign followed by a decimal number specifying the maximum
104expected number of digits after the radix character.
105.It
106A
107.Sq Cm \&.
108character followed by a decimal number specifying the number
109of digits after the radix character.
110.It
111One of the following conversion specifiers:
112.Bl -tag -width "XXX"
113.It Cm i
114The
115.Vt double
116argument is formatted as an international monetary amount.
117.It Cm n
118The
119.Vt double
120argument is formatted as a national monetary amount.
121.It Cm %
122A
123.Sq Li %
124character is written.
125.El
126.El
127.Sh RETURN VALUES
128If the total number of resulting bytes including the terminating
3d960e09 129.Dv NUL
c6ddf9d0
SW
130byte is not more than
131.Fa maxsize ,
132.Fn strfmon
133returns the number of bytes placed into the array pointed to by
134.Fa s ,
135not including the terminating
3d960e09 136.Dv NUL
c6ddf9d0
SW
137byte.
138Otherwise, \-1 is returned,
139the contents of the array are indeterminate,
140and
141.Va errno
142is set to indicate the error.
3d960e09
SW
143.Pp
144The
145.Fn strfmon_l
146function returns the same values as
147.Fn strfmon .
c6ddf9d0
SW
148.Sh ERRORS
149The
150.Fn strfmon
94d35d83
SW
151and
152.Fn strfmon_l
153functions will fail if:
c6ddf9d0
SW
154.Bl -tag -width Er
155.It Bq Er E2BIG
156Conversion stopped due to lack of space in the buffer.
157.It Bq Er EINVAL
158The format string is invalid.
159.It Bq Er ENOMEM
160Not enough memory for temporary buffers.
161.El
162.Sh SEE ALSO
163.Xr localeconv 3
164.Sh STANDARDS
165The
166.Fn strfmon
167function
168conforms to
169.St -p1003.1-2001 .
3d960e09
SW
170The
171.Fn strfmon_l
172function conforms to
173.St -p1003.1-2008 .
c6ddf9d0
SW
174.Sh AUTHORS
175.An -nosplit
176The
177.Fn strfmon
178function was implemented by
98b3d9ad 179.An Alexey Zelkin Aq Mt phantom@FreeBSD.org .
c6ddf9d0
SW
180.Pp
181This manual page was written by
98b3d9ad 182.An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org
c6ddf9d0
SW
183based on the standard's text.
184.Sh BUGS
185The
186.Fn strfmon
94d35d83
SW
187and
188.Fn strfmon_l
189functions do not correctly handle multibyte characters in the
c6ddf9d0
SW
190.Fa format
191argument.