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