lib/libm/man/feclearexcept.3

   1 .\" Copyright (c) 2004 David Schultz <das@FreeBSD.org>
   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 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: head/lib/msun/man/feclearexcept.3 140225 2005-01-14 09:12:05Z ru $
  26 .\"
  27 .Dd May 8, 2004
  28 .Dt FECLEAREXCEPT 3
  29 .Os
  30 .Sh NAME
  31 .Nm feclearexcept ,
  32 .Nm fegetexceptflag ,
  33 .Nm feraiseexcept ,
  34 .Nm fesetexceptflag ,
  35 .Nm fetestexcept
  36 .Nd floating-point exception flag manipulation
  37 .Sh LIBRARY
  38 .Lb libm
  39 .Sh SYNOPSIS
  40 .In fenv.h
  41 .Fd "#pragma STDC FENV_ACCESS ON"
  42 .Ft int
  43 .Fn feclearexcept "int excepts"
  44 .Ft int
  45 .Fn fegetexceptflag "fexcept_t *flagp" "int excepts"
  46 .Ft int
  47 .Fn feraiseexcept "int excepts"
  48 .Ft int
  49 .Fn fesetexceptflag "const fexcept_t *flagp" "int excepts"
  50 .Ft int
  51 .Fn fetestexcept "int excepts"
  52 .Sh DESCRIPTION
  53 The
  54 .Fn feclearexcept
  55 routine clears the floating-point exception flags specified by
  56 .Fa excepts ,
  57 whereas
  58 .Fn feraiseexcept
  59 raises the specified exceptions.
  60 Raising an exception causes the corresponding flag to be set,
  61 and a
  62 .Dv SIGFPE
  63 is delivered to the process if the exception is unmasked.
  64 .Pp
  65 The
  66 .Fn fetestexcept
  67 function determines which flags are currently set, of those specified by
  68 .Fa excepts .
  69 .Pp
  70 The
  71 .Fn fegetexceptflag
  72 function stores the state of the exception flags specified in
  73 .Fa excepts
  74 in the opaque object pointed to by
  75 .Fa flagp .
  76 Similarly,
  77 .Fn fesetexceptflag
  78 changes the specified exception flags to reflect the state stored in
  79 the object pointed to by
  80 .Fa flagp .
  81 Note that the flags restored with
  82 .Fn fesetexceptflag
  83 must be a (not necessarily proper) subset of the flags recorded by
  84 a prior call to
  85 .Fn fegetexceptflag .
  86 .Pp
  87 For all of these functions, the possible types of exceptions
  88 include those described in
  89 .Xr fenv 3 .
  90 Some architectures may define other types of floating-point exceptions.
  91 .Sh IMPLEMENTATION NOTES
  92 On some architectures, raising an overflow or underflow exception
  93 also causes an inexact exception to be raised.
  94 In these cases, the overflow or underflow will be raised first.
  95 .Pp
  96 The
  97 .Fn fegetexceptflag
  98 and
  99 .Fn fesetexceptflag
 100 routines are preferred to
 101 .Fn fetestexcept
 102 and
 103 .Fn feraiseexcept ,
 104 respectively, for saving and restoring exception flags.
 105 The latter do not re-raise exceptions and may preserve
 106 architecture-specific information such as addresses where
 107 exceptions occurred.
 108 .Sh RETURN VALUES
 109 The
 110 .Fn feclearexcept ,
 111 .Fn fegetexceptflag ,
 112 .Fn feraiseexcept ,
 113 and
 114 .Fn fesetexceptflag
 115 functions return 0 upon success, and non-zero otherwise.
 116 The
 117 .Fn fetestexcept
 118 function returns the bitwise OR of the values of the current exception
 119 flags that were requested.
 120 .Sh SEE ALSO
 121 .Xr sigaction 2 ,
 122 .Xr feholdexcept 3 ,
 123 .Xr fenv 3 ,
 124 .Xr feupdateenv 3 ,
 125 .Xr fpgetsticky 3 ,
 126 .Xr fpresetsticky 3
 127 .Sh STANDARDS
 128 The
 129 .Fn feclearexcept ,
 130 .Fn fegetexceptflag ,
 131 .Fn feraiseexcept ,
 132 .Fn fesetexceptflag ,
 133 and
 134 .Fn fetestexcept
 135 routines conform to
 136 .St -isoC-99 .
 137 .Sh HISTORY
 138 These functions first appeared in
 139 .Fx 5.3 .