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