original/man3/strtod.3

   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 2014-08-19 "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 .SS Multithreading (see pthreads(7))
 161 The
 162 .BR strtod (),
 163 .BR strtof (),
 164 and
 165 .BR strtold ()
 166 functions are thread-safe with exceptions.
 167 These functions can be safely used in multithreaded applications,
 168 as long as
 169 .BR setlocale (3)
 170 is not called to change the locale during their execution.
 171 .SH CONFORMING TO
 172 C89 describes
 173 .BR strtod (),
 174 C99
 175 describes the other two functions.
 176 .SH NOTES
 177 Since
 178 0 can legitimately be returned
 179 on both success and failure, the calling program should set
 180 .I errno
 181 to 0 before the call,
 182 and then determine if an error occurred by checking whether
 183 .I errno
 184 has a nonzero value after the call.
 185
 186 In the glibc implementation, the
 187 .IR n-char-sequence
 188 that optionally follows "NAN"
 189 is interpreted as an integer number
 190 (with an optional '0' or '0x' prefix to select base 8 or 16)
 191 that is to be placed in the
 192 mantissa component of the returned value.
 193 .\" From glibc 2.8's stdlib/strtod_l.c:
 194 .\"     We expect it to be a number which is put in the
 195 .\"     mantissa of the number.
 196 .\" It looks as though at least FreeBSD (according to the manual) does
 197 .\" something similar.
 198 .\" C11 says: "An implementation may use the n-char sequence to determine
 199 .\"     extra information to be represented in the NaN's significant."
 200 .SH EXAMPLE
 201 See the example on the
 202 .BR strtol (3)
 203 manual page;
 204 the use of the functions described in this manual page is similar.
 205 .SH SEE ALSO
 206 .BR atof (3),
 207 .BR atoi (3),
 208 .BR atol (3),
 209 .BR nan (3),
 210 .BR nanf (3),
 211 .BR nanl (3),
 212 .BR strtol (3),
 213 .BR strtoul (3)