man3/lgamma.3

   1 .\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de)
   2 .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: GPL-1.0-or-later
   6 .\"
   7 .\" based on glibc infopages
   8 .\"
   9 .TH LGAMMA 3 2022-09-09 "Linux man-pages (unreleased)"
  10 .SH NAME
  11 lgamma, lgammaf, lgammal, lgamma_r, lgammaf_r, lgammal_r, signgam \-
  12 log gamma function
  13 .SH LIBRARY
  14 Math library
  15 .RI ( libm ", " \-lm )
  16 .SH SYNOPSIS
  17 .nf
  18 .B #include <math.h>
  19 .PP
  20 .BI "double lgamma(double " x );
  21 .BI "float lgammaf(float " x );
  22 .BI "long double lgammal(long double " x );
  23 .PP
  24 .BI "double lgamma_r(double " x ", int *" signp );
  25 .BI "float lgammaf_r(float " x ", int *" signp );
  26 .BI "long double lgammal_r(long double " x ", int *" signp );
  27 .PP
  28 .BI "extern int " signgam ;
  29 .fi
  30 .PP
  31 .RS -4
  32 Feature Test Macro Requirements for glibc (see
  33 .BR feature_test_macros (7)):
  34 .RE
  35 .PP
  36 .nf
  37 .BR lgamma ():
  38     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE
  39         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  40         || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  41 .fi
  42 .PP
  43 .BR lgammaf (),
  44 .BR lgammal ():
  45 .nf
  46     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  47         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  48         || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  49 .fi
  50 .PP
  51 .BR lgamma_r (),
  52 .BR lgammaf_r (),
  53 .BR lgammal_r ():
  54 .nf
  55     /* Since glibc 2.19: */ _DEFAULT_SOURCE
  56         || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  57 .fi
  58 .PP
  59 .IR signgam :
  60 .nf
  61     _XOPEN_SOURCE
  62         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  63         || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  64 .fi
  65 .SH DESCRIPTION
  66 For the definition of the Gamma function, see
  67 .BR tgamma (3).
  68 .PP
  69 The
  70 .BR lgamma (),
  71 .BR lgammaf (),
  72 and
  73 .BR lgammal ()
  74 functions return the natural logarithm of
  75 the absolute value of the Gamma function.
  76 The sign of the Gamma function is returned in the
  77 external integer
  78 .I signgam
  79 declared in
  80 .IR <math.h> .
  81 It is 1 when the Gamma function is positive or zero, \-1
  82 when it is negative.
  83 .PP
  84 Since using a constant location
  85 .I signgam
  86 is not thread-safe, the functions
  87 .BR lgamma_r (),
  88 .BR lgammaf_r (),
  89 and
  90 .BR lgammal_r ()
  91 have been introduced; they return the sign via the argument
  92 .IR signp .
  93 .SH RETURN VALUE
  94 On success, these functions return the natural logarithm of Gamma(x).
  95 .PP
  96 If
  97 .I x
  98 is a NaN, a NaN is returned.
  99 .PP
 100 If
 101 .I x
 102 is 1 or 2, +0 is returned.
 103 .PP
 104 If
 105 .I x
 106 is positive infinity or negative infinity,
 107 positive infinity is returned.
 108 .PP
 109 If
 110 .I x
 111 is a nonpositive integer,
 112 a pole error occurs,
 113 and the functions return
 114 .RB + HUGE_VAL ,
 115 .RB + HUGE_VALF ,
 116 or
 117 .RB + HUGE_VALL ,
 118 respectively.
 119 .PP
 120 If the result overflows,
 121 a range error occurs,
 122 .\" e.g., lgamma(DBL_MAX)
 123 and the functions return
 124 .BR HUGE_VAL ,
 125 .BR HUGE_VALF ,
 126 or
 127 .BR HUGE_VALL ,
 128 respectively, with the correct mathematical sign.
 129 .SH ERRORS
 130 See
 131 .BR math_error (7)
 132 for information on how to determine whether an error has occurred
 133 when calling these functions.
 134 .PP
 135 The following errors can occur:
 136 .TP
 137 Pole error: \fIx\fP is a nonpositive integer
 138 .I errno
 139 is set to
 140 .B ERANGE
 141 (but see BUGS).
 142 A divide-by-zero floating-point exception
 143 .RB ( FE_DIVBYZERO )
 144 is raised.
 145 .TP
 146 Range error: result overflow
 147 .I errno
 148 is set to
 149 .BR ERANGE .
 150 An overflow floating-point exception
 151 .RB ( FE_OVERFLOW )
 152 is raised.
 153 .\" glibc (as at 2.8) also supports an inexact
 154 .\" exception for various cases.
 155 .SH STANDARDS
 156 The
 157 .BR lgamma ()
 158 functions are specified in C99, POSIX.1-2001, and POSIX.1-2008.
 159 .I signgam
 160 is specified in POSIX.1-2001 and POSIX.1-2008, but not in C99.
 161 The
 162 .BR lgamma_r ()
 163 functions are nonstandard, but present on several other systems.
 164 .SH BUGS
 165 In glibc 2.9 and earlier,
 166 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6777
 167 when a pole error occurs,
 168 .I errno
 169 is set to
 170 .BR EDOM ;
 171 instead of the POSIX-mandated
 172 .BR ERANGE .
 173 Since version 2.10, glibc does the right thing.
 174 .SH SEE ALSO
 175 .BR tgamma (3)