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 2014-06-13 "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 .SS Multithreading (see pthreads(7))
279 function is thread-safe.
281 The example program demonstrates the use of
285 The program takes up to three command-line arguments.
286 The first argument is the floating-point number to be given to
288 If the optional second argument is provided, then
294 is called, and the integer supplied in the
295 command-line argument is used as the return value from
297 If the optional third command-line argument is supplied,
298 then it specifies an alternative return value that
300 should assign as the return value of the math function.
302 The following example run, where
304 is given an argument of 0.0, does not use
309 .RB "$" " ./a.out 0.0"
310 errno: Numerical result out of range
315 In the following run,
317 is called, and returns 0:
321 .RB "$" " ./a.out 0.0 0"
322 matherr SING exception in log() function
323 args: 0.000000, 0.000000
324 retval: \-340282346638528859811704183484516925440.000000
326 errno: Numerical argument out of domain
327 x=-340282346638528859811704183484516925440.000000
331 The message "log: SING error" was printed by the C library.
333 In the following run,
335 is called, and returns a nonzero value:
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
347 In this case, the C library did not print a message, and
351 In the following run,
353 is called, changes the return value of the math function,
354 and returns a nonzero value:
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
374 static int matherr_ret = 0; /* Value that matherr()
376 static int change_retval = 0; /* Should matherr() change
377 function\(aqs return value? */
378 static double new_retval; /* New function return value */
381 matherr(struct exception *exc)
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" : "???",
391 fprintf(stderr, " args: %f, %f\\n",
392 exc\->arg1, exc\->arg2);
393 fprintf(stderr, " retval: %f\\n", exc\->retval);
396 exc\->retval = new_retval;
402 main(int argc, char *argv[])
407 fprintf(stderr, "Usage: %s <argval>"
408 " [<matherr\-ret> [<new\-func\-retval>]]\\n", argv[0]);
413 _LIB_VERSION = _SVID_;
414 matherr_ret = atoi(argv[2]);
419 new_retval = atof(argv[3]);
422 x = log(atof(argv[1]));
426 printf("x=%f\\n", x);