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