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