man3/tgamma.3

   1 .\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de)
   2 .\"
   3 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   4 .\" Distributed under GPL
   5 .\" %%%LICENSE_END
   6 .\"
   7 .\" Based on glibc infopages
   8 .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
   9 .\"     <mtk.manpages@gmail.com>
  10 .\" Modified 2004-11-15, fixed error noted by Fabian Kreutz
  11 .\"      <kreutz@dbs.uni-hannover.de>
  12 .\"
  13 .TH TGAMMA 3 2017-09-15 "GNU" "Linux Programmer's Manual"
  14 .SH NAME
  15 tgamma, tgammaf, tgammal \- true gamma function
  16 .SH SYNOPSIS
  17 .B #include <math.h>
  18 .PP
  19 .BI "double tgamma(double " x );
  20 .br
  21 .BI "float tgammaf(float " x );
  22 .br
  23 .BI "long double tgammal(long double " x );
  24 .PP
  25 Link with \fI\-lm\fP.
  26 .PP
  27 .in -4n
  28 Feature Test Macro Requirements for glibc (see
  29 .BR feature_test_macros (7)):
  30 .in
  31 .PP
  32 .ad l
  33 .BR tgamma (),
  34 .BR tgammaf (),
  35 .BR tgammal ():
  36 .RS 4
  37 _ISOC99_SOURCE ||
  38 _POSIX_C_SOURCE\ >=\ 200112L
  39 .RE
  40 .ad
  41 .SH DESCRIPTION
  42 These functions calculate the Gamma function of
  43 .IR x .
  44 .PP
  45 The Gamma function is defined by
  46 .PP
  47 .RS
  48 Gamma(x) = integral from 0 to infinity of t^(x\-1) e^\-t dt
  49 .RE
  50 .PP
  51 It is defined for every real number except for nonpositive integers.
  52 For nonnegative integral
  53 .I m
  54 one has
  55 .PP
  56 .RS
  57 Gamma(m+1) = m!
  58 .RE
  59 .PP
  60 and, more generally, for all
  61 .IR x :
  62 .PP
  63 .RS
  64 Gamma(x+1) = x * Gamma(x)
  65 .RE
  66 .PP
  67 Furthermore, the following is valid for all values of
  68 .I x
  69 outside the poles:
  70 .PP
  71 .RS
  72 Gamma(x) * Gamma(1 \- x) = PI / sin(PI * x)
  73 .RE
  74 .SH RETURN VALUE
  75 On success, these functions return Gamma(x).
  76 .PP
  77 If
  78 .I x
  79 is a NaN, a NaN is returned.
  80 .PP
  81 If
  82 .I x
  83 is positive infinity, positive infinity is returned.
  84 .PP
  85 If
  86 .I x
  87 is a negative integer, or is negative infinity,
  88 a domain error occurs,
  89 and a NaN is returned.
  90 .PP
  91 If the result overflows,
  92 a range error occurs,
  93 and the functions return
  94 .BR HUGE_VAL ,
  95 .BR HUGE_VALF ,
  96 or
  97 .BR HUGE_VALL ,
  98 respectively, with the correct mathematical sign.
  99 .PP
 100 If the result underflows,
 101 a range error occurs,
 102 and the functions return 0, with the correct mathematical sign.
 103 .PP
 104 If
 105 .I x
 106 is \-0 or +0,
 107 a pole error occurs,
 108 and the functions return
 109 .BR HUGE_VAL ,
 110 .BR HUGE_VALF ,
 111 or
 112 .BR HUGE_VALL ,
 113 respectively, with the same sign as the 0.
 114 .SH ERRORS
 115 See
 116 .BR math_error (7)
 117 for information on how to determine whether an error has occurred
 118 when calling these functions.
 119 .PP
 120 The following errors can occur:
 121 .TP
 122 Domain error: \fIx\fP is a negative integer, or negative infinity
 123 .I errno
 124 is set to
 125 .BR EDOM .
 126 An invalid floating-point exception
 127 .RB ( FE_INVALID )
 128 is raised (but see BUGS).
 129 .TP
 130 Pole error: \fIx\fP is +0 or \-0
 131 .I errno
 132 is set to
 133 .BR ERANGE .
 134 A divide-by-zero floating-point exception
 135 .RB ( FE_DIVBYZERO )
 136 is raised.
 137 .TP
 138 Range error: result overflow
 139 .I errno
 140 is set to
 141 .BR ERANGE .
 142 An overflow floating-point exception
 143 .RB ( FE_OVERFLOW )
 144 is raised.
 145 .PP
 146 glibc also gives the following error which is not specified
 147 in C99 or POSIX.1-2001.
 148 .TP
 149 Range error: result underflow
 150 .\" e.g., tgamma(-172.5) on glibc 2.8/x86-32
 151 .\" .I errno
 152 .\" is set to
 153 .\" .BR ERANGE .
 154 An underflow floating-point exception
 155 .RB ( FE_UNDERFLOW )
 156 is raised, and
 157 .I errno
 158 is set to
 159 .BR ERANGE .
 160 .\" glibc (as at 2.8) also supports an inexact
 161 .\" exception for various cases.
 162 .SH VERSIONS
 163 These functions first appeared in glibc in version 2.1.
 164 .SH ATTRIBUTES
 165 For an explanation of the terms used in this section, see
 166 .BR attributes (7).
 167 .TS
 168 allbox;
 169 lbw30 lb lb
 170 l l l.
 171 Interface       Attribute       Value
 172 T{
 173 .BR tgamma (),
 174 .BR tgammaf (),
 175 .BR tgammal ()
 176 T}      Thread safety   MT-Safe
 177 .TE
 178 .SH CONFORMING TO
 179 C99, POSIX.1-2001, POSIX.1-2008.
 180 .SH NOTES
 181 This function had to be called "true gamma function"
 182 since there is already a function
 183 .BR gamma (3)
 184 that returns something else (see
 185 .BR gamma (3)
 186 for details).
 187 .SH BUGS
 188 Before version 2.18, the glibc implementation of these functions did not set
 189 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6809
 190 .I errno
 191 to
 192 .B EDOM
 193 when
 194 .I x
 195 is negative infinity.
 196 .PP
 197 Before glibc 2.19,
 198 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6810
 199 the glibc implementation of these functions did not set
 200 .I errno
 201 to
 202 .B ERANGE
 203 on an underflow range error.
 204 .I x
 205 .PP
 206 .\"
 207 In glibc versions 2.3.3 and earlier,
 208 an argument of +0 or \-0 incorrectly produced a domain error
 209 .RI ( errno
 210 set to
 211 .B EDOM
 212 and an
 213 .B FE_INVALID
 214 exception raised), rather than a pole error.
 215 .SH SEE ALSO
 216 .BR gamma (3),
 217 .BR lgamma (3)