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

FreeBSD Manual Pages


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

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

       #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);

       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
		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

       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-

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

       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.

       These functions will fail if:

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

       These functions may fail	if:

       EINVAL	       No conversion could be performed.

       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:

       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);
		l = strtol(s, &endp, 0);
		if (s != endp && *endp == `\0')
		    printf("It's an integer with value %ld\n", 1);
		    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.

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

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

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

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

       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

	   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-

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

	       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)


Want to link to this manual page? Use this URL:

home | help