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