logb.3: floor(log2(fabs(x))) has rounding errors

[thirdparty/man-pages.git] / man3 / logb.3

'\" t
.\" Copyright 2004 Andries Brouwer <aeb@cwi.nl>.
.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
.\"     <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\" Inspired by a page by Walter Harms created 2002-08-10
.\"
.TH logb 3 (date) "Linux man-pages (unreleased)"
.SH NAME
logb, logbf, logbl \- get exponent of a floating-point value
.SH LIBRARY
Math library
.RI ( libm ", " \-lm )
.SH SYNOPSIS
.nf
.B #include <math.h>
.P
.BI "double logb(double " x );
.BI "float logbf(float " x );
.BI "long double logbl(long double " x );
.fi
.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
.P
.BR logb ():
.nf
    _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
        || _XOPEN_SOURCE >= 500
.\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
        || /* Since glibc 2.19: */ _DEFAULT_SOURCE
        || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
.P
.BR logbf (),
.BR logbl ():
.nf
    _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
        || /* Since glibc 2.19: */ _DEFAULT_SOURCE
        || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
.fi
.SH DESCRIPTION
These functions extract the exponent from the
internal floating-point representation of
.I x
and return it as a floating-point value.
The integer constant
.BR FLT_RADIX ,
defined in
.IR <float.h> ,
indicates the radix used for the system's floating-point representation.
If
.B FLT_RADIX
is 2,
.BI logb( x )
is similar to
.BI floor(log2(fabs( x )))\f[R],\f[]
except that the latter may give an incorrect integer
due to intermediate rounding.
.P
If
.I x
is subnormal,
.BR logb ()
returns the exponent
.I x
would have if it were normalized.
.SH RETURN VALUE
On success, these functions return the exponent of
.IR x .
.P
If
.I x
is a NaN,
a NaN is returned.
.P
If
.I x
is zero, then a pole error occurs, and the functions return
.RB \- HUGE_VAL ,
.RB \- HUGE_VALF ,
or
.RB \- HUGE_VALL ,
respectively.
.P
If
.I x
is negative infinity or positive infinity, then
positive infinity is returned.
.SH ERRORS
See
.BR math_error (7)
for information on how to determine whether an error has occurred
when calling these functions.
.P
The following errors can occur:
.TP
Pole error: \fIx\fP is 0
.\" .I errno
.\" is set to
.\" .BR ERANGE .
A divide-by-zero floating-point exception
.RB ( FE_DIVBYZERO )
is raised.
.P
These functions do not set
.IR errno .
.\" FIXME . Is it intentional that these functions do not set errno?
.\" log(), log2(), log10() do set errno
.\" Bug raised: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6793
.\"
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.TS
allbox;
lbx lb lb
l l l.
Interface	Attribute	Value
T{
.na
.nh
.BR logb (),
.BR logbf (),
.BR logbl ()
T}	Thread safety	MT-Safe
.TE
.SH STANDARDS
C11, POSIX.1-2008.
.SH HISTORY
C99, POSIX.1-2001.
.TP
.BR logb ()
4.3BSD
(see IEEE.3 in the 4.3BSD manual).
.SH SEE ALSO
.BR ilogb (3),
.BR log (3)