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