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