man3/matherr.3

   1 '\" t
   2 .\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .TH matherr 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 matherr \- SVID math library exception handling
  10 .SH LIBRARY
  11 Math library
  12 .RI ( libm ", " \-lm )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <math.h>
  16 .P
  17 .BI "[[deprecated]] int matherr(struct exception *" exc );
  18 .P
  19 .B [[deprecated]] extern _LIB_VERSION_TYPE _LIB_VERSION;
  20 .fi
  21 .SH DESCRIPTION
  22 .IR Note :
  23 the mechanism described in this page is no longer supported by glibc.
  24 Before glibc 2.27, it had been marked as obsolete.
  25 Since glibc 2.27,
  26 .\" glibc commit 813378e9fe17e029caf627cab76fe23eb46815fa
  27 the mechanism has been removed altogether.
  28 New applications should use the techniques described in
  29 .BR math_error (7)
  30 and
  31 .BR fenv (3).
  32 This page documents the
  33 .BR matherr ()
  34 mechanism as an aid for maintaining and porting older applications.
  35 .P
  36 The System V Interface Definition (SVID) specifies that various
  37 math functions should invoke a function called
  38 .BR matherr ()
  39 if a math exception is detected.
  40 This function is called before the math function returns;
  41 after
  42 .BR matherr ()
  43 returns, the system then returns to the math function,
  44 which in turn returns to the caller.
  45 .P
  46 To employ
  47 .BR matherr (),
  48 the programmer must define the
  49 .B _SVID_SOURCE
  50 feature test macro
  51 (before including
  52 .I any
  53 header files),
  54 and assign the value
  55 .B _SVID_
  56 to the external variable
  57 .BR _LIB_VERSION .
  58 .P
  59 The system provides a default version of
  60 .BR matherr ().
  61 This version does nothing, and returns zero
  62 (see below for the significance of this).
  63 The default
  64 .BR matherr ()
  65 can be overridden by a programmer-defined
  66 version, which will be invoked when an exception occurs.
  67 The function is invoked with one argument, a pointer to an
  68 .I exception
  69 structure, defined as follows:
  70 .P
  71 .in +4n
  72 .EX
  73 struct exception {
  74     int    type;      /* Exception type */
  75     char  *name;      /* Name of function causing exception */
  76     double arg1;      /* 1st argument to function */
  77     double arg2;      /* 2nd argument to function */
  78     double retval;    /* Function return value */
  79 }
  80 .EE
  81 .in
  82 .P
  83 The
  84 .I type
  85 field has one of the following values:
  86 .TP 12
  87 .B DOMAIN
  88 A domain error occurred (the function argument was outside the range
  89 for which the function is defined).
  90 The return value depends on the function;
  91 .I errno
  92 is set to
  93 .BR EDOM .
  94 .TP
  95 .B SING
  96 A pole error occurred (the function result is an infinity).
  97 The return value in most cases is
  98 .B HUGE
  99 (the largest single precision floating-point number),
 100 appropriately signed.
 101 In most cases,
 102 .I errno
 103 is set to
 104 .BR EDOM .
 105 .TP
 106 .B OVERFLOW
 107 An overflow occurred.
 108 In most cases, the value
 109 .B HUGE
 110 is returned, and
 111 .I errno
 112 is set to
 113 .BR ERANGE .
 114 .TP
 115 .B UNDERFLOW
 116 An underflow occurred.
 117 0.0 is returned, and
 118 .I errno
 119 is set to
 120 .BR ERANGE .
 121 .TP
 122 .B TLOSS
 123 Total loss of significance.
 124 0.0 is returned, and
 125 .I errno
 126 is set to
 127 .BR ERANGE .
 128 .TP
 129 .B PLOSS
 130 Partial loss of significance.
 131 This value is unused on glibc
 132 (and many other systems).
 133 .P
 134 The
 135 .I arg1
 136 and
 137 .I arg2
 138 fields are the arguments supplied to the function
 139 .RI ( arg2
 140 is undefined for functions that take only one argument).
 141 .P
 142 The
 143 .I retval
 144 field specifies the return value that the math
 145 function will return to its caller.
 146 The programmer-defined
 147 .BR matherr ()
 148 can modify this field to change the return value of the math function.
 149 .P
 150 If the
 151 .BR matherr ()
 152 function returns zero, then the system sets
 153 .I errno
 154 as described above, and may print an error message on standard error
 155 (see below).
 156 .P
 157 If the
 158 .BR matherr ()
 159 function returns a nonzero value, then the system does not set
 160 .IR errno ,
 161 and doesn't print an error message.
 162 .SS Math functions that employ matherr()
 163 The table below lists the functions and circumstances in which
 164 .BR matherr ()
 165 is called.
 166 The "Type" column indicates the value assigned to
 167 .I exc\->type
 168 when calling
 169 .BR matherr ().
 170 The "Result" column is the default return value assigned to
 171 .IR exc\->retval .
 172 .P
 173 The "Msg?" and "errno" columns describe the default behavior if
 174 .BR matherr ()
 175 returns zero.
 176 If the "Msg?" columns contains "y",
 177 then the system prints an error message on standard error.
 178 .P
 179 The table uses the following notations and abbreviations:
 180 .P
 181 .RS
 182 .TS
 183 l l.
 184 x        first argument to function
 185 y        second argument to function
 186 fin      finite value for argument
 187 neg      negative value for argument
 188 int      integral value for argument
 189 o/f      result overflowed
 190 u/f      result underflowed
 191 |x|      absolute value of x
 192 X_TLOSS  is a constant defined in \fI<math.h>\fP
 193 .TE
 194 .RE
 195 .\" Details below from glibc 2.8's sysdeps/ieee754/k_standard.c
 196 .\" A subset of cases were test by experimental programs.
 197 .TS
 198 lB lB lB cB lB
 199 l l l c l.
 200 Function        Type    Result  Msg?    errno
 201 acos(|x|>1)     DOMAIN  HUGE    y       EDOM
 202 asin(|x|>1)     DOMAIN  HUGE    y       EDOM
 203 atan2(0,0)      DOMAIN  HUGE    y       EDOM
 204 acosh(x<1)      DOMAIN  NAN     y       EDOM    \" retval is 0.0/0.0
 205 atanh(|x|>1)    DOMAIN  NAN     y       EDOM    \" retval is 0.0/0.0
 206 atanh(|x|==1)   SING    (x>0.0)?        y       EDOM    \" retval is x/0.0
 207 \       \       HUGE_VAL :
 208 \       \       \-HUGE_VAL
 209 cosh(fin) o/f   OVERFLOW        HUGE    n       ERANGE
 210 sinh(fin) o/f   OVERFLOW        (x>0.0) ?       n       ERANGE
 211 \       \       HUGE : \-HUGE
 212 sqrt(x<0)       DOMAIN  0.0     y       EDOM
 213 hypot(fin,fin) o/f      OVERFLOW        HUGE    n       ERANGE
 214 exp(fin) o/f    OVERFLOW        HUGE    n       ERANGE
 215 exp(fin) u/f    UNDERFLOW       0.0     n       ERANGE
 216 exp2(fin) o/f   OVERFLOW        HUGE    n       ERANGE
 217 exp2(fin) u/f   UNDERFLOW       0.0     n       ERANGE
 218 exp10(fin) o/f  OVERFLOW        HUGE    n       ERANGE
 219 exp10(fin) u/f  UNDERFLOW       0.0     n       ERANGE
 220 j0(|x|>X_TLOSS) TLOSS   0.0     y       ERANGE
 221 j1(|x|>X_TLOSS) TLOSS   0.0     y       ERANGE
 222 jn(|x|>X_TLOSS) TLOSS   0.0     y       ERANGE
 223 y0(x>X_TLOSS)   TLOSS   0.0     y       ERANGE
 224 y1(x>X_TLOSS)   TLOSS   0.0     y       ERANGE
 225 yn(x>X_TLOSS)   TLOSS   0.0     y       ERANGE
 226 y0(0)   DOMAIN  \-HUGE  y       EDOM
 227 y0(x<0) DOMAIN  \-HUGE  y       EDOM
 228 y1(0)   DOMAIN  \-HUGE  y       EDOM
 229 y1(x<0) DOMAIN  \-HUGE  y       EDOM
 230 yn(n,0) DOMAIN  \-HUGE  y       EDOM
 231 yn(x<0) DOMAIN  \-HUGE  y       EDOM
 232 lgamma(fin) o/f OVERFLOW        HUGE    n       ERANGE
 233 lgamma(\-int) or        SING    HUGE    y       EDOM
 234 \ \ lgamma(0)
 235 tgamma(fin) o/f OVERFLOW        HUGE_VAL        n       ERANGE
 236 tgamma(\-int)   SING    NAN     y       EDOM
 237 tgamma(0)       SING    copysign(       y       ERANGE
 238 \       \       HUGE_VAL,x)
 239 log(0)  SING    \-HUGE  y       EDOM
 240 log(x<0)        DOMAIN  \-HUGE  y       EDOM
 241 log2(0) SING    \-HUGE  n       EDOM    \" different from log()
 242 log2(x<0)       DOMAIN  \-HUGE  n       EDOM    \" different from log()
 243 log10(0)        SING    \-HUGE  y       EDOM
 244 log10(x<0)      DOMAIN  \-HUGE  y       EDOM
 245 pow(0.0,0.0)    DOMAIN  0.0     y       EDOM
 246 pow(x,y) o/f    OVERFLOW        HUGE    n       ERANGE
 247 pow(x,y) u/f    UNDERFLOW       0.0     n       ERANGE
 248 pow(NaN,0.0)    DOMAIN  x       n       EDOM
 249 0**neg  DOMAIN  0.0     y       EDOM    \" +0 and -0
 250 neg**non-int    DOMAIN  0.0     y       EDOM
 251 scalb() o/f     OVERFLOW        (x>0.0) ?       n       ERANGE
 252 \       \       HUGE_VAL :
 253 \       \       \-HUGE_VAL
 254 scalb() u/f     UNDERFLOW       copysign(       n       ERANGE
 255 \       \       \ \ 0.0,x)
 256 fmod(x,0)       DOMAIN  x       y       EDOM
 257 remainder(x,0)  DOMAIN  NAN     y       EDOM    \" retval is 0.0/0.0
 258 .TE
 259 .SH ATTRIBUTES
 260 For an explanation of the terms used in this section, see
 261 .BR attributes (7).
 262 .TS
 263 allbox;
 264 lbx lb lb
 265 l l l.
 266 Interface       Attribute       Value
 267 T{
 268 .na
 269 .nh
 270 .BR matherr ()
 271 T}      Thread safety   MT-Safe
 272 .TE
 273 .SH EXAMPLES
 274 The example program demonstrates the use of
 275 .BR matherr ()
 276 when calling
 277 .BR log (3).
 278 The program takes up to three command-line arguments.
 279 The first argument is the floating-point number to be given to
 280 .BR log (3).
 281 If the optional second argument is provided, then
 282 .B _LIB_VERSION
 283 is set to
 284 .B _SVID_
 285 so that
 286 .BR matherr ()
 287 is called, and the integer supplied in the
 288 command-line argument is used as the return value from
 289 .BR matherr ().
 290 If the optional third command-line argument is supplied,
 291 then it specifies an alternative return value that
 292 .BR matherr ()
 293 should assign as the return value of the math function.
 294 .P
 295 The following example run, where
 296 .BR log (3)
 297 is given an argument of 0.0, does not use
 298 .BR matherr ():
 299 .P
 300 .in +4n
 301 .EX
 302 .RB "$" " ./a.out 0.0"
 303 errno: Numerical result out of range
 304 x=\-inf
 305 .EE
 306 .in
 307 .P
 308 In the following run,
 309 .BR matherr ()
 310 is called, and returns 0:
 311 .P
 312 .in +4n
 313 .EX
 314 .RB "$" " ./a.out 0.0 0"
 315 matherr SING exception in log() function
 316         args:   0.000000, 0.000000
 317         retval: \-340282346638528859811704183484516925440.000000
 318 log: SING error
 319 errno: Numerical argument out of domain
 320 x=\-340282346638528859811704183484516925440.000000
 321 .EE
 322 .in
 323 .P
 324 The message "log: SING error" was printed by the C library.
 325 .P
 326 In the following run,
 327 .BR matherr ()
 328 is called, and returns a nonzero value:
 329 .P
 330 .in +4n
 331 .EX
 332 .RB "$" " ./a.out 0.0 1"
 333 matherr SING exception in log() function
 334         args:   0.000000, 0.000000
 335         retval: \-340282346638528859811704183484516925440.000000
 336 x=\-340282346638528859811704183484516925440.000000
 337 .EE
 338 .in
 339 .P
 340 In this case, the C library did not print a message, and
 341 .I errno
 342 was not set.
 343 .P
 344 In the following run,
 345 .BR matherr ()
 346 is called, changes the return value of the math function,
 347 and returns a nonzero value:
 348 .P
 349 .in +4n
 350 .EX
 351 .RB "$" " ./a.out 0.0 1 12345.0"
 352 matherr SING exception in log() function
 353         args:   0.000000, 0.000000
 354         retval: \-340282346638528859811704183484516925440.000000
 355 x=12345.000000
 356 .EE
 357 .in
 358 .SS Program source
 359 \&
 360 .\" [[deprecated]] SRC BEGIN (matherr.c)
 361 .EX
 362 #define _SVID_SOURCE
 363 #include <errno.h>
 364 #include <math.h>
 365 #include <stdio.h>
 366 #include <stdlib.h>
 367 \&
 368 static int matherr_ret = 0;     /* Value that matherr()
 369                                    should return */
 370 static int change_retval = 0;   /* Should matherr() change
 371                                    function\[aq]s return value? */
 372 static double new_retval;       /* New function return value */
 373 \&
 374 int
 375 matherr(struct exception *exc)
 376 {
 377     fprintf(stderr, "matherr %s exception in %s() function\en",
 378             (exc\->type == DOMAIN) ?    "DOMAIN" :
 379             (exc\->type == OVERFLOW) ?  "OVERFLOW" :
 380             (exc\->type == UNDERFLOW) ? "UNDERFLOW" :
 381             (exc\->type == SING) ?      "SING" :
 382             (exc\->type == TLOSS) ?     "TLOSS" :
 383             (exc\->type == PLOSS) ?     "PLOSS" : "???",
 384             exc\->name);
 385     fprintf(stderr, "        args:   %f, %f\en",
 386             exc\->arg1, exc\->arg2);
 387     fprintf(stderr, "        retval: %f\en", exc\->retval);
 388 \&
 389     if (change_retval)
 390         exc\->retval = new_retval;
 391 \&
 392     return matherr_ret;
 393 }
 394 \&
 395 int
 396 main(int argc, char *argv[])
 397 {
 398     double x;
 399 \&
 400     if (argc < 2) {
 401         fprintf(stderr, "Usage: %s <argval>"
 402                 " [<matherr\-ret> [<new\-func\-retval>]]\en", argv[0]);
 403         exit(EXIT_FAILURE);
 404     }
 405 \&
 406     if (argc > 2) {
 407         _LIB_VERSION = _SVID_;
 408         matherr_ret = atoi(argv[2]);
 409     }
 410 \&
 411     if (argc > 3) {
 412         change_retval = 1;
 413         new_retval = atof(argv[3]);
 414     }
 415 \&
 416     x = log(atof(argv[1]));
 417     if (errno != 0)
 418         perror("errno");
 419 \&
 420     printf("x=%f\en", x);
 421     exit(EXIT_SUCCESS);
 422 }
 423 .EE
 424 .\" SRC END
 425 .SH SEE ALSO
 426 .BR fenv (3),
 427 .BR math_error (7),
 428 .BR standards (7)