[unix-history] / usr / src / lib / libm / common_source / infnan.3

.\" Copyright (c) 1985, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)infnan.3	8.1 (Berkeley) %G%
.\"
.Dd 
.Dt INFNAN 3
.Os BSD 4.3
.Sh NAME
.Nm infnan
.Nd signals invalid floating\-point operations on a
.Tn VAX
(temporary)
.Sh SYNOPSIS
.Fd #include <math.h>
.Ft double 
.Fn infnan "int iarg"
.Sh DESCRIPTION
At some time in the future, some of the useful properties of
the Infinities and \*(Nas in the
.Tn IEEE
standard 754 for Binary
Floating\-Point Arithmetic will be simulated in
.Tn UNIX
on the
.Tn DEC VAX
by using its Reserved Operands.  Meanwhile, the
Invalid, Overflow and Divide\-by\-Zero exceptions of the
.Tn IEEE
standard are being approximated on a
.Tn VAX
by calls to a
procedure
.Fn infnan
in appropriate places in
.Xr libm 3 .
When
better exception\-handling is implemented in
.Tn UNIX , 
only
.Fn infnan
among the codes in
.Xr libm
will have to be changed.
And users of
.Xr libm
can design their own
.Fn infnan
now to
insulate themselves from future changes.
.Pp
Whenever an elementary function code in
.Xr libm
has to
simulate one of the aforementioned
.Tn IEEE
exceptions, it calls
.Fn infnan iarg
with an appropriate value of
.Fa iarg .
Then a
reserved operand fault stops computation.  But
.Fn infnan
could
be replaced by a function with the same name that returns
some plausible value, assigns an apt value to the global
variable
.Va errno ,
and allows computation to resume.
Alternatively, the Reserved Operand Fault Handler could be
changed to respond by returning that plausible value, etc.
instead of aborting.
.Pp
In the table below, the first two columns show various
exceptions signaled by the
.Tn IEEE
standard, and the default
result it prescribes.  The third column shows what value is
given to
.Fa iarg
by functions in
.Xr libm
when they
invoke
.Fn infnan iarg
under analogous circumstances on a
.Tn VAX . 
Currently
.Fn infnan
stops computation under all those
circumstances.  The last two columns offer an alternative;
they suggest a setting for
.Va errno
and a value for a
revised
.Fn infnan
to return.  And a C program to
implement that suggestion follows. 
.sp 0.5
.Bd -filled -offset indent
.Bl -column "IEEE Signal" "IEEE Default" XXERANGE ERANGEXXorXXEDOM
.It IEEE Signal	IEEE Default Ta
.Fa iarg Ta
.Va errno Ta
.Fn infnan
.It Invalid	\*(Na Ta
.Dv EDOM	EDOM	0
.It Overflow	\(+-\*(If Ta
.Dv ERANGE	ERANGE	HUGE
.It Div\-by\-0	\(+-Infinity Ta
.Dv \(+-ERANGE	ERANGE or EDOM	\(+-HUGE
.It 	( Ns Dv HUGE No "= 1.7e38 ... nearly  2.0**127)"
.El
.Ed
.Pp
ALTERNATIVE
.Fn infnan :
.Bd -literal -offset indent
#include	<math.h>
#include	<errno.h>
extern int	errno ;
double	infnan(iarg)
int	iarg ;
{
	switch(iarg) {
	case	\0ERANGE:	errno = ERANGE; return(HUGE);
	case	\-ERANGE:	errno = EDOM;	return(\-HUGE);
	default:		errno = EDOM;	return(0);
	}
}
.Ed
.Sh SEE ALSO
.Xr math 3 ,
.Xr intro 2 ,
.Xr signal 3 .
.Pp
.Dv ERANGE
and
.Dv EDOM
are defined in
.Aq Pa errno.h .
(See
.Xr intro 2
for explanation of
.Dv EDOM
and
.Dv ERANGE . )
.Sh HISTORY
The
.Fn infnan
function appeared in 
.Bx 4.3 .
Commit	Line	Data
c3d39550 KB	1	.\" Copyright (c) 1985, 1991, 1993
c3d39550 KB	2	.\" The Regents of the University of California. All rights reserved.
f9628029	3	.\"
ae59e04c	4	.\" %sccs.include.redist.man%
f9628029	5	.\"
c3d39550	6	.\" @(#)infnan.3 8.1 (Berkeley) %G%
ae59e04c CL	7	.\"
	8	.Dd
	9	.Dt INFNAN 3
	10	.Os BSD 4.3
	11	.Sh NAME
	12	.Nm infnan
	13	.Nd signals invalid floating\-point operations on a
	14	.Tn VAX
	15	(temporary)
	16	.Sh SYNOPSIS
	17	.Fd #include <math.h>
	18	.Ft double
	19	.Fn infnan "int iarg"
	20	.Sh DESCRIPTION
bacd7cb7	21	At some time in the future, some of the useful properties of
ae59e04c CL	22	the Infinities and \*(Nas in the
	23	.Tn IEEE
	24	standard 754 for Binary
	25	Floating\-Point Arithmetic will be simulated in
	26	.Tn UNIX
	27	on the
	28	.Tn DEC VAX
	29	by using its Reserved Operands. Meanwhile, the
bacd7cb7	30	Invalid, Overflow and Divide\-by\-Zero exceptions of the
ae59e04c CL	31	.Tn IEEE
	32	standard are being approximated on a
	33	.Tn VAX
	34	by calls to a
	35	procedure
	36	.Fn infnan
	37	in appropriate places in
	38	.Xr libm 3 .
	39	When
	40	better exception\-handling is implemented in
	41	.Tn UNIX ,
	42	only
	43	.Fn infnan
	44	among the codes in
	45	.Xr libm
	46	will have to be changed.
	47	And users of
	48	.Xr libm
	49	can design their own
	50	.Fn infnan
	51	now to
bacd7cb7	52	insulate themselves from future changes.
ae59e04c CL	53	.Pp
	54	Whenever an elementary function code in
	55	.Xr libm
	56	has to
	57	simulate one of the aforementioned
	58	.Tn IEEE
	59	exceptions, it calls
	60	.Fn infnan iarg
	61	with an appropriate value of
	62	.Fa iarg .
	63	Then a
	64	reserved operand fault stops computation. But
	65	.Fn infnan
	66	could
bacd7cb7 MAN	67	be replaced by a function with the same name that returns
bacd7cb7 MAN	68	some plausible value, assigns an apt value to the global
ae59e04c CL	69	variable
	70	.Va errno ,
	71	and allows computation to resume.
bacd7cb7	72	Alternatively, the Reserved Operand Fault Handler could be
875ee27b	73	changed to respond by returning that plausible value, etc.
bacd7cb7	74	instead of aborting.
ae59e04c	75	.Pp
bacd7cb7	76	In the table below, the first two columns show various
ae59e04c CL	77	exceptions signaled by the
	78	.Tn IEEE
	79	standard, and the default
bacd7cb7	80	result it prescribes. The third column shows what value is
ae59e04c CL	81	given to
	82	.Fa iarg
	83	by functions in
	84	.Xr libm
	85	when they
	86	invoke
	87	.Fn infnan iarg
	88	under analogous circumstances on a
	89	.Tn VAX .
	90	Currently
	91	.Fn infnan
	92	stops computation under all those
bacd7cb7	93	circumstances. The last two columns offer an alternative;
ae59e04c CL	94	they suggest a setting for
	95	.Va errno
	96	and a value for a
	97	revised
	98	.Fn infnan
	99	to return. And a C program to
bacd7cb7 MAN	100	implement that suggestion follows.
bacd7cb7 MAN	101	.sp 0.5
ae59e04c CL	102	.Bd -filled -offset indent
	103	.Bl -column "IEEE Signal" "IEEE Default" XXERANGE ERANGEXXorXXEDOM
	104	.It IEEE Signal IEEE Default Ta
	105	.Fa iarg Ta
	106	.Va errno Ta
	107	.Fn infnan
	108	.It Invalid \*(Na Ta
	109	.Dv EDOM EDOM 0
	110	.It Overflow \(+-\*(If Ta
	111	.Dv ERANGE ERANGE HUGE
	112	.It Div\-by\-0 \(+-Infinity Ta
	113	.Dv \(+-ERANGE ERANGE or EDOM \(+-HUGE
	114	.It ( Ns Dv HUGE No "= 1.7e38 ... nearly 2.0**127)"
	115	.El
	116	.Ed
	117	.Pp
	118	ALTERNATIVE
	119	.Fn infnan :
	120	.Bd -literal -offset indent
bacd7cb7 MAN	121	#include <math.h>
	122	#include <errno.h>
	123	extern int errno ;
	124	double infnan(iarg)
	125	int iarg ;
	126	{
	127	switch(iarg) {
ae59e04c	128	case \0ERANGE: errno = ERANGE; return(HUGE);
bacd7cb7 MAN	129	case \-ERANGE: errno = EDOM; return(\-HUGE);
	130	default: errno = EDOM; return(0);
	131	}
ae59e04c CL	132	}
	133	.Ed
	134	.Sh SEE ALSO
	135	.Xr math 3 ,
	136	.Xr intro 2 ,
	137	.Xr signal 3 .
	138	.Pp
	139	.Dv ERANGE
	140	and
	141	.Dv EDOM
	142	are defined in
	143	.Aq Pa errno.h .
	144	(See
	145	.Xr intro 2
	146	for explanation of
	147	.Dv EDOM
	148	and
	149	.Dv ERANGE . )
	150	.Sh HISTORY
	151	The
	152	.Fn infnan
	153	function appeared in
	154	.Bx 4.3 .