usr/src/man/man3m/lgamma.3m

   1 '\" te
   2 .\" Copyright (c) 2001, the Institute of Electrical
   3 .\" and Electronics Engineers, Inc. and The Open Group. All Rights Reserved.
   4 .\" Copyright (c) 1992, X/Open Company Limited.
   5 .\"  All Rights Reserved.
   6 .\" Copyright (c) 1983 Regents of the University
   7 .\" of California. All rights reserved. The Berkeley software License Agreement
   8 .\" specifies the terms and conditions for redistribution.
   9 .\" Portions Copyright (c) 2006, Sun Microsystems,
  10 .\" Inc. All Rights Reserved.
  11 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
  12 .\" http://www.opengroup.org/bookstore/.
  13 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
  14 .\"  This notice shall appear on any product containing this material.
  15 .TH LGAMMA 3M "Jul 12, 2006" "SunOS 5.11" "Mathematical Library Functions"
  16 .SH NAME
  17 lgamma, lgammaf, lgammal, lgamma_r, lgammaf_r, lgammal_r, gamma, gammaf,
  18 gammal, gamma_r, gammaf_r, gammal_r \- log gamma function
  19 .SH SYNOPSIS
  20 .LP
  21 .nf
  22 c99 [ \fIflag\fR... ] \fIfile\fR... \fB-lm\fR [ \fIlibrary\fR... ]
  23 #include <math.h>
  24
  25 extern int signgam;
  26
  27 \fBdouble\fR \fBlgamma\fR(\fBdouble\fR \fIx\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBfloat\fR \fBlgammaf\fR(\fBfloat\fR \fIx\fR);
  33 .fi
  34
  35 .LP
  36 .nf
  37 \fBlong double\fR \fBlgammal\fR(\fBlong double\fR \fIx\fR);
  38 .fi
  39
  40 .LP
  41 .nf
  42 \fBdouble\fR \fBgamma\fR(\fBdouble\fR \fIx\fR);
  43 .fi
  44
  45 .LP
  46 .nf
  47 \fBfloat\fR \fBgammaf\fR(\fBfloat\fR \fIx\fR);
  48 .fi
  49
  50 .LP
  51 .nf
  52 \fBlong double\fR \fBgammal\fR(\fBlong double\fR \fIx\fR);
  53 .fi
  54
  55 .LP
  56 .nf
  57 \fBdouble\fR \fBlgamma_r\fR(\fBdouble\fR \fIx\fR, \fBint *\fR\fIsigngamp\fR);
  58 .fi
  59
  60 .LP
  61 .nf
  62 \fBfloat\fR \fBlgammaf_r\fR(\fBfloat\fR \fIx\fR, \fBint *\fR\fIsigngamp\fR);
  63 .fi
  64
  65 .LP
  66 .nf
  67 \fBlong double\fR \fBlgammal_r\fR(\fBlong double\fR \fIx\fR, \fBint *\fR\fIsigngamp\fR);
  68 .fi
  69
  70 .LP
  71 .nf
  72 \fBdouble\fR \fBgamma_r\fR(\fBdouble\fR \fIx\fR, \fBint *\fR\fIsigngamp\fR);
  73 .fi
  74
  75 .LP
  76 .nf
  77 \fBfloat\fR \fBgammaf_r\fR(\fBfloat\fR \fIx\fR, \fBint *\fR\fIsigngamp\fR);
  78 .fi
  79
  80 .LP
  81 .nf
  82 \fBlong double\fR \fBgammal_r\fR(\fBlong double\fR \fIx\fR, \fBint *\fR\fIsigngamp\fR);
  83 .fi
  84
  85 .SH DESCRIPTION
  86 .sp
  87 .LP
  88 These functions return
  89 .sp
  90 ln||~(x)|
  91 .sp
  92 .LP
  93 where
  94 .sp
  95 |~(x) = integral from 0 to +Infinity of pow(t,x-1)*exp(-t) dt
  96 .sp
  97 .LP
  98 for x > 0 and
  99 .sp
 100 |~(x) = n/(|~(1-x)sin(nx))
 101 .sp
 102 .LP
 103 for x < 1.
 104 .sp
 105 .LP
 106 These functions use the external integer \fBsigngam\fR to return the sign of
 107 \fB|~(x)\fR while \fBlgamma_r()\fR and \fBgamma_r()\fR use the user-allocated
 108 space addressed by \fBsigngamp\fR.
 109 .SH RETURN VALUES
 110 .sp
 111 .LP
 112 Upon successful completion, these functions return the logarithmic gamma of
 113 \fIx\fR.
 114 .sp
 115 .LP
 116 If \fIx\fR is a non-positive integer, a pole error occurs and these functions
 117 return +\fBHUGE_VAL\fR, +\fBHUGE_VALF\fR, and +\fBHUGE_VALL\fR, respectively.
 118 .sp
 119 .LP
 120 If \fIx\fR is NaN, a NaN is returned.
 121 .sp
 122 .LP
 123 If \fIx\fR is 1 or 2, +0 shall be returned.
 124 .sp
 125 .LP
 126 If \fIx\fR is \(+-Inf, +Inf is returned.
 127 .SH ERRORS
 128 .sp
 129 .LP
 130 These functions will fail if:
 131 .sp
 132 .ne 2
 133 .mk
 134 .na
 135 \fBPole Error\fR
 136 .ad
 137 .RS 14n
 138 .rt
 139 The \fIx\fR argument is a negative integer or 0.
 140 .sp
 141 If the integer expression (\fBmath_errhandling\fR & \fBMATH_ERREXCEPT\fR) is
 142 non-zero, then the divide-by-zero floating-point exception is raised.
 143 .RE
 144
 145 .SH USAGE
 146 .sp
 147 .LP
 148 An application wanting to check for exceptions should call
 149 \fBfeclearexcept\fR(\fBFE_ALL_EXCEPT\fR) before calling these functions. On
 150 return, if \fBfetestexcept\fR(\fBFE_INVALID\fR | \fBFE_DIVBYZERO\fR |
 151 \fBFE_OVERFLOW\fR | \fBFE_UNDERFLOW\fR) is non-zero, an exception has been
 152 raised. An application should either examine the return value or check the
 153 floating point exception flags to detect exceptions.
 154 .sp
 155 .LP
 156 In the case of \fBlgamma()\fR, do not use the expression
 157 \fBsigngam*exp(lgamma(x))\fR to compute
 158 .sp
 159 `g  := |~(x)'
 160 .sp
 161 .LP
 162 Instead compute \fBlgamma()\fR first:
 163 .sp
 164 .LP
 165 \fBlg = lgamma(x); g = signgam*exp(lg);\fR
 166 .sp
 167 .LP
 168 only after \fBlgamma()\fR has returned can \fBsigngam\fR be correct. Note that
 169 \fB|~(x)\fR must overflow when \fIx\fR is large enough, underflow when
 170 \(mi\fIx\fR is large enough, and generate a division by 0 exception at the
 171 singularities \fIx\fR a nonpositive integer.
 172 .SH ATTRIBUTES
 173 .sp
 174 .LP
 175 See \fBattributes\fR(5) for descriptions of the following attributes:
 176 .sp
 177
 178 .sp
 179 .TS
 180 tab(    ) box;
 181 cw(2.75i) |cw(2.75i)
 182 lw(2.75i) |lw(2.75i)
 183 .
 184 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 185 _
 186 Interface Stability     See below.
 187 _
 188 MT-Level        See below.
 189 .TE
 190
 191 .sp
 192 .LP
 193 The \fBlgamma()\fR, \fBlgammaf()\fR, \fBlgammal()\fR, and \fBgamma()\fR
 194 functions are Standard. The \fBlgamma_r()\fR, \fBlgammaf_r()\fR,
 195 \fBlgammal_r()\fR, \fBgamma_r()\fR, \fBgammaf_r()\fR, and \fBgammal_r()\fR,
 196 functions are Stable.
 197 .sp
 198 .LP
 199 The \fBlgamma()\fR, \fBlgammaf()\fR, \fBlgammal()\fR, \fBgamma()\fR,
 200 \fBgammaf()\fR, and \fBgammal()\fR functions are Unsafe in multithreaded
 201 applications. The \fBlgamma_r()\fR, \fBlgammaf_r()\fR, \fBlgammal_r()\fR,
 202 \fBgamma_r()\fR, \fBgammaf_r()\fR, and \fBgammal_r()\fR functions are MT-Safe
 203 and should be used instead.
 204 .SH SEE ALSO
 205 .sp
 206 .LP
 207 \fBexp\fR(3M), \fBfeclearexcept\fR(3M), \fBfetestexcept\fR(3M),
 208 \fBisnan\fR(3M), \fBmath.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5)
 209 .SH NOTES
 210 .sp
 211 .LP
 212 When compiling multithreaded applications, the \fB_REENTRANT\fR flag must be
 213 defined on the compile line.  This flag should only be used in multithreaded
 214 applications.