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