contrib/openbsd_libm/man/lgamma.3

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