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 January 14, 2005
  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 gamma ,
  40 .Nm gamma_r ,
  41 .Nm gammaf ,
  42 .Nm gammaf_r ,
  43 .Nm tgamma
  44 .Nd log gamma functions, gamma function
  45 .Sh LIBRARY
  46 .Lb libm
  47 .Sh SYNOPSIS
  48 .In math.h
  49 .Ft extern int
  50 .Fa signgam ;
  51 .sp
  52 .Ft double
  53 .Fn lgamma "double x"
  54 .Ft double
  55 .Fn lgamma_r "double x" "int *signgamp"
  56 .Ft float
  57 .Fn lgammaf "float x"
  58 .Ft float
  59 .Fn lgammaf_r "float x" "int *signgamp"
  60 .Ft double
  61 .Fn gamma "double x"
  62 .Ft double
  63 .Fn gamma_r "double x" "int *signgamp"
  64 .Ft float
  65 .Fn gammaf "float x"
  66 .Ft float
  67 .Fn gammaf_r "float x" "int *signgamp"
  68 .Ft double
  69 .Fn tgamma "double x"
  70 .Sh DESCRIPTION
  71 .Fn lgamma x
  72 and
  73 .Fn lgammaf x
  74 .if t \{\
  75 return ln\||\(*G(x)| where
  76 .Bd -unfilled -offset indent
  77 \(*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
  78 \(*G(x) = \(*p/(\(*G(1\-x)\|sin(\(*px)) for x < 1.
  79 .Ed
  80 .\}
  81 .if n \
  82 return ln\||\(*G(x)|.
  83 .Pp
  84 The external integer
  85 .Fa signgam
  86 returns the sign of \(*G(x).
  87 .Pp
  88 .Fn lgamma_r x signgamp
  89 and
  90 .Fn lgammaf_r x signgamp
  91 provide the same functionality as
  92 .Fn lgamma x
  93 and
  94 .Fn lgammaf x
  95 but the caller must provide an integer to store the sign of \(*G(x).
  96 .Pp
  97 .Fn gamma ,
  98 .Fn gammaf ,
  99 .Fn gamma_r ,
 100 and
 101 .Fn gammaf_r
 102 are deprecated aliases for
 103 .Fn lgamma ,
 104 .Fn lgammaf ,
 105 .Fn lgamma_r ,
 106 and
 107 .Fn lgammaf_r ,
 108 respectively.
 109 .Fn tgamma x
 110 returns \(*G(x), with no effect on
 111 .Fa signgam .
 112 .Sh IDIOSYNCRASIES
 113 Do not use the expression
 114 .Dq Li signgam\(**exp(lgamma(x))
 115 to compute g := \(*G(x).
 116 Instead use a program like this (in C):
 117 .Bd -literal -offset indent
 118 lg = lgamma(x); g = signgam\(**exp(lg);
 119 .Ed
 120 .Pp
 121 Only after
 122 .Fn lgamma
 123 or
 124 .Fn lgammaf
 125 has returned can signgam be correct.
 126 .Pp
 127 For arguments in its range,
 128 .Fn tgamma
 129 is preferred, as for positive arguments
 130 it is accurate to within one unit in the last place.
 131 Exponentiation of
 132 .Fn lgamma
 133 will lose up to 10 significant bits.
 134 .Sh RETURN VALUES
 135 .Fn gamma ,
 136 .Fn gamma_r ,
 137 .Fn gammaf ,
 138 .Fn gammaf_r ,
 139 .Fn lgamma ,
 140 .Fn lgamma_r ,
 141 .Fn lgammaf ,
 142 and
 143 .Fn lgammaf_r
 144 return appropriate values unless an argument is out of range.
 145 Overflow will occur for sufficiently large positive values, and
 146 non-positive integers.
 147 For large non-integer negative values,
 148 .Fn tgamma
 149 will underflow.
 150 .Sh SEE ALSO
 151 .Xr math 3
 152 .Sh STANDARDS
 153 The
 154 .Fn lgamma
 155 and
 156 .Fn tgamma
 157 functions are expected to conform to
 158 .St -isoC-99 .
 159 .Sh HISTORY
 160 The
 161 .Fn lgamma
 162 function appeared in
 163 .Bx 4.3 .
 164 The
 165 .Fn gamma
 166 function appeared in
 167 .Bx 4.4
 168 as a function which computed \(*G(x).
 169 This version was used in
 170 .Fx 1.1 .
 171 The name
 172 .Fn gamma
 173 was originally dedicated to the
 174 .Fn lgamma
 175 function,
 176 and that usage was restored by switching to Sun's fdlibm in
 177 .Fx 1.1.5 .
 178 The
 179 .Fn tgamma
 180 function appeared in
 181 .Fx 5.0 .