1MATHERR(3) Linux Programmer's Manual MATHERR(3)
2
6 matherr - SVID math library exception handling
7
9 #include <math.h>
10 int matherr(struct exception *exc);
12 extern _LIB_VERSION_TYPE _LIB_VERSION;
14 Link with -lm.
16
18 Note: the mechanism described in this page is no longer supported by
19 glibc. Before glibc 2.27, it had been marked as obsolete. Since glibc
20 2.27, the mechanism has been removed altogether. New applications
21 should use the techniques described in math_error(7) and fenv(3). This
22 page documents the matherr() mechanism as an aid for maintaining and
23 porting older applications.
24 The System V Interface Definition (SVID) specifies that various math
26 functions should invoke a function called matherr() if a math exception
27 is detected. This function is called before the math function returns;
28 after matherr() returns, the system then returns to the math function,
29 which in turn returns to the caller.
30 To employ matherr(), the programmer must define the _SVID_SOURCE fea‐
32 ture test macro (before including any header files), and assign the
33 value _SVID_ to the external variable _LIB_VERSION.
34 The system provides a default version of matherr(). This version does
36 nothing, and returns zero (see below for the significance of this).
37 The default matherr() can be overridden by a programmer-defined ver‐
38 sion, which will be invoked when an exception occurs. The function is
39 invoked with one argument, a pointer to an exception structure, defined
40 as follows:
41 struct exception {
43 int type; /* Exception type */
44 char *name; /* Name of function causing exception */
45 double arg1; /* 1st argument to function */
46 double arg2; /* 2nd argument to function */
47 double retval; /* Function return value */
48 }
49 The type field has one of the following values:
51 DOMAIN A domain error occurred (the function argument was outside
53 the range for which the function is defined). The return
54 value depends on the function; errno is set to EDOM.
55 SING A pole error occurred (the function result is an infinity).
57 The return value in most cases is HUGE (the largest single
58 precision floating-point number), appropriately signed. In
59 most cases, errno is set to EDOM.
60 OVERFLOW An overflow occurred. In most cases, the value HUGE is re‐
62 turned, and errno is set to ERANGE.
63 UNDERFLOW An underflow occurred. 0.0 is returned, and errno is set
65 to ERANGE.
66 TLOSS Total loss of significance. 0.0 is returned, and errno is
68 set to ERANGE.
69 PLOSS Partial loss of significance. This value is unused on
71 glibc (and many other systems).
72 The arg1 and arg2 fields are the arguments supplied to the function
74 (arg2 is undefined for functions that take only one argument).
75 The retval field specifies the return value that the math function will
77 return to its caller. The programmer-defined matherr() can modify this
78 field to change the return value of the math function.
79 If the matherr() function returns zero, then the system sets errno as
81 described above, and may print an error message on standard error (see
82 below).
83 If the matherr() function returns a nonzero value, then the system does
85 not set errno, and doesn't print an error message.
86 Math functions that employ matherr()
88 The table below lists the functions and circumstances in which math‐
89 err() is called. The "Type" column indicates the value assigned to
90 exc->type when calling matherr(). The "Result" column is the default
91 return value assigned to exc->retval.
92 The "Msg?" and "errno" columns describe the default behavior if math‐
94 err() returns zero. If the "Msg?" columns contains "y", then the sys‐
95 tem prints an error message on standard error.
96 The table uses the following notations and abbreviations:
98 x first argument to function
100 y second argument to function
101 fin finite value for argument
102 neg negative value for argument
103 int integral value for argument
104 o/f result overflowed
105 u/f result underflowed
106 |x| absolute value of x
107 X_TLOSS is a constant defined in <math.h>
108 Function Type Result Msg? errno
110 acos(|x|>1) DOMAIN HUGE y EDOM
111 asin(|x|>1) DOMAIN HUGE y EDOM
112 atan2(0,0) DOMAIN HUGE y EDOM
113 acosh(x<1) DOMAIN NAN y EDOM
114 atanh(|x|>1) DOMAIN NAN y EDOM
115 atanh(|x|==1) SING (x>0.0)? y EDOM
116 HUGE_VAL :
117 -HUGE_VAL
118 cosh(fin) o/f OVERFLOW HUGE n ERANGE
119 sinh(fin) o/f OVERFLOW (x>0.0) ? n ERANGE
120 HUGE : -HUGE
121 sqrt(x<0) DOMAIN 0.0 y EDOM
122 hypot(fin,fin) o/f OVERFLOW HUGE n ERANGE
123 exp(fin) o/f OVERFLOW HUGE n ERANGE
124 exp(fin) u/f UNDERFLOW 0.0 n ERANGE
125 exp2(fin) o/f OVERFLOW HUGE n ERANGE
126 exp2(fin) u/f UNDERFLOW 0.0 n ERANGE
127 exp10(fin) o/f OVERFLOW HUGE n ERANGE
128 exp10(fin) u/f UNDERFLOW 0.0 n ERANGE
129 j0(|x|>X_TLOSS) TLOSS 0.0 y ERANGE
130 j1(|x|>X_TLOSS) TLOSS 0.0 y ERANGE
131 jn(|x|>X_TLOSS) TLOSS 0.0 y ERANGE
132 y0(x>X_TLOSS) TLOSS 0.0 y ERANGE
134 y1(x>X_TLOSS) TLOSS 0.0 y ERANGE
135 yn(x>X_TLOSS) TLOSS 0.0 y ERANGE
136 y0(0) DOMAIN -HUGE y EDOM
137 y0(x<0) DOMAIN -HUGE y EDOM
138 y1(0) DOMAIN -HUGE y EDOM
139 y1(x<0) DOMAIN -HUGE y EDOM
140 yn(n,0) DOMAIN -HUGE y EDOM
141 yn(x<0) DOMAIN -HUGE y EDOM
142 lgamma(fin) o/f OVERFLOW HUGE n ERANGE
143 lgamma(-int) or SING HUGE y EDOM
144 lgamma(0)
145 tgamma(fin) o/f OVERFLOW HUGE_VAL n ERANGE
146 tgamma(-int) SING NAN y EDOM
147 tgamma(0) SING copysign( y ERANGE
148 HUGE_VAL,x)
149 log(0) SING -HUGE y EDOM
150 log(x<0) DOMAIN -HUGE y EDOM
151 log2(0) SING -HUGE n EDOM
152 log2(x<0) DOMAIN -HUGE n EDOM
153 log10(0) SING -HUGE y EDOM
154 log10(x<0) DOMAIN -HUGE y EDOM
155 pow(0.0,0.0) DOMAIN 0.0 y EDOM
156 pow(x,y) o/f OVERFLOW HUGE n ERANGE
157 pow(x,y) u/f UNDERFLOW 0.0 n ERANGE
158 pow(NaN,0.0) DOMAIN x n EDOM
159 0**neg DOMAIN 0.0 y EDOM
160 neg**non-int DOMAIN 0.0 y EDOM
161 scalb() o/f OVERFLOW (x>0.0) ? n ERANGE
162 HUGE_VAL :
163 -HUGE_VAL
164 scalb() u/f UNDERFLOW copysign( n ERANGE
165 0.0,x)
166 fmod(x,0) DOMAIN x y EDOM
167 remainder(x,0) DOMAIN NAN y EDOM
168
170 For an explanation of the terms used in this section, see at‐
171 tributes(7).
172 ┌────────────────────────────────────────────┬───────────────┬─────────┐
174 │Interface │ Attribute │ Value │
175 ├────────────────────────────────────────────┼───────────────┼─────────┤
176 │matherr() │ Thread safety │ MT-Safe │
177 └────────────────────────────────────────────┴───────────────┴─────────┘
178
180 The example program demonstrates the use of matherr() when calling
181 log(3). The program takes up to three command-line arguments. The
182 first argument is the floating-point number to be given to log(3). If
183 the optional second argument is provided, then _LIB_VERSION is set to
184 _SVID_ so that matherr() is called, and the integer supplied in the
185 command-line argument is used as the return value from matherr(). If
186 the optional third command-line argument is supplied, then it specifies
187 an alternative return value that matherr() should assign as the return
188 value of the math function.
189 The following example run, where log(3) is given an argument of 0.0,
191 does not use matherr():
192 $ ./a.out 0.0
194 errno: Numerical result out of range
195 x=-inf
196 In the following run, matherr() is called, and returns 0:
198 $ ./a.out 0.0 0
200 matherr SING exception in log() function
201 args: 0.000000, 0.000000
202 retval: -340282346638528859811704183484516925440.000000
203 log: SING error
204 errno: Numerical argument out of domain
205 x=-340282346638528859811704183484516925440.000000
206 The message "log: SING error" was printed by the C library.
208 In the following run, matherr() is called, and returns a nonzero value:
210 $ ./a.out 0.0 1
212 matherr SING exception in log() function
213 args: 0.000000, 0.000000
214 retval: -340282346638528859811704183484516925440.000000
215 x=-340282346638528859811704183484516925440.000000
216 In this case, the C library did not print a message, and errno was not
218 set.
219 In the following run, matherr() is called, changes the return value of
221 the math function, and returns a nonzero value:
222 $ ./a.out 0.0 1 12345.0
224 matherr SING exception in log() function
225 args: 0.000000, 0.000000
226 retval: -340282346638528859811704183484516925440.000000
227 x=12345.000000
228 Program source
230 #define _SVID_SOURCE
232 #include <errno.h>
233 #include <math.h>
234 #include <stdio.h>
235 #include <stdlib.h>
236 static int matherr_ret = 0; /* Value that matherr()
238 should return */
239 static int change_retval = 0; /* Should matherr() change
240 function's return value? */
241 static double new_retval; /* New function return value */
242 int
244 matherr(struct exception *exc)
245 {
246 fprintf(stderr, "matherr %s exception in %s() function\n",
247 (exc->type == DOMAIN) ? "DOMAIN" :
248 (exc->type == OVERFLOW) ? "OVERFLOW" :
249 (exc->type == UNDERFLOW) ? "UNDERFLOW" :
250 (exc->type == SING) ? "SING" :
251 (exc->type == TLOSS) ? "TLOSS" :
252 (exc->type == PLOSS) ? "PLOSS" : "???",
253 exc->name);
254 fprintf(stderr, " args: %f, %f\n",
255 exc->arg1, exc->arg2);
256 fprintf(stderr, " retval: %f\n", exc->retval);
257 if (change_retval)
259 exc->retval = new_retval;
260 return matherr_ret;
262 }
263 int
265 main(int argc, char *argv[])
266 {
267 double x;
268 if (argc < 2) {
270 fprintf(stderr, "Usage: %s <argval>"
271 " [<matherr-ret> [<new-func-retval>]]\n", argv[0]);
272 exit(EXIT_FAILURE);
273 }
274 if (argc > 2) {
276 _LIB_VERSION = _SVID_;
277 matherr_ret = atoi(argv[2]);
278 }
279 if (argc > 3) {
281 change_retval = 1;
282 new_retval = atof(argv[3]);
283 }
284 x = log(atof(argv[1]));
286 if (errno != 0)
287 perror("errno");
288 printf("x=%f\n", x);
290 exit(EXIT_SUCCESS);
291 }
292
294 fenv(3), math_error(7), standards(7)
295
297 This page is part of release 5.12 of the Linux man-pages project. A
298 description of the project, information about reporting bugs, and the
299 latest version of this page, can be found at
300 https://www.kernel.org/doc/man-pages/.
301Linux 2021-03-22 MATHERR(3)