logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

strtod.3p (9751B)


  1. '\" et
  2. .TH STRTOD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. strtod,
  12. strtof,
  13. strtold
  14. \(em convert a string to a double-precision number
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <stdlib.h>
  19. .P
  20. double strtod(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP);
  21. float strtof(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP);
  22. long double strtold(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP);
  23. .fi
  24. .SH DESCRIPTION
  25. The functionality described on this reference page is aligned with the
  26. ISO\ C standard. Any conflict between the requirements described here and the
  27. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  28. .P
  29. These functions shall convert the initial portion of the string pointed
  30. to by
  31. .IR nptr
  32. to
  33. .BR double ,
  34. .BR float ,
  35. and
  36. .BR "long double"
  37. representation, respectively. First, they decompose the input string
  38. into three parts:
  39. .IP " 1." 4
  40. An initial, possibly empty, sequence of white-space characters (as
  41. specified by
  42. \fIisspace\fR())
  43. .IP " 2." 4
  44. A subject sequence interpreted as a floating-point constant or
  45. representing infinity or NaN
  46. .IP " 3." 4
  47. A final string of one or more unrecognized characters, including the
  48. terminating NUL character of the input string
  49. .P
  50. Then they shall attempt to convert the subject sequence to a
  51. floating-point number, and return the result.
  52. .P
  53. The expected form of the subject sequence is an optional
  54. .BR '+'
  55. or
  56. .BR '\-'
  57. sign, then one of the following:
  58. .IP " *" 4
  59. A non-empty sequence of decimal digits optionally containing a radix
  60. character; then an optional exponent part consisting of the character
  61. .BR 'e'
  62. or the character
  63. .BR 'E' ,
  64. optionally followed by a
  65. .BR '+'
  66. or
  67. .BR '\-'
  68. character, and then followed by one or more decimal digits
  69. .IP " *" 4
  70. A 0x or 0X, then a non-empty sequence of hexadecimal digits optionally
  71. containing a radix character; then an optional binary exponent part
  72. consisting of the character
  73. .BR 'p'
  74. or the character
  75. .BR 'P' ,
  76. optionally followed by a
  77. .BR '+'
  78. or
  79. .BR '\-'
  80. character, and then followed by one or more decimal digits
  81. .IP " *" 4
  82. One of INF or INFINITY, ignoring case
  83. .IP " *" 4
  84. One of NAN or NAN(\fIn-char-sequence\s-3\dopt\u\s+3\fR), ignoring case in
  85. the NAN part, where:
  86. .RS 4
  87. .sp
  88. .RS 4
  89. .nf
  90. n-char-sequence:
  91. digit
  92. nondigit
  93. n-char-sequence digit
  94. n-char-sequence nondigit
  95. .fi
  96. .P
  97. .RE
  98. .RE
  99. .P
  100. The subject sequence is defined as the longest initial subsequence of
  101. the input string, starting with the first non-white-space character,
  102. that is of the expected form. The subject sequence contains no
  103. characters if the input string is not of the expected form.
  104. .P
  105. If the subject sequence has the expected form for a floating-point
  106. number, the sequence of characters starting with the first digit or the
  107. decimal-point character (whichever occurs first) shall be interpreted
  108. as a floating constant of the C language, except that the radix
  109. character shall be used in place of a period, and that if neither an
  110. exponent part nor a radix character appears in a decimal floating-point
  111. number, or if a binary exponent part does not appear in a hexadecimal
  112. floating-point number, an exponent part of the appropriate type with
  113. value zero is assumed to follow the last digit in the string. If the
  114. subject sequence begins with a
  115. <hyphen-minus>,
  116. the sequence shall be
  117. interpreted as negated. A character sequence INF or INFINITY shall be
  118. interpreted as an infinity, if representable in the return type, else
  119. as if it were a floating constant that is too large for the range of
  120. the return type. A character sequence NAN or
  121. NAN(\fIn-char-sequence\s-3\dopt\u\s+3\fR) shall be interpreted as a
  122. quiet NaN, if supported in the return type, else as if it were a
  123. subject sequence part that does not have the expected form; the meaning
  124. of the \fIn\fR-char sequences is implementation-defined. A pointer to
  125. the final string is stored in the object pointed to by
  126. .IR endptr ,
  127. provided that
  128. .IR endptr
  129. is not a null pointer.
  130. .P
  131. If the subject sequence has the hexadecimal form and FLT_RADIX is a
  132. power of 2, the value resulting from the conversion is correctly
  133. rounded.
  134. .P
  135. The radix character is defined in the current locale (category
  136. .IR LC_NUMERIC ).
  137. In the POSIX locale, or in a locale where the radix character is not
  138. defined, the radix character shall default to a
  139. <period>
  140. (\c
  141. .BR '.' ).
  142. .P
  143. In other than the C
  144. or POSIX
  145. locale, additional locale-specific subject sequence forms may be
  146. accepted.
  147. .P
  148. If the subject sequence is empty or does not have the expected form, no
  149. conversion shall be performed; the value of
  150. .IR nptr
  151. is stored in the object pointed to by
  152. .IR endptr ,
  153. provided that
  154. .IR endptr
  155. is not a null pointer.
  156. .P
  157. These functions shall not change the setting of
  158. .IR errno
  159. if successful.
  160. .P
  161. Since 0 is returned on error and is also a valid return on success,
  162. an application wishing to check for error situations should set
  163. .IR errno
  164. to 0, then call
  165. \fIstrtod\fR(),
  166. \fIstrtof\fR(),
  167. or
  168. \fIstrtold\fR(),
  169. then check
  170. .IR errno .
  171. .SH "RETURN VALUE"
  172. Upon successful completion, these functions shall return the converted
  173. value. If no conversion could be performed, 0 shall be returned, and
  174. .IR errno
  175. may be set to
  176. .BR [EINVAL] .
  177. .P
  178. If the correct value is outside the range of representable values,
  179. \(+-HUGE_VAL, \(+-HUGE_VALF, or \(+-HUGE_VALL shall be returned
  180. (according to the sign of the value), and
  181. .IR errno
  182. shall be set to
  183. .BR [ERANGE] .
  184. .P
  185. If the correct value would cause an underflow, a value whose magnitude
  186. is no greater than the smallest normalized positive number in the
  187. return type shall be returned and
  188. .IR errno
  189. set to
  190. .BR [ERANGE] .
  191. .SH ERRORS
  192. These functions shall fail if:
  193. .TP
  194. .BR ERANGE
  195. The value to be returned would cause overflow
  196. or underflow.
  197. .P
  198. These functions may fail if:
  199. .TP
  200. .BR EINVAL
  201. No conversion could be performed.
  202. .LP
  203. .IR "The following sections are informative."
  204. .SH EXAMPLES
  205. None.
  206. .SH "APPLICATION USAGE"
  207. If the subject sequence has the hexadecimal form and FLT_RADIX is not a
  208. power of 2, and the result is not exactly representable, the result
  209. should be one of the two numbers in the appropriate internal format
  210. that are adjacent to the hexadecimal floating source value, with the
  211. extra stipulation that the error should have a correct sign for the
  212. current rounding direction.
  213. .P
  214. If the subject sequence has the decimal form and at most DECIMAL_DIG
  215. (defined in
  216. .IR <float.h> )
  217. significant digits, the result should be correctly rounded. If the
  218. subject sequence
  219. .IR D
  220. has the decimal form and more than DECIMAL_DIG significant digits,
  221. consider the two bounding, adjacent decimal strings
  222. .IR L
  223. and
  224. .IR U ,
  225. both having DECIMAL_DIG significant digits, such that the values of
  226. .IR L ,
  227. .IR D ,
  228. and
  229. .IR U
  230. satisfy
  231. .IR L
  232. <=
  233. .IR D
  234. <=
  235. .IR U .
  236. The result should be one of the (equal or adjacent) values that would
  237. be obtained by correctly rounding
  238. .IR L
  239. and
  240. .IR U
  241. according to the current rounding direction, with the extra stipulation
  242. that the error with respect to
  243. .IR D
  244. should have a correct sign for the current rounding direction.
  245. .P
  246. The changes to
  247. \fIstrtod\fR()
  248. introduced by the ISO/IEC\ 9899:\|1999 standard can alter the behavior of well-formed
  249. applications complying with the ISO/IEC\ 9899:\|1990 standard and thus earlier versions of
  250. this standard. One such example would be:
  251. .sp
  252. .RS 4
  253. .nf
  254. int
  255. what_kind_of_number (char *s)
  256. {
  257. char *endp;
  258. double d;
  259. long l;
  260. .P
  261. d = strtod(s, &endp);
  262. if (s != endp && *endp == `\e0\(aq)
  263. printf("It\(aqs a float with value %g\en", d);
  264. else
  265. {
  266. l = strtol(s, &endp, 0);
  267. if (s != endp && *endp == `\e0\(aq)
  268. printf("It\(aqs an integer with value %ld\en", 1);
  269. else
  270. return 1;
  271. }
  272. return 0;
  273. }
  274. .fi
  275. .P
  276. .RE
  277. .P
  278. If the function is called with:
  279. .sp
  280. .RS 4
  281. .nf
  282. what_kind_of_number ("0x10")
  283. .fi
  284. .P
  285. .RE
  286. .P
  287. an ISO/IEC\ 9899:\|1990 standard-compliant library will result in the function printing:
  288. .sp
  289. .RS 4
  290. .nf
  291. It\(aqs an integer with value 16
  292. .fi
  293. .P
  294. .RE
  295. .P
  296. With the ISO/IEC\ 9899:\|1999 standard, the result is:
  297. .sp
  298. .RS 4
  299. .nf
  300. It\(aqs a float with value 16
  301. .fi
  302. .P
  303. .RE
  304. .P
  305. The change in behavior is due to the inclusion of floating-point
  306. numbers in hexadecimal notation without requiring that either a decimal
  307. point or the binary exponent be present.
  308. .SH RATIONALE
  309. None.
  310. .SH "FUTURE DIRECTIONS"
  311. None.
  312. .SH "SEE ALSO"
  313. .IR "\fIfscanf\fR\^(\|)",
  314. .IR "\fIisspace\fR\^(\|)",
  315. .IR "\fIlocaleconv\fR\^(\|)",
  316. .IR "\fIsetlocale\fR\^(\|)",
  317. .IR "\fIstrtol\fR\^(\|)"
  318. .P
  319. The Base Definitions volume of POSIX.1\(hy2017,
  320. .IR "Chapter 7" ", " "Locale",
  321. .IR "\fB<float.h>\fP",
  322. .IR "\fB<stdlib.h>\fP"
  323. .\"
  324. .SH COPYRIGHT
  325. Portions of this text are reprinted and reproduced in electronic form
  326. from IEEE Std 1003.1-2017, Standard for Information Technology
  327. -- Portable Operating System Interface (POSIX), The Open Group Base
  328. Specifications Issue 7, 2018 Edition,
  329. Copyright (C) 2018 by the Institute of
  330. Electrical and Electronics Engineers, Inc and The Open Group.
  331. In the event of any discrepancy between this version and the original IEEE and
  332. The Open Group Standard, the original IEEE and The Open Group Standard
  333. is the referee document. The original Standard can be obtained online at
  334. http://www.opengroup.org/unix/online.html .
  335. .PP
  336. Any typographical or formatting errors that appear
  337. in this page are most likely
  338. to have been introduced during the conversion of the source files to
  339. man page format. To report such errors, see
  340. https://www.kernel.org/doc/man-pages/reporting_bugs.html .