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
62 returned, 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
171 attributes(7).
172 ┌──────────┬───────────────┬─────────┐
174 │Interface │ Attribute │ Value │
175 ├──────────┼───────────────┼─────────┤
176 │matherr() │ Thread safety │ MT-Safe │
177 └──────────┴───────────────┴─────────┘
179 The example program demonstrates the use of matherr() when calling
180 log(3). The program takes up to three command-line arguments. The
181 first argument is the floating-point number to be given to log(3). If
182 the optional second argument is provided, then _LIB_VERSION is set to
183 _SVID_ so that matherr() is called, and the integer supplied in the
184 command-line argument is used as the return value from matherr(). If
185 the optional third command-line argument is supplied, then it specifies
186 an alternative return value that matherr() should assign as the return
187 value of the math function.
188 The following example run, where log(3) is given an argument of 0.0,
190 does not use matherr():
191 $ ./a.out 0.0
193 errno: Numerical result out of range
194 x=-inf
195 In the following run, matherr() is called, and returns 0:
197 $ ./a.out 0.0 0
199 matherr SING exception in log() function
200 args: 0.000000, 0.000000
201 retval: -340282346638528859811704183484516925440.000000
202 log: SING error
203 errno: Numerical argument out of domain
204 x=-340282346638528859811704183484516925440.000000
205 The message "log: SING error" was printed by the C library.
207 In the following run, matherr() is called, and returns a nonzero value:
209 $ ./a.out 0.0 1
211 matherr SING exception in log() function
212 args: 0.000000, 0.000000
213 retval: -340282346638528859811704183484516925440.000000
214 x=-340282346638528859811704183484516925440.000000
215 In this case, the C library did not print a message, and errno was not
217 set.
218 In the following run, matherr() is called, changes the return value of
220 the math function, and returns a nonzero value:
221 $ ./a.out 0.0 1 12345.0
223 matherr SING exception in log() function
224 args: 0.000000, 0.000000
225 retval: -340282346638528859811704183484516925440.000000
226 x=12345.000000
227 Program source
229 #define _SVID_SOURCE
231 #include <errno.h>
232 #include <math.h>
233 #include <stdio.h>
234 #include <stdlib.h>
235 static int matherr_ret = 0; /* Value that matherr()
237 should return */
238 static int change_retval = 0; /* Should matherr() change
239 function's return value? */
240 static double new_retval; /* New function return value */
241 int
243 matherr(struct exception *exc)
244 {
245 fprintf(stderr, "matherr %s exception in %s() function\n",
246 (exc->type == DOMAIN) ? "DOMAIN" :
247 (exc->type == OVERFLOW) ? "OVERFLOW" :
248 (exc->type == UNDERFLOW) ? "UNDERFLOW" :
249 (exc->type == SING) ? "SING" :
250 (exc->type == TLOSS) ? "TLOSS" :
251 (exc->type == PLOSS) ? "PLOSS" : "???",
252 exc->name);
253 fprintf(stderr, " args: %f, %f\n",
254 exc->arg1, exc->arg2);
255 fprintf(stderr, " retval: %f\n", exc->retval);
256 if (change_retval)
258 exc->retval = new_retval;
259 return matherr_ret;
261 }
262 int
264 main(int argc, char *argv[])
265 {
266 double x;
267 if (argc < 2) {
269 fprintf(stderr, "Usage: %s <argval>"
270 " [<matherr-ret> [<new-func-retval>]]\n", argv[0]);
271 exit(EXIT_FAILURE);
272 }
273 if (argc > 2) {
275 _LIB_VERSION = _SVID_;
276 matherr_ret = atoi(argv[2]);
277 }
278 if (argc > 3) {
280 change_retval = 1;
281 new_retval = atof(argv[3]);
282 }
283 x = log(atof(argv[1]));
285 if (errno != 0)
286 perror("errno");
287 printf("x=%f\n", x);
289 exit(EXIT_SUCCESS);
290 }
291
293 fenv(3), math_error(7), standards(7)
294
296 This page is part of release 5.07 of the Linux man-pages project. A
297 description of the project, information about reporting bugs, and the
298 latest version of this page, can be found at
299 https://www.kernel.org/doc/man-pages/.
300Linux 2020-06-09 MATHERR(3)