man3/matherr.3

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