Debian Codegraph @

upstream/debian-unstable/man3/strfromd.3

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