xref: /netbsd-src/lib/libc/stdlib/strtod.3 (revision 49e10846a684d8faa456046705ad6d3d7bce8f4c) 
1.\"	$NetBSD: strtod.3,v 1.30 2022/12/04 11:25:08 uwe Exp $
2.\"
3.\" Copyright (c) 1990, 1991, 1993
4.\"	The Regents of the University of California.  All rights reserved.
5.\"
6.\" This code is derived from software contributed to Berkeley by
7.\" the American National Standards Committee X3, on Information
8.\" Processing Systems.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\"    notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\"    notice, this list of conditions and the following disclaimer in the
17.\"    documentation and/or other materials provided with the distribution.
18.\" 3. Neither the name of the University nor the names of its contributors
19.\"    may be used to endorse or promote products derived from this software
20.\"    without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\"     from: @(#)strtod.3	8.1 (Berkeley) 6/4/93
35.\"
36.Dd November 4, 2016
37.Dt STRTOD 3
38.Os
39.Sh NAME
40.Nm strtod ,
41.Nm strtof ,
42.Nm strtold
43.Nd convert
44.Tn ASCII
45string to double, float, or long double
46.Sh LIBRARY
47.Lb libc
48.Sh SYNOPSIS
49.In stdlib.h
50.Ft double
51.Fn strtod "const char * restrict nptr" "char ** restrict endptr"
52.Ft float
53.Fn strtof "const char * restrict nptr" "char ** restrict endptr"
54.Ft long double
55.Fn strtold "const char * restrict nptr" "char ** restrict endptr"
56.Sh DESCRIPTION
57The
58.Fn strtod
59function converts the initial portion of the string
60pointed to by
61.Fa nptr
62to
63.Em double
64representation.
65.Pp
66The
67.Fn strtof
68function converts the initial portion of the string
69pointed to by
70.Fa nptr
71to
72.Em float
73representation.
74.Pp
75The
76.Fn strtold
77function converts the initial portion of the string
78pointed to by
79.Fa nptr
80to
81.Em long double
82representation.
83.Pp
84The expected form of the string is an optional plus
85.Pq Sq +
86or minus sign
87.Pq Sq \-
88followed by one of the following:
89.Bl -dash
90.It
91a sequence of digits optionally containing
92a decimal-point character, optionally followed by an exponent.
93An exponent consists of an
94.Sq E
95or
96.Sq e ,
97followed by an optional plus
98or minus sign, followed by a sequence of digits.
99.It
100one of
101.Li INF
102or
103.Li INFINITY ,
104ignoring case.
105.It
106one of
107.Li NAN
108or
109.Li NAN(n-char-sequence-opt) ,
110ignoring case.
111This implementation currently does not interpret such a sequence.
112.El
113.Pp
114Leading white-space characters in the string (as defined by the
115.Xr isspace 3
116function) are skipped.
117.Sh RETURN VALUES
118The
119.Fn strtod ,
120.Fn strtof ,
121and
122.Fn strtold
123functions return the converted value, if any.
124.Pp
125A character sequence
126.Li INF
127or
128.Li INFINITY
129is converted to \*(If,
130if supported, else to the largest finite floating-point number representable
131on the machine (i.e.,
132.Tn VAX ) .
133.Pp
134A character sequence
135.Li NAN
136or
137.Li NAN(n-char-sequence-opt)
138is converted to a quiet \*(Na, if supported, else remains unrecognized (i.e.,
139.Tn VAX ) .
140.Pp
141If
142.Fa endptr
143is not
144.Dv NULL ,
145a pointer to the character after the last character used
146in the conversion is stored in the location referenced by
147.Fa endptr .
148.Pp
149If no conversion is performed, zero is returned and the value of
150.Fa nptr
151is stored in the location referenced by
152.Fa endptr .
153.Pp
154If the correct value is too large in magnitude to be represented
155.Pq Sq overflow ,
156plus or minus
157.Dv HUGE_VAL ,
158.Dv HUGE_VALF ,
159or
160.Dv HUGE_VALL
161is returned (according to the return type and sign of the value), and
162.Er ERANGE
163is stored in
164.Va errno .
165.Pp
166If the correct value is too small in magnitude to be represented
167normally with full precision
168.Pq Sq underflow ,
169the closest subnormal value, or zero, is returned, and
170.Er ERANGE
171is stored in
172.Va errno .
173.Sh EXAMPLES
174Since there is no out-of-band channel or sentinel value to indicate an
175error, callers who wish to know whether there was overflow or underflow
176must set
177.Va errno
178to zero before calling
179.Fn strtod ,
180.Fn strtof ,
181or
182.Fn strtold ;
183in the case of no underflow or overflow, these functions preserve
184.Va errno .
185.Pp
186To check for syntax errors, callers must
187.Em also
188check whether
189.Fa endptr
190was updated to reflect the true end of the string in order to determine
191whether the full string was consumed or whether there were additional
192erroneous characters in it.
193.Bd -literal -offset abcd
194char *end;
195double d;
196
197\&...
198
199errno = 0;
200d = strtod(s, &end);
201if (end == s)
202	errx(EXIT_FAILURE, "invalid syntax");
203if (end[0] != '\e0')
204	errx(EXIT_FAILURE, "trailing garbage");
205if (errno) {
206	assert(errno == ERANGE);
207	assert(isinf(d) || d == 0 ||
208	    fpclassify(d) == FP_SUBNORMAL);
209	warnx("%s", isinf(d) ? "overflow" : "underflow");
210}
211/* d is the best floating-point approximation to the number in s */
212.Ed
213.Sh ERRORS
214.Bl -tag -width Er
215.It Bq Er ERANGE
216The conversion resulted in floating-point underflow or overflow.
217.El
218.Sh SEE ALSO
219.Xr atof 3 ,
220.Xr atoi 3 ,
221.Xr atol 3 ,
222.Xr math 3 ,
223.Xr strtol 3 ,
224.Xr strtoul 3
225.Sh STANDARDS
226The
227.Fn strtod
228function
229conforms to
230.St -ansiC .
231The
232.Fn strtof
233and
234.Fn strtold
235functions conform to
236.St -isoC-99 .
237.Sh HISTORY
238The
239.Fn strtof
240and
241.Fn strtold
242functions appeared in
243.Nx 4.0 .
244