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 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)strtod.3    5.3 (Berkeley) 6/29/91
  37 .\"
  38 .\" Modified Sun Aug 21 17:16:22 1994 by Rik Faith (faith@cs.unc.edu)
  39 .\" Modified Sat May 04 19:34:31 MET DST 1996 by Michael Haardt
  40 .\"   (michael@cantor.informatik.rwth-aachen.de)
  41 .\" Added strof, strtold, aeb, 2001-06-07
  42 .\"
  43 .TH STRTOD 3 2001-06-07 "Linux" "Library functions"
  44 .SH NAME
  45 strtod, strtof, strtold \- convert ASCII string to floating point number
  46 .SH SYNOPSIS
  47 .B #include <stdlib.h>
  48 .sp
  49 .BI "double strtod(const char *" nptr ", char **" endptr );
  50 .sp
  51 .BR "#define _XOPEN_SOURCE 600" "   /* or #define _ISOC99_SOURCE */"
  52 .br
  53 .B #include <stdlib.h>
  54 .sp
  55 .BI "float strtof(const char *" nptr ", char **" endptr );
  56 .br
  57 .BI "long double strtold(const char *" nptr ", char **" endptr );
  58 .SH DESCRIPTION
  59 The
  60 .BR strtod (),
  61 .BR strtof (),
  62 and
  63 .BR strtold ()
  64 functions convert the initial portion of the string pointed to by
  65 .I nptr
  66 to
  67 .IR double ,
  68 .IR float ,
  69 and
  70 .I long double
  71 representation, respectively.
  72
  73 The expected form of the (initial portion of the) string is
  74 optional leading white space as recognized by \fBisspace\fP(3),
  75 an optional plus (``+'') or minus sign (``\-'') and then either
  76 (i) a decimal number, or (ii) a hexadecimal number,
  77 or (iii) an infinity, or (iv) a NAN (not-a-number).
  78 .LP
  79 A
  80 .I "decimal number"
  81 consists of a nonempty sequence of decimal digits
  82 possibly containing a radix character (decimal point, locale dependent,
  83 usually ``.''), optionally followed by a decimal exponent.  A
  84 decimal exponent consists of an ``E'' or ``e'', followed by an
  85 optional plus or minus sign, followed by a non-empty sequence of
  86 decimal digits, and indicates multiplication by a power of 10.
  87 .LP
  88 A
  89 .I "hexadecimal number"
  90 consists of a ``0x'' or ``0X'' followed by a nonempty sequence of
  91 hexadecimal digits possibly containing a radix character,
  92 optionally followed by a binary exponent. A binary exponent
  93 consists of a ``P'' or ``p'', followed by an optional
  94 plus or minus sign, followed by a non-empty sequence of
  95 decimal digits, and indicates multiplication by a power of 2.
  96 At least one of radix character and binary exponent must be present.
  97 .LP
  98 An
  99 .I infinity
 100 is either ``INF'' or ``INFINITY'', disregarding case.
 101 .LP
 102 A
 103 .I NAN
 104 is ``NAN'' (disregarding case) optionally followed by `(',
 105 a sequence of characters, followed by ')'.
 106 The character string specifies in an implementation-dependent
 107 way the type of NAN.
 108 .SH "RETURN VALUE"
 109 These functions return the converted value, if any.
 110
 111 If
 112 .I endptr
 113 is not NULL,
 114 a pointer to the character after the last character used in the conversion
 115 is stored in the location referenced by
 116 .IR endptr .
 117
 118 If no conversion is performed, zero is returned and the value of
 119 .I nptr
 120 is stored in the location referenced by
 121 .IR endptr .
 122
 123 If the correct value would cause overflow, plus or minus
 124 .B HUGE_VAL
 125 .RB ( HUGE_VALF ,
 126 .BR HUGE_VALL )
 127 is returned (according to the sign of the value), and
 128 .B ERANGE
 129 is stored in
 130 .IR errno .
 131 If the correct value would cause underflow, zero is
 132 returned and
 133 .B ERANGE
 134 is stored in
 135 .IR errno .
 136 .SH ERRORS
 137 .TP
 138 .B ERANGE
 139 Overflow or underflow occurred.
 140 .SH "CONFORMING TO"
 141 C89 describes
 142 .BR strtod (),
 143 C99
 144 describes the other two functions.
 145 .SH NOTES
 146 Since
 147 0 can legitimately be returned
 148 on both success and failure, the calling program should set
 149 .I errno
 150 to 0 before the call,
 151 and then determine if an error occurred by checking whether
 152 .I errno
 153 has a non-zero value after the call.
 154 .SH EXAMPLE
 155 See the example on the
 156 .BR strtol (3)
 157 manual page;
 158 the use of the functions described in this manual page is similar.
 159 .SH "SEE ALSO"
 160 .BR atof (3),
 161 .BR atoi (3),
 162 .BR atol (3),
 163 .BR strtol (3),
 164 .BR strtoul (3),
 165 .BR feature_test_macros (7)