.\" 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:
.\" 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
.\"
.\" (michael@cantor.informatik.rwth-aachen.de)
.\" Added strof, strtold, aeb, 2001-06-07
.\"
-.TH STRTOD 3 2001-06-07 "Linux" "Library functions"
+.TH STRTOD 3 2017-09-15 "Linux" "Linux Programmer's Manual"
.SH NAME
-strtod, strtof, strtold \- convert ASCII string to floating point number
+strtod, strtof, strtold \- convert ASCII string to floating-point number
.SH SYNOPSIS
.B #include <stdlib.h>
-.sp
+.PP
.BI "double strtod(const char *" nptr ", char **" endptr );
-.sp
-.BR "#define _XOPEN_SOURCE=600" " /* or #define _ISOC99_SOURCE */"
.br
-.B #include <stdlib.h>
-.sp
.BI "float strtof(const char *" nptr ", char **" endptr );
.br
.BI "long double strtold(const char *" nptr ", char **" endptr );
+.PP
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.ad l
+.PP
+.BR strtof (),
+.BR strtold ():
+.RS 4
+_ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L
+.RE
+.ad
.SH DESCRIPTION
The
.BR strtod (),
.IR double ,
.IR float ,
and
-.I long double
+.I long double
representation, respectively.
-
+.PP
The expected form of the (initial portion of the) string is
-optional leading white space as recognized by \fIisspace\fP(3),
-an optional plus (``+'') or minus sign (``\-'') and then either
+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
+.PP
A
.I "decimal number"
consists of a nonempty sequence of decimal digits
-possibly containing a radix character (decimal point, locale dependent,
-usually ``.''), optionally followed by a decimal exponent. A
-decimal exponent consists of an ``E'' or ``e'', followed by an
-optional plus or minus sign, followed by a non-empty sequence of
+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
+.PP
A
.I "hexadecimal number"
-consists of a ``0x'' or ``0X'' followed by a nonempty sequence of
+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 ``P'' or ``p'', followed by an optional
-plus or minus sign, followed by a non-empty sequence of
+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
+.PP
An
.I infinity
-is either ``INF'' or ``INFINITY'', disregarding case.
-.LP
+is either "INF" or "INFINITY", disregarding case.
+.PP
A
.I NAN
-is ``NAN'' (disregarding case) optionally followed by `(',
-a sequence of characters, followed by ')'.
-The character string specifies in an implementation-dependent
-way the type of NAN.
-
-.SH "RETURN VALUE"
+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.
-
+.PP
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
+.PP
+If no conversion is performed, zero is returned and (unless
+.I endptr
+is null) the value of
.I nptr
is stored in the location referenced by
.IR endptr .
-
+.PP
If the correct value would cause overflow, plus or minus
.B HUGE_VAL
.RB ( HUGE_VALF ,
If the correct value would cause underflow, zero is
returned and
.B ERANGE
-is stored in
+is stored in
.IR errno .
.SH ERRORS
.TP
.B ERANGE
Overflow or underflow occurred.
-.SH "CONFORMING TO"
-ANSI C describes
+.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 (),
-C99
-describes the other two functions.
+.BR strtof (),
+.BR strtold ()
+T} Thread safety MT-Safe locale
+.TE
+.SH CONFORMING TO
+POSIX.1-2001, POSIX.1-2008, C99.
+.PP
+.BR strtod ()
+was also described in C89.
.SH NOTES
-Since
-0 can legitimately be returned
+Since
+0 can legitimately be returned
on both success and failure, the calling program should set
.I errno
-to 0 before the call,
+to 0 before the call,
and then determine if an error occurred by checking whether
.I errno
-has a non-zero value after the call.
+has a nonzero value after the call.
+.PP
+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;
+manual page;
the use of the functions described in this manual page is similar.
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR atof (3),
.BR atoi (3),
.BR atol (3),
+.BR nan (3),
+.BR nanf (3),
+.BR nanl (3),
+.BR strfromd (3),
.BR strtol (3),
.BR strtoul (3)
projects / thirdparty / man-pages.git / blobdiff