xref: /freebsd/share/man/man3/tgmath.3 (revision fd51ce66aa149cc4c0546c0e5b84201535ac35b8)

.\" Copyright (c) 2004 Stefan Farfeleder
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd Aug 14, 2004
.Os
.Dt TGMATH 3
.Sh NAME
.Nm tgmath
.Nd type-generic macros
.Sh SYNOPSIS
.In tgmath.h
.Sh DESCRIPTION
The header
.In tgmath.h
provides type-generic macros
for
.In math.h
and
.In complex.h
functions that have
.Vt float
(suffixed with
.Sm off
.Sy f )
,
.Sm on
.Vt double
and
.Vt long double
(suffixed with
.Sy l )
versions.
The arguments that vary across the three functions and have type
.Vt float ,
.Vt double
and
.Vt "long double" ,
respectively, are called
.Em generic arguments .
.Pp
The following rules describe which function is actually called if a
type-generic macro is invoked.  If any generic argument has type
.Vt "long double"
or
.Vt "long double complex" ,
the
.Vt "long double"
function is called.  Else if any generic argument has type
.Vt double ,
.Vt "double complex"
or an integer type, the
.Vt double
version is invoked.  Otherwise the macro expands to the
.Vt float
implementation.
.Pp
For the macros in the following table, both real and complex functions
exist.
The real functions are prototyped in
.In math.h
and the complex equivalents in
.In complex.h .
The complex function is called if any of the generic arguments is a
complex value.
Otherwise the real equivalent is called.
.Bl -column -offset indent ".Sy Macro" "Sy real function" ".Sy complex function"
.It Sy Macro Ta Sy real function Ta Sy complex function
.It Li acos Ta acos Ta cacos
.It Li asin Ta asin Ta casin
.It Li atan Ta atan Ta catan
.It Li acosh Ta acosh Ta cacosh
.It Li asinh Ta asinh Ta casinh
.It Li atanh Ta atanh Ta catanh
.It Li cos Ta cos Ta ccos
.It Li sin Ta sin Ta csin
.It Li tan  Ta tan Ta ctan
.It Li cosh Ta cosh Ta ccosh
.It Li sinh Ta sinh Ta csinh
.It Li tanh Ta tanh Ta ctanh
.It Li exp Ta exp Ta cexp
.It Li log Ta log Ta clog
.It Li pow Ta pow Ta cpow
.It Li fabs Ta fabs Ta cabs
.El
.Pp
No complex functions exist for the following macros, so passing a
complex value to a generic argument invokes undefined behaviour:
.Bl -column -offset indent nexttoward nexttoward nexttoward nexttoward
.It Li atan2 Ta fma Ta llround Ta remainder
.It Li cbrt Ta fmax Ta log10 Ta remquo
.It Li ceil Ta fmin Ta log1p Ta rint
.It Li copysign Ta fmod Ta log2 Ta round
.It Li erf Ta frexp Ta logb Ta scalbn
.It Li erfc Ta hypot Ta lrint Ta scalbln
.It Li exp2 Ta ilogb Ta lround Ta tgamma
.It Li expm1 Ta ldexp Ta nextbyint Ta trunc
.It Li fdim Ta lgamma Ta nextafter
.It Li floor Ta llrint Ta nexttoward
.El
.Pp
The following macros always expand to a complex function:
.Bl -column -offset indent cimag cimag cimag cimag cimag
.It Li carg Ta cimag Ta conj Ta cproj Ta creal
.El
.Pp
This header includes
.In complex.h
and
.In math.h .
.Sh STANDARDS
.In tgmath.h
conforms to
.St -isoC-99 .
.Sh HISTORY
The header
.In tgmath.h
first appeared in
.Fx 5.3 .
.Sh BUGS
.In tgmath.h
cannot be implemented with strictly conforming C code and needs
special compiler support.  The current implementation only works for GCC.
.Pp
Many of the functions mentioned here are not prototyped in
.In math.h
or
.In complex.h
as they are not yet implemented.