| blob | 66b2f0fe81339ea6fcb7cc9df96362c9cd5cd3d1 |
1 '\" t
2 .\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
3 .\" <mtk.manpages@gmail.com>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH matherr 3 (date) "Linux man-pages (unreleased)"
8 .SH NAME
9 matherr \- SVID math library exception handling
10 .SH LIBRARY
11 Math library
12 .RI ( libm ", " \-lm )
13 .SH SYNOPSIS
14 .nf
15 .B #include <math.h>
16 .P
17 .BI "[[deprecated]] int matherr(struct exception *" exc );
18 .P
19 .B [[deprecated]] extern _LIB_VERSION_TYPE _LIB_VERSION;
20 .fi
21 .SH DESCRIPTION
22 .IR Note :
23 the mechanism described in this page is no longer supported by glibc.
24 Before glibc 2.27, it had been marked as obsolete.
25 Since glibc 2.27,
26 .\" glibc commit 813378e9fe17e029caf627cab76fe23eb46815fa
27 the mechanism has been removed altogether.
28 New applications should use the techniques described in
29 .BR math_error (7)
30 and
31 .BR fenv (3).
32 This page documents the
33 .BR matherr ()
34 mechanism as an aid for maintaining and porting older applications.
35 .P
36 The System V Interface Definition (SVID) specifies that various
37 math functions should invoke a function called
38 .BR matherr ()
39 if a math exception is detected.
40 This function is called before the math function returns;
41 after
42 .BR matherr ()
43 returns, the system then returns to the math function,
44 which in turn returns to the caller.
45 .P
46 To employ
47 .BR matherr (),
48 the programmer must define the
49 .B _SVID_SOURCE
50 feature test macro
51 (before including
52 .I any
53 header files),
54 and assign the value
55 .B _SVID_
56 to the external variable
57 .BR _LIB_VERSION .
58 .P
59 The system provides a default version of
60 .BR matherr ().
61 This version does nothing, and returns zero
62 (see below for the significance of this).
63 The default
64 .BR matherr ()
65 can be overridden by a programmer-defined
66 version, which will be invoked when an exception occurs.
67 The function is invoked with one argument, a pointer to an
68 .I exception
69 structure, defined as follows:
70 .P
71 .in +4n
72 .EX
73 struct exception {
74 int type; /* Exception type */
75 char *name; /* Name of function causing exception */
76 double arg1; /* 1st argument to function */
77 double arg2; /* 2nd argument to function */
78 double retval; /* Function return value */
79 }
80 .EE
81 .in
82 .P
83 The
84 .I type
85 field has one of the following values:
86 .TP 12
87 .B DOMAIN
88 A domain error occurred (the function argument was outside the range
89 for which the function is defined).
90 The return value depends on the function;
91 .I errno
92 is set to
93 .BR EDOM .
94 .TP
95 .B SING
96 A pole error occurred (the function result is an infinity).
97 The return value in most cases is
98 .B HUGE
99 (the largest single precision floating-point number),
100 appropriately signed.
101 In most cases,
102 .I errno
103 is set to
104 .BR EDOM .
105 .TP
106 .B OVERFLOW
107 An overflow occurred.
108 In most cases, the value
109 .B HUGE
110 is returned, and
111 .I errno
112 is set to
113 .BR ERANGE .
114 .TP
115 .B UNDERFLOW
116 An underflow occurred.
117 0.0 is returned, and
118 .I errno
119 is set to
120 .BR ERANGE .
121 .TP
122 .B TLOSS
123 Total loss of significance.
124 0.0 is returned, and
125 .I errno
126 is set to
127 .BR ERANGE .
128 .TP
129 .B PLOSS
130 Partial loss of significance.
131 This value is unused on glibc
132 (and many other systems).
133 .P
134 The
135 .I arg1
136 and
137 .I arg2
138 fields are the arguments supplied to the function
139 .RI ( arg2
140 is undefined for functions that take only one argument).
141 .P
142 The
143 .I retval
144 field specifies the return value that the math
145 function will return to its caller.
146 The programmer-defined
147 .BR matherr ()
148 can modify this field to change the return value of the math function.
149 .P
150 If the
151 .BR matherr ()
152 function returns zero, then the system sets
153 .I errno
154 as described above, and may print an error message on standard error
155 (see below).
156 .P
157 If the
158 .BR matherr ()
159 function returns a nonzero value, then the system does not set
160 .IR errno ,
161 and doesn't print an error message.
162 .SS Math functions that employ matherr()
163 The table below lists the functions and circumstances in which
164 .BR matherr ()
165 is called.
166 The "Type" column indicates the value assigned to
167 .I exc\->type
168 when calling
169 .BR matherr ().
170 The "Result" column is the default return value assigned to
171 .IR exc\->retval .
172 .P
173 The "Msg?" and "errno" columns describe the default behavior if
174 .BR matherr ()
175 returns zero.
176 If the "Msg?" columns contains "y",
177 then the system prints an error message on standard error.
178 .P
179 The table uses the following notations and abbreviations:
180 .P
181 .RS
182 .TS
183 l l.
184 x first argument to function
185 y second argument to function
186 fin finite value for argument
187 neg negative value for argument
188 int integral value for argument
189 o/f result overflowed
190 u/f result underflowed
191 |x| absolute value of x
192 X_TLOSS is a constant defined in \fI<math.h>\fP
193 .TE
194 .RE
195 .\" Details below from glibc 2.8's sysdeps/ieee754/k_standard.c
196 .\" A subset of cases were test by experimental programs.
197 .TS
198 lB lB lB cB lB
199 l l l c l.
200 Function Type Result Msg? errno
201 acos(|x|>1) DOMAIN HUGE y EDOM
202 asin(|x|>1) DOMAIN HUGE y EDOM
203 atan2(0,0) DOMAIN HUGE y EDOM
204 acosh(x<1) DOMAIN NAN y EDOM \" retval is 0.0/0.0
205 atanh(|x|>1) DOMAIN NAN y EDOM \" retval is 0.0/0.0
206 atanh(|x|==1) SING (x>0.0)? y EDOM \" retval is x/0.0
207 \ \ HUGE_VAL :
208 \ \ \-HUGE_VAL
209 cosh(fin) o/f OVERFLOW HUGE n ERANGE
210 sinh(fin) o/f OVERFLOW (x>0.0) ? n ERANGE
211 \ \ HUGE : \-HUGE
212 sqrt(x<0) DOMAIN 0.0 y EDOM
213 hypot(fin,fin) o/f OVERFLOW HUGE n ERANGE
214 exp(fin) o/f OVERFLOW HUGE n ERANGE
215 exp(fin) u/f UNDERFLOW 0.0 n ERANGE
216 exp2(fin) o/f OVERFLOW HUGE n ERANGE
217 exp2(fin) u/f UNDERFLOW 0.0 n ERANGE
218 exp10(fin) o/f OVERFLOW HUGE n ERANGE
219 exp10(fin) u/f UNDERFLOW 0.0 n ERANGE
220 j0(|x|>X_TLOSS) TLOSS 0.0 y ERANGE
221 j1(|x|>X_TLOSS) TLOSS 0.0 y ERANGE
222 jn(|x|>X_TLOSS) TLOSS 0.0 y ERANGE
223 y0(x>X_TLOSS) TLOSS 0.0 y ERANGE
224 y1(x>X_TLOSS) TLOSS 0.0 y ERANGE
225 yn(x>X_TLOSS) TLOSS 0.0 y ERANGE
226 y0(0) DOMAIN \-HUGE y EDOM
227 y0(x<0) DOMAIN \-HUGE y EDOM
228 y1(0) DOMAIN \-HUGE y EDOM
229 y1(x<0) DOMAIN \-HUGE y EDOM
230 yn(n,0) DOMAIN \-HUGE y EDOM
231 yn(x<0) DOMAIN \-HUGE y EDOM
232 lgamma(fin) o/f OVERFLOW HUGE n ERANGE
233 lgamma(\-int) or SING HUGE y EDOM
234 \ \ lgamma(0)
235 tgamma(fin) o/f OVERFLOW HUGE_VAL n ERANGE
236 tgamma(\-int) SING NAN y EDOM
237 tgamma(0) SING copysign( y ERANGE
238 \ \ HUGE_VAL,x)
239 log(0) SING \-HUGE y EDOM
240 log(x<0) DOMAIN \-HUGE y EDOM
241 log2(0) SING \-HUGE n EDOM \" different from log()
242 log2(x<0) DOMAIN \-HUGE n EDOM \" different from log()
243 log10(0) SING \-HUGE y EDOM
244 log10(x<0) DOMAIN \-HUGE y EDOM
245 pow(0.0,0.0) DOMAIN 0.0 y EDOM
246 pow(x,y) o/f OVERFLOW HUGE n ERANGE
247 pow(x,y) u/f UNDERFLOW 0.0 n ERANGE
248 pow(NaN,0.0) DOMAIN x n EDOM
249 0**neg DOMAIN 0.0 y EDOM \" +0 and -0
250 neg**non-int DOMAIN 0.0 y EDOM
251 scalb() o/f OVERFLOW (x>0.0) ? n ERANGE
252 \ \ HUGE_VAL :
253 \ \ \-HUGE_VAL
254 scalb() u/f UNDERFLOW copysign( n ERANGE
255 \ \ \ \ 0.0,x)
256 fmod(x,0) DOMAIN x y EDOM
257 remainder(x,0) DOMAIN NAN y EDOM \" retval is 0.0/0.0
258 .TE
259 .SH ATTRIBUTES
260 For an explanation of the terms used in this section, see
261 .BR attributes (7).
262 .TS
263 allbox;
264 lbx lb lb
265 l l l.
266 Interface Attribute Value
267 T{
268 .na
269 .nh
270 .BR matherr ()
271 T} Thread safety MT-Safe
272 .TE
273 .SH EXAMPLES
274 The example program demonstrates the use of
275 .BR matherr ()
276 when calling
277 .BR log (3).
278 The program takes up to three command-line arguments.
279 The first argument is the floating-point number to be given to
280 .BR log (3).
281 If the optional second argument is provided, then
282 .B _LIB_VERSION
283 is set to
284 .B _SVID_
285 so that
286 .BR matherr ()
287 is called, and the integer supplied in the
288 command-line argument is used as the return value from
289 .BR matherr ().
290 If the optional third command-line argument is supplied,
291 then it specifies an alternative return value that
292 .BR matherr ()
293 should assign as the return value of the math function.
294 .P
295 The following example run, where
296 .BR log (3)
297 is given an argument of 0.0, does not use
298 .BR matherr ():
299 .P
300 .in +4n
301 .EX
302 .RB "$" " ./a.out 0.0"
303 errno: Numerical result out of range
304 x=\-inf
305 .EE
306 .in
307 .P
308 In the following run,
309 .BR matherr ()
310 is called, and returns 0:
311 .P
312 .in +4n
313 .EX
314 .RB "$" " ./a.out 0.0 0"
315 matherr SING exception in log() function
316 args: 0.000000, 0.000000
317 retval: \-340282346638528859811704183484516925440.000000
318 log: SING error
319 errno: Numerical argument out of domain
320 x=\-340282346638528859811704183484516925440.000000
321 .EE
322 .in
323 .P
324 The message "log: SING error" was printed by the C library.
325 .P
326 In the following run,
327 .BR matherr ()
328 is called, and returns a nonzero value:
329 .P
330 .in +4n
331 .EX
332 .RB "$" " ./a.out 0.0 1"
333 matherr SING exception in log() function
334 args: 0.000000, 0.000000
335 retval: \-340282346638528859811704183484516925440.000000
336 x=\-340282346638528859811704183484516925440.000000
337 .EE
338 .in
339 .P
340 In this case, the C library did not print a message, and
341 .I errno
342 was not set.
343 .P
344 In the following run,
345 .BR matherr ()
346 is called, changes the return value of the math function,
347 and returns a nonzero value:
348 .P
349 .in +4n
350 .EX
351 .RB "$" " ./a.out 0.0 1 12345.0"
352 matherr SING exception in log() function
353 args: 0.000000, 0.000000
354 retval: \-340282346638528859811704183484516925440.000000
355 x=12345.000000
356 .EE
357 .in
358 .SS Program source
359 \&
360 .\" SRC BEGIN (matherr.c)
361 .EX
362 #define _SVID_SOURCE
363 #include <errno.h>
364 #include <math.h>
365 #include <stdio.h>
366 #include <stdlib.h>
367 \&
368 static int matherr_ret = 0; /* Value that matherr()
369 should return */
370 static int change_retval = 0; /* Should matherr() change
371 function\[aq]s return value? */
372 static double new_retval; /* New function return value */
373 \&
374 int
375 matherr(struct exception *exc)
376 {
377 fprintf(stderr, "matherr %s exception in %s() function\en",
378 (exc\->type == DOMAIN) ? "DOMAIN" :
379 (exc\->type == OVERFLOW) ? "OVERFLOW" :
380 (exc\->type == UNDERFLOW) ? "UNDERFLOW" :
381 (exc\->type == SING) ? "SING" :
382 (exc\->type == TLOSS) ? "TLOSS" :
383 (exc\->type == PLOSS) ? "PLOSS" : "???",
384 exc\->name);
385 fprintf(stderr, " args: %f, %f\en",
386 exc\->arg1, exc\->arg2);
387 fprintf(stderr, " retval: %f\en", exc\->retval);
388 \&
389 if (change_retval)
390 exc\->retval = new_retval;
391 \&
392 return matherr_ret;
393 }
394 \&
395 int
396 main(int argc, char *argv[])
397 {
398 double x;
399 \&
400 if (argc < 2) {
401 fprintf(stderr, "Usage: %s <argval>"
402 " [<matherr\-ret> [<new\-func\-retval>]]\en", argv[0]);
403 exit(EXIT_FAILURE);
404 }
405 \&
406 if (argc > 2) {
407 _LIB_VERSION = _SVID_;
408 matherr_ret = atoi(argv[2]);
409 }
410 \&
411 if (argc > 3) {
412 change_retval = 1;
413 new_retval = atof(argv[3]);
414 }
415 \&
416 x = log(atof(argv[1]));
417 if (errno != 0)
418 perror("errno");
419 \&
420 printf("x=%f\en", x);
421 exit(EXIT_SUCCESS);
422 }
423 .EE
424 .\" SRC END
425 .SH SEE ALSO
426 .BR fenv (3),
427 .BR math_error (7),
428 .BR standards (7)