Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
strtod(3C)		 Standard C Library Functions		    strtod(3C)

NAME
       strtod, strtof, strtold,	atof - convert string to floating-point	number

SYNOPSIS
       #include	<stdlib.h>

       double strtod(const char	*restrict nptr,	char **restrict	endptr);

       float strtof(const char *restrict nptr, char **restrict endptr);

       long double strtold(const char *restrict	nptr, char **restrict endptr);

       double atof(const char *str);

DESCRIPTION
       The  strtod(),  strtof(),  and  strtold() functions convert the initial
       portion of the string pointed to	by nptr	to  double,  float,  and  long
       double  representation,	respectively.  First  they decompose the input
       string into three parts:

       1.  An initial, possibly	empty, sequence	of white-space characters  (as
	   specified by	isspace(3C))

       2.  A subject sequence interpreted as a floating-point constant or rep-
	   resenting infinity or NaN

       3.  A final string of one or more  unrecognized	characters,  including
	   the terminating null	byte of	the input string.

       Then  they  attempt to convert the subject sequence to a	floating-point
       number, and return the result.

       The expected form of the	subject	sequence is an optional	plus or	 minus
       sign, then one of the following:

	 o  A non-empty	sequence of digits optionally containing a radix char-
	    acter, then	an optional exponent part

	 o  A 0x or 0X,	 then  a  non-empty  sequence  of  hexadecimal	digits
	    optionally	containing  a radix character, then an optional	binary
	    exponent part

	 o  One	of INF or INFINITY, ignoring case

	 o  One	of NAN or NAN(n-char-sequenceopt), ignoring case  in  the  NAN
	    part, where:

	    n-char-sequence:
		digit
		nondigit
		n-char-sequence	digit
		n-char-sequence	nondigit

       In   default   mode  for	 strtod(),  only  decimal,  INF/INFINITY,  and
       NAN/NAN(n-char-sequence)	forms are recognized. In C99/SUSv3 mode, hexa-
       decimal strings are also	recognized.

       In  default  mode  for strtod(),	the n-char-sequence in the NAN(n-char-
       equence)	form can contain any character except ')' (right  parenthesis)
       or  '\0'	 (null).   In  C99/SUSv3 mode, the n-char-sequence can contain
       only upper and lower case letters, digits, and '_' (underscore).

       The strtof() and	strtold() functions always function in	C99/SUSv3-con-
       formant mode.

       The  subject  sequence is defined as the	longest	initial	subsequence of
       the input string, starting with the  first  non-white-space  character,
       that  is	of the expected	form. The subject sequence contains no charac-
       ters if the input string	is not of the expected form.

       If the subject sequence has the expected	form for a floating-point num-
       ber,  the  sequence  of characters starting with	the first digit	or the
       decimal-point character (whichever 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  in  a	decimal	floating-point number, or if a
       binary exponent part does not appear in	a  hexadecimal	floating-point
       number,	an  exponent  part  of the appropriate type with value zero is
       assumed to follow the  last  digit  in  the  string.   If  the  subject
       sequence	 begins	 with  a  minus	 sign,	the sequence is	interpreted as
       negated.	A character sequence INF or  INFINITY  is  interpreted	as  an
       infinity. A character sequence NAN or NAN(n-char-sequenceopt) is	inter-
       preted as a quiet NaN. A	pointer	to the final string is stored  in  the
       object  pointed	to  by	endptr,	 provided  that	 endptr	 is not	a null
       pointer.

       If the subject sequence has either the decimal or hexadecimal form, the
       value  resulting	 from the conversion is	rounded	correctly according to
       the prevailing floating point rounding direction	mode.  The  conversion
       also  raises  floating point inexact, underflow,	or overflow exceptions
       as appropriate.

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

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

       The strtod() function does not change the setting of errno if  success-
       ful.

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

RETURN VALUES
       Upon successful completion, these functions return the converted	value.
       If no conversion	could be performed, 0 is returned.

       If  the	correct	 value	is  outside the	range of representable values,
       +-HUGE_VAL, +-HUGE_VALF,	or +-HUGE_VALL is returned (according  to  the
       sign  of	the value), a floating point overflow exception	is raised, and
       errno is	set to ERANGE.

       If the correct value would cause	an underflow,  the  correctly  rounded
       result  (which may be normal, subnormal,	or zero) is returned, a	float-
       ing point underflow exception is	raised,	and errno is set to ERANGE.

ERRORS
       These functions will fail if:

       ERANGE	       The value to be returned	would cause overflow or	under-
		       flow

       These functions may fail	if:

       EINVAL	       No conversion could be performed.

USAGE
       Since  0	is returned on error and is also a valid return	on success, an
       application wishing to check for	error situations should	set  errno  to
       0, then call strtod(), strtof(),	or strtold(), then check errno.

       The  changes  to	strtod() introduced by the ISO/IEC 9899: 1999 standard
       can alter the behavior of well-formed applications complying  with  the
       ISO/IEC	9899:  1990  standard  and  thus  earlier versions of IEEE Std
       1003.1-200x. One	such example would be:

       int
       what_kind_of_number (char *s)
       {
	    char *endp;
	    double d;
	    long l;
	    d =	strtod(s, &endp);
	    if (s != endp && *endp == `	')
		printf("It's a float with value	%g\n", d);
	    else
	    {
		l = strtol(s, &endp, 0);
		if (s != endp && *endp == `\0')
		    printf("It's an integer with value %ld\n", 1);
		else
		    return 1;
	    }
	    return 0;
       }

       If the function is called with:

       what_kind_of_number ("0x10")

       an ISO/IEC 9899:	1990 standard-compliant	library	 will  result  in  the
       function	printing:

       It's an integer with value 16

       With the	ISO/IEC	9899: 1999 standard, the result	is:

       It's a float with value 16

       The  change  in behavior	is due to the inclusion	of floating-point num-
       bers in hexadecimal notation without requiring that  either  a  decimal
       point or	the binary exponent be present.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |CSI			     |Enabled			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe with exceptions	   |
       +-----------------------------+-----------------------------+

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	 multithreaded
       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 (SUSv2) and
       the 1989	C Standard to describe the behavior of the strtod()  function.
       Since  some  users have reported	that they find the description confus-
       ing, the	following notes	might be helpful.

       1.  The strtod()	function does not modify the string pointed to by  str
	   and	does not malloc() space	to hold	the decomposed 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	evalu-
		   ated	to 0.0.	 (In this case,	errno will be left unchanged.)

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

	       c.  The "subject	sequence" specified a numeric value whose con-
		   version  resulted  in  a floating point underflow.  In this
		   case, an underflow exception	is raised and errno is set  to
		   ERANGE.

	   Note	that the standards do not require that implementations distin-
	   guish 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 character of
	   str when strtod() returns, you have detected	case  (b).   Case  (c)
	   can be detected by examining	the underflow flag or by looking for a
	   non-zero digit before the exponent part of the "subject  sequence".
	   Note,  however,  that  the decimal-point character is locale-depen-
	   dent.

       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	 posi-
		   tive	 value,	causing	a floating point overflow exception to
		   be raised.

	       b.  If -HUGE_VAL	is returned and	errno  is  set	to  ERANGE,  a
		   floating  point  overflow occurred while processing a nega-
		   tive	value, causing a floating point	overflow exception  to
		   be raised.

	       c.  If  strtod()	does not set errno to ERANGE, the value	speci-
		   fied	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) can be distinguished from cases (a) and (b) by examining	either
	   ERANGE or the overflow flag.

SunOS 5.10			  1 Nov	2003			    strtod(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=strtod&sektion=3c&manpath=SunOS+5.10>

home | help