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  op-
	    tionally containing	a radix	character, then	an optional binary ex-
	    ponent 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 bi-
       nary exponent part does not appear in a hexadecimal floating-point num-
       ber,  an	 exponent  part	of the appropriate type	with value zero	is as-
       sumed 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 interpreted 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_NU-
       MERIC). In the POSIX locale, or in a locale where the  radix  character
       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),  at-
       tributes(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  lo-
       cale.

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