release/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 .\"*******************************************************************
  26 .\"
  27 .\" This file was generated with po4a. Translate the source file.
  28 .\"
  29 .\"*******************************************************************
  30 .TH MATHERR 3 2010\-09\-10 Linux "Linux Programmer's Manual"
  31 .SH 名前
  32 matherr \- SVID math library exception handling
  33 .SH 書式
  34 .nf
  35 \fB#define _SVID_SOURCE\fP             /* See feature_test_macros(7) */
  36 \fB#include <math.h>\fP
  37
  38 \fBint matherr(struct exception *\fP\fIexc\fP\fB);\fP
  39
  40 \fBextern _LIB_VERSION_TYPE _LIB_VERSION;\fP
  41 .fi
  42 .sp
  43 \fI\-lm\fP でリンクする。
  44 .SH 説明
  45 The System V Interface Definition (SVID) specifies that various math
  46 functions should invoke a function called \fBmatherr\fP()  if a math exception
  47 is detected.  This function is called before the math function returns;
  48 after \fBmatherr\fP()  returns, the system then returns to the math function,
  49 which in turn returns to the caller.
  50
  51 The \fBmatherr\fP()  mechanism is supported by glibc, but is now obsolete: new
  52 applications should use the techniques described in \fBmath_error\fP(7)  and
  53 \fBfenv\fP(3).  This page documents the glibc \fBmatherr\fP()  mechanism as an aid
  54 for maintaining and porting older applications.
  55
  56 To employ \fBmatherr\fP(), the programmer must define the \fB_SVID_SOURCE\fP
  57 feature test macro (before including \fIany\fP header files), and assign the
  58 value \fB_SVID_\fP to the external variable \fB_LIB_VERSION\fP.
  59
  60 The system provides a default version of \fBmatherr\fP().  This version does
  61 nothing, and returns zero (see below for the significance of this).  The
  62 default \fBmatherr\fP()  can be overridden by a programmer\-defined version,
  63 which will be invoked when an exception occurs.  The function is invoked
  64 with one argument, a pointer to an \fIexception\fP structure, defined as
  65 follows:
  66
  67 .in +4n
  68 .nf
  69 struct exception {
  70     int    type;      /* Exception type */
  71     char  *name;      /* Name of function causing exception */
  72     double arg1;      /* 1st argument to function */
  73     double arg2;      /* 2nd argument to function */
  74     double retval;    /* Function return value */
  75 }
  76 .fi
  77 .in
  78 .PP
  79 The \fItype\fP field has one of the following values:
  80 .TP  12
  81 \fBDOMAIN\fP
  82 A domain error occurred (the function argument was outside the range for
  83 which the function is defined).  The return value depends on the function;
  84 \fIerrno\fP is set to \fBEDOM\fP.
  85 .TP
  86 \fBSING\fP
  87 A pole error occurred (the function result is an infinity).  The return
  88 value in most cases is \fBHUGE\fP (the largest single precision floating\-point
  89 number), appropriately signed.  In most cases, \fIerrno\fP is set to \fBEDOM\fP.
  90 .TP
  91 \fBOVERFLOW\fP
  92 An overflow occurred.  In most cases, the value \fBHUGE\fP is returned, and
  93 \fIerrno\fP is set to \fBERANGE\fP.
  94 .TP
  95 \fBUNDERFLOW\fP
  96 An underflow occurred.  0.0 is returned, and \fIerrno\fP is set to \fBERANGE\fP.
  97 .TP
  98 \fBTLOSS\fP
  99 Total loss of significance.  0.0 is returned, and \fIerrno\fP is set to
 100 \fBERANGE\fP.
 101 .TP
 102 \fBPLOSS\fP
 103 Partial loss of significance.  This value is unused on glibc (and many other
 104 systems).
 105 .PP
 106 The \fIarg1\fP and \fIarg2\fP fields are the arguments supplied to the function
 107 (\fIarg2\fP is undefined for functions that take only one argument).
 108
 109 The \fIretval\fP field specifies the return value that the math function will
 110 return to its caller.  The programmer\-defined \fBmatherr\fP()  can modify this
 111 field to change the return value of the math function.
 112
 113 If the \fBmatherr\fP()  function returns zero, then the system sets \fIerrno\fP as
 114 described above, and may print an error message on standard error (see
 115 below).
 116
 117 If the \fBmatherr\fP()  function returns a nonzero value, then the system does
 118 not set \fIerrno\fP, and doesn't print an error message.
 119 .SS "Math functions that employ matherr()"
 120 The table below lists the functions and circumstances in which \fBmatherr\fP()
 121 is called.  The "Type" column indicates the value assigned to
 122 \fIexc\->type\fP when calling \fBmatherr\fP().  The "Result" column is the
 123 default return value assigned to \fIexc\->retval\fP.
 124
 125 The "Msg?" and "errno" columns describe the default behavior if \fBmatherr\fP()
 126 returns zero.  If the "Msg?" columns contains "y", then the system prints an
 127 error message on standard error.
 128
 129 The table uses the following notations and abbreviations:
 130 .RS
 131 .nf
 132
 133 x        first argument to function
 134 y        second argument to function
 135 fin      finite value for argument
 136 neg      negative value for argument
 137 int      integral value for argument
 138 o/f      result overflowed
 139 u/f      result underflowed
 140 |x|      absolute value of x
 141 X_TLOSS  is a constant defined in \fI<math.h>\fP
 142 .fi
 143 .RE
 144 .\" Details below from glibc 2.8's sysdeps/ieee754/k_standard.c
 145 .\" A subset of cases were test by experimental programs.
 146 .TS
 147 lB lB lB cB lB
 148 l l l c l.
 149 Function        Type    Result  Msg?    errno
 150 acos(|x|>1)     DOMAIN  HUGE    y       EDOM
 151 asin(|x|>1)     DOMAIN  HUGE    y       EDOM
 152 atan2(0,0)      DOMAIN  HUGE    y       EDOM
 153 .\" retval is 0.0/0.0
 154 acosh(x<1)      DOMAIN  NAN     y       EDOM
 155 .\" retval is 0.0/0.0
 156 atanh(|x|>1)    DOMAIN  NAN     y       EDOM
 157 .\" retval is x/0.0
 158 atanh(|x|==1)   SING    (x>0.0)?        y       EDOM
 159 \       \       HUGE_VAL :
 160 \       \       \-HUGE_VAL
 161 cosh(fin) o/f   OVERFLOW        HUGE    n       ERANGE
 162 sinh(fin) o/f   OVERFLOW        (x>0.0) ?       n       ERANGE
 163 \       \       HUGE : \-HUGE
 164 sqrt(x<0)       DOMAIN  0.0     y       EDOM
 165 hypot(fin,fin) o/f      OVERFLOW        HUGE    n       ERANGE
 166 exp(fin) o/f    OVERFLOW        HUGE    n       ERANGE
 167 exp(fin) u/f    UNDERFLOW       0.0     n       ERANGE
 168 exp2(fin) o/f   OVERFLOW        HUGE    n       ERANGE
 169 exp2(fin) u/f   UNDERFLOW       0.0     n       ERANGE
 170 exp10(fin) o/f  OVERFLOW        HUGE    n       ERANGE
 171 exp10(fin) u/f  UNDERFLOW       0.0     n       ERANGE
 172 j0(|x|>X_TLOSS) TLOSS   0.0     y       ERANGE
 173 j1(|x|>X_TLOSS) TLOSS   0.0     y       ERANGE
 174 jn(|x|>X_TLOSS) TLOSS   0.0     y       ERANGE
 175 y0(x>X_TLOSS)   TLOSS   0.0     y       ERANGE
 176 y1(x>X_TLOSS)   TLOSS   0.0     y       ERANGE
 177 yn(x>X_TLOSS)   TLOSS   0.0     y       ERANGE
 178 y0(0)   DOMAIN  \-HUGE  y       EDOM
 179 y0(x<0) DOMAIN  \-HUGE  y       EDOM
 180 y1(0)   DOMAIN  \-HUGE  y       EDOM
 181 y1(x<0) DOMAIN  \-HUGE  y       EDOM
 182 yn(n,0) DOMAIN  \-HUGE  y       EDOM
 183 yn(x<0) DOMAIN  \-HUGE  y       EDOM
 184 lgamma(fin) o/f OVERFLOW        HUGE    n       ERANGE
 185 lgamma(\-int) or        SING    HUGE    y       EDOM
 186 \ \ lgamma(0)
 187 tgamma(fin) o/f OVERFLOW        HUGE_VAL        n       ERANGE
 188 tgamma(\-int)   SING    NAN     y       EDOM
 189 tgamma(0)       SING    copysign(       y       ERANGE
 190 \       \       HUGE_VAL,x)
 191 log(0)  SING    \-HUGE  y       EDOM
 192 log(x<0)        DOMAIN  \-HUGE  y       EDOM
 193 .\" different from log()
 194 log2(0) SING    \-HUGE  n       EDOM
 195 .\" different from log()
 196 log2(x<0)       DOMAIN  \-HUGE  n       EDOM
 197 log10(0)        SING    \-HUGE  y       EDOM
 198 log10(x<0)      DOMAIN  \-HUGE  y       EDOM
 199 pow(0.0,0.0)    DOMAIN  0.0     y       EDOM
 200 pow(x,y) o/f    OVERFLOW        HUGE    n       ERANGE
 201 pow(x,y) u/f    UNDERFLOW       0.0     n       ERANGE
 202 pow(NaN,0.0)    DOMAIN  x       n       EDOM
 203 .\" +0 and -0
 204 0**neg  DOMAIN  0.0     y       EDOM
 205 neg**non\-int   DOMAIN  0.0     y       EDOM
 206 scalb() o/f     OVERFLOW        (x>0.0) ?       n       ERANGE
 207 \       \       HUGE_VAL :
 208 \       \       \-HUGE_VAL
 209 scalb() u/f     UNDERFLOW       copysign(       n       ERANGE
 210 \       \       \ \ 0.0,x)
 211 fmod(x,0)       DOMAIN  x       y       EDOM
 212 .\" retval is 0.0/0.0
 213 remainder(x,0)  DOMAIN  NAN     y       EDOM
 214 .TE
 215 .SH 例
 216 The example program demonstrates the use of \fBmatherr\fP()  when calling
 217 \fBlog\fP(3).  The program takes up to three command\-line arguments.  The first
 218 argument is the floating\-point number to be given to \fBlog\fP(3).  If the
 219 optional second argument is provided, then \fB_LIB_VERSION\fP is set to
 220 \fB_SVID_\fP so that \fBmatherr\fP()  is called, and the integer supplied in the
 221 command\-line argument is used as the return value from \fBmatherr\fP().  If the
 222 optional third command\-line argument is supplied, then it specifies an
 223 alternative return value that \fBmatherr\fP()  should assign as the return
 224 value of the math function.
 225
 226 The following example run, where \fBlog\fP(3)  is given an argument of 0.0,
 227 does not use \fBmatherr\fP():
 228
 229 .in +4n
 230 .nf
 231 $\fB ./a.out 0.0\fP
 232 errno: Numerical result out of range
 233 x=\-inf
 234 .fi
 235 .in
 236
 237 In the following run, \fBmatherr\fP()  is called, and returns 0:
 238
 239 .in +4n
 240 .nf
 241 $\fB ./a.out 0.0 0\fP
 242 matherr SING exception in log() function
 243         args:   0.000000, 0.000000
 244         retval: \-340282346638528859811704183484516925440.000000
 245 log: SING error
 246 errno: Numerical argument out of domain
 247 x=\-340282346638528859811704183484516925440.000000
 248 .fi
 249 .in
 250
 251 The message "log: SING error" was printed by the C library.
 252
 253 In the following run, \fBmatherr\fP()  is called, and returns a nonzero value:
 254
 255 .in +4n
 256 .nf
 257 $\fB ./a.out 0.0 1\fP
 258 matherr SING exception in log() function
 259         args:   0.000000, 0.000000
 260         retval: \-340282346638528859811704183484516925440.000000
 261 x=\-340282346638528859811704183484516925440.000000
 262 .fi
 263 .in
 264
 265 In this case, the C library did not print a message, and \fIerrno\fP was not
 266 set.
 267
 268 In the following run, \fBmatherr\fP()  is called, changes the return value of
 269 the math function, and returns a nonzero value:
 270
 271 .in +4n
 272 .nf
 273 $\fB ./a.out 0.0 1 12345.0\fP
 274 matherr SING exception in log() function
 275         args:   0.000000, 0.000000
 276         retval: \-340282346638528859811704183484516925440.000000
 277 x=12345.000000
 278 .fi
 279 .in
 280 .SS プログラムのソース
 281 \&
 282 .nf
 283 #define _SVID_SOURCE
 284 #include <errno.h>
 285 #include <math.h>
 286 #include <stdio.h>
 287 #include <stdlib.h>
 288
 289 static int matherr_ret = 0;     /* Value that matherr()
 290                                    should return */
 291 static int change_retval = 0;   /* Should matherr() change
 292                                    function\(aqs return value? */
 293 static double new_retval;       /* New function return value */
 294
 295 int
 296 matherr(struct exception *exc)
 297 {
 298     fprintf(stderr, "matherr %s exception in %s() function\en",
 299            (exc\->type == DOMAIN) ?    "DOMAIN" :
 300            (exc\->type == OVERFLOW) ?  "OVERFLOW" :
 301            (exc\->type == UNDERFLOW) ? "UNDERFLOW" :
 302            (exc\->type == SING) ?      "SING" :
 303            (exc\->type == TLOSS) ?     "TLOSS" :
 304            (exc\->type == PLOSS) ?     "PLOSS" : "???",
 305             exc\->name);
 306     fprintf(stderr, "        args:   %f, %f\en",
 307             exc\->arg1, exc\->arg2);
 308     fprintf(stderr, "        retval: %f\en", exc\->retval);
 309
 310     if (change_retval)
 311         exc\->retval = new_retval;
 312
 313     return matherr_ret;
 314 }
 315
 316 int
 317 main(int argc, char *argv[])
 318 {
 319     double x;
 320
 321     if (argc < 2) {
 322         fprintf(stderr, "Usage: %s <argval>"
 323                 " [<matherr\-ret> [<new\-func\-retval>]]\en", argv[0]);
 324         exit(EXIT_FAILURE);
 325     }
 326
 327     if (argc > 2) {
 328         _LIB_VERSION = _SVID_;
 329         matherr_ret = atoi(argv[2]);
 330     }
 331
 332     if (argc > 3) {
 333         change_retval = 1;
 334         new_retval = atof(argv[3]);
 335     }
 336
 337     x = log(atof(argv[1]));
 338     if (errno != 0)
 339         perror("errno");
 340
 341     printf("x=%f\en", x);
 342     exit(EXIT_SUCCESS);
 343 }
 344 .fi
 345 .SH 関連項目
 346 \fBfenv\fP(3), \fBmath_error\fP(7), \fBstandards\fP(7)