[thirdparty/man-pages.git] / man3 / strtod.3

.\" Copyright (c) 1990, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the American National Standards Committee X3, on Information
.\" Processing Systems.
.\"
.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\" %%%LICENSE_END
.\"
.\"     @(#)strtod.3	5.3 (Berkeley) 6/29/91
.\"
.\" Modified Sun Aug 21 17:16:22 1994 by Rik Faith (faith@cs.unc.edu)
.\" Modified Sat May 04 19:34:31 MET DST 1996 by Michael Haardt
.\"   (michael@cantor.informatik.rwth-aachen.de)
.\" Added strof, strtold, aeb, 2001-06-07
.\"
.TH STRTOD 3 2015-08-08 "Linux" "Linux Programmer's Manual"
.SH NAME
strtod, strtof, strtold \- convert ASCII string to floating-point number
.SH SYNOPSIS
.B #include <stdlib.h>
.sp
.BI "double strtod(const char *" nptr ", char **" endptr );
.br
.BI "float strtof(const char *" nptr ", char **" endptr );
.br
.BI "long double strtold(const char *" nptr ", char **" endptr );
.sp
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
.ad l
.sp
.BR strtof (),
.BR strtold ():
.RS 4
_XOPEN_SOURCE\ >=\ 600 || _ISOC99_SOURCE ||
_POSIX_C_SOURCE\ >=\ 200112L;
.br
or
.I cc\ -std=c99
.RE
.ad
.SH DESCRIPTION
The
.BR strtod (),
.BR strtof (),
and
.BR strtold ()
functions convert the initial portion of the string pointed to by
.I nptr
to
.IR double ,
.IR float ,
and
.I long double
representation, respectively.

The expected form of the (initial portion of the) string is
optional leading white space as recognized by
.BR isspace (3),
an optional plus (\(aq+\(aq) or minus sign (\(aq\-\(aq) and then either
(i) a decimal number, or (ii) a hexadecimal number,
or (iii) an infinity, or (iv) a NAN (not-a-number).
.LP
A
.I "decimal number"
consists of a nonempty sequence of decimal digits
possibly containing a radix character (decimal point, locale-dependent,
usually \(aq.\(aq), optionally followed by a decimal exponent.
A decimal exponent consists of an \(aqE\(aq or \(aqe\(aq, followed by an
optional plus or minus sign, followed by a nonempty sequence of
decimal digits, and indicates multiplication by a power of 10.
.LP
A
.I "hexadecimal number"
consists of a "0x" or "0X" followed by a nonempty sequence of
hexadecimal digits possibly containing a radix character,
optionally followed by a binary exponent.
A binary exponent
consists of a \(aqP\(aq or \(aqp\(aq, followed by an optional
plus or minus sign, followed by a nonempty sequence of
decimal digits, and indicates multiplication by a power of 2.
At least one of radix character and binary exponent must be present.
.LP
An
.I infinity
is either "INF" or "INFINITY", disregarding case.
.LP
A
.I NAN
is "NAN" (disregarding case) optionally followed by a string,
.IR (n-char-sequence) ,
where
.IR n-char-sequence
specifies in an implementation-dependent
way the type of NAN (see NOTES).
.SH RETURN VALUE
These functions return the converted value, if any.

If
.I endptr
is not NULL,
a pointer to the character after the last character used in the conversion
is stored in the location referenced by
.IR endptr .

If no conversion is performed, zero is returned and the value of
.I nptr
is stored in the location referenced by
.IR endptr .

If the correct value would cause overflow, plus or minus
.B HUGE_VAL
.RB ( HUGE_VALF ,
.BR HUGE_VALL )
is returned (according to the sign of the value), and
.B ERANGE
is stored in
.IR errno .
If the correct value would cause underflow, zero is
returned and
.B ERANGE
is stored in
.IR errno .
.SH ERRORS
.TP
.B ERANGE
Overflow or underflow occurred.
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.TS
allbox;
lbw29 lb lb
l l l.
Interface	Attribute	Value
T{
.BR strtod (),
.BR strtof (),
.BR strtold ()
T}	Thread safety	MT-Safe locale
.TE
.SH CONFORMING TO
POSIX.1-2001, POSIX.1-2008, C99.

.BR strtod ()
was also described in C89.
.SH NOTES
Since
0 can legitimately be returned
on both success and failure, the calling program should set
.I errno
to 0 before the call,
and then determine if an error occurred by checking whether
.I errno
has a nonzero value after the call.

In the glibc implementation, the
.IR n-char-sequence
that optionally follows "NAN"
is interpreted as an integer number
(with an optional '0' or '0x' prefix to select base 8 or 16)
that is to be placed in the
mantissa component of the returned value.
.\" From glibc 2.8's stdlib/strtod_l.c:
.\"     We expect it to be a number which is put in the
.\"     mantissa of the number.
.\" It looks as though at least FreeBSD (according to the manual) does
.\" something similar.
.\" C11 says: "An implementation may use the n-char sequence to determine
.\"	extra information to be represented in the NaN's significant."
.SH EXAMPLE
See the example on the
.BR strtol (3)
manual page;
the use of the functions described in this manual page is similar.
.SH SEE ALSO
.BR atof (3),
.BR atoi (3),
.BR atol (3),
.BR nan (3),
.BR nanf (3),
.BR nanl (3),
.BR strtol (3),
.BR strtoul (3)
Commit	Line	Data
	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	.\"
	8	.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
	9	.\" Redistribution and use in source and binary forms, with or without
	10	.\" modification, are permitted provided that the following conditions
	11	.\" are met:
	12	.\" 1. Redistributions of source code must retain the above copyright
	13	.\" notice, this list of conditions and the following disclaimer.
	14	.\" 2. Redistributions in binary form must reproduce the above copyright
	15	.\" notice, this list of conditions and the following disclaimer in the
	16	.\" documentation and/or other materials provided with the distribution.
	17	.\" 3. All advertising materials mentioning features or use of this software
	18	.\" must display the following acknowledgement:
	19	.\" This product includes software developed by the University of
	20	.\" California, Berkeley and its contributors.
	21	.\" 4. Neither the name of the University nor the names of its contributors
	22	.\" may be used to endorse or promote products derived from this software
	23	.\" without specific prior written permission.
	24	.\"
	25	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	26	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	27	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	28	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	29	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	30	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	31	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	32	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	33	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	34	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	35	.\" SUCH DAMAGE.
	36	.\" %%%LICENSE_END
	37	.\"
	38	.\" @(#)strtod.3 5.3 (Berkeley) 6/29/91
	39	.\"
	40	.\" Modified Sun Aug 21 17:16:22 1994 by Rik Faith (faith@cs.unc.edu)
	41	.\" Modified Sat May 04 19:34:31 MET DST 1996 by Michael Haardt
	42	.\" (michael@cantor.informatik.rwth-aachen.de)
	43	.\" Added strof, strtold, aeb, 2001-06-07
	44	.\"
	45	.TH STRTOD 3 2015-08-08 "Linux" "Linux Programmer's Manual"
	46	.SH NAME
	47	strtod, strtof, strtold \- convert ASCII string to floating-point number
	48	.SH SYNOPSIS
	49	.B #include <stdlib.h>
	50	.sp
	51	.BI "double strtod(const char " nptr ", char *" endptr );
	52	.br
	53	.BI "float strtof(const char " nptr ", char *" endptr );
	54	.br
	55	.BI "long double strtold(const char " nptr ", char *" endptr );
	56	.sp
	57	.in -4n
	58	Feature Test Macro Requirements for glibc (see
	59	.BR feature_test_macros (7)):
	60	.in
	61	.ad l
	62	.sp
	63	.BR strtof (),
	64	.BR strtold ():
	65	.RS 4
	66	_XOPEN_SOURCE\ >=\ 600 \|\| _ISOC99_SOURCE \|\|
	67	_POSIX_C_SOURCE\ >=\ 200112L;
	68	.br
	69	or
	70	.I cc\ -std=c99
	71	.RE
	72	.ad
	73	.SH DESCRIPTION
	74	The
	75	.BR strtod (),
	76	.BR strtof (),
	77	and
	78	.BR strtold ()
	79	functions convert the initial portion of the string pointed to by
	80	.I nptr
	81	to
	82	.IR double ,
	83	.IR float ,
	84	and
	85	.I long double
	86	representation, respectively.
	87
	88	The expected form of the (initial portion of the) string is
	89	optional leading white space as recognized by
	90	.BR isspace (3),
	91	an optional plus (\(aq+\(aq) or minus sign (\(aq\-\(aq) and then either
	92	(i) a decimal number, or (ii) a hexadecimal number,
	93	or (iii) an infinity, or (iv) a NAN (not-a-number).
	94	.LP
	95	A
	96	.I "decimal number"
	97	consists of a nonempty sequence of decimal digits
	98	possibly containing a radix character (decimal point, locale-dependent,
	99	usually \(aq.\(aq), optionally followed by a decimal exponent.
	100	A decimal exponent consists of an \(aqE\(aq or \(aqe\(aq, followed by an
	101	optional plus or minus sign, followed by a nonempty sequence of
	102	decimal digits, and indicates multiplication by a power of 10.
	103	.LP
	104	A
	105	.I "hexadecimal number"
	106	consists of a "0x" or "0X" followed by a nonempty sequence of
	107	hexadecimal digits possibly containing a radix character,
	108	optionally followed by a binary exponent.
	109	A binary exponent
	110	consists of a \(aqP\(aq or \(aqp\(aq, followed by an optional
	111	plus or minus sign, followed by a nonempty sequence of
	112	decimal digits, and indicates multiplication by a power of 2.
	113	At least one of radix character and binary exponent must be present.
	114	.LP
	115	An
	116	.I infinity
	117	is either "INF" or "INFINITY", disregarding case.
	118	.LP
	119	A
	120	.I NAN
	121	is "NAN" (disregarding case) optionally followed by a string,
	122	.IR (n-char-sequence) ,
	123	where
	124	.IR n-char-sequence
	125	specifies in an implementation-dependent
	126	way the type of NAN (see NOTES).
	127	.SH RETURN VALUE
	128	These functions return the converted value, if any.
	129
	130	If
	131	.I endptr
	132	is not NULL,
	133	a pointer to the character after the last character used in the conversion
	134	is stored in the location referenced by
	135	.IR endptr .
	136
	137	If no conversion is performed, zero is returned and the value of
	138	.I nptr
	139	is stored in the location referenced by
	140	.IR endptr .
	141
	142	If the correct value would cause overflow, plus or minus
	143	.B HUGE_VAL
	144	.RB ( HUGE_VALF ,
	145	.BR HUGE_VALL )
	146	is returned (according to the sign of the value), and
	147	.B ERANGE
	148	is stored in
	149	.IR errno .
	150	If the correct value would cause underflow, zero is
	151	returned and
	152	.B ERANGE
	153	is stored in
	154	.IR errno .
	155	.SH ERRORS
	156	.TP
	157	.B ERANGE
	158	Overflow or underflow occurred.
	159	.SH ATTRIBUTES
	160	For an explanation of the terms used in this section, see
	161	.BR attributes (7).
	162	.TS
	163	allbox;
	164	lbw29 lb lb
	165	l l l.
	166	Interface Attribute Value
	167	T{
	168	.BR strtod (),
	169	.BR strtof (),
	170	.BR strtold ()
	171	T} Thread safety MT-Safe locale
	172	.TE
	173	.SH CONFORMING TO
	174	POSIX.1-2001, POSIX.1-2008, C99.
	175
	176	.BR strtod ()
	177	was also described in C89.
	178	.SH NOTES
	179	Since
	180	0 can legitimately be returned
	181	on both success and failure, the calling program should set
	182	.I errno
	183	to 0 before the call,
	184	and then determine if an error occurred by checking whether
	185	.I errno
	186	has a nonzero value after the call.
	187
	188	In the glibc implementation, the
	189	.IR n-char-sequence
	190	that optionally follows "NAN"
	191	is interpreted as an integer number
	192	(with an optional '0' or '0x' prefix to select base 8 or 16)
	193	that is to be placed in the
	194	mantissa component of the returned value.
	195	.\" From glibc 2.8's stdlib/strtod_l.c:
	196	.\" We expect it to be a number which is put in the
	197	.\" mantissa of the number.
	198	.\" It looks as though at least FreeBSD (according to the manual) does
	199	.\" something similar.
	200	.\" C11 says: "An implementation may use the n-char sequence to determine
	201	.\" extra information to be represented in the NaN's significant."
	202	.SH EXAMPLE
	203	See the example on the
	204	.BR strtol (3)
	205	manual page;
	206	the use of the functions described in this manual page is similar.
	207	.SH SEE ALSO
	208	.BR atof (3),
	209	.BR atoi (3),
	210	.BR atol (3),
	211	.BR nan (3),
	212	.BR nanf (3),
	213	.BR nanl (3),
	214	.BR strtol (3),
	215	.BR strtoul (3)