Loading...
stdlib/FreeBSD/strtod.3 Libc-763.13 Libc-1583.60.2
--- Libc/Libc-763.13/stdlib/FreeBSD/strtod.3
+++ Libc/Libc-1583.60.2/stdlib/FreeBSD/strtod.3
@@ -32,7 +32,7 @@
 .\"     @(#)strtod.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD: src/lib/libc/stdlib/strtod.3,v 1.22 2007/12/16 21:19:28 das Exp $
 .\"
-.Dd March 2, 2003
+.Dd July 2, 2021
 .Dt STRTOD 3
 .Os
 .Sh NAME
@@ -45,11 +45,20 @@
 .Sh SYNOPSIS
 .In stdlib.h
 .Ft double
-.Fn strtod "const char * restrict nptr" "char ** restrict endptr"
+.Fo strtod
+.Fa "const char *restrict nptr"
+.Fa "char **restrict endptr"
+.Fc
 .Ft float
-.Fn strtof "const char * restrict nptr" "char ** restrict endptr"
+.Fo strtof
+.Fa "const char *restrict nptr"
+.Fa "char **restrict endptr"
+.Fc
 .Ft "long double"
-.Fn strtold "const char * restrict nptr" "char ** restrict endptr"
+.Fo strtold
+.Fa "const char *restrict nptr"
+.Fa "char **restrict endptr"
+.Fc
 .Sh DESCRIPTION
 These conversion
 functions convert the initial portion of the string
@@ -62,16 +71,17 @@
 .Vt "long double"
 representation, respectively.
 .Pp
-The expected form of the string is an optional plus (``+'') or minus
-sign (``\-'') followed by either:
+The expected form of the string
+is an optional plus (``+'') or minus (``\-'') sign,
+followed by either:
 .Bl -bullet
 .It
-a decimal significand consisting of a sequence of decimal digits
-optionally containing a decimal-point character, or
+a decimal significand, consisting of a sequence of decimal digits
+(optionally containing a decimal-point character) or
 .It
-a hexadecimal significand consisting of a ``0X'' or ``0x'' followed
-by a sequence of hexadecimal digits optionally containing a
-decimal-point character.
+a hexadecimal significand, consisting of a ``0X'' or ``0x'' followed
+by a sequence of hexadecimal digits
+(optionally containing a decimal-point character).
 .El
 .Pp
 In both cases, the significand may be optionally followed by an
@@ -85,13 +95,17 @@
 For hexadecimal constants, the scaling is instead done by powers
 of 2.
 .Pp
-Alternatively, if the portion of the string following the optional
+If the portion of the string following the optional
 plus or minus sign begins with
 .Dq INFINITY
 or
+.Dq INF ,
+ignoring case, it is interpreted as an infinity.
+.Pp
+If the portion of the string following the optional
+plus or minus sign begins with
 .Dq NAN ,
-ignoring case, it is interpreted as an infinity or a quiet \*(Na,
-respectively.
+ignoring case, it is interpreted as a quiet \*(Na.
 The syntax
 .Dq Xo Pf NAN( Ar "s" ) Xc ,
 where
@@ -116,13 +130,28 @@
 The decimal point
 character is defined in the program's locale (category
 .Dv LC_NUMERIC ) .
+.Pp
+Extended locale versions of these functions are documented in
+.Xr strtod_l 3 .
+See
+.Xr xlocale 3
+for more information.
 .Sh RETURN VALUES
 The
 .Fn strtod ,
 .Fn strtof ,
 and
 .Fn strtold
-functions return the converted value, if any.
+functions return the converted value, if any, rounded to the nearest
+representable value of the corresponding type according to the rounding
+mode currently in effect.
+See
+.Xr fegetround 3
+for more information on rounding modes.
+If flush-to-zero behavior is enabled in the current floating-point
+environment, the behavior is identical except that any subnormal
+values that would be returned will instead be returned as the
+correspondingly-signed zero.
 .Pp
 If
 .Fa endptr
@@ -137,20 +166,26 @@
 is stored in the location referenced by
 .Fa endptr .
 .Pp
-If the correct value would cause overflow, plus or minus
+The input is converted by first rounding the value to the precision of
+the target type but allowing an unbounded exponent range.
+If the resulting exponent is too large for the target
+type, overflow is deemed to have occurred.
+Overflow is signalled by returning
 .Dv HUGE_VAL ,
 .Dv HUGE_VALF ,
 or
 .Dv HUGE_VALL
-is returned (according to the sign and type of the return value), and
+(according to the sign of the input and type of the return value), and storing
+.Er ERANGE
+in
+.Va errno .
+.Pp
+If the input string is not an explicit representation of zero and the
+correctly-rounded result is a subnormal or zero value, then
 .Er ERANGE
 is stored in
-.Va errno .
-If the correct value would cause underflow, zero is
-returned and
-.Er ERANGE
-is stored in
-.Va errno .
+.Va errno
+to indicate underflow has occurred.
 .Sh ERRORS
 .Bl -tag -width Er
 .It Bq Er ERANGE
@@ -161,6 +196,7 @@
 .Xr atoi 3 ,
 .Xr atol 3 ,
 .Xr nan 3 ,
+.Xr strtod_l 3 ,
 .Xr strtol 3 ,
 .Xr strtoul 3 ,
 .Xr wcstod 3
@@ -169,11 +205,7 @@
 .Fn strtod
 function
 conforms to
-.St -isoC-99 ,
-with the exception of the bug noted below.
-.Sh AUTHORS
-The author of this software is
-.An David M. Gay .
+.St -isoC-99 .
 .Pp
 .Bd -literal
 Copyright (c) 1998 by Lucent Technologies