2 .\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
3 .\" <mtk.manpages@gmail.com>
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.
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.
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
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
27 .TH MATHERR 3 2010-09-10 "Linux" "Linux Programmer's Manual"
29 matherr \- SVID math library exception handling
32 .BR "#define _SVID_SOURCE" " /* See feature_test_macros(7) */"
35 .BI "int matherr(struct exception *" exc );
37 .B extern _LIB_VERSION_TYPE _LIB_VERSION;
42 The System V Interface Definition (SVID) specifies that various
43 math functions should invoke a function called
45 if a math exception is detected.
46 This function is called before the math function returns;
49 returns, the system then returns to the math function,
50 which in turn returns to the caller.
54 mechanism is supported by glibc, but is now obsolete:
55 new applications should use the techniques described in
59 This page documents the glibc
61 mechanism as an aid for maintaining and porting older applications.
65 the programmer must define the
73 to the external variable
76 The system provides a default version of
78 This version does nothing, and returns zero
79 (see below for the significance of this).
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
86 structure, defined as follows:
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 */
102 field has one of the following values:
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;
113 A pole error occurred (the function result is an infinity).
114 The return value in most cases is
116 (the largest single precision floating-point number),
117 appropriately signed.
124 An overflow occurred.
125 In most cases, the value
133 An underflow occurred.
140 Total loss of significance.
147 Partial loss of significance.
148 This value is unused on glibc
149 (and many other systems).
155 fields are the arguments supplied to the function
157 is undefined for functions that take only one argument).
161 field specifies the return value that the math
162 function will return to its caller.
163 The programmer-defined
165 can modify this field to change the return value of the math function.
169 function returns zero, then the system sets
171 as described above, and may print an error message on standard error
176 function returns a nonzero value, then the system does not set
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
183 The "Type" column indicates the value assigned to
187 The "Result" column is the default return value assigned to
190 The "Msg?" and "errno" columns describe the default behavior if
193 If the "Msg?" columns contains "y",
194 then the system prints an error message on standard error.
196 The table uses the following notations and abbreviations:
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
211 .\" Details below from glibc 2.8's sysdeps/ieee754/k_standard.c
212 .\" A subset of cases were test by experimental programs.
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
225 cosh(fin) o/f OVERFLOW HUGE n ERANGE
226 sinh(fin) o/f OVERFLOW (x>0.0) ? n ERANGE
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
251 tgamma(fin) o/f OVERFLOW HUGE_VAL n ERANGE
252 tgamma(\-int) SING NAN y EDOM
253 tgamma(0) SING copysign( y ERANGE
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
270 scalb() u/f UNDERFLOW copysign( n ERANGE
272 fmod(x,0) DOMAIN x y EDOM
273 remainder(x,0) DOMAIN NAN y EDOM \" retval is 0.0/0.0
276 The example program demonstrates the use of
280 The program takes up to three command-line arguments.
281 The first argument is the floating-point number to be given to
283 If the optional second argument is provided, then
289 is called, and the integer supplied in the
290 command-line argument is used as the return value from
292 If the optional third command-line argument is supplied,
293 then it specifies an alternative return value that
295 should assign as the return value of the math function.
297 The following example run, where
299 is given an argument of 0.0, does not use
304 .RB "$" " ./a.out 0.0"
305 errno: Numerical result out of range
310 In the following run,
312 is called, and returns 0:
316 .RB "$" " ./a.out 0.0 0"
317 matherr SING exception in log() function
318 args: 0.000000, 0.000000
319 retval: \-340282346638528859811704183484516925440.000000
321 errno: Numerical argument out of domain
322 x=-340282346638528859811704183484516925440.000000
326 The message "log: SING error" was printed by the C library.
328 In the following run,
330 is called, and returns a nonzero value:
334 .RB "$" " ./a.out 0.0 1"
335 matherr SING exception in log() function
336 args: 0.000000, 0.000000
337 retval: \-340282346638528859811704183484516925440.000000
338 x=-340282346638528859811704183484516925440.000000
342 In this case, the C library did not print a message, and
346 In the following run,
348 is called, changes the return value of the math function,
349 and returns a nonzero value:
353 .RB "$" " ./a.out 0.0 1 12345.0"
354 matherr SING exception in log() function
355 args: 0.000000, 0.000000
356 retval: \-340282346638528859811704183484516925440.000000
369 static int matherr_ret = 0; /* Value that matherr()
371 static int change_retval = 0; /* Should matherr() change
372 function\(aqs return value? */
373 static double new_retval; /* New function return value */
376 matherr(struct exception *exc)
378 fprintf(stderr, "matherr %s exception in %s() function\\n",
379 (exc\->type == DOMAIN) ? "DOMAIN" :
380 (exc\->type == OVERFLOW) ? "OVERFLOW" :
381 (exc\->type == UNDERFLOW) ? "UNDERFLOW" :
382 (exc\->type == SING) ? "SING" :
383 (exc\->type == TLOSS) ? "TLOSS" :
384 (exc\->type == PLOSS) ? "PLOSS" : "???",
386 fprintf(stderr, " args: %f, %f\\n",
387 exc\->arg1, exc\->arg2);
388 fprintf(stderr, " retval: %f\\n", exc\->retval);
391 exc\->retval = new_retval;
397 main(int argc, char *argv[])
402 fprintf(stderr, "Usage: %s <argval>"
403 " [<matherr\-ret> [<new\-func\-retval>]]\\n", argv[0]);
408 _LIB_VERSION = _SVID_;
409 matherr_ret = atoi(argv[2]);
414 new_retval = atof(argv[3]);
417 x = log(atof(argv[1]));
421 printf("x=%f\\n", x);