Debian Codegraph @

upstream/debian-unstable/man3/matherr.3

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