lib/msun/man/lgamma.3

   1 .\" Copyright (c) 1985, 1991 Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     from: @(#)lgamma.3      6.6 (Berkeley) 12/3/92
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd September 12, 2014
  32 .Dt LGAMMA 3
  33 .Os
  34 .Sh NAME
  35 .Nm lgamma ,
  36 .Nm lgamma_r ,
  37 .Nm lgammaf ,
  38 .Nm lgammaf_r ,
  39 .Nm lgammal ,
  40 .Nm lgammal_r ,
  41 .Nm gamma ,
  42 .Nm gamma_r ,
  43 .Nm gammaf ,
  44 .Nm gammaf_r ,
  45 .Nm tgamma ,
  46 .Nm tgammaf
  47 .Nd log gamma functions, gamma function
  48 .Sh LIBRARY
  49 .Lb libm
  50 .Sh SYNOPSIS
  51 .In math.h
  52 .Ft extern int
  53 .Fa signgam ;
  54 .sp
  55 .Ft double
  56 .Fn lgamma "double x"
  57 .Ft double
  58 .Fn lgamma_r "double x" "int *signgamp"
  59 .Ft float
  60 .Fn lgammaf "float x"
  61 .Ft float
  62 .Fn lgammaf_r "float x" "int *signgamp"
  63 .Ft "long double"
  64 .Fn lgammal "long double x"
  65 .Ft "long double"
  66 .Fn lgammal_r "long double x" "int *signgamp"
  67 .Ft double
  68 .Fn gamma "double x"
  69 .Ft double
  70 .Fn gamma_r "double x" "int *signgamp"
  71 .Ft float
  72 .Fn gammaf "float x"
  73 .Ft float
  74 .Fn gammaf_r "float x" "int *signgamp"
  75 .Ft "long double"
  76 .Fn tgamma "double x"
  77 .Ft float
  78 .Fn tgammaf "float x"
  79 .Sh DESCRIPTION
  80 .Fn lgamma x ,
  81 .Fn lgammaf x ,
  82 and
  83 .Fn lgammal x
  84 .if t \{\
  85 return ln\||\(*G(x)| where
  86 .Bd -unfilled -offset indent
  87 \(*G(x) = \(is\d\s8\z0\s10\u\u\s8\(if\s10\d t\u\s8x\-1\s10\d e\u\s8\-t\s10\d dt for x > 0 and
  88 \(*G(x) = \(*p/(\(*G(1\-x)\|sin(\(*px)) for x < 1.
  89 .Ed
  90 .\}
  91 .if n \
  92 return ln\||\(*G(x)|.
  93 The external integer
  94 .Fa signgam
  95 returns the sign of \(*G(x).
  96 .Pp
  97 .Fn lgamma_r x signgamp ,
  98 .Fn lgammaf_r x signgamp ,
  99 and
 100 .Fn lgammal_r x signgamp
 101 provide the same functionality as
 102 .Fn lgamma x ,
 103 .Fn lgammaf x ,
 104 and
 105 .Fn lgammal x ,
 106 but the caller must provide an integer to store the sign of \(*G(x).
 107 .Pp
 108 The
 109 .Fn tgamma x
 110 and
 111 .Fn tgammaf x
 112 functions return \(*G(x), with no effect on
 113 .Fa signgam .
 114 .Pp
 115 .Fn gamma ,
 116 .Fn gammaf ,
 117 .Fn gamma_r ,
 118 and
 119 .Fn gammaf_r
 120 are deprecated aliases for
 121 .Fn lgamma ,
 122 .Fn lgammaf ,
 123 .Fn lgamma_r ,
 124 and
 125 .Fn lgammaf_r ,
 126 respectively.
 127 .Sh IDIOSYNCRASIES
 128 Do not use the expression
 129 .Dq Li signgam\(**exp(lgamma(x))
 130 to compute g := \(*G(x).
 131 Instead use a program like this (in C):
 132 .Bd -literal -offset indent
 133 lg = lgamma(x); g = signgam\(**exp(lg);
 134 .Ed
 135 .Pp
 136 Only after
 137 .Fn lgamma
 138 or
 139 .Fn lgammaf
 140 has returned can signgam be correct.
 141 .Pp
 142 For arguments in its range,
 143 .Fn tgamma
 144 is preferred, as for positive arguments
 145 it is accurate to within one unit in the last place.
 146 Exponentiation of
 147 .Fn lgamma
 148 will lose up to 10 significant bits.
 149 .Sh RETURN VALUES
 150 .Fn gamma ,
 151 .Fn gammaf ,
 152 .Fn gammal ,
 153 .Fn gamma_r ,
 154 .Fn gammaf_r ,
 155 .Fn gammal_r ,
 156 .Fn lgamma ,
 157 .Fn lgammaf ,
 158 .Fn lgammal ,
 159 .Fn lgamma_r ,
 160 .Fn lgammaf_r ,
 161 and
 162 .Fn lgammal_r
 163 return appropriate values unless an argument is out of range.
 164 Overflow will occur for sufficiently large positive values, and
 165 non-positive integers.
 166 For large non-integer negative values,
 167 .Fn tgamma
 168 will underflow.
 169 .Sh SEE ALSO
 170 .Xr math 3
 171 .Sh STANDARDS
 172 The
 173 .Fn lgamma ,
 174 .Fn lgammaf ,
 175 .Fn lgammal ,
 176 .Fn tgamma ,
 177 and
 178 .Fn tgammaf
 179 functions are expected to conform to
 180 .St -isoC-99 .
 181 .Sh HISTORY
 182 The
 183 .Fn lgamma
 184 function appeared in
 185 .Bx 4.3 .
 186 The
 187 .Fn gamma
 188 function appeared in
 189 .Bx 4.4
 190 as a function which computed \(*G(x).
 191 This version was used in
 192 .Fx 1.1 .
 193 The name
 194 .Fn gamma
 195 was originally dedicated to the
 196 .Fn lgamma
 197 function,
 198 and that usage was restored by switching to Sun's fdlibm in
 199 .Fx 1.1.5 .
 200 The
 201 .Fn tgamma
 202 function appeared in
 203 .Fx 5.0 .