xref: /freebsd/share/man/man3/tgmath.3 (revision 7aa383846770374466b1dcb2cefd71bde9acf463)
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.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
36The header
37.In tgmath.h
38provides type-generic macros
39for
40.In math.h
41and
42.In complex.h
43functions that have
44.Vt float
45(suffixed with
46.Sy f ) ,
47.Vt double
48and
49.Vt "long double"
50(suffixed with
51.Sy l )
52versions.
53The arguments that vary across the three functions and have type
54.Vt float , double
55and
56.Vt "long double" ,
57respectively, are called
58.Em "generic arguments" .
59.Pp
60The following rules describe which function is actually called if a
61type-generic macro is invoked.
62If any generic argument has type
63.Vt "long double"
64or
65.Vt "long double complex" ,
66the
67.Vt "long double"
68function is called.
69Else, if any generic argument has type
70.Vt double , "double complex"
71or an integer type, the
72.Vt double
73version is invoked.
74Otherwise, the macro expands to the
75.Vt float
76implementation.
77.Pp
78For the macros in the following table, both real and complex functions
79exist.
80The real functions are prototyped in
81.In math.h
82and the complex equivalents in
83.In complex.h .
84The complex function is called if any of the generic arguments is a
85complex value.
86Otherwise, 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
108No complex functions exist for the following macros, so passing a
109complex 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 nextbyint Ta Fn trunc
119.It Fn fdim Ta Fn lgamma Ta Fn nextafter
120.It Fn floor Ta Fn llrint Ta Fn nexttoward
121.El
122.Pp
123The 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
128This header includes
129.In complex.h
130and
131.In math.h .
132.Sh STANDARDS
133The header
134.In tgmath.h
135conforms to
136.St -isoC-99 .
137.Sh HISTORY
138The header
139.In tgmath.h
140first appeared in
141.Fx 5.3 .
142.Sh BUGS
143The header
144.In tgmath.h
145cannot be implemented with strictly conforming C code and needs
146special compiler support.
147The current implementation only works for GCC.
148.Pp
149Many of the functions mentioned here are not prototyped in
150.In math.h
151or
152.In complex.h
153as they are not yet implemented.
154