man3/expm1.3

   1 '\" t
   2 .\" Copyright 1995 Jim Van Zandt <jrv@vanzandt.mv.com>
   3 .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
   4 .\"     <mtk.manpages@gmail.com>
   5 .\"
   6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   7 .\"
   8 .\" Modified 2002-07-27 Walter Harms
   9 .\"     (walter.harms@informatik.uni-oldenburg.de)
  10 .\"
  11 .TH expm1 3 (date) "Linux man-pages (unreleased)"
  12 .SH NAME
  13 expm1, expm1f, expm1l \- exponential minus 1
  14 .SH LIBRARY
  15 Math library
  16 .RI ( libm ", " \-lm )
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <math.h>
  20 .PP
  21 .BI "double expm1(double " x );
  22 .BI "float expm1f(float " x );
  23 .BI "long double expm1l(long double " x );
  24 .PP
  25 .fi
  26 .RS -4
  27 Feature Test Macro Requirements for glibc (see
  28 .BR feature_test_macros (7)):
  29 .RE
  30 .PP
  31 .BR expm1 ():
  32 .nf
  33     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  34         || _XOPEN_SOURCE >= 500
  35 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  36         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  37         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  38 .fi
  39 .PP
  40 .BR expm1f (),
  41 .BR expm1l ():
  42 .nf
  43     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  44         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  45         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  46 .fi
  47 .SH DESCRIPTION
  48 These functions return a value equivalent to
  49 .PP
  50 .nf
  51     exp(x) \- 1
  52 .fi
  53 .PP
  54 The result is computed in a way that is accurate even if the value of
  55 .I x
  56 is near
  57 zero\[em]a case where
  58 .I "exp(x) \- 1"
  59 would be inaccurate due to
  60 subtraction of two numbers that are nearly equal.
  61 .SH RETURN VALUE
  62 On success, these functions return
  63 .IR "exp(x)\ \-\ 1" .
  64 .PP
  65 If
  66 .I x
  67 is a NaN,
  68 a NaN is returned.
  69 .PP
  70 If
  71 .I x
  72 is +0 (\-0),
  73 +0 (\-0) is returned.
  74 .PP
  75 If
  76 .I x
  77 is positive infinity, positive infinity is returned.
  78 .PP
  79 If
  80 .I x
  81 is negative infinity, \-1 is returned.
  82 .PP
  83 If the result overflows, a range error occurs,
  84 and the functions return
  85 .RB \- HUGE_VAL ,
  86 .RB \- HUGE_VALF ,
  87 or
  88 .RB \- HUGE_VALL ,
  89 respectively.
  90 .SH ERRORS
  91 See
  92 .BR math_error (7)
  93 for information on how to determine whether an error has occurred
  94 when calling these functions.
  95 .PP
  96 The following errors can occur:
  97 .TP
  98 Range error, overflow
  99 .I errno
 100 is set to
 101 .B ERANGE
 102 (but see BUGS).
 103 An overflow floating-point exception
 104 .RB ( FE_OVERFLOW )
 105 is raised.
 106 .\"
 107 .\" POSIX.1 specifies an optional range error (underflow) if
 108 .\" x is subnormal.  glibc does not implement this.
 109 .SH ATTRIBUTES
 110 For an explanation of the terms used in this section, see
 111 .BR attributes (7).
 112 .TS
 113 allbox;
 114 lbx lb lb
 115 l l l.
 116 Interface       Attribute       Value
 117 T{
 118 .na
 119 .nh
 120 .BR expm1 (),
 121 .BR expm1f (),
 122 .BR expm1l ()
 123 T}      Thread safety   MT-Safe
 124 .TE
 125 .sp 1
 126 .SH STANDARDS
 127 C11, POSIX.1-2008.
 128 .SH HISTORY
 129 C99, POSIX.1-2001.
 130 BSD.
 131 .SH BUGS
 132 Before glibc 2.17,
 133 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6778
 134 on certain architectures (e.g., x86, but not x86_64)
 135 .BR expm1 ()
 136 raised a bogus underflow floating-point exception
 137 for some large negative
 138 .I x
 139 values (where the function result approaches \-1).
 140 .PP
 141 Before approximately glibc 2.11,
 142 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6814
 143 .\" e.g., expm1(1e5) through expm1(1.00199970127e5),
 144 .\" but not expm1(1.00199970128e5) and beyond.
 145 .BR expm1 ()
 146 raised a bogus invalid floating-point exception in addition to the expected
 147 overflow exception, and returned a NaN instead of positive infinity,
 148 for some large positive
 149 .I x
 150 values.
 151 .PP
 152 Before glibc 2.11,
 153 .\" It looks like the fix was in glibc 2.11, or possibly glibc 2.12.
 154 .\" I have no test system for glibc 2.11, but glibc 2.12 passes.
 155 .\" From the source (sysdeps/i386/fpu/s_expm1.S) it looks
 156 .\" like the changes were in glibc 2.11.
 157 the glibc implementation did not set
 158 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6788
 159 .I errno
 160 to
 161 .B ERANGE
 162 when a range error occurred.
 163 .SH SEE ALSO
 164 .BR exp (3),
 165 .BR log (3),
 166 .BR log1p (3)