FPGETROUND(3)

🦋 FPGETROUND(3) 🦋

okay bestie, welcome to the Library Functions Manual page for the IEEE floating point interface. This is the whole fpgetround / fpsetround / fpsetprec / fpgetprec / fpgetmask / fpsetmask / fpgetsticky / fpresetsticky situation, and yes, we're gonna get through it together 💖

---

✨ NAME ✨

This page is about fpgetround, fpsetround, fpsetprec, fpgetprec, fpgetmask, fpsetmask, fpgetsticky, and fpresetsticky — the IEEE floating point interface 🎀

---

🎀 SYNOPSIS 🎀

First, you pull in this header:

#include <ieeefp.h>

Then the rounding-mode enum:

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;

And the rounding functions:

fp_rnd_t
fpgetround(void);

fp_rnd_t
fpsetround(fp_rnd_t direction);

Next, the precision enum:

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;

And the precision functions:

fp_prec_t
fpgetprec(void);

fp_prec_t
fpsetprec(fp_prec_t precision);

Then the exception-mask defines and the mask/sticky functions:

#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 */

fp_except_t
fpgetmask(void);

fp_except_t
fpsetmask(fp_except_t mask);

fp_except_t
fpgetsticky(void);

fp_except_t
fpresetsticky(fp_except_t sticky);

---

🌸 DESCRIPTION 🌸

okay so first things first: these routines are deprecated 🫶 New code should use the functionality provided by fenv(3). Not me being dramatic, that's just the assignment.

Here's the vibe: 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 let you set the floating point exception masks, and they let you reset the exception sticky flags after an exception is detected. They also let you set the floating point rounding mode and precision. iconic, honestly ✨

Now the function-by-function breakdown:

• fpgetround() — returns the current floating point rounding mode.
• fpsetround() — sets the floating point rounding mode and returns the previous mode.
• fpgetprec() — returns the current floating point precision.
• fpsetprec() — sets the floating point precision and returns the previous precision.
• fpgetmask() — returns the current floating point exception masks.
• fpsetmask() — sets the floating point exception masks and returns the previous masks.
• fpgetsticky() — returns the current floating point sticky flags.
• fpresetsticky() — clears the floating point sticky flags and returns the previous flags.

And here's sample code which prevents a trap on divide-by-zero, bestie:

fpsetmask(~FP_X_DZ);
a = 1.0;
b = 0;
c = a / b;
fpresetsticky(FP_X_DZ);
fpsetmask(FP_X_DZ);

---

🧚 IMPLEMENTATION NOTES 🧚

The fpgetprec() and fpsetprec() functions provide functionality unavailable on many platforms. At present, they are implemented only on the i386 and amd64 platforms.

Changing precision is not a supported feature: it may be ineffective when code is compiled to take advantage of SSE, and many library functions and compiler optimizations depend upon the default precision for correct behavior. so yeah, tread carefully, bestie 💅

---

🌈 SEE ALSO 🌈

• fenv(3)
• isnan(3)

---

👑 HISTORY 👑

These routines are based on SysV/386 routines of the same name. vintage behavior, lowkey iconic 🎀

---

💀 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. no cap, this one matters 😭

---

xoxo, Debian — December 3, 2010 💖💅