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