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  2016-03-15 "" "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 _XOPEN_SOURCE
  76     || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  77     || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
  78 .RE
  79 .br
  80 .BR y0f (),
  81 .BR y0l (),
  82 .BR y1f (),
  83 .BR y1l (),
  84 .BR ynf (),
  85 .BR ynl ():
  86 .RS 4
  87 _XOPEN_SOURCE \ >=\ 600
  88     || (_ISOC99_SOURCE && _XOPEN_SOURCE)
  89     || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  90     || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
  91 .RE
  92 .ad b
  93 .SH DESCRIPTION
  94 .PP
  95 The
  96 .BR y0 ()
  97 and
  98 .BR y1 ()
  99 functions return Bessel functions of
 100 .I x
 101 of the second kind of orders 0 and 1, respectively.
 102 The
 103 .BR yn ()
 104 function
 105 returns the Bessel function of
 106 .I x
 107 of the second kind of order
 108 .IR n .
 109 .PP
 110 The value of
 111 .I x
 112 must be positive.
 113 .PP
 114 The
 115 .BR y0f (),
 116 .BR y1f (),
 117 and
 118 .BR ynf ()
 119 functions are versions that take and return
 120 .I float
 121 values.
 122 The
 123 .BR y0l (),
 124 .BR y1l (),
 125 and
 126 .BR ynl ()
 127 functions are versions that take and return
 128 .I "long double"
 129 values.
 130 .SH RETURN VALUE
 131 On success, these functions return the appropriate
 132 Bessel value of the second kind for
 133 .IR x .
 134
 135 If
 136 .I x
 137 is a NaN, a NaN is returned.
 138
 139 If
 140 .I x
 141 is negative,
 142 a domain error occurs,
 143 and the functions return
 144 .RB - HUGE_VAL ,
 145 .RB - HUGE_VALF ,
 146 or
 147 .RB - HUGE_VALL ,
 148 respectively.
 149 (POSIX.1-2001 also allows a NaN return for this case.)
 150
 151 If
 152 .I x
 153 is 0.0,
 154 a pole error occurs,
 155 and the functions return
 156 .RB - HUGE_VAL ,
 157 .RB - HUGE_VALF ,
 158 or
 159 .RB - HUGE_VALL ,
 160 respectively.
 161
 162 If the result underflows,
 163 a range error occurs,
 164 and the functions return 0.0
 165
 166 If the result overflows,
 167 a range error occurs,
 168 and the functions return
 169 .RB - HUGE_VAL ,
 170 .RB - HUGE_VALF ,
 171 or
 172 .RB - HUGE_VALL ,
 173 respectively.
 174 (POSIX.1-2001 also allows a 0.0 return for this case.)
 175 .SH ERRORS
 176 See
 177 .BR math_error (7)
 178 for information on how to determine whether an error has occurred
 179 when calling these functions.
 180 .PP
 181 The following errors can occur:
 182 .TP
 183 Domain error: \fIx\fP is negative
 184 .I errno
 185 is set to
 186 .BR EDOM .
 187 An invalid floating-point exception
 188 .RB ( FE_INVALID )
 189 is raised.
 190 .TP
 191 Pole error: \fIx\fP is 0.0
 192 .\" Before POSIX.1-2001 TC2, this was (inconsistently) specified
 193 .\" as a range error.
 194 .I errno
 195 is set to
 196 .\" FIXME . y0(0.0) gives EDOM
 197 .BR ERANGE
 198 (but see BUGS).
 199 No
 200 .B FE_DIVBYZERO
 201 exception is returned by
 202 .BR fetestexcept (3)
 203 for this case.
 204 .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6808
 205 .TP
 206 Range error: result underflow
 207 .\" e.g., y0(1e33) on glibc 2.8/x86-32
 208 .I errno
 209 is set to
 210 .BR ERANGE .
 211 .\" An underflow floating-point exception
 212 .\" .RB ( FE_UNDERFLOW )
 213 .\" is raised.
 214 .\" FIXME . Is it intentional that these functions do not use FE_*?
 215 .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6806
 216 No
 217 .B FE_UNDERFLOW
 218 exception is returned by
 219 .BR fetestexcept (3)
 220 for this case.
 221 .TP
 222 Range error: result overflow
 223 .\" e.g., yn(10, 1e-40) on glibc 2.8/x86-32
 224 .\" .I errno
 225 .\" is set to
 226 .\" .BR ERANGE .
 227 .I errno
 228 is not set for this case.
 229 .\" FIXME . Is it intentional that errno is not set?
 230 .\" Bug raised: http://sources.redhat.com/bugzilla/show_bug.cgi?id=6808
 231 An overflow floating-point exception
 232 .RB ( FE_OVERFLOW )
 233 is raised.
 234 .SH ATTRIBUTES
 235 For an explanation of the terms used in this section, see
 236 .BR attributes (7).
 237 .TS
 238 allbox;
 239 lb lb lb
 240 l l l.
 241 Interface       Attribute       Value
 242 T{
 243 .BR y0 (),
 244 .BR y0f (),
 245 .BR y0l ()
 246 T}      Thread safety   MT-Safe
 247 T{
 248 .BR y1 (),
 249 .BR y1f (),
 250 .BR y1l ()
 251 T}      Thread safety   MT-Safe
 252 T{
 253 .BR yn (),
 254 .BR ynf (),
 255 .BR ynl ()
 256 T}      Thread safety   MT-Safe
 257 .TE
 258 .SH CONFORMING TO
 259 The functions returning
 260 .I double
 261 conform to SVr4, 4.3BSD,
 262 POSIX.1-2001, POSIX.1-2008.
 263 The others are nonstandard functions that also exist on the BSDs.
 264 .SH BUGS
 265 On a pole error, these functions set
 266 .I errno
 267 to
 268 .BR EDOM ,
 269 instead of
 270 .BR ERANGE
 271 as POSIX.1-2004 requires.
 272 .\" FIXME .
 273 .\" Bug raised: http://sourceware.org/bugzilla/show_bug.cgi?id=6807
 274
 275 In glibc version 2.3.2 and earlier,
 276 .\" FIXME . Actually, 2.3.2 is the earliest test result I have; so yet
 277 .\" to confirm if this error occurs only in 2.3.2.
 278 these functions do not raise an invalid floating-point exception
 279 .RB ( FE_INVALID )
 280 when a domain error occurs.
 281 .SH SEE ALSO
 282 .BR j0 (3)