[dragonfly.git] / share / man / man3 / fpgetround.3

.\" Copyright (c) 1993 Andrew Moore, Talke Studio
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)fpgetround.3	1.0 (Berkeley) 9/23/93
.\" $FreeBSD: src/share/man/man3/fpgetround.3,v 1.15 2005/07/15 17:35:25 hrs Exp $
.\" $DragonFly: src/share/man/man3/fpgetround.3,v 1.4 2008/05/02 02:05:05 swildner Exp $
.\"
.Dd April 23, 2009
.Dt FPGETROUND 3
.Os
.Sh NAME
.Nm fpgetround ,
.Nm fpsetround ,
.Nm fpsetprec ,
.Nm fpgetprec ,
.Nm fpgetmask ,
.Nm fpsetmask ,
.Nm fpgetsticky ,
.Nm fpsetsticky ,
.Nm fpresetsticky
.Nd IEEE floating point interface
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In ieeefp.h
.Bd -literal
typedef enum {
	FP_RN,		/* round to nearest */
	FP_RM,		/* round down to minus infinity */
	FP_RP,		/* round up to plus infinity */
	FP_RZ		/* truncate */
} fp_rnd_t;
.Ed
.Ft fp_rnd_t
.Fn fpgetround void
.Ft fp_rnd_t
.Fn fpsetround "fp_rnd_t direction"
.Bd -literal
typedef enum {
	FP_PS,		/* 24 bit (single-precision) */
	FP_PRS,		/* reserved */
	FP_PD,		/* 53 bit (double-precision) */
	FP_PE		/* 64 bit (extended-precision) */
} fp_prec_t;
.Ed
.Ft fp_prec_t
.Fn fpgetprec void
.Ft fp_prec_t
.Fn fpsetprec "fp_prec_t precision"
.Bd -literal
#define fp_except_t	int
#define FP_X_INV	0x01	/* invalid operation */
#define FP_X_DNML	0x02	/* denormal */
#define FP_X_DZ		0x04	/* zero divide */
#define FP_X_OFL	0x08	/* overflow */
#define FP_X_UFL	0x10	/* underflow */
#define FP_X_IMP	0x20	/* (im)precision */
#define FP_X_STK	0x40	/* stack fault */
.Ed
.Ft fp_except_t
.Fn fpgetmask void
.Ft fp_except_t
.Fn fpsetmask "fp_except_t mask"
.Ft fp_except_t
.Fn fpgetsticky void
.Ft fp_except_t
.Fn fpsetsticky "fp_except_t sticky"
.Ft fp_except_t
.Fn fpresetsticky "fp_except_t sticky"
.Sh DESCRIPTION
The routines described herein are deprecated.
New code should use the functionality provided by
.Xr fenv 3 .
.Pp
When a floating point exception is detected, the exception sticky flag is
set and the exception mask is tested.
If the mask is set, then a trap occurs.
These routines allow both setting the floating point exception
masks, and resetting the exception sticky flags after an exception is
detected.
In addition, they allow setting the floating point rounding mode
and precision.
.Pp
The
.Fn fpgetround
function
returns the current floating point rounding mode.
.Pp
The
.Fn fpsetround
function
sets the floating point rounding mode and returns
the previous mode.
.Pp
The
.Fn fpgetprec
function
returns the current floating point precision.
.Pp
The
.Fn fpsetprec
function
sets the floating point precision and returns
the previous precision.
.Pp
The
.Fn fpgetmask
function
returns the current floating point exception masks.
.Pp
The
.Fn fpsetmask
function
sets the floating point exception masks and returns the
previous masks.
.Pp
The
.Fn fpgetsticky
function
returns the current floating point sticky flags.
.Pp
The
.Fn fpsetsticky
sets the floating point sticky flags and returns
the previous flags.
.Pp
The
.Fn fpresetsticky
function
clears the floating point sticky flags and returns
the previous flags.
.Pp
Sample code which prevents a trap on divide-by-zero:
.Bd -literal -offset indent
fpsetmask(~FP_X_DZ);
a = 1.0;
b = 0;
c = a / b;
fpresetsticky(FP_X_DZ);
fpsetmask(FP_X_DZ);
.Ed
.Sh IMPLEMENTATION NOTES
The
.Fn fpgetprec
and
.Fn fpsetprec
functions provide functionality unavailable on many platforms.
At present, they are implemented only on the i386 and x86_64 platforms.
.Sh SEE ALSO
.Xr fenv 3 ,
.Xr isnan 3
.Sh CAVEATS
After a floating point exception and before a mask is set, the sticky
flags must be reset.
If another exception occurs before the sticky
flags are reset, then a wrong exception type may be signaled.
.Sh HISTORY
These routines are based on SysV/386 routines of the same name.
Commit	Line	Data
984263bc MD	1	.\" Copyright (c) 1993 Andrew Moore, Talke Studio
	2	.\" All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\" 3. All advertising materials mentioning features or use of this software
	13	.\" must display the following acknowledgement:
	14	.\" This product includes software developed by the University of
	15	.\" California, Berkeley and its contributors.
	16	.\" 4. Neither the name of the University nor the names of its contributors
	17	.\" may be used to endorse or promote products derived from this software
	18	.\" without specific prior written permission.
	19	.\"
	20	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	21	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	22	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	23	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	24	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	25	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	26	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	27	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	28	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	30	.\" SUCH DAMAGE.
	31	.\"
	32	.\" @(#)fpgetround.3 1.0 (Berkeley) 9/23/93
13d93081	33	.\" $FreeBSD: src/share/man/man3/fpgetround.3,v 1.15 2005/07/15 17:35:25 hrs Exp $
8a7bdfea	34	.\" $DragonFly: src/share/man/man3/fpgetround.3,v 1.4 2008/05/02 02:05:05 swildner Exp $
984263bc	35	.\"
67956a9a	36	.Dd April 23, 2009
984263bc MD	37	.Dt FPGETROUND 3
	38	.Os
	39	.Sh NAME
	40	.Nm fpgetround ,
	41	.Nm fpsetround ,
	42	.Nm fpsetprec ,
	43	.Nm fpgetprec ,
	44	.Nm fpgetmask ,
	45	.Nm fpsetmask ,
	46	.Nm fpgetsticky ,
67956a9a	47	.Nm fpsetsticky ,
984263bc MD	48	.Nm fpresetsticky
984263bc MD	49	.Nd IEEE floating point interface
1bc160bc SW	50	.Sh LIBRARY
1bc160bc SW	51	.Lb libc
984263bc MD	52	.Sh SYNOPSIS
984263bc MD	53	.In ieeefp.h
984263bc MD	54	.Bd -literal
	55	typedef enum {
	56	FP_RN, /* round to nearest */
	57	FP_RM, /* round down to minus infinity */
	58	FP_RP, /* round up to plus infinity */
	59	FP_RZ /* truncate */
	60	} fp_rnd_t;
	61	.Ed
	62	.Ft fp_rnd_t
	63	.Fn fpgetround void
	64	.Ft fp_rnd_t
	65	.Fn fpsetround "fp_rnd_t direction"
984263bc MD	66	.Bd -literal
	67	typedef enum {
	68	FP_PS, /* 24 bit (single-precision) */
	69	FP_PRS, /* reserved */
	70	FP_PD, /* 53 bit (double-precision) */
	71	FP_PE /* 64 bit (extended-precision) */
	72	} fp_prec_t;
	73	.Ed
	74	.Ft fp_prec_t
	75	.Fn fpgetprec void
	76	.Ft fp_prec_t
	77	.Fn fpsetprec "fp_prec_t precision"
984263bc MD	78	.Bd -literal
	79	#define fp_except_t int
	80	#define FP_X_INV 0x01 /* invalid operation */
	81	#define FP_X_DNML 0x02 /* denormal */
	82	#define FP_X_DZ 0x04 /* zero divide */
	83	#define FP_X_OFL 0x08 /* overflow */
	84	#define FP_X_UFL 0x10 /* underflow */
	85	#define FP_X_IMP 0x20 /* (im)precision */
	86	#define FP_X_STK 0x40 /* stack fault */
	87	.Ed
	88	.Ft fp_except_t
	89	.Fn fpgetmask void
	90	.Ft fp_except_t
	91	.Fn fpsetmask "fp_except_t mask"
	92	.Ft fp_except_t
	93	.Fn fpgetsticky void
ae3f4859 SW	94	.Ft fp_except_t
ae3f4859 SW	95	.Fn fpsetsticky "fp_except_t sticky"
984263bc MD	96	.Ft fp_except_t
	97	.Fn fpresetsticky "fp_except_t sticky"
	98	.Sh DESCRIPTION
13d93081 SW	99	The routines described herein are deprecated.
	100	New code should use the functionality provided by
	101	.Xr fenv 3 .
	102	.Pp
984263bc MD	103	When a floating point exception is detected, the exception sticky flag is
984263bc MD	104	set and the exception mask is tested.
13d93081 SW	105	If the mask is set, then a trap occurs.
	106	These routines allow both setting the floating point exception
	107	masks, and resetting the exception sticky flags after an exception is
	108	detected.
	109	In addition, they allow setting the floating point rounding mode
984263bc MD	110	and precision.
	111	.Pp
	112	The
	113	.Fn fpgetround
	114	function
	115	returns the current floating point rounding mode.
	116	.Pp
	117	The
	118	.Fn fpsetround
	119	function
	120	sets the floating point rounding mode and returns
	121	the previous mode.
	122	.Pp
	123	The
	124	.Fn fpgetprec
	125	function
	126	returns the current floating point precision.
	127	.Pp
	128	The
	129	.Fn fpsetprec
	130	function
	131	sets the floating point precision and returns
	132	the previous precision.
	133	.Pp
	134	The
	135	.Fn fpgetmask
	136	function
	137	returns the current floating point exception masks.
	138	.Pp
	139	The
	140	.Fn fpsetmask
	141	function
	142	sets the floating point exception masks and returns the
	143	previous masks.
	144	.Pp
	145	The
	146	.Fn fpgetsticky
	147	function
	148	returns the current floating point sticky flags.
	149	.Pp
	150	The
67956a9a SW	151	.Fn fpsetsticky
	152	sets the floating point sticky flags and returns
	153	the previous flags.
	154	.Pp
	155	The
984263bc MD	156	.Fn fpresetsticky
	157	function
	158	clears the floating point sticky flags and returns
	159	the previous flags.
	160	.Pp
	161	Sample code which prevents a trap on divide-by-zero:
	162	.Bd -literal -offset indent
	163	fpsetmask(~FP_X_DZ);
	164	a = 1.0;
	165	b = 0;
	166	c = a / b;
	167	fpresetsticky(FP_X_DZ);
	168	fpsetmask(FP_X_DZ);
	169	.Ed
13d93081 SW	170	.Sh IMPLEMENTATION NOTES
	171	The
	172	.Fn fpgetprec
	173	and
	174	.Fn fpsetprec
	175	functions provide functionality unavailable on many platforms.
c1543a89	176	At present, they are implemented only on the i386 and x86_64 platforms.
984263bc	177	.Sh SEE ALSO
13d93081	178	.Xr fenv 3 ,
984263bc	179	.Xr isnan 3
13d93081	180	.Sh CAVEATS
984263bc	181	After a floating point exception and before a mask is set, the sticky
13d93081 SW	182	flags must be reset.
13d93081 SW	183	If another exception occurs before the sticky
984263bc MD	184	flags are reset, then a wrong exception type may be signaled.
	185	.Sh HISTORY
	186	These routines are based on SysV/386 routines of the same name.