man3/y0.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" References consulted:
  28 .\"     Linux libc source code
  29 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  30 .\"     386BSD man pages
  31 .\" Modified Sat Jul 24 19:08:17 1993 by Rik Faith (faith@cs.unc.edu)
  32 .\" Modified 2002-08-25, aeb
  33 .\" Modified 2004-11-12 as per suggestion by Fabian Kreutz/AEB
  34 .\" 2008-07-24, mtk, created this page, based on material from j0.3.
  35 .\"
  36 .TH Y0 3  2014-01-18 "" "Linux Programmer's Manual"
  37 .SH NAME
  38 y0, y0f, y0l, y1, y1f, y1l, yn, ynf, ynl \-
  39 Bessel functions of the second kind
  40 .SH SYNOPSIS
  41 .nf
  42 .B #include <math.h>
  43 .sp
  44 .BI "double y0(double " x );
  45 .br
  46 .BI "double y1(double " x );
  47 .br
  48 .BI "double yn(int " n ", double " x );
  49 .sp
  50 .BI "float y0f(float " x );
  51 .br
  52 .BI "float y1f(float " x );
  53 .br
  54 .BI "float ynf(int " n ", float " x );
  55 .sp
  56 .BI "long double y0l(long double " x );
  57 .br
  58 .BI "long double y1l(long double " x );
  59 .br
  60 .BI "long double ynl(int " n ", long double " x );
  61 .fi
  62 .sp
  63 Link with \fI\-lm\fP.
  64 .sp
  65 .in -4n
  66 Feature Test Macro Requirements for glibc (see
  67 .BR feature_test_macros (7)):
  68 .in
  69 .sp
  70 .ad l
  71 .BR y0 (),
  72 .BR y1 (),
  73 .BR yn ():
  74 .RS 4
  75 _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE
  76 .RE
  77 .br
  78 .BR y0f (),
  79 .BR y0l (),
  80 .BR y1f (),
  81 .BR y1l (),
  82 .BR ynf (),
  83 .BR ynl ():
  84 .RS 4
  85 _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 600
  86 .\" Also seems to work: -std=c99 -D_XOPEN_SOURCE
  87 .RE
  88 .ad b
  89 .SH DESCRIPTION
  90 .PP
  91 The
  92 .BR y0 ()
  93 and
  94 .BR y1 ()
  95 functions return Bessel functions of
  96 .I x
  97 of the second kind of orders 0 and 1, respectively.
  98 The
  99 .BR yn ()
 100 function
 101 returns the Bessel function of
 102 .I x
 103 of the second kind of order
 104 .IR n .
 105 .PP
 106 The value of
 107 .I x
 108 must be positive.
 109 .PP
 110 The
 111 .BR y0f (),
 112 .BR y1f (),
 113 and
 114 .BR ynf ()
 115 functions are versions that take and return
 116 .I float
 117 values.
 118 The
 119 .BR y0l (),
 120 .BR y1l (),
 121 and
 122 .BR ynl ()
 123 functions are versions that take and return
 124 .I "long double"
 125 values.
 126 .SH RETURN VALUE
 127 On success, these functions return the appropriate
 128 Bessel value of the second kind for
 129 .IR x .
 130
 131 If
 132 .I x
 133 is a NaN, a NaN is returned.
 134
 135 If
 136 .I x
 137 is negative,
 138 a domain error occurs,
 139 and the functions return
 140 .RB - HUGE_VAL ,
 141 .RB - HUGE_VALF ,
 142 or
 143 .RB - HUGE_VALL ,
 144 respectively.
 145 (POSIX.1-2001 also allows a NaN return for this case.)
 146
 147 If
 148 .I x
 149 is 0.0,
 150 a pole error occurs,
 151 and the functions return
 152 .RB - HUGE_VAL ,
 153 .RB - HUGE_VALF ,
 154 or
 155 .RB - HUGE_VALL ,
 156 respectively.
 157
 158 If the result underflows,
 159 a range error occurs,
 160 and the functions return 0.0
 161
 162 If the result overflows,
 163 a range error occurs,
 164 and the functions return
 165 .RB - HUGE_VAL ,
 166 .RB - HUGE_VALF ,
 167 or
 168 .RB - HUGE_VALL ,
 169 respectively.
 170 (POSIX.1-2001 also allows a 0.0 return for this case.)
 171 .SH ERRORS
 172 See
 173 .BR math_error (7)
 174 for information on how to determine whether an error has occurred
 175 when calling these functions.
 176 .PP
 177 The following errors can occur:
 178 .TP
 179 Domain error: \fIx\fP is negative
 180 .I errno
 181 is set to
 182 .BR EDOM .
 183 An invalid floating-point exception
 184 .RB ( FE_INVALID )
 185 is raised.
 186 .TP
 187 Pole error: \fIx\fP is 0.0
 188 .\" Before POSIX.1-2001 TC2, this was (inconsistently) specified
 189 .\" as a range error.
 190 .I errno
 191 is set to
 192 .\" FIXME . y0(0.0) gives EDOM
 193 .BR ERANGE
 194 (but see BUGS).
 195 No
 196 .B FE_DIVBYZERO
 197 exception is returned by
 198 .BR fetestexcept (3)
 199 for this case.
 200 .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6808
 201 .TP
 202 Range error: result underflow
 203 .\" e.g., y0(1e33) on glibc 2.8/x86-32
 204 .I errno
 205 is set to
 206 .BR ERANGE .
 207 .\" An underflow floating-point exception
 208 .\" .RB ( FE_UNDERFLOW )
 209 .\" is raised.
 210 .\" FIXME . Is it intentional that these functions do not use FE_*?
 211 .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6806
 212 No
 213 .B FE_UNDERFLOW
 214 exception is returned by
 215 .BR fetestexcept (3)
 216 for this case.
 217 .TP
 218 Range error: result overflow
 219 .\" e.g., yn(10, 1e-40) on glibc 2.8/x86-32
 220 .\" .I errno
 221 .\" is set to
 222 .\" .BR ERANGE .
 223 .I errno
 224 is not set for this case.
 225 .\" FIXME . Is it intentional that errno is not set?
 226 .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6808
 227 An overflow floating-point exception
 228 .RB ( FE_OVERFLOW )
 229 is raised.
 230 .SH CONFORMING TO
 231 The functions returning
 232 .I double
 233 conform to SVr4, 4.3BSD,
 234 POSIX.1-2001.
 235 The others are nonstandard functions that also exist on the BSDs.
 236 .SH BUGS
 237 On a pole error, these functions set
 238 .I errno
 239 to
 240 .BR EDOM ,
 241 instead of
 242 .BR ERANGE
 243 as POSIX.1-2004 requires.
 244 .\" FIXME .
 245 .\" Bug raised: http://sourceware.org/bugzilla/show_bug.cgi?id=6807
 246
 247 In glibc version 2.3.2 and earlier,
 248 .\" FIXME . Actually, 2.3.2 is the earliest test result I have; so yet
 249 .\" to confirm if this error occurs only in 2.3.2.
 250 these functions do not raise an invalid floating-point exception
 251 .RB ( FE_INVALID )
 252 when a domain error occurs.
 253 .SH SEE ALSO
 254 .BR j0 (3)