original/man3/tgamma.3

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