original/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 2010-09-11 "" "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 etc. have
  92 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
  97 If
  98 .I x
  99 is a NaN, a NaN is returned.
 100
 101 If
 102 .I x
 103 is 1 or 2, +0 is returned.
 104
 105 If
 106 .I x
 107 is positive infinity or negative infinity,
 108 positive infinity is returned.
 109
 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
 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 and POSIX.1-2001.
 160 .I signgam
 161 is specified in POSIX.1-2001, 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)