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