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: head/share/man/man3/tgmath.3 233992 2012-04-07 09:05:30Z joel $
  26 .\"
  27 .Dd June 2, 2013
  28 .Dt TGMATH 3
  29 .Os
  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 sqrt Ta Fn sqrt Ta Fn csqrt
 105 .It Fn fabs Ta Fn fabs Ta Fn cabs
 106 .El
 107 .Pp
 108 No complex functions exist for the following macros, so passing a
 109 complex value to a generic argument invokes undefined behaviour:
 110 .Bl -column -offset indent ".Fn nexttoward" ".Fn nexttoward" ".Fn nexttoward" ".Fn nexttoward"
 111 .It Fn atan2 Ta Fn fma Ta Fn llround Ta Fn remainder
 112 .It Fn cbrt Ta Fn fmax Ta Fn log10 Ta Fn remquo
 113 .It Fn ceil Ta Fn fmin Ta Fn log1p Ta Fn rint
 114 .It Fn copysign Ta Fn fmod Ta Fn log2 Ta Fn round
 115 .It Fn erf Ta Fn frexp Ta Fn logb Ta Fn scalbn
 116 .It Fn erfc Ta Fn hypot Ta Fn lrint Ta Fn scalbln
 117 .It Fn exp2 Ta Fn ilogb Ta Fn lround Ta Fn tgamma
 118 .It Fn expm1 Ta Fn ldexp Ta Fn nearbyint Ta Fn trunc
 119 .It Fn fdim Ta Fn lgamma Ta Fn nextafter Ta \&
 120 .It Fn floor Ta Fn llrint Ta Fn nexttoward Ta \&
 121 .El
 122 .Pp
 123 The following macros always expand to a complex function:
 124 .Bl -column -offset indent ".Fn cimag" ".Fn cimag" ".Fn cimag" ".Fn cimag" ".Fn cimag"
 125 .It Fn carg Ta Fn cimag Ta Fn conj Ta Fn cproj Ta Fn creal
 126 .El
 127 .Pp
 128 This header includes
 129 .In complex.h
 130 and
 131 .In math.h .
 132 .Sh STANDARDS
 133 The header
 134 .In tgmath.h
 135 conforms to
 136 .St -isoC-99 .
 137 .Sh HISTORY
 138 The header
 139 .In tgmath.h
 140 first appeared in
 141 .Fx 5.3 .
 142 .Sh COMPILER SUPPORT
 143 Before
 144 .St -isoC-2011 ,
 145 the header
 146 .In tgmath.h
 147 could not be implemented with strictly conforming C code and needed
 148 special compiler support.
 149 As of
 150 .St -isoC-2011 ,
 151 this header file can be implemented using the
 152 .Fn _Generic
 153 language keyword.
 154 In addition to compilers that support this keyword, this header file
 155 works with GCC.
 156 .Sh BUGS
 157 Many of the functions mentioned here are not prototyped in
 158 .In math.h
 159 or
 160 .In complex.h
 161 as they are not yet implemented.
 162 This prevents the corresponding type-generic macro from working at all.