]>
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 | .\" | |
f75bdcaf | 32 | .TH STRFROMD 3 2016-12-02 "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 . | |
73 | .sp | |
74 | The terminating null character ('\\0') is written if and only if | |
75 | .I n | |
76 | is sufficiently large, otherwise the written string is truncated at | |
77 | .I n | |
78 | characters. | |
79 | .sp | |
80 | The | |
81 | .BR strfromd (), | |
82 | .BR strfromf (), | |
83 | and | |
84 | .BR strfroml () | |
85 | functions are equivalent to | |
847e0d88 | 86 | .PP |
f75bdcaf | 87 | snprintf(str, n, format, fp); |
847e0d88 | 88 | .PP |
d8be6d2b WSM |
89 | except for the |
90 | .I format | |
91 | string. | |
92 | .SS Format of the format string | |
93 | The | |
94 | .I format | |
f75bdcaf MK |
95 | string must start with the character \(aq%\(aq. |
96 | This is followed by an optional precision which starts with the period | |
d8be6d2b | 97 | character (.), followed by an optional decimal integer. |
f75bdcaf MK |
98 | If no integer is specified after the period character, |
99 | a precision of zero is used. | |
100 | Finally, the format string should have one of the conversion specifiers | |
d8be6d2b WSM |
101 | .BR a , |
102 | .BR A , | |
103 | .BR e , | |
104 | .BR E , | |
105 | .BR f , | |
106 | .BR F , | |
107 | .BR g , | |
108 | or | |
109 | .BR G . | |
110 | .sp | |
111 | The conversion specifier is applied based on the floating-point type | |
112 | indicated by the function suffix. | |
113 | Therefore, unlike | |
114 | .BR snprintf (), | |
115 | the format string does not have a length modifier character. | |
116 | See | |
117 | .BR snprintf (3) | |
118 | for a detailed description of these conversion specifiers. | |
119 | .sp | |
120 | The implementation conforms to the C99 standard on conversion of NaN and | |
121 | infinity values: | |
847e0d88 | 122 | .PP |
f75bdcaf | 123 | .RS |
d8be6d2b WSM |
124 | If |
125 | .I fp | |
126 | is a NaN, +NaN, or -NaN, and | |
127 | .BR f | |
128 | (or | |
129 | .BR a , | |
130 | .BR e , | |
131 | .BR g ) | |
132 | is the conversion specifier, the conversion is to "nan", "nan", or "-nan", | |
133 | respectively. | |
134 | If | |
135 | .B F | |
136 | (or | |
137 | .BR A , | |
138 | .BR E , | |
139 | .BR G ) | |
140 | is the conversion specifier, the conversion is to "NAN" or "-NAN". | |
141 | .sp | |
142 | Likewise if | |
143 | .I fp | |
144 | is infinity, it is converted to [-]inf or [-]INF. | |
f75bdcaf | 145 | .RE |
847e0d88 | 146 | .PP |
d8be6d2b WSM |
147 | A malformed |
148 | .I format | |
149 | string results in undefined behavior. | |
150 | .SH RETURN VALUE | |
151 | The | |
152 | .BR strfromd (), | |
153 | .BR strfromf (), | |
154 | and | |
155 | .BR strfroml () | |
156 | functions return the number of characters that would have been written in | |
157 | .I str | |
158 | if | |
159 | .I n | |
160 | had enough space, | |
161 | not counting the terminating null character. | |
162 | Thus, a return value of | |
163 | .I n | |
164 | or greater means that the output was truncated. | |
165 | .SH VERSIONS | |
166 | The | |
167 | .BR strfromd (), | |
168 | .BR strfromf (), | |
169 | and | |
170 | .BR strfroml () | |
171 | functions are available in glibc since version 2.25. | |
172 | .SH ATTRIBUTES | |
173 | For an explanation of the terms used in this section, see | |
174 | .BR attributes (7) | |
175 | and the | |
176 | .B POSIX Safety Concepts | |
177 | section in GNU C Library manual. | |
178 | .sp | |
179 | .TS | |
180 | allbox; | |
f75bdcaf | 181 | lbw11 lb lb |
d8be6d2b WSM |
182 | l l l. |
183 | Interface Attribute Value | |
184 | T{ | |
185 | .BR strfromd (), | |
186 | .BR strfromf (), | |
187 | .BR strfroml () | |
188 | T} Thread safety MT-Safe locale | |
189 | \^ Asynchronous signal safety AS-Unsafe heap | |
190 | \^ Asynchronous cancellation safety AC-Unsafe mem | |
191 | .TE | |
192 | .sp | |
193 | Note: these attributes are preliminary. | |
194 | .SH CONFORMING TO | |
195 | C99, ISO/IEC TS 18661-1. | |
196 | .SH NOTES | |
f75bdcaf | 197 | The |
d8be6d2b WSM |
198 | .BR strfromd (), |
199 | .BR strfromf (), | |
200 | and | |
201 | .BR strfroml () | |
202 | functions take account of the | |
203 | .B LC_NUMERIC | |
204 | category of the current locale. | |
d8be6d2b WSM |
205 | .SH EXAMPLES |
206 | To convert the value 12.1 as a float type to a string using decimal | |
207 | notation, resulting in "12.100000": | |
208 | .sp | |
209 | .in +4 | |
210 | .nf | |
211 | #define __STDC_WANT_IEC_60559_BFP_EXT__ | |
212 | #include <stdlib.h> | |
213 | int ssize = 10; | |
214 | char s[ssize]; | |
215 | strfromf(s, ssize, "%f", 12.1); | |
216 | .fi | |
217 | .in | |
218 | .sp | |
219 | To convert the value 12.3456 as a float type to a string using | |
220 | decimal notation with two digits of precision, resulting in "12.35": | |
221 | .sp | |
222 | .in +4 | |
223 | .nf | |
224 | #define __STDC_WANT_IEC_60559_BFP_EXT__ | |
225 | #include <stdlib.h> | |
226 | int ssize = 10; | |
227 | char s[ssize]; | |
228 | strfromf(s, ssize, "%.2f", 12.3456); | |
229 | .fi | |
230 | .in | |
231 | .sp | |
232 | To convert the value 12.345e19 as a double type to a string using | |
233 | scientific notation with zero digits of precision, resulting in "1E+20": | |
234 | .sp | |
235 | .in +4 | |
236 | .nf | |
237 | #define __STDC_WANT_IEC_60559_BFP_EXT__ | |
238 | #include <stdlib.h> | |
239 | int ssize = 10; | |
240 | char s[ssize]; | |
241 | strfromd(s, ssize, "%.E", 12.345e19); | |
242 | .fi | |
243 | .in | |
244 | .SH SEE ALSO | |
245 | .BR atof (3), | |
246 | .BR snprintf (3), | |
247 | .BR strtod (3) |