original/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 2014-06-13 "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 .SS Multithreading (see pthreads(7))
 277 The
 278 .BR matherr ()
 279 function is thread-safe.
 280 .SH EXAMPLE
 281 The example program demonstrates the use of
 282 .BR matherr ()
 283 when calling
 284 .BR log (3).
 285 The program takes up to three command-line arguments.
 286 The first argument is the floating-point number to be given to
 287 .BR log (3).
 288 If the optional second argument is provided, then
 289 .B _LIB_VERSION
 290 is set to
 291 .B _SVID_
 292 so that
 293 .BR matherr ()
 294 is called, and the integer supplied in the
 295 command-line argument is used as the return value from
 296 .BR matherr ().
 297 If the optional third command-line argument is supplied,
 298 then it specifies an alternative return value that
 299 .BR matherr ()
 300 should assign as the return value of the math function.
 301
 302 The following example run, where
 303 .BR log (3)
 304 is given an argument of 0.0, does not use
 305 .BR matherr ():
 306
 307 .in +4n
 308 .nf
 309 .RB "$" " ./a.out 0.0"
 310 errno: Numerical result out of range
 311 x=-inf
 312 .fi
 313 .in
 314
 315 In the following run,
 316 .BR matherr ()
 317 is called, and returns 0:
 318
 319 .in +4n
 320 .nf
 321 .RB "$" " ./a.out 0.0 0"
 322 matherr SING exception in log() function
 323         args:   0.000000, 0.000000
 324         retval: \-340282346638528859811704183484516925440.000000
 325 log: SING error
 326 errno: Numerical argument out of domain
 327 x=-340282346638528859811704183484516925440.000000
 328 .fi
 329 .in
 330
 331 The message "log: SING error" was printed by the C library.
 332
 333 In the following run,
 334 .BR matherr ()
 335 is called, and returns a nonzero value:
 336
 337 .in +4n
 338 .nf
 339 .RB "$" " ./a.out 0.0 1"
 340 matherr SING exception in log() function
 341         args:   0.000000, 0.000000
 342         retval: \-340282346638528859811704183484516925440.000000
 343 x=-340282346638528859811704183484516925440.000000
 344 .fi
 345 .in
 346
 347 In this case, the C library did not print a message, and
 348 .I errno
 349 was not set.
 350
 351 In the following run,
 352 .BR matherr ()
 353 is called, changes the return value of the math function,
 354 and returns a nonzero value:
 355
 356 .in +4n
 357 .nf
 358 .RB "$" " ./a.out 0.0 1 12345.0"
 359 matherr SING exception in log() function
 360         args:   0.000000, 0.000000
 361         retval: \-340282346638528859811704183484516925440.000000
 362 x=12345.000000
 363 .fi
 364 .in
 365 .SS Program source
 366 \&
 367 .nf
 368 #define _SVID_SOURCE
 369 #include <errno.h>
 370 #include <math.h>
 371 #include <stdio.h>
 372 #include <stdlib.h>
 373
 374 static int matherr_ret = 0;     /* Value that matherr()
 375                                    should return */
 376 static int change_retval = 0;   /* Should matherr() change
 377                                    function\(aqs return value? */
 378 static double new_retval;       /* New function return value */
 379
 380 int
 381 matherr(struct exception *exc)
 382 {
 383     fprintf(stderr, "matherr %s exception in %s() function\\n",
 384            (exc\->type == DOMAIN) ?    "DOMAIN" :
 385            (exc\->type == OVERFLOW) ?  "OVERFLOW" :
 386            (exc\->type == UNDERFLOW) ? "UNDERFLOW" :
 387            (exc\->type == SING) ?      "SING" :
 388            (exc\->type == TLOSS) ?     "TLOSS" :
 389            (exc\->type == PLOSS) ?     "PLOSS" : "???",
 390             exc\->name);
 391     fprintf(stderr, "        args:   %f, %f\\n",
 392             exc\->arg1, exc\->arg2);
 393     fprintf(stderr, "        retval: %f\\n", exc\->retval);
 394
 395     if (change_retval)
 396         exc\->retval = new_retval;
 397
 398     return matherr_ret;
 399 }
 400
 401 int
 402 main(int argc, char *argv[])
 403 {
 404     double x;
 405
 406     if (argc < 2) {
 407         fprintf(stderr, "Usage: %s <argval>"
 408                 " [<matherr\-ret> [<new\-func\-retval>]]\\n", argv[0]);
 409         exit(EXIT_FAILURE);
 410     }
 411
 412     if (argc > 2) {
 413         _LIB_VERSION = _SVID_;
 414         matherr_ret = atoi(argv[2]);
 415     }
 416
 417     if (argc > 3) {
 418         change_retval = 1;
 419         new_retval = atof(argv[3]);
 420     }
 421
 422     x = log(atof(argv[1]));
 423     if (errno != 0)
 424         perror("errno");
 425
 426     printf("x=%f\\n", x);
 427     exit(EXIT_SUCCESS);
 428 }
 429 .fi
 430 .SH SEE ALSO
 431 .BR fenv (3),
 432 .BR math_error (7),
 433 .BR standards (7)
 434 .SH COLOPHON
 435 This page is part of release 3.79 of the Linux
 436 .I man-pages
 437 project.
 438 A description of the project,
 439 information about reporting bugs,
 440 and the latest version of this page,
 441 can be found at
 442 \%http://www.kernel.org/doc/man\-pages/.