Debian Codegraph @

upstream/debian-trixie/man3/strfromd.3

raw
1 '\" t
2 .\" Copyright (c) 2016, IBM Corporation.
3 .\" Written by Wainer dos Santos Moschetta <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\" References consulted:
8 .\" glibc 2.25 source code and manual.
9 .\" C99 standard document.
10 .\" ISO/IEC TS 18661-1 technical specification.
11 .\" snprintf and other man.3 pages.
12 .\"
13 .TH strfromd 3 2024-06-15 "Linux man-pages 6.9.1"
14 .SH NAME
15 strfromd, strfromf, strfroml \- convert a floating-point value into
16 a string
17 .SH LIBRARY
18 Standard C library
19 .RI ( libc ", " \-lc )
20 .SH SYNOPSIS
21 .nf
22 .B #include <stdlib.h>
23 .P
24 .BI "int strfromd(char " str "[restrict ." n "], size_t " n ,
25 .BI " const char *restrict " format ", double " fp ");"
26 .BI "int strfromf(char " str "[restrict ." n "], size_t " n ,
27 .BI " const char *restrict " format ", float "fp ");"
28 .BI "int strfroml(char " str "[restrict ." n "], size_t " n ,
29 .BI " const char *restrict " format ", long double " fp ");"
30 .fi
31 .P
32 .RS -4
33 Feature Test Macro Requirements for glibc (see
34 .BR feature_test_macros (7)):
35 .RE
36 .P
37 .BR strfromd (),
38 .BR strfromf (),
39 .BR strfroml ():
40 .nf
41 __STDC_WANT_IEC_60559_BFP_EXT__
42 .fi
43 .SH DESCRIPTION
44 These functions convert a floating-point value,
45 .IR fp ,
46 into a string of characters,
47 .IR str ,
48 with a configurable
49 .I format
50 string.
51 At most
52 .I n
53 characters are stored into
54 .IR str .
55 .P
56 The terminating null byte ('\[rs]0') is written if and only if
57 .I n
58 is sufficiently large, otherwise the written string is truncated at
59 .I n
60 characters.
61 .P
62 The
63 .BR strfromd (),
64 .BR strfromf (),
65 and
66 .BR strfroml ()
67 functions are equivalent to
68 .P
69 .in +4n
70 .EX
71 snprintf(str, n, format, fp);
72 .EE
73 .in
74 .P
75 except for the
76 .I format
77 string.
78 .SS Format of the format string
79 The
80 .I format
81 string must start with the character \[aq]%\[aq].
82 This is followed by an optional precision which starts with the period
83 character (.), followed by an optional decimal integer.
84 If no integer is specified after the period character,
85 a precision of zero is used.
86 Finally, the format string should have one of the conversion specifiers
87 .BR a ,
88 .BR A ,
89 .BR e ,
90 .BR E ,
91 .BR f ,
92 .BR F ,
93 .BR g ,
94 or
95 .BR G .
96 .P
97 The conversion specifier is applied based on the floating-point type
98 indicated by the function suffix.
99 Therefore, unlike
100 .BR snprintf (),
101 the format string does not have a length modifier character.
102 See
103 .BR snprintf (3)
104 for a detailed description of these conversion specifiers.
105 .P
106 The implementation conforms to the C99 standard on conversion of NaN and
107 infinity values:
108 .P
109 .RS
110 If
111 .I fp
112 is a NaN, +NaN, or \-NaN, and
113 .B f
114 (or
115 .BR a ,
116 .BR e ,
117 .BR g )
118 is the conversion specifier, the conversion is to "nan", "nan", or "\-nan",
119 respectively.
120 If
121 .B F
122 (or
123 .BR A ,
124 .BR E ,
125 .BR G )
126 is the conversion specifier, the conversion is to "NAN" or "\-NAN".
127 .P
128 Likewise if
129 .I fp
130 is infinity, it is converted to [\-]inf or [\-]INF.
131 .RE
132 .P
133 A malformed
134 .I format
135 string results in undefined behavior.
136 .SH RETURN VALUE
137 The
138 .BR strfromd (),
139 .BR strfromf (),
140 and
141 .BR strfroml ()
142 functions return the number of characters that would have been written in
143 .I str
144 if
145 .I n
146 had enough space,
147 not counting the terminating null byte.
148 Thus, a return value of
149 .I n
150 or greater means that the output was truncated.
151 .SH ATTRIBUTES
152 For an explanation of the terms used in this section, see
153 .BR attributes (7)
154 and the
155 .B POSIX Safety Concepts
156 section in GNU C Library manual.
157 .P
158 .TS
159 allbox;
160 lbx lb lb
161 l l l.
162 Interface Attribute Value
163 T{
164 .na
165 .nh
166 .BR strfromd (),
167 .BR strfromf (),
168 .BR strfroml ()
169 T} Thread safety MT-Safe locale
170 \^ Async-signal safety AS-Unsafe heap
171 \^ Async-cancel safety AC-Unsafe mem
172 .TE
173 .P
174 Note: these attributes are preliminary.
175 .SH STANDARDS
176 ISO/IEC TS 18661-1.
177 .SH VERSIONS
178 .TP
179 .BR strfromd ()
180 .TQ
181 .BR strfromf ()
182 .TQ
183 .BR strfroml ()
184 glibc 2.25.
185 .SH NOTES
186 These functions take account of the
187 .B LC_NUMERIC
188 category of the current locale.
189 .SH EXAMPLES
190 To convert the value 12.1 as a float type to a string using decimal
191 notation, resulting in "12.100000":
192 .P
193 .in +4n
194 .EX
195 #define __STDC_WANT_IEC_60559_BFP_EXT__
196 #include <stdlib.h>
197 int ssize = 10;
198 char s[ssize];
199 strfromf(s, ssize, "%f", 12.1);
200 .EE
201 .in
202 .P
203 To convert the value 12.3456 as a float type to a string using
204 decimal notation with two digits of precision, resulting in "12.35":
205 .P
206 .in +4n
207 .EX
208 #define __STDC_WANT_IEC_60559_BFP_EXT__
209 #include <stdlib.h>
210 int ssize = 10;
211 char s[ssize];
212 strfromf(s, ssize, "%.2f", 12.3456);
213 .EE
214 .in
215 .P
216 To convert the value 12.345e19 as a double type to a string using
217 scientific notation with zero digits of precision, resulting in "1E+20":
218 .P
219 .in +4n
220 .EX
221 #define __STDC_WANT_IEC_60559_BFP_EXT__
222 #include <stdlib.h>
223 int ssize = 10;
224 char s[ssize];
225 strfromd(s, ssize, "%.E", 12.345e19);
226 .EE
227 .in
228 .SH SEE ALSO
229 .BR atof (3),
230 .BR snprintf (3),
231 .BR strtod (3)