lib/libm/man/fegetenv.3

   1 .\"     $NetBSD: fegetenv.3,v 1.2 2010/08/04 18:58:18 wiz Exp $
   2 .\" Copyright (c) 2004 David Schultz <das@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .Dd May 8, 2004
  27 .Dt FEGETENV 3
  28 .Os
  29 .Sh NAME
  30 .Nm fegetenv ,
  31 .Nm feholdexcept ,
  32 .Nm fesetenv ,
  33 .Nm feupdateenv
  34 .Nd floating-point environment save and restore
  35 .Sh LIBRARY
  36 .Lb libm
  37 .Sh SYNOPSIS
  38 .In fenv.h
  39 .Fd "#pragma STDC FENV_ACCESS ON"
  40 .Ft int
  41 .Fn fegetenv "fenv_t *envp"
  42 .Ft int
  43 .Fn feholdexcept "fenv_t *envp"
  44 .Ft int
  45 .Fn fesetenv "const fenv_t *envp"
  46 .Ft int
  47 .Fn feupdateenv "const fenv_t *envp"
  48 .Sh DESCRIPTION
  49 The floating-point environment includes exception flags and masks, the
  50 current rounding mode, and other architecture-specific settings.
  51 However, it does not include the floating-point register file.
  52 .Pp
  53 The
  54 .Fn fegetenv
  55 function stores the current floating-point environment in the object
  56 pointed to by
  57 .Fa envp ,
  58 whereas
  59 .Fn feholdexcept
  60 saves the current environment, then clears all exception flags
  61 and masks all floating-point exceptions.
  62 .Pp
  63 The
  64 .Fn fesetenv
  65 function restores a previously saved environment.
  66 The
  67 .Fn feupdateenv
  68 function restores a saved environment as well, but it also
  69 raises any exceptions that were set in the environment it
  70 replaces.
  71 .Pp
  72 The
  73 .Fn feholdexcept
  74 function is often used with
  75 .Fn feupdateenv
  76 or
  77 .Fn fesetenv
  78 to suppress spurious exceptions that occur as a result of
  79 intermediate computations.
  80 An example in
  81 .Xr fenv 3
  82 demonstrates how to do this.
  83 .Sh RETURN VALUES
  84 The
  85 .Fn fegetenv ,
  86 .Fn feholdexcept ,
  87 .Fn fesetenv ,
  88 and
  89 .Fn feupdateenv
  90 functions return 0 if they succeed, and non-zero otherwise.
  91 .Sh SEE ALSO
  92 .Xr feclearexcept 3 ,
  93 .Xr fenv 3 ,
  94 .Xr feraiseexcept 3 ,
  95 .Xr fesetenv 3 ,
  96 .Xr fetestexcept 3 ,
  97 .Xr fpgetmask 3 ,
  98 .\"Xr fpgetprec 3 ,
  99 .Xr fpsetmask 3
 100 .\"Xr fpsetprec 3
 101 .Sh STANDARDS
 102 The
 103 .Fn fegetenv ,
 104 .Fn feholdexcept ,
 105 .Fn fesetenv ,
 106 and
 107 .Fn feupdateenv
 108 functions conform to
 109 .St -isoC-99 .
 110 .Sh HISTORY
 111 These routines first appeared in
 112 .Fx 5.3
 113 and
 114 .Nx 6.0 .