lib/libm/man/feclearexcept.3

   1 .\"     $NetBSD: feclearexcept.3,v 1.2 2010/08/07 18:13:12 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 FECLEAREXCEPT 3
  28 .Os
  29 .Sh NAME
  30 .Nm feclearexcept ,
  31 .Nm fegetexceptflag ,
  32 .Nm feraiseexcept ,
  33 .Nm fesetexceptflag ,
  34 .Nm fetestexcept
  35 .Nd floating-point exception flag manipulation
  36 .Sh LIBRARY
  37 .Lb libm
  38 .Sh SYNOPSIS
  39 .In fenv.h
  40 .Fd "#pragma STDC FENV_ACCESS ON"
  41 .Ft int
  42 .Fn feclearexcept "int excepts"
  43 .Ft int
  44 .Fn fegetexceptflag "fexcept_t *flagp" "int excepts"
  45 .Ft int
  46 .Fn feraiseexcept "int excepts"
  47 .Ft int
  48 .Fn fesetexceptflag "const fexcept_t *flagp" "int excepts"
  49 .Ft int
  50 .Fn fetestexcept "int excepts"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn feclearexcept
  54 routine clears the floating-point exception flags specified by
  55 .Fa excepts ,
  56 whereas
  57 .Fn feraiseexcept
  58 raises the specified exceptions.
  59 Raising an exception causes the corresponding flag to be set,
  60 and a
  61 .Dv SIGFPE
  62 is delivered to the process if the exception is unmasked.
  63 .Pp
  64 The
  65 .Fn fetestexcept
  66 function determines which flags are currently set, of those specified by
  67 .Fa excepts .
  68 .Pp
  69 The
  70 .Fn fegetexceptflag
  71 function stores the state of the exception flags specified in
  72 .Fa excepts
  73 in the opaque object pointed to by
  74 .Fa flagp .
  75 Similarly,
  76 .Fn fesetexceptflag
  77 changes the specified exception flags to reflect the state stored in
  78 the object pointed to by
  79 .Fa flagp .
  80 Note that the flags restored with
  81 .Fn fesetexceptflag
  82 must be a (not necessarily proper) subset of the flags recorded by
  83 a prior call to
  84 .Fn fegetexceptflag .
  85 .Pp
  86 For all of these functions, the possible types of exceptions
  87 include those described in
  88 .Xr fenv 3 .
  89 Some architectures may define other types of floating-point exceptions.
  90 .Sh IMPLEMENTATION NOTES
  91 On some architectures, raising an overflow or underflow exception
  92 also causes an inexact exception to be raised.
  93 In these cases, the overflow or underflow will be raised first.
  94 .Pp
  95 The
  96 .Fn fegetexceptflag
  97 and
  98 .Fn fesetexceptflag
  99 routines are preferred to
 100 .Fn fetestexcept
 101 and
 102 .Fn feraiseexcept ,
 103 respectively, for saving and restoring exception flags.
 104 The latter do not re-raise exceptions and may preserve
 105 architecture-specific information such as addresses where
 106 exceptions occurred.
 107 .Sh RETURN VALUES
 108 The
 109 .Fn feclearexcept ,
 110 .Fn fegetexceptflag ,
 111 .Fn feraiseexcept ,
 112 and
 113 .Fn fesetexceptflag
 114 functions return 0 upon success, and non-zero otherwise.
 115 The
 116 .Fn fetestexcept
 117 function returns the bitwise OR of the values of the current exception
 118 flags that were requested.
 119 .Sh SEE ALSO
 120 .Xr sigaction 2 ,
 121 .Xr feholdexcept 3 ,
 122 .Xr fenv 3 ,
 123 .Xr feupdateenv 3 ,
 124 .Xr fpgetsticky 3
 125 .Sh STANDARDS
 126 The
 127 .Fn feclearexcept ,
 128 .Fn fegetexceptflag ,
 129 .Fn feraiseexcept ,
 130 .Fn fesetexceptflag ,
 131 and
 132 .Fn fetestexcept
 133 routines conform to
 134 .St -isoC-99 .
 135 .Sh HISTORY
 136 These functions first appeared in
 137 .Fx 5.3
 138 and
 139 .Nx 6.0 .