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 2016-03-15 "Linux" "Linux Programmer's Manual"
29 matherr \- SVID math library exception handling
34 .BI "int matherr(struct exception *" exc );
36 .B extern _LIB_VERSION_TYPE _LIB_VERSION;
40 Feature Test Macro Requirements for glibc (see
41 .BR feature_test_macros (7)):
49 /* Since glibc 2.19: */ _DEFAULT_SOURCE
50 || /* Glibc versions <= 2.19: */ _SVID_SOURCE
56 The System V Interface Definition (SVID) specifies that various
57 math functions should invoke a function called
59 if a math exception is detected.
60 This function is called before the math function returns;
63 returns, the system then returns to the math function,
64 which in turn returns to the caller.
68 mechanism is supported by glibc, but is now obsolete:
69 new applications should use the techniques described in
73 This page documents the glibc
75 mechanism as an aid for maintaining and porting older applications.
79 the programmer must define the
87 to the external variable
90 The system provides a default version of
92 This version does nothing, and returns zero
93 (see below for the significance of this).
96 can be overridden by a programmer-defined
97 version, which will be invoked when an exception occurs.
98 The function is invoked with one argument, a pointer to an
100 structure, defined as follows:
105 int type; /* Exception type */
106 char *name; /* Name of function causing exception */
107 double arg1; /* 1st argument to function */
108 double arg2; /* 2nd argument to function */
109 double retval; /* Function return value */
116 field has one of the following values:
119 A domain error occurred (the function argument was outside the range
120 for which the function is defined).
121 The return value depends on the function;
127 A pole error occurred (the function result is an infinity).
128 The return value in most cases is
130 (the largest single precision floating-point number),
131 appropriately signed.
138 An overflow occurred.
139 In most cases, the value
147 An underflow occurred.
154 Total loss of significance.
161 Partial loss of significance.
162 This value is unused on glibc
163 (and many other systems).
169 fields are the arguments supplied to the function
171 is undefined for functions that take only one argument).
175 field specifies the return value that the math
176 function will return to its caller.
177 The programmer-defined
179 can modify this field to change the return value of the math function.
183 function returns zero, then the system sets
185 as described above, and may print an error message on standard error
190 function returns a nonzero value, then the system does not set
192 and doesn't print an error message.
193 .SS Math functions that employ matherr()
194 The table below lists the functions and circumstances in which
197 The "Type" column indicates the value assigned to
201 The "Result" column is the default return value assigned to
204 The "Msg?" and "errno" columns describe the default behavior if
207 If the "Msg?" columns contains "y",
208 then the system prints an error message on standard error.
210 The table uses the following notations and abbreviations:
214 x first argument to function
215 y second argument to function
216 fin finite value for argument
217 neg negative value for argument
218 int integral value for argument
219 o/f result overflowed
220 u/f result underflowed
221 |x| absolute value of x
222 X_TLOSS is a constant defined in \fI<math.h>\fP
225 .\" Details below from glibc 2.8's sysdeps/ieee754/k_standard.c
226 .\" A subset of cases were test by experimental programs.
230 Function Type Result Msg? errno
231 acos(|x|>1) DOMAIN HUGE y EDOM
232 asin(|x|>1) DOMAIN HUGE y EDOM
233 atan2(0,0) DOMAIN HUGE y EDOM
234 acosh(x<1) DOMAIN NAN y EDOM \" retval is 0.0/0.0
235 atanh(|x|>1) DOMAIN NAN y EDOM \" retval is 0.0/0.0
236 atanh(|x|==1) SING (x>0.0)? y EDOM \" retval is x/0.0
239 cosh(fin) o/f OVERFLOW HUGE n ERANGE
240 sinh(fin) o/f OVERFLOW (x>0.0) ? n ERANGE
242 sqrt(x<0) DOMAIN 0.0 y EDOM
243 hypot(fin,fin) o/f OVERFLOW HUGE n ERANGE
244 exp(fin) o/f OVERFLOW HUGE n ERANGE
245 exp(fin) u/f UNDERFLOW 0.0 n ERANGE
246 exp2(fin) o/f OVERFLOW HUGE n ERANGE
247 exp2(fin) u/f UNDERFLOW 0.0 n ERANGE
248 exp10(fin) o/f OVERFLOW HUGE n ERANGE
249 exp10(fin) u/f UNDERFLOW 0.0 n ERANGE
250 j0(|x|>X_TLOSS) TLOSS 0.0 y ERANGE
251 j1(|x|>X_TLOSS) TLOSS 0.0 y ERANGE
252 jn(|x|>X_TLOSS) TLOSS 0.0 y ERANGE
253 y0(x>X_TLOSS) TLOSS 0.0 y ERANGE
254 y1(x>X_TLOSS) TLOSS 0.0 y ERANGE
255 yn(x>X_TLOSS) TLOSS 0.0 y ERANGE
256 y0(0) DOMAIN \-HUGE y EDOM
257 y0(x<0) DOMAIN \-HUGE y EDOM
258 y1(0) DOMAIN \-HUGE y EDOM
259 y1(x<0) DOMAIN \-HUGE y EDOM
260 yn(n,0) DOMAIN \-HUGE y EDOM
261 yn(x<0) DOMAIN \-HUGE y EDOM
262 lgamma(fin) o/f OVERFLOW HUGE n ERANGE
263 lgamma(\-int) or SING HUGE y EDOM
265 tgamma(fin) o/f OVERFLOW HUGE_VAL n ERANGE
266 tgamma(\-int) SING NAN y EDOM
267 tgamma(0) SING copysign( y ERANGE
269 log(0) SING \-HUGE y EDOM
270 log(x<0) DOMAIN \-HUGE y EDOM
271 log2(0) SING \-HUGE n EDOM \" different from log()
272 log2(x<0) DOMAIN \-HUGE n EDOM \" different from log()
273 log10(0) SING \-HUGE y EDOM
274 log10(x<0) DOMAIN \-HUGE y EDOM
275 pow(0.0,0.0) DOMAIN 0.0 y EDOM
276 pow(x,y) o/f OVERFLOW HUGE n ERANGE
277 pow(x,y) u/f UNDERFLOW 0.0 n ERANGE
278 pow(NaN,0.0) DOMAIN x n EDOM
279 0**neg DOMAIN 0.0 y EDOM \" +0 and -0
280 neg**non-int DOMAIN 0.0 y EDOM
281 scalb() o/f OVERFLOW (x>0.0) ? n ERANGE
284 scalb() u/f UNDERFLOW copysign( n ERANGE
286 fmod(x,0) DOMAIN x y EDOM
287 remainder(x,0) DOMAIN NAN y EDOM \" retval is 0.0/0.0
290 For an explanation of the terms used in this section, see
296 Interface Attribute Value
299 T} Thread safety MT-Safe
302 The example program demonstrates the use of
306 The program takes up to three command-line arguments.
307 The first argument is the floating-point number to be given to
309 If the optional second argument is provided, then
315 is called, and the integer supplied in the
316 command-line argument is used as the return value from
318 If the optional third command-line argument is supplied,
319 then it specifies an alternative return value that
321 should assign as the return value of the math function.
323 The following example run, where
325 is given an argument of 0.0, does not use
330 .RB "$" " ./a.out 0.0"
331 errno: Numerical result out of range
336 In the following run,
338 is called, and returns 0:
342 .RB "$" " ./a.out 0.0 0"
343 matherr SING exception in log() function
344 args: 0.000000, 0.000000
345 retval: \-340282346638528859811704183484516925440.000000
347 errno: Numerical argument out of domain
348 x=-340282346638528859811704183484516925440.000000
352 The message "log: SING error" was printed by the C library.
354 In the following run,
356 is called, and returns a nonzero value:
360 .RB "$" " ./a.out 0.0 1"
361 matherr SING exception in log() function
362 args: 0.000000, 0.000000
363 retval: \-340282346638528859811704183484516925440.000000
364 x=-340282346638528859811704183484516925440.000000
368 In this case, the C library did not print a message, and
372 In the following run,
374 is called, changes the return value of the math function,
375 and returns a nonzero value:
379 .RB "$" " ./a.out 0.0 1 12345.0"
380 matherr SING exception in log() function
381 args: 0.000000, 0.000000
382 retval: \-340282346638528859811704183484516925440.000000
395 static int matherr_ret = 0; /* Value that matherr()
397 static int change_retval = 0; /* Should matherr() change
398 function\(aqs return value? */
399 static double new_retval; /* New function return value */
402 matherr(struct exception *exc)
404 fprintf(stderr, "matherr %s exception in %s() function\\n",
405 (exc\->type == DOMAIN) ? "DOMAIN" :
406 (exc\->type == OVERFLOW) ? "OVERFLOW" :
407 (exc\->type == UNDERFLOW) ? "UNDERFLOW" :
408 (exc\->type == SING) ? "SING" :
409 (exc\->type == TLOSS) ? "TLOSS" :
410 (exc\->type == PLOSS) ? "PLOSS" : "???",
412 fprintf(stderr, " args: %f, %f\\n",
413 exc\->arg1, exc\->arg2);
414 fprintf(stderr, " retval: %f\\n", exc\->retval);
417 exc\->retval = new_retval;
423 main(int argc, char *argv[])
428 fprintf(stderr, "Usage: %s <argval>"
429 " [<matherr\-ret> [<new\-func\-retval>]]\\n", argv[0]);
434 _LIB_VERSION = _SVID_;
435 matherr_ret = atoi(argv[2]);
440 new_retval = atof(argv[3]);
443 x = log(atof(argv[1]));
447 printf("x=%f\\n", x);