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

ilogb.3p (5519B)


  1. '\" et
  2. .TH ILOGB "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. .EQ
  11. delim $$
  12. .EN
  13. .SH NAME
  14. ilogb,
  15. ilogbf,
  16. ilogbl
  17. \(em return an unbiased exponent
  18. .SH SYNOPSIS
  19. .LP
  20. .nf
  21. #include <math.h>
  22. .P
  23. int ilogb(double \fIx\fP);
  24. int ilogbf(float \fIx\fP);
  25. int ilogbl(long double \fIx\fP);
  26. .fi
  27. .SH DESCRIPTION
  28. The functionality described on this reference page is aligned with the
  29. ISO\ C standard. Any conflict between the requirements described here and the
  30. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  31. .P
  32. These functions shall return the exponent part of their argument
  33. .IR x .
  34. Formally, the return value is the integral part of $log sub{r}|x|$ as a
  35. signed integral value, for non-zero
  36. .IR x ,
  37. where
  38. .IR r
  39. is the radix of the machine's floating-point arithmetic, which is the
  40. value of FLT_RADIX defined in
  41. .IR <float.h> .
  42. .P
  43. An application wishing to check for error situations should set
  44. .IR errno
  45. to zero and call
  46. .IR feclearexcept (FE_ALL_EXCEPT)
  47. before calling these functions. On return, if
  48. .IR errno
  49. is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO |
  50. FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred.
  51. .SH "RETURN VALUE"
  52. Upon successful completion, these functions shall return the exponent
  53. part of
  54. .IR x
  55. as a signed integer value. They are equivalent to calling the
  56. corresponding
  57. \fIlogb\fR()
  58. function and casting the returned value to type
  59. .BR int .
  60. .P
  61. If
  62. .IR x
  63. is 0, the value FP_ILOGB0 shall be returned.
  64. On XSI-conformant systems, a domain error shall occur;
  65. .br
  66. otherwise, a
  67. domain
  68. error may occur.
  69. .P
  70. If
  71. .IR x
  72. is \(+-Inf, the value
  73. {INT_MAX}
  74. shall be returned.
  75. On XSI-conformant systems, a domain error shall occur;
  76. .br
  77. otherwise, a
  78. domain
  79. error may occur.
  80. .P
  81. If
  82. .IR x
  83. is a NaN, the value FP_ILOGBNAN shall be returned.
  84. On XSI-conformant systems, a domain error shall occur;
  85. .br
  86. otherwise, a
  87. domain
  88. error may occur.
  89. .P
  90. If the correct value is greater than
  91. {INT_MAX},
  92. a domain error shall occur and
  93. an unspecified value shall be returned.
  94. On XSI-conformant systems, a domain error shall occur and
  95. {INT_MAX}
  96. shall be returned.
  97. .P
  98. If the correct value is less than
  99. {INT_MIN},
  100. a domain error shall occur and
  101. an unspecified value shall be returned.
  102. On XSI-conformant systems, a domain error shall occur and
  103. {INT_MIN}
  104. shall be returned.
  105. .SH ERRORS
  106. These functions shall fail if:
  107. .IP "Domain\ Error" 12
  108. The correct value is not representable as an integer.
  109. .RS 12
  110. .P
  111. The
  112. .IR x
  113. argument is zero, NaN, or \(+-Inf.
  114. .P
  115. If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is
  116. non-zero, then
  117. .IR errno
  118. shall be set to
  119. .BR [EDOM] .
  120. If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is
  121. non-zero, then the invalid floating-point exception shall be raised.
  122. .RE
  123. .P
  124. These functions may fail if:
  125. .IP "Domain\ Error" 12
  126. The
  127. .IR x
  128. argument is zero, NaN, or \(+-Inf.
  129. .RS 12
  130. .P
  131. If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is
  132. non-zero, then
  133. .IR errno
  134. shall be set to
  135. .BR [EDOM] .
  136. If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is
  137. non-zero, then the invalid floating-point exception shall be raised.
  138. .RE
  139. .LP
  140. .IR "The following sections are informative."
  141. .SH EXAMPLES
  142. None.
  143. .SH "APPLICATION USAGE"
  144. On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and
  145. (\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each
  146. other, but at least one of them must be non-zero.
  147. .SH RATIONALE
  148. The errors come from taking the expected floating-point value and
  149. converting it to
  150. .BR int ,
  151. which is an invalid operation in IEEE\ Std\ 754\(hy1985 (since overflow, infinity, and
  152. NaN are not representable in a type
  153. .BR int ),
  154. so should be a domain error.
  155. .P
  156. There are no known implementations that overflow. For overflow to
  157. happen,
  158. {INT_MAX}
  159. must be less than LDBL_MAX_EXP*\fIlog2\fP(FLT_RADIX) or
  160. {INT_MIN}
  161. must be greater than LDBL_MIN_EXP*\fIlog2\fP(FLT_RADIX) if subnormals
  162. are not supported, or
  163. {INT_MIN}
  164. must be greater than (LDBL_MIN_EXP-LDBL_MANT_DIG)*\fIlog2\fP(FLT_RADIX)
  165. if subnormals are supported.
  166. .SH "FUTURE DIRECTIONS"
  167. None.
  168. .SH "SEE ALSO"
  169. .IR "\fIfeclearexcept\fR\^(\|)",
  170. .IR "\fIfetestexcept\fR\^(\|)",
  171. .IR "\fIlogb\fR\^(\|)",
  172. .IR "\fIscalbln\fR\^(\|)"
  173. .P
  174. The Base Definitions volume of POSIX.1\(hy2017,
  175. .IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions",
  176. .IR "\fB<float.h>\fP",
  177. .IR "\fB<math.h>\fP"
  178. .\"
  179. .SH COPYRIGHT
  180. Portions of this text are reprinted and reproduced in electronic form
  181. from IEEE Std 1003.1-2017, Standard for Information Technology
  182. -- Portable Operating System Interface (POSIX), The Open Group Base
  183. Specifications Issue 7, 2018 Edition,
  184. Copyright (C) 2018 by the Institute of
  185. Electrical and Electronics Engineers, Inc and The Open Group.
  186. In the event of any discrepancy between this version and the original IEEE and
  187. The Open Group Standard, the original IEEE and The Open Group Standard
  188. is the referee document. The original Standard can be obtained online at
  189. http://www.opengroup.org/unix/online.html .
  190. .PP
  191. Any typographical or formatting errors that appear
  192. in this page are most likely
  193. to have been introduced during the conversion of the source files to
  194. man page format. To report such errors, see
  195. https://www.kernel.org/doc/man-pages/reporting_bugs.html .