2 .\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
3 .\" <mtk.manpages@gmail.com>
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.
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.
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
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
25 .TH MATHERR 3 2010-09-10 "Linux" "Linux Programmer's Manual"
27 matherr \- SVID math library exception handling
30 .BR "#define _SVID_SOURCE" " /* See feature_test_macros(7) */"
33 .BI "int matherr(struct exception *" exc );
35 .B extern _LIB_VERSION_TYPE _LIB_VERSION;
40 The System V Interface Definition (SVID) specifies that various
41 math functions should invoke a function called
43 if a math exception is detected.
44 This function is called before the math function returns;
47 returns, the system then returns to the math function,
48 which in turn returns to the caller.
52 mechanism is supported by glibc, but is now obsolete:
53 new applications should use the techniques described in
57 This page documents the glibc
59 mechanism as an aid for maintaining and porting older applications.
63 the programmer must define the
71 to the external variable
74 The system provides a default version of
76 This version does nothing, and returns zero
77 (see below for the significance of this).
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
84 structure, defined as follows:
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 */
100 field has one of the following values:
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;
111 A pole error occurred (the function result is an infinity).
112 The return value in most cases is
114 (the largest single precision floating-point number),
115 appropriately signed.
122 An overflow occurred.
123 In most cases, the value
131 An underflow occurred.
138 Total loss of significance.
145 Partial loss of significance.
146 This value is unused on glibc
147 (and many other systems).
153 fields are the arguments supplied to the function
155 is undefined for functions that take only one argument).
159 field specifies the return value that the math
160 function will return to its caller.
161 The programmer-defined
163 can modify this field to change the return value of the math function.
167 function returns zero, then the system sets
169 as described above, and may print an error message on standard error
174 function returns a nonzero value, then the system does not set
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
181 The "Type" column indicates the value assigned to
185 The "Result" column is the default return value assigned to
188 The "Msg?" and "errno" columns describe the default behavior if
191 If the "Msg?" columns contains "y",
192 then the system prints an error message on standard error.
194 The table uses the following notations and abbreviations:
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
209 .\" Details below from glibc 2.8's sysdeps/ieee754/k_standard.c
210 .\" A subset of cases were test by experimental programs.
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
223 cosh(fin) o/f OVERFLOW HUGE n ERANGE
224 sinh(fin) o/f OVERFLOW (x>0.0) ? n ERANGE
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
249 tgamma(fin) o/f OVERFLOW HUGE_VAL n ERANGE
250 tgamma(\-int) SING NAN y EDOM
251 tgamma(0) SING copysign( y ERANGE
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
268 scalb() u/f UNDERFLOW copysign( n ERANGE
270 fmod(x,0) DOMAIN x y EDOM
271 remainder(x,0) DOMAIN NAN y EDOM \" retval is 0.0/0.0
274 The example program demonstrates the use of
278 The program takes up to three command-line arguments.
279 The first argument is the floating-point number to be given to
281 If the optional second argument is provided, then
287 is called, and the integer supplied in the
288 command-line argument is used as the return value from
290 If the optional third command-line argument is supplied,
291 then it specifies an alternative return value that
293 should assign as the return value of the math function.
295 The following example run, where
297 is given an argument of 0.0, does not use
302 .RB "$" " ./a.out 0.0"
303 errno: Numerical result out of range
308 In the following run,
310 is called, and returns 0:
314 .RB "$" " ./a.out 0.0 0"
315 matherr SING exception in log() function
316 args: 0.000000, 0.000000
317 retval: \-340282346638528859811704183484516925440.000000
319 errno: Numerical argument out of domain
320 x=-340282346638528859811704183484516925440.000000
324 The message "log: SING error" was printed by the C library.
326 In the following run,
328 is called, and returns a nonzero value:
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
340 In this case, the C library did not print a message, and
344 In the following run,
346 is called, changes the return value of the math function,
347 and returns a nonzero value:
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
367 static int matherr_ret = 0; /* Value that matherr()
369 static int change_retval = 0; /* Should matherr() change
370 function\(aqs return value? */
371 static double new_retval; /* New function return value */
374 matherr(struct exception *exc)
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" : "???",
384 fprintf(stderr, " args: %f, %f\\n",
385 exc\->arg1, exc->arg2);
386 fprintf(stderr, " retval: %f\\n", exc\->retval);
389 exc\->retval = new_retval;
395 main(int argc, char *argv[])
400 fprintf(stderr, "Usage: %s <argval>"
401 " [<matherr\-ret> [<new\-func-retval>]]\\n", argv[0]);
406 _LIB_VERSION = _SVID_;
407 matherr_ret = atoi(argv[2]);
412 new_retval = atof(argv[3]);
415 x = log(atof(argv[1]));
419 printf("x=%f\\n", x);