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