From 7f3caba522f4d24764f29d83aa2de9198bb7f01c Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 24 May 2024 06:52:22 +0200 Subject: Adding upstream version 6.8. Signed-off-by: Daniel Baumann --- man3/matherr.3 | 428 --------------------------------------------------------- 1 file changed, 428 deletions(-) delete mode 100644 man3/matherr.3 (limited to 'man3/matherr.3') diff --git a/man3/matherr.3 b/man3/matherr.3 deleted file mode 100644 index 351baf5..0000000 --- a/man3/matherr.3 +++ /dev/null @@ -1,428 +0,0 @@ -'\" t -.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk -.\" -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH matherr 3 2024-02-26 "Linux man-pages 6.7" -.SH NAME -matherr \- SVID math library exception handling -.SH LIBRARY -Math library -.RI ( libm ", " \-lm ) -.SH SYNOPSIS -.nf -.B #include -.P -.BI "[[deprecated]] int matherr(struct exception *" exc ); -.P -.B [[deprecated]] extern _LIB_VERSION_TYPE _LIB_VERSION; -.fi -.SH DESCRIPTION -.IR Note : -the mechanism described in this page is no longer supported by glibc. -Before glibc 2.27, it had been marked as obsolete. -Since glibc 2.27, -.\" glibc commit 813378e9fe17e029caf627cab76fe23eb46815fa -the mechanism has been removed altogether. -New applications should use the techniques described in -.BR math_error (7) -and -.BR fenv (3). -This page documents the -.BR matherr () -mechanism as an aid for maintaining and porting older applications. -.P -The System V Interface Definition (SVID) specifies that various -math functions should invoke a function called -.BR matherr () -if a math exception is detected. -This function is called before the math function returns; -after -.BR matherr () -returns, the system then returns to the math function, -which in turn returns to the caller. -.P -To employ -.BR matherr (), -the programmer must define the -.B _SVID_SOURCE -feature test macro -(before including -.I any -header files), -and assign the value -.B _SVID_ -to the external variable -.BR _LIB_VERSION . -.P -The system provides a default version of -.BR matherr (). -This version does nothing, and returns zero -(see below for the significance of this). -The default -.BR matherr () -can be overridden by a programmer-defined -version, which will be invoked when an exception occurs. -The function is invoked with one argument, a pointer to an -.I exception -structure, defined as follows: -.P -.in +4n -.EX -struct exception { - int type; /* Exception type */ - char *name; /* Name of function causing exception */ - double arg1; /* 1st argument to function */ - double arg2; /* 2nd argument to function */ - double retval; /* Function return value */ -} -.EE -.in -.P -The -.I type -field has one of the following values: -.TP 12 -.B DOMAIN -A domain error occurred (the function argument was outside the range -for which the function is defined). -The return value depends on the function; -.I errno -is set to -.BR EDOM . -.TP -.B SING -A pole error occurred (the function result is an infinity). -The return value in most cases is -.B HUGE -(the largest single precision floating-point number), -appropriately signed. -In most cases, -.I errno -is set to -.BR EDOM . -.TP -.B OVERFLOW -An overflow occurred. -In most cases, the value -.B HUGE -is returned, and -.I errno -is set to -.BR ERANGE . -.TP -.B UNDERFLOW -An underflow occurred. -0.0 is returned, and -.I errno -is set to -.BR ERANGE . -.TP -.B TLOSS -Total loss of significance. -0.0 is returned, and -.I errno -is set to -.BR ERANGE . -.TP -.B PLOSS -Partial loss of significance. -This value is unused on glibc -(and many other systems). -.P -The -.I arg1 -and -.I arg2 -fields are the arguments supplied to the function -.RI ( arg2 -is undefined for functions that take only one argument). -.P -The -.I retval -field specifies the return value that the math -function will return to its caller. -The programmer-defined -.BR matherr () -can modify this field to change the return value of the math function. -.P -If the -.BR matherr () -function returns zero, then the system sets -.I errno -as described above, and may print an error message on standard error -(see below). -.P -If the -.BR matherr () -function returns a nonzero value, then the system does not set -.IR errno , -and doesn't print an error message. -.SS Math functions that employ matherr() -The table below lists the functions and circumstances in which -.BR matherr () -is called. -The "Type" column indicates the value assigned to -.I exc\->type -when calling -.BR matherr (). -The "Result" column is the default return value assigned to -.IR exc\->retval . -.P -The "Msg?" and "errno" columns describe the default behavior if -.BR matherr () -returns zero. -If the "Msg?" columns contains "y", -then the system prints an error message on standard error. -.P -The table uses the following notations and abbreviations: -.P -.RS -.TS -l l. -x first argument to function -y second argument to function -fin finite value for argument -neg negative value for argument -int integral value for argument -o/f result overflowed -u/f result underflowed -|x| absolute value of x -X_TLOSS is a constant defined in \fI\fP -.TE -.RE -.\" Details below from glibc 2.8's sysdeps/ieee754/k_standard.c -.\" A subset of cases were test by experimental programs. -.TS -lB lB lB cB lB -l l l c l. -Function Type Result Msg? errno -acos(|x|>1) DOMAIN HUGE y EDOM -asin(|x|>1) DOMAIN HUGE y EDOM -atan2(0,0) DOMAIN HUGE y EDOM -acosh(x<1) DOMAIN NAN y EDOM \" retval is 0.0/0.0 -atanh(|x|>1) DOMAIN NAN y EDOM \" retval is 0.0/0.0 -atanh(|x|==1) SING (x>0.0)? y EDOM \" retval is x/0.0 -\ \ HUGE_VAL : -\ \ \-HUGE_VAL -cosh(fin) o/f OVERFLOW HUGE n ERANGE -sinh(fin) o/f OVERFLOW (x>0.0) ? n ERANGE -\ \ HUGE : \-HUGE -sqrt(x<0) DOMAIN 0.0 y EDOM -hypot(fin,fin) o/f OVERFLOW HUGE n ERANGE -exp(fin) o/f OVERFLOW HUGE n ERANGE -exp(fin) u/f UNDERFLOW 0.0 n ERANGE -exp2(fin) o/f OVERFLOW HUGE n ERANGE -exp2(fin) u/f UNDERFLOW 0.0 n ERANGE -exp10(fin) o/f OVERFLOW HUGE n ERANGE -exp10(fin) u/f UNDERFLOW 0.0 n ERANGE -j0(|x|>X_TLOSS) TLOSS 0.0 y ERANGE -j1(|x|>X_TLOSS) TLOSS 0.0 y ERANGE -jn(|x|>X_TLOSS) TLOSS 0.0 y ERANGE -y0(x>X_TLOSS) TLOSS 0.0 y ERANGE -y1(x>X_TLOSS) TLOSS 0.0 y ERANGE -yn(x>X_TLOSS) TLOSS 0.0 y ERANGE -y0(0) DOMAIN \-HUGE y EDOM -y0(x<0) DOMAIN \-HUGE y EDOM -y1(0) DOMAIN \-HUGE y EDOM -y1(x<0) DOMAIN \-HUGE y EDOM -yn(n,0) DOMAIN \-HUGE y EDOM -yn(x<0) DOMAIN \-HUGE y EDOM -lgamma(fin) o/f OVERFLOW HUGE n ERANGE -lgamma(\-int) or SING HUGE y EDOM -\ \ lgamma(0) -tgamma(fin) o/f OVERFLOW HUGE_VAL n ERANGE -tgamma(\-int) SING NAN y EDOM -tgamma(0) SING copysign( y ERANGE -\ \ HUGE_VAL,x) -log(0) SING \-HUGE y EDOM -log(x<0) DOMAIN \-HUGE y EDOM -log2(0) SING \-HUGE n EDOM \" different from log() -log2(x<0) DOMAIN \-HUGE n EDOM \" different from log() -log10(0) SING \-HUGE y EDOM -log10(x<0) DOMAIN \-HUGE y EDOM -pow(0.0,0.0) DOMAIN 0.0 y EDOM -pow(x,y) o/f OVERFLOW HUGE n ERANGE -pow(x,y) u/f UNDERFLOW 0.0 n ERANGE -pow(NaN,0.0) DOMAIN x n EDOM -0**neg DOMAIN 0.0 y EDOM \" +0 and -0 -neg**non-int DOMAIN 0.0 y EDOM -scalb() o/f OVERFLOW (x>0.0) ? n ERANGE -\ \ HUGE_VAL : -\ \ \-HUGE_VAL -scalb() u/f UNDERFLOW copysign( n ERANGE -\ \ \ \ 0.0,x) -fmod(x,0) DOMAIN x y EDOM -remainder(x,0) DOMAIN NAN y EDOM \" retval is 0.0/0.0 -.TE -.SH ATTRIBUTES -For an explanation of the terms used in this section, see -.BR attributes (7). -.TS -allbox; -lbx lb lb -l l l. -Interface Attribute Value -T{ -.na -.nh -.BR matherr () -T} Thread safety MT-Safe -.TE -.SH EXAMPLES -The example program demonstrates the use of -.BR matherr () -when calling -.BR log (3). -The program takes up to three command-line arguments. -The first argument is the floating-point number to be given to -.BR log (3). -If the optional second argument is provided, then -.B _LIB_VERSION -is set to -.B _SVID_ -so that -.BR matherr () -is called, and the integer supplied in the -command-line argument is used as the return value from -.BR matherr (). -If the optional third command-line argument is supplied, -then it specifies an alternative return value that -.BR matherr () -should assign as the return value of the math function. -.P -The following example run, where -.BR log (3) -is given an argument of 0.0, does not use -.BR matherr (): -.P -.in +4n -.EX -.RB "$" " ./a.out 0.0" -errno: Numerical result out of range -x=\-inf -.EE -.in -.P -In the following run, -.BR matherr () -is called, and returns 0: -.P -.in +4n -.EX -.RB "$" " ./a.out 0.0 0" -matherr SING exception in log() function - args: 0.000000, 0.000000 - retval: \-340282346638528859811704183484516925440.000000 -log: SING error -errno: Numerical argument out of domain -x=\-340282346638528859811704183484516925440.000000 -.EE -.in -.P -The message "log: SING error" was printed by the C library. -.P -In the following run, -.BR matherr () -is called, and returns a nonzero value: -.P -.in +4n -.EX -.RB "$" " ./a.out 0.0 1" -matherr SING exception in log() function - args: 0.000000, 0.000000 - retval: \-340282346638528859811704183484516925440.000000 -x=\-340282346638528859811704183484516925440.000000 -.EE -.in -.P -In this case, the C library did not print a message, and -.I errno -was not set. -.P -In the following run, -.BR matherr () -is called, changes the return value of the math function, -and returns a nonzero value: -.P -.in +4n -.EX -.RB "$" " ./a.out 0.0 1 12345.0" -matherr SING exception in log() function - args: 0.000000, 0.000000 - retval: \-340282346638528859811704183484516925440.000000 -x=12345.000000 -.EE -.in -.SS Program source -\& -.\" SRC BEGIN (matherr.c) -.EX -#define _SVID_SOURCE -#include -#include -#include -#include -\& -static int matherr_ret = 0; /* Value that matherr() - should return */ -static int change_retval = 0; /* Should matherr() change - function\[aq]s return value? */ -static double new_retval; /* New function return value */ -\& -int -matherr(struct exception *exc) -{ - fprintf(stderr, "matherr %s exception in %s() function\en", - (exc\->type == DOMAIN) ? "DOMAIN" : - (exc\->type == OVERFLOW) ? "OVERFLOW" : - (exc\->type == UNDERFLOW) ? "UNDERFLOW" : - (exc\->type == SING) ? "SING" : - (exc\->type == TLOSS) ? "TLOSS" : - (exc\->type == PLOSS) ? "PLOSS" : "???", - exc\->name); - fprintf(stderr, " args: %f, %f\en", - exc\->arg1, exc\->arg2); - fprintf(stderr, " retval: %f\en", exc\->retval); -\& - if (change_retval) - exc\->retval = new_retval; -\& - return matherr_ret; -} -\& -int -main(int argc, char *argv[]) -{ - double x; -\& - if (argc < 2) { - fprintf(stderr, "Usage: %s " - " [ []]\en", argv[0]); - exit(EXIT_FAILURE); - } -\& - if (argc > 2) { - _LIB_VERSION = _SVID_; - matherr_ret = atoi(argv[2]); - } -\& - if (argc > 3) { - change_retval = 1; - new_retval = atof(argv[3]); - } -\& - x = log(atof(argv[1])); - if (errno != 0) - perror("errno"); -\& - printf("x=%f\en", x); - exit(EXIT_SUCCESS); -} -.EE -.\" SRC END -.SH SEE ALSO -.BR fenv (3), -.BR math_error (7), -.BR standards (7) -- cgit v1.2.3