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