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-01-22 "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 l
  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 \(aq(\(aq,
 122 a sequence of characters, followed by \(aq)\(aq.
 123 The character string specifies in an implementation-dependent
 124 way the type of NAN.
 125 .\" From glibc 2.8's stdlib/strtod_l.c:
 126 .\"     We expect it to be a number which is put in the
 127 .\"     mantissa of the number.
 128 .SH RETURN VALUE
 129 These functions return the converted value, if any.
 130
 131 If
 132 .I endptr
 133 is not NULL,
 134 a pointer to the character after the last character used in the conversion
 135 is stored in the location referenced by
 136 .IR endptr .
 137
 138 If no conversion is performed, zero is returned and the value of
 139 .I nptr
 140 is stored in the location referenced by
 141 .IR endptr .
 142
 143 If the correct value would cause overflow, plus or minus
 144 .B HUGE_VAL
 145 .RB ( HUGE_VALF ,
 146 .BR HUGE_VALL )
 147 is returned (according to the sign of the value), and
 148 .B ERANGE
 149 is stored in
 150 .IR errno .
 151 If the correct value would cause underflow, zero is
 152 returned and
 153 .B ERANGE
 154 is stored in
 155 .IR errno .
 156 .SH ERRORS
 157 .TP
 158 .B ERANGE
 159 Overflow or underflow occurred.
 160 .SH ATTRIBUTES
 161 .SS Multithreading (see pthreads(7))
 162 The
 163 .BR strtod (),
 164 .BR strtof (),
 165 and
 166 .BR strtold ()
 167 functions are thread-safe with exceptions.
 168 These functions can be safely used in multithreaded applications,
 169 as long as
 170 .BR setlocale (3)
 171 is not called to change the locale during their execution.
 172 .SH CONFORMING TO
 173 C89 describes
 174 .BR strtod (),
 175 C99
 176 describes the other two functions.
 177 .SH NOTES
 178 Since
 179 0 can legitimately be returned
 180 on both success and failure, the calling program should set
 181 .I errno
 182 to 0 before the call,
 183 and then determine if an error occurred by checking whether
 184 .I errno
 185 has a nonzero value after the call.
 186 .SH EXAMPLE
 187 See the example on the
 188 .BR strtol (3)
 189 manual page;
 190 the use of the functions described in this manual page is similar.
 191 .SH SEE ALSO
 192 .BR atof (3),
 193 .BR atoi (3),
 194 .BR atol (3),
 195 .BR strtol (3),
 196 .BR strtoul (3)
 197 .SH COLOPHON
 198 This page is part of release 3.67 of the Linux
 199 .I man-pages
 200 project.
 201 A description of the project,
 202 information about reporting bugs,
 203 and the latest version of this page,
 204 can be found at
 205 \%http://www.kernel.org/doc/man\-pages/.