Debian Codegraph @

upstream/debian-trixie/man3/strtod.3

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