man3/matherr.3

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