share/man/man3/tgmath.3

   1 .\" Copyright (c) 2004 Stefan Farfeleder
   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 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 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$
  26 .\"
  27 .Dd August 14, 2004
  28 .Os
  29 .Dt TGMATH 3
  30 .Sh NAME
  31 .Nm tgmath
  32 .Nd "type-generic macros"
  33 .Sh SYNOPSIS
  34 .In tgmath.h
  35 .Sh DESCRIPTION
  36 The header
  37 .In tgmath.h
  38 provides type-generic macros
  39 for
  40 .In math.h
  41 and
  42 .In complex.h
  43 functions that have
  44 .Vt float
  45 (suffixed with
  46 .Sy f ) ,
  47 .Vt double
  48 and
  49 .Vt "long double"
  50 (suffixed with
  51 .Sy l )
  52 versions.
  53 The arguments that vary across the three functions and have type
  54 .Vt float , double
  55 and
  56 .Vt "long double" ,
  57 respectively, are called
  58 .Em "generic arguments" .
  59 .Pp
  60 The following rules describe which function is actually called if a
  61 type-generic macro is invoked.
  62 If any generic argument has type
  63 .Vt "long double"
  64 or
  65 .Vt "long double complex" ,
  66 the
  67 .Vt "long double"
  68 function is called.
  69 Else, if any generic argument has type
  70 .Vt double , "double complex"
  71 or an integer type, the
  72 .Vt double
  73 version is invoked.
  74 Otherwise, the macro expands to the
  75 .Vt float
  76 implementation.
  77 .Pp
  78 For the macros in the following table, both real and complex functions
  79 exist.
  80 The real functions are prototyped in
  81 .In math.h
  82 and the complex equivalents in
  83 .In complex.h .
  84 The complex function is called if any of the generic arguments is a
  85 complex value.
  86 Otherwise, the real equivalent is called.
  87 .Bl -column -offset indent ".Fn acosh" "Sy real function" ".Sy complex function"
  88 .It Sy Macro Ta Sy real function Ta Sy complex function
  89 .It Fn acos Ta Fn acos Ta Fn cacos
  90 .It Fn asin Ta Fn asin Ta Fn casin
  91 .It Fn atan Ta Fn atan Ta Fn catan
  92 .It Fn acosh Ta Fn acosh Ta Fn cacosh
  93 .It Fn asinh Ta Fn asinh Ta Fn casinh
  94 .It Fn atanh Ta Fn atanh Ta Fn catanh
  95 .It Fn cos Ta Fn cos Ta Fn ccos
  96 .It Fn sin Ta Fn sin Ta Fn csin
  97 .It Fn tan  Ta Fn tan Ta Fn ctan
  98 .It Fn cosh Ta Fn cosh Ta Fn ccosh
  99 .It Fn sinh Ta Fn sinh Ta Fn csinh
 100 .It Fn tanh Ta Fn tanh Ta Fn ctanh
 101 .It Fn exp Ta Fn exp Ta Fn cexp
 102 .It Fn log Ta Fn log Ta Fn clog
 103 .It Fn pow Ta Fn pow Ta Fn cpow
 104 .It Fn fabs Ta Fn fabs Ta Fn cabs
 105 .El
 106 .Pp
 107 No complex functions exist for the following macros, so passing a
 108 complex value to a generic argument invokes undefined behaviour:
 109 .Bl -column -offset indent ".Fn nexttoward" ".Fn nexttoward" ".Fn nexttoward" ".Fn nexttoward"
 110 .It Fn atan2 Ta Fn fma Ta Fn llround Ta Fn remainder
 111 .It Fn cbrt Ta Fn fmax Ta Fn log10 Ta Fn remquo
 112 .It Fn ceil Ta Fn fmin Ta Fn log1p Ta Fn rint
 113 .It Fn copysign Ta Fn fmod Ta Fn log2 Ta Fn round
 114 .It Fn erf Ta Fn frexp Ta Fn logb Ta Fn scalbn
 115 .It Fn erfc Ta Fn hypot Ta Fn lrint Ta Fn scalbln
 116 .It Fn exp2 Ta Fn ilogb Ta Fn lround Ta Fn tgamma
 117 .It Fn expm1 Ta Fn ldexp Ta Fn nextbyint Ta Fn trunc
 118 .It Fn fdim Ta Fn lgamma Ta Fn nextafter
 119 .It Fn floor Ta Fn llrint Ta Fn nexttoward
 120 .El
 121 .Pp
 122 The following macros always expand to a complex function:
 123 .Bl -column -offset indent ".Fn cimag" ".Fn cimag" ".Fn cimag" ".Fn cimag" ".Fn cimag"
 124 .It Fn carg Ta Fn cimag Ta Fn conj Ta Fn cproj Ta Fn creal
 125 .El
 126 .Pp
 127 This header includes
 128 .In complex.h
 129 and
 130 .In math.h .
 131 .Sh STANDARDS
 132 The header
 133 .In tgmath.h
 134 conforms to
 135 .St -isoC-99 .
 136 .Sh HISTORY
 137 The header
 138 .In tgmath.h
 139 first appeared in
 140 .Fx 5.3 .
 141 .Sh BUGS
 142 The header
 143 .In tgmath.h
 144 cannot be implemented with strictly conforming C code and needs
 145 special compiler support.
 146 The current implementation only works for GCC.
 147 .Pp
 148 Many of the functions mentioned here are not prototyped in
 149 .In math.h
 150 or
 151 .In complex.h
 152 as they are not yet implemented.