Debian Codegraph @

upstream/debian-unstable/man3/strtod.3

raw
1 '\" t
2 .\" Copyright 1990-1991, The Regents of the University of California.
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: BSD-4-Clause-UC
6 .\"
7 .TH strtod 3 2025-05-17 "Linux man-pages 6.18"
8 .SH NAME
9 strtod, strtof, strtold \- convert ASCII string to floating-point number
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <stdlib.h>
16 .P
17 .BI "double strtod(const char *restrict " nptr ,
18 .BI " char **_Nullable restrict " endptr );
19 .BI "float strtof(const char *restrict " nptr ,
20 .BI " char **_Nullable restrict " endptr );
21 .BI "long double strtold(const char *restrict " nptr ,
22 .BI " char **_Nullable restrict " endptr );
23 .fi
24 .P
25 .RS -4
26 Feature Test Macro Requirements for glibc (see
27 .BR feature_test_macros (7)):
28 .RE
29 .P
30 .BR strtof (),
31 .BR strtold ():
32 .nf
33 _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
34 .fi
35 .SH DESCRIPTION
36 The
37 .BR strtod (),
38 .BR strtof (),
39 and
40 .BR strtold ()
41 functions convert the initial portion of the string pointed to by
42 .I nptr
43 to
44 .IR double ,
45 .IR float ,
46 and
47 .I long double
48 representation, respectively.
49 .P
50 The expected form of the (initial portion of the) string is
51 optional leading white space as recognized by
52 .BR isspace (3),
53 an optional plus (\[aq]+\[aq]) or minus sign (\[aq]\-\[aq]) and then either
54 (i) a decimal number, or (ii) a hexadecimal number,
55 or (iii) an infinity, or (iv) a NAN (not-a-number).
56 .P
57 A
58 .I "decimal number"
59 consists of a nonempty sequence of decimal digits
60 possibly containing a radix character (decimal point, locale-dependent,
61 usually \[aq].\[aq]), optionally followed by a decimal exponent.
62 A decimal exponent consists of an \[aq]E\[aq] or \[aq]e\[aq], followed by an
63 optional plus or minus sign, followed by a nonempty sequence of
64 decimal digits, and indicates multiplication by a power of 10.
65 .P
66 A
67 .I "hexadecimal number"
68 consists of a "0x" or "0X" followed by a nonempty sequence of
69 hexadecimal digits possibly containing a radix character,
70 optionally followed by a binary exponent.
71 A binary exponent
72 consists of a \[aq]P\[aq] or \[aq]p\[aq], followed by an optional
73 plus or minus sign, followed by a nonempty sequence of
74 decimal digits, and indicates multiplication by a power of 2.
75 At least one of radix character and binary exponent must be present.
76 .P
77 An
78 .I infinity
79 is either "INF" or "INFINITY", disregarding case.
80 .P
81 A
82 .I NAN
83 is "NAN" (disregarding case) optionally followed by a string,
84 .IR (n-char-sequence) ,
85 where
86 .I n-char-sequence
87 specifies in an implementation-dependent
88 way the type of NAN (see VERSIONS).
89 .SH RETURN VALUE
90 These functions return the converted value, if any.
91 .P
92 If
93 .I endptr
94 is not NULL,
95 a pointer to the character after the last character used in the conversion
96 is stored in the location referenced by
97 .IR endptr .
98 .P
99 If no conversion is performed, zero is returned and (unless
100 .I endptr
101 is null) the value of
102 .I nptr
103 is stored in the location referenced by
104 .IR endptr .
105 .P
106 If the correct value would cause overflow, plus or minus
107 .BR HUGE_VAL ,
108 .BR HUGE_VALF ,
109 or
110 .B HUGE_VALL
111 is returned (according to the return type and sign of the value),
112 and
113 .B ERANGE
114 is stored in
115 .IR errno .
116 .P
117 If the correct value would cause underflow,
118 a value with magnitude no larger than
119 .BR DBL_MIN ,
120 .BR FLT_MIN ,
121 or
122 .B LDBL_MIN
123 is returned and
124 .B ERANGE
125 is stored in
126 .IR errno .
127 .SH ERRORS
128 .TP
129 .B ERANGE
130 Overflow or underflow occurred.
131 .SH ATTRIBUTES
132 For an explanation of the terms used in this section, see
133 .BR attributes (7).
134 .TS
135 allbox;
136 lbx lb lb
137 l l l.
138 Interface Attribute Value
139 T{
140 .na
141 .nh
142 .BR strtod (),
143 .BR strtof (),
144 .BR strtold ()
145 T} Thread safety MT-Safe locale
146 .TE
147 .SH VERSIONS
148 In the glibc implementation, the
149 .I n-char-sequence
150 that optionally follows "NAN"
151 is interpreted as an integer number
152 (with an optional '0' or '0x' prefix to select base 8 or 16)
153 that is to be placed in the
154 mantissa component of the returned value.
155 .\" From glibc 2.8's stdlib/strtod_l.c:
156 .\" We expect it to be a number which is put in the
157 .\" mantissa of the number.
158 .\" It looks as though at least FreeBSD (according to the manual) does
159 .\" something similar.
160 .\" C11 says: "An implementation may use the n-char sequence to determine
161 .\" extra information to be represented in the NaN's significant."
162 .SH STANDARDS
163 C11, POSIX.1-2008.
164 .SH HISTORY
165 .TP
166 .BR strtod ()
167 C89, POSIX.1-2001.
168 .TP
169 .BR strtof ()
170 .TQ
171 .BR strtold ()
172 C99, POSIX.1-2001.
173 .SH CAVEATS
174 Since
175 0 can legitimately be returned
176 on both success and failure, the calling program should set
177 .I errno
178 to 0 before the call,
179 and then determine if an error occurred by checking whether
180 .I errno
181 has a nonzero value after the call.
182 .SH EXAMPLES
183 See the example on the
184 .BR strtol (3)
185 manual page;
186 the use of the functions described in this manual page is similar.
187 .SH SEE ALSO
188 .BR atof (3),
189 .BR atoi (3),
190 .BR atol (3),
191 .BR nan (3),
192 .BR nanf (3),
193 .BR nanl (3),
194 .BR strfromd (3),
195 .BR strtol (3),
196 .BR strtoul (3)