atof(3C)




NAME

     strtod, atof - convert string to double-precision number


SYNOPSIS

     #include <stdlib.h>

     double strtod(const char *str, char **endptr);

     double atof(const char *str);


DESCRIPTION

     The strtod() function converts the initial  portion  of  the
     string  pointed  to  by  str  to type double representation.
     First it decomposes the input string into  three  parts:  an
     initial,  possibly empty, sequence of white-space characters
     (as specified by isspace(3C));  a  subject  sequence  inter-
     preted  as  a floating-point constant; and a final string of
     one or more unrecognized characters, including the terminat-
     ing  null byte of the input string. Then it attempts to con-
     vert the subject sequence to a  floating-point  number,  and
     returns the result.

     The expected form of the subject sequence is an  optional  +
     or  -  sign,  then a non-empty sequence of digits optionally
     containing a radix  character,  then  an  optional  exponent
     part.  An  exponent  part consists of e or E, followed by an
     optional sign, followed by one or more decimal  digits.  The
     subject  sequence  is  defined as the longest initial subse-
     quence of the input string, starting  with  the  first  non-
     white-space  character,  that  is  of the expected form. The
     subject sequence is empty if the input string  is  empty  or
     consists entirely of white-space characters, or if the first
     character that is not white space is other than  a  sign,  a
     digit or a radix character.

     If the subject sequence has the expected form, the  sequence
     starting with the first digit or the radix character (which-
     ever occurs first) is interpreted as a floating constant  of
     the  C  language, except that the radix character is used in
     place of a period, and that if neither an exponent part  nor
     a  radix  character appears, a radix character is assumed to
     follow the last digit in the string. If the subject sequence
     begins  with  a  minus  sign,  the  value resulting from the
     conversion is negated. A pointer  to  the  final  string  is
     stored  in  the  object  pointed to by endptr, provided that
     endptr is not a null pointer.

     The radix character  is  defined  in  the  program's  locale
     (category  LC_NUMERIC).  In the POSIX locale, or in a locale
     where the radix character is not defined, the radix  charac-
     ter defaults to a period (.).

     In  other  than  the  POSIX  locale,  other  implementation-
     dependent subject sequence forms may be accepted.

     If the subject sequence  is  empty  or  does  not  have  the
     expected  form, no conversion is performed; the value of str
     is stored in the object pointed to by endptr, provided  that
     endptr is not a null pointer.

  atof()
     The atof(str) function call  is  equivalent  to  strtod(str,
     (char **)NULL).


RETURN VALUES

     Upon successful completion, strtod() returns  the  converted
     value.  If  no  conversion could be performed, 0 is returned
     and errno may be set to EINVAL.

     If the correct value is outside the range  of  representable
     values,  _HUGE  is  returned  (according  to the sign of the
     value), and errno is set to ERANGE. When the -Xc or -Xa com-
     pilation  options  are used, HUGE_VAL is returned instead of
     HUGE.

     If the correct value would cause an underflow, 0 is returned
     and errno is set to ERANGE.

     If str is NaN, then atof() returns NaN.


ERRORS

     The strtod() function will fail if:

     ERANGE
           The value to  be  returned  would  cause  overflow  or
           underflow. The strtod() function may fail if:

     EINVAL
           No conversion could be performed.


USAGE

     Because 0 is returned on error and is also a valid return on
     success,  an  application  wishing to check for error situa-
     tions should set errno to 0, then call strtod(), then  check
     errno and if it is non-zero, assume an error has occurred.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe with exceptions     |
    |_____________________________|_____________________________|
    | CSI                         | Enabled                     |
    |_____________________________|_____________________________|


SEE ALSO

     isspace(3C),   localeconv(3C),   scanf(3C),   setlocale(3C),
     strtol(3C), attributes(5), standards(5)


NOTES

     The strtod() and atof() functions can be used safely in mul-
     tithreaded  applications,  as  long  as setlocale(3C) is not
     called to change the locale.

     The DESCRIPTION and RETURN VALUES sections  above  are  very
     similar to the wording used by the Single UNIX Specification
     version 2 and the 1989 C Standard to describe  the  behavior
     of  the  strtod()  function.  Since some users have reported
     that they find  the  description  confusing,  the  following
     notes may be helpful.

     1. The strtod() function does not modify the string  pointed
        to  by str and does not malloc() space to hold the decom-
        posed portions of the input string.

     2. If endptr is not (char **)NULL,  strtod()  will  set  the
        pointer  pointed  to  by  endptr to the first byte of the
        "final string of unrecognized characters".  (If all input
        characters  were  processed,  the  pointer  pointed to by
        endptr will be set to point to the null character at  the
        end of the input string.)

     3. If strtod() returns 0.0, one of the following occurred:

        a. The "subject sequence" was not an  empty  string,  but
           evaluated  to  0.0.  (In this case, errno will be left
           unchanged.)

        b. The "subject sequence" was an empty string.  (In  this
           case,  the  Single UNIX Specification version 2 allows
           errno to be set to EINVAL or  to  be  left  unchanged.
           The  C Standard does not specify any specific behavior
           in this case.)

        c. The "subject sequence" specified a numeric value  that
           would  cause  a  floating  point  underflow.  (In this
           case, errno may be  set  to  ERANGE  or  may  be  left
           unchanged.)

     Note that the standards do not require that  implementations
     distinguish  between  these three cases.  An application can
     determine case (b) by making sure that there are no  leading
     white-space  characters  in the string pointed to by str and
     giving strtod() an endptr that is  not  (char  **)NULL.   If
     endptr  points  to the first chartacter of str when strtod()
     returns, you have  detected  case  (b).   Case  (c)  can  be
     detected by looking for a non-zero digit before the exponent
     part of the "subject sequence".   Note,  however,  that  the
     decimal-point character is locale-dependent.

     4. If strtod() returns +HUGE_VAL or -HUGE_VAL,  one  of  the
        following occurred:

        a. If +HUGE_VAL is returned and errno is set to ERANGE, a
           floating  point  overflow  occurred while processing a
           positive value.

        b. If -HUGE_VAL is returned and errno is set to ERANGE, a
           floating  point  overflow  occurred while processing a
           negative value.

        c. If strtod() does not set errno to  ERANGE,  the  value
           specified   by   the  "subject  string"  converted  to
           +HUGE_VAL or -HUGE_VAL, respectively.

     Note that if errno is set to ERANGE when strtod() is called,
     case (c) is indistinguishable from cases (a) and (b).


Man(1) output converted with man2html