strtold man page on OpenIndiana

Man page or keyword search:  
man Server   20441 pages
apropos Keyword Search (all sections)
Output format
OpenIndiana logo
[printable version]

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  charac‐
		  ters (as specified by isspace(3C))

	   2.	  A  subject sequence interpreted as a floating-point constant
		  or representing 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
		  character, 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-sequence(opt)),  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-sequence(opt)) 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_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 underflow

       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	     │Committed			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │MT-Safe with exceptions	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Standard		     │See standards(5).		   │
       └─────────────────────────────┴─────────────────────────────┘

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  charac‐
		  ters	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, errno will be left	unchanged.  (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 whose
		      conversion 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 fol‐
		  lowing occurred:

	       a.     If +HUGE_VAL is returned and errno is set to  ERANGE,  a
		      floating point overflow occurred while processing a pos‐
		      itive 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 neg‐
		      ative value, causing a floating point overflow exception
		      to be raised.

	       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) can be distinguished from cases (a) and (b) by examining either
	   ERANGE or the overflow flag.

SunOS 5.11			  1 Nov 2003			    strtod(3C)
[top]

List of man pages available for OpenIndiana

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net