]>
Commit | Line | Data |
---|---|---|
d8be6d2b WSM |
1 | .\" Copyright (c) 2016, IBM Corporation. |
2 | .\" Written by Wainer dos Santos Moschetta <wainersm@linux.vnet.ibm.com> | |
3 | .\" | |
4 | .\" %%%LICENSE_START(VERBATIM) | |
5 | .\" Permission is granted to make and distribute verbatim copies of this | |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of | |
10 | .\" this manual under the conditions for verbatim copying, provided that | |
11 | .\" the entire resulting derived work is distributed under the terms of | |
12 | .\" a permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume. | |
16 | .\" no responsibility for errors or omissions, or for damages resulting. | |
17 | .\" from the use of the information contained herein. The author(s) may. | |
18 | .\" not have taken the same level of care in the production of this. | |
19 | .\" manual, which is licensed free of charge, as they might when working. | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
24 | .\" %%%LICENSE_END | |
25 | .\" | |
26 | .\" References consulted: | |
27 | .\" Glibc 2.25 source code and manual. | |
28 | .\" C99 standard document. | |
29 | .\" ISO/IEC TS 18661-1 technical specification. | |
30 | .\" snprintf and other man.3 pages. | |
31 | .\" | |
9ba01802 | 32 | .TH STRFROMD 3 2019-03-06 "GNU" "Linux Programmer's Manual" |
d8be6d2b WSM |
33 | .SH NAME |
34 | strfromd, strfromf, strfroml \- convert a floating-point value into | |
f75bdcaf | 35 | a string |
d8be6d2b | 36 | .SH SYNOPSIS |
f75bdcaf | 37 | .nf |
d8be6d2b | 38 | .B #include <stdlib.h> |
f90f031e | 39 | .PP |
f75bdcaf MK |
40 | .BI "int strfromd(char *restrict " str ", size_t " n ", |
41 | .BI " const char *restrict " format ", double " fp ");" | |
42 | .BI "int strfromf(char *restrict " str ", size_t " n ", | |
43 | .BI " const char *restrict " format ", float "fp ");" | |
44 | .BI "int strfroml(char *restrict " str ", size_t " n ", | |
45 | .BI " const char *restrict " format ", long double " fp ");" | |
46 | .fi | |
f90f031e | 47 | .PP |
d8be6d2b WSM |
48 | .in -4 |
49 | Feature Test Macro Requirements for glibc (see | |
50 | .BR feature_test_macros (7)): | |
51 | .in | |
68e4db0a | 52 | .PP |
d8be6d2b WSM |
53 | .ad l |
54 | .BR strfromd (), | |
55 | .BR strfromf (), | |
56 | .BR strfroml (): | |
57 | .RS 4 | |
58 | __STDC_WANT_IEC_60559_BFP_EXT__ | |
59 | .RE | |
60 | .ad b | |
61 | .SH DESCRIPTION | |
f75bdcaf MK |
62 | These functions convert a floating-point value, |
63 | .IR fp , | |
64 | into a string of characters, | |
d8be6d2b WSM |
65 | .IR str , |
66 | with a configurable | |
67 | .IR format | |
68 | string. | |
69 | At most | |
70 | .I n | |
71 | characters are stored into | |
72 | .IR str . | |
51f5698d | 73 | .PP |
d1a71985 | 74 | The terminating null character ('\e0') is written if and only if |
d8be6d2b WSM |
75 | .I n |
76 | is sufficiently large, otherwise the written string is truncated at | |
77 | .I n | |
78 | characters. | |
51f5698d | 79 | .PP |
d8be6d2b WSM |
80 | The |
81 | .BR strfromd (), | |
82 | .BR strfromf (), | |
83 | and | |
84 | .BR strfroml () | |
85 | functions are equivalent to | |
847e0d88 | 86 | .PP |
bdd915e2 MK |
87 | .in +4n |
88 | .EX | |
89 | snprintf(str, n, format, fp); | |
90 | .EE | |
91 | .in | |
847e0d88 | 92 | .PP |
d8be6d2b WSM |
93 | except for the |
94 | .I format | |
95 | string. | |
96 | .SS Format of the format string | |
97 | The | |
98 | .I format | |
f75bdcaf MK |
99 | string must start with the character \(aq%\(aq. |
100 | This is followed by an optional precision which starts with the period | |
d8be6d2b | 101 | character (.), followed by an optional decimal integer. |
f75bdcaf MK |
102 | If no integer is specified after the period character, |
103 | a precision of zero is used. | |
104 | Finally, the format string should have one of the conversion specifiers | |
d8be6d2b WSM |
105 | .BR a , |
106 | .BR A , | |
107 | .BR e , | |
108 | .BR E , | |
109 | .BR f , | |
110 | .BR F , | |
111 | .BR g , | |
112 | or | |
113 | .BR G . | |
51f5698d | 114 | .PP |
d8be6d2b WSM |
115 | The conversion specifier is applied based on the floating-point type |
116 | indicated by the function suffix. | |
117 | Therefore, unlike | |
118 | .BR snprintf (), | |
119 | the format string does not have a length modifier character. | |
120 | See | |
121 | .BR snprintf (3) | |
122 | for a detailed description of these conversion specifiers. | |
51f5698d | 123 | .PP |
d8be6d2b WSM |
124 | The implementation conforms to the C99 standard on conversion of NaN and |
125 | infinity values: | |
847e0d88 | 126 | .PP |
f75bdcaf | 127 | .RS |
d8be6d2b WSM |
128 | If |
129 | .I fp | |
130 | is a NaN, +NaN, or -NaN, and | |
131 | .BR f | |
132 | (or | |
133 | .BR a , | |
134 | .BR e , | |
135 | .BR g ) | |
136 | is the conversion specifier, the conversion is to "nan", "nan", or "-nan", | |
137 | respectively. | |
138 | If | |
139 | .B F | |
140 | (or | |
141 | .BR A , | |
142 | .BR E , | |
143 | .BR G ) | |
144 | is the conversion specifier, the conversion is to "NAN" or "-NAN". | |
51f5698d | 145 | .PP |
d8be6d2b WSM |
146 | Likewise if |
147 | .I fp | |
148 | is infinity, it is converted to [-]inf or [-]INF. | |
f75bdcaf | 149 | .RE |
847e0d88 | 150 | .PP |
d8be6d2b WSM |
151 | A malformed |
152 | .I format | |
153 | string results in undefined behavior. | |
154 | .SH RETURN VALUE | |
155 | The | |
156 | .BR strfromd (), | |
157 | .BR strfromf (), | |
158 | and | |
159 | .BR strfroml () | |
160 | functions return the number of characters that would have been written in | |
161 | .I str | |
162 | if | |
163 | .I n | |
164 | had enough space, | |
165 | not counting the terminating null character. | |
166 | Thus, a return value of | |
167 | .I n | |
168 | or greater means that the output was truncated. | |
169 | .SH VERSIONS | |
170 | The | |
171 | .BR strfromd (), | |
172 | .BR strfromf (), | |
173 | and | |
174 | .BR strfroml () | |
175 | functions are available in glibc since version 2.25. | |
176 | .SH ATTRIBUTES | |
177 | For an explanation of the terms used in this section, see | |
178 | .BR attributes (7) | |
179 | and the | |
180 | .B POSIX Safety Concepts | |
181 | section in GNU C Library manual. | |
51f5698d | 182 | .PP |
d8be6d2b WSM |
183 | .TS |
184 | allbox; | |
f75bdcaf | 185 | lbw11 lb lb |
d8be6d2b WSM |
186 | l l l. |
187 | Interface Attribute Value | |
188 | T{ | |
189 | .BR strfromd (), | |
190 | .BR strfromf (), | |
191 | .BR strfroml () | |
192 | T} Thread safety MT-Safe locale | |
193 | \^ Asynchronous signal safety AS-Unsafe heap | |
194 | \^ Asynchronous cancellation safety AC-Unsafe mem | |
195 | .TE | |
bdd915e2 | 196 | .sp 1 |
d8be6d2b WSM |
197 | Note: these attributes are preliminary. |
198 | .SH CONFORMING TO | |
199 | C99, ISO/IEC TS 18661-1. | |
200 | .SH NOTES | |
f75bdcaf | 201 | The |
d8be6d2b WSM |
202 | .BR strfromd (), |
203 | .BR strfromf (), | |
204 | and | |
205 | .BR strfroml () | |
206 | functions take account of the | |
207 | .B LC_NUMERIC | |
208 | category of the current locale. | |
d8be6d2b WSM |
209 | .SH EXAMPLES |
210 | To convert the value 12.1 as a float type to a string using decimal | |
211 | notation, resulting in "12.100000": | |
51f5698d | 212 | .PP |
d8be6d2b | 213 | .in +4 |
bdd915e2 | 214 | .EX |
d8be6d2b WSM |
215 | #define __STDC_WANT_IEC_60559_BFP_EXT__ |
216 | #include <stdlib.h> | |
217 | int ssize = 10; | |
218 | char s[ssize]; | |
219 | strfromf(s, ssize, "%f", 12.1); | |
bdd915e2 | 220 | .EE |
d8be6d2b | 221 | .in |
51f5698d | 222 | .PP |
d8be6d2b WSM |
223 | To convert the value 12.3456 as a float type to a string using |
224 | decimal notation with two digits of precision, resulting in "12.35": | |
51f5698d | 225 | .PP |
d8be6d2b | 226 | .in +4 |
bdd915e2 | 227 | .EX |
d8be6d2b WSM |
228 | #define __STDC_WANT_IEC_60559_BFP_EXT__ |
229 | #include <stdlib.h> | |
230 | int ssize = 10; | |
231 | char s[ssize]; | |
232 | strfromf(s, ssize, "%.2f", 12.3456); | |
bdd915e2 | 233 | .EE |
d8be6d2b | 234 | .in |
51f5698d | 235 | .PP |
d8be6d2b WSM |
236 | To convert the value 12.345e19 as a double type to a string using |
237 | scientific notation with zero digits of precision, resulting in "1E+20": | |
51f5698d | 238 | .PP |
d8be6d2b | 239 | .in +4 |
bdd915e2 | 240 | .EX |
d8be6d2b WSM |
241 | #define __STDC_WANT_IEC_60559_BFP_EXT__ |
242 | #include <stdlib.h> | |
243 | int ssize = 10; | |
244 | char s[ssize]; | |
245 | strfromd(s, ssize, "%.E", 12.345e19); | |
bdd915e2 | 246 | .EE |
d8be6d2b WSM |
247 | .in |
248 | .SH SEE ALSO | |
249 | .BR atof (3), | |
250 | .BR snprintf (3), | |
251 | .BR strtod (3) |