]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" This code is derived from software contributed to Berkeley by | |
5 | .\" the American National Standards Committee X3, on Information | |
6 | .\" Processing Systems. | |
7 | .\" | |
47009d5e | 8 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
fea681da MK |
9 | .\" |
10 | .\" @(#)strtod.3 5.3 (Berkeley) 6/29/91 | |
11 | .\" | |
12 | .\" Modified Sun Aug 21 17:16:22 1994 by Rik Faith (faith@cs.unc.edu) | |
13 | .\" Modified Sat May 04 19:34:31 MET DST 1996 by Michael Haardt | |
14 | .\" (michael@cantor.informatik.rwth-aachen.de) | |
7145b9a9 | 15 | .\" Added strof, strtold, aeb, 2001-06-07 |
fea681da | 16 | .\" |
45186a5d | 17 | .TH STRTOD 3 2021-03-22 "Linux man-pages (unreleased)" |
fea681da | 18 | .SH NAME |
c45bd688 | 19 | strtod, strtof, strtold \- convert ASCII string to floating-point number |
dd4e04b3 AC |
20 | .SH LIBRARY |
21 | Standard C library | |
8fc3b2cf | 22 | .RI ( libc ", " \-lc ) |
fea681da | 23 | .SH SYNOPSIS |
c7db92b9 | 24 | .nf |
fea681da | 25 | .B #include <stdlib.h> |
68e4db0a | 26 | .PP |
4e234640 AC |
27 | .BI "double strtod(const char *restrict " nptr ", char **restrict " endptr ); |
28 | .BI "float strtof(const char *restrict " nptr ", char **restrict " endptr ); | |
29 | .BI "long double strtold(const char *restrict " nptr \ | |
30 | ", char **restrict " endptr ); | |
c7db92b9 | 31 | .fi |
68e4db0a | 32 | .PP |
d39ad78f | 33 | .RS -4 |
cc4615cc MK |
34 | Feature Test Macro Requirements for glibc (see |
35 | .BR feature_test_macros (7)): | |
d39ad78f | 36 | .RE |
68e4db0a | 37 | .PP |
cc4615cc MK |
38 | .BR strtof (), |
39 | .BR strtold (): | |
9d2adbae | 40 | .nf |
5c10d2c5 | 41 | _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L |
9d2adbae | 42 | .fi |
fea681da MK |
43 | .SH DESCRIPTION |
44 | The | |
e511ffb6 MK |
45 | .BR strtod (), |
46 | .BR strtof (), | |
fea681da | 47 | and |
e511ffb6 | 48 | .BR strtold () |
fea681da MK |
49 | functions convert the initial portion of the string pointed to by |
50 | .I nptr | |
51 | to | |
9ff08aad MK |
52 | .IR double , |
53 | .IR float , | |
fea681da | 54 | and |
c13182ef | 55 | .I long double |
fea681da | 56 | representation, respectively. |
847e0d88 | 57 | .PP |
fea681da | 58 | The expected form of the (initial portion of the) string is |
60a90ecd MK |
59 | optional leading white space as recognized by |
60 | .BR isspace (3), | |
f81fb444 | 61 | an optional plus (\(aq+\(aq) or minus sign (\(aq\-\(aq) and then either |
fea681da MK |
62 | (i) a decimal number, or (ii) a hexadecimal number, |
63 | or (iii) an infinity, or (iv) a NAN (not-a-number). | |
dd3568a1 | 64 | .PP |
fea681da MK |
65 | A |
66 | .I "decimal number" | |
aa796481 | 67 | consists of a nonempty sequence of decimal digits |
a43eed0c | 68 | possibly containing a radix character (decimal point, locale-dependent, |
f81fb444 MK |
69 | usually \(aq.\(aq), optionally followed by a decimal exponent. |
70 | A decimal exponent consists of an \(aqE\(aq or \(aqe\(aq, followed by an | |
aa796481 | 71 | optional plus or minus sign, followed by a nonempty sequence of |
fea681da | 72 | decimal digits, and indicates multiplication by a power of 10. |
dd3568a1 | 73 | .PP |
fea681da MK |
74 | A |
75 | .I "hexadecimal number" | |
aa796481 | 76 | consists of a "0x" or "0X" followed by a nonempty sequence of |
fea681da | 77 | hexadecimal digits possibly containing a radix character, |
c13182ef MK |
78 | optionally followed by a binary exponent. |
79 | A binary exponent | |
f81fb444 | 80 | consists of a \(aqP\(aq or \(aqp\(aq, followed by an optional |
aa796481 | 81 | plus or minus sign, followed by a nonempty sequence of |
fea681da MK |
82 | decimal digits, and indicates multiplication by a power of 2. |
83 | At least one of radix character and binary exponent must be present. | |
dd3568a1 | 84 | .PP |
fea681da MK |
85 | An |
86 | .I infinity | |
324633ae | 87 | is either "INF" or "INFINITY", disregarding case. |
dd3568a1 | 88 | .PP |
fea681da MK |
89 | A |
90 | .I NAN | |
145fb1b4 MK |
91 | is "NAN" (disregarding case) optionally followed by a string, |
92 | .IR (n-char-sequence) , | |
93 | where | |
1ae6b2c7 | 94 | .I n-char-sequence |
145fb1b4 MK |
95 | specifies in an implementation-dependent |
96 | way the type of NAN (see NOTES). | |
47297adb | 97 | .SH RETURN VALUE |
fea681da | 98 | These functions return the converted value, if any. |
847e0d88 | 99 | .PP |
fea681da MK |
100 | If |
101 | .I endptr | |
8478ee02 | 102 | is not NULL, |
fea681da MK |
103 | a pointer to the character after the last character used in the conversion |
104 | is stored in the location referenced by | |
105 | .IR endptr . | |
847e0d88 | 106 | .PP |
5c61e57f MK |
107 | If no conversion is performed, zero is returned and (unless |
108 | .I endptr | |
109 | is null) the value of | |
fea681da MK |
110 | .I nptr |
111 | is stored in the location referenced by | |
112 | .IR endptr . | |
847e0d88 | 113 | .PP |
fea681da | 114 | If the correct value would cause overflow, plus or minus |
c4c038c9 JW |
115 | .BR HUGE_VAL , |
116 | .BR HUGE_VALF , | |
117 | or | |
118 | .B HUGE_VALL | |
119 | is returned (according to the return type and sign of the value), | |
120 | and | |
fea681da MK |
121 | .B ERANGE |
122 | is stored in | |
123 | .IR errno . | |
c4c038c9 JW |
124 | .PP |
125 | If the correct value would cause underflow, | |
126 | a value with magnitude no larger than | |
127 | .BR DBL_MIN , | |
128 | .BR FLT_MIN , | |
129 | or | |
130 | .B LDBL_MIN | |
131 | is returned and | |
fea681da | 132 | .B ERANGE |
c13182ef | 133 | is stored in |
fea681da MK |
134 | .IR errno . |
135 | .SH ERRORS | |
136 | .TP | |
137 | .B ERANGE | |
138 | Overflow or underflow occurred. | |
89a0ffe3 | 139 | .SH ATTRIBUTES |
612f31e5 PH |
140 | For an explanation of the terms used in this section, see |
141 | .BR attributes (7). | |
c466875e MK |
142 | .ad l |
143 | .nh | |
612f31e5 PH |
144 | .TS |
145 | allbox; | |
c466875e | 146 | lbx lb lb |
612f31e5 PH |
147 | l l l. |
148 | Interface Attribute Value | |
149 | T{ | |
89a0ffe3 PH |
150 | .BR strtod (), |
151 | .BR strtof (), | |
89a0ffe3 | 152 | .BR strtold () |
612f31e5 PH |
153 | T} Thread safety MT-Safe locale |
154 | .TE | |
c466875e MK |
155 | .hy |
156 | .ad | |
157 | .sp 1 | |
3113c7f3 | 158 | .SH STANDARDS |
78c186e7 | 159 | POSIX.1-2001, POSIX.1-2008, C99. |
847e0d88 | 160 | .PP |
78c186e7 MK |
161 | .BR strtod () |
162 | was also described in C89. | |
fefe023e | 163 | .SH NOTES |
c13182ef MK |
164 | Since |
165 | 0 can legitimately be returned | |
fefe023e MK |
166 | on both success and failure, the calling program should set |
167 | .I errno | |
c13182ef | 168 | to 0 before the call, |
fefe023e MK |
169 | and then determine if an error occurred by checking whether |
170 | .I errno | |
c7094399 | 171 | has a nonzero value after the call. |
847e0d88 | 172 | .PP |
145fb1b4 | 173 | In the glibc implementation, the |
1ae6b2c7 | 174 | .I n-char-sequence |
145fb1b4 MK |
175 | that optionally follows "NAN" |
176 | is interpreted as an integer number | |
177 | (with an optional '0' or '0x' prefix to select base 8 or 16) | |
178 | that is to be placed in the | |
179 | mantissa component of the returned value. | |
180 | .\" From glibc 2.8's stdlib/strtod_l.c: | |
181 | .\" We expect it to be a number which is put in the | |
182 | .\" mantissa of the number. | |
183 | .\" It looks as though at least FreeBSD (according to the manual) does | |
184 | .\" something similar. | |
185 | .\" C11 says: "An implementation may use the n-char sequence to determine | |
186 | .\" extra information to be represented in the NaN's significant." | |
a14af333 | 187 | .SH EXAMPLES |
5a1cae6b MK |
188 | See the example on the |
189 | .BR strtol (3) | |
c13182ef | 190 | manual page; |
5a1cae6b | 191 | the use of the functions described in this manual page is similar. |
47297adb | 192 | .SH SEE ALSO |
fea681da MK |
193 | .BR atof (3), |
194 | .BR atoi (3), | |
195 | .BR atol (3), | |
9b944b8d MK |
196 | .BR nan (3), |
197 | .BR nanf (3), | |
198 | .BR nanl (3), | |
b61e3789 | 199 | .BR strfromd (3), |
fea681da | 200 | .BR strtol (3), |
cc4615cc | 201 | .BR strtoul (3) |