original/man3/matherr.3

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