mirror of https://github.com/mkerrisk/man-pages
346 lines
9.5 KiB
Plaintext
346 lines
9.5 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "<tgmath.h>" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" <tgmath.h>
|
|
.SH NAME
|
|
tgmath.h \- type-generic macros
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <tgmath.h>\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fI<tgmath.h>\fP header shall include the headers \fI<math.h>\fP
|
|
and \fI<complex.h>\fP and shall define several type-generic macros.
|
|
.LP
|
|
Of the functions contained within the \fI<math.h>\fP and \fI<complex.h>\fP
|
|
headers without an \fIf\fP ( \fBfloat\fP) or \fIl\fP ( \fBlong
|
|
double\fP) suffix, several have one or more parameters whose corresponding
|
|
real type is \fBdouble\fP. For each such function,
|
|
except \fImodf\fP(), there shall be a corresponding type-generic macro.
|
|
The parameters whose
|
|
corresponding real type is \fBdouble\fP in the function synopsis are
|
|
generic parameters. Use of the macro invokes a function whose
|
|
corresponding real type and type domain are determined by the arguments
|
|
for the generic parameters.
|
|
.LP
|
|
Use of the macro invokes a function whose generic parameters have
|
|
the corresponding real type determined as follows:
|
|
.IP " *" 3
|
|
First, if any argument for generic parameters has type \fBlong double\fP,
|
|
the type determined is \fBlong double\fP.
|
|
.LP
|
|
.IP " *" 3
|
|
Otherwise, if any argument for generic parameters has type \fBdouble\fP
|
|
or is of integer type, the type determined is
|
|
\fBdouble\fP.
|
|
.LP
|
|
.IP " *" 3
|
|
Otherwise, the type determined is \fBfloat\fP.
|
|
.LP
|
|
.LP
|
|
For each unsuffixed function in the \fI<math.h>\fP header for which
|
|
there is a
|
|
function in the \fI<complex.h>\fP header with the same name except
|
|
for a \fIc\fP
|
|
prefix, the corresponding type-generic macro (for both functions)
|
|
has the same name as the function in the \fI<math.h>\fP header. The
|
|
corresponding type-generic macro for \fIfabs\fP() and \fIcabs\fP()
|
|
is \fIfabs\fP().
|
|
.TS C
|
|
center; l l l.
|
|
\fB<math.h>\fP \fB<complex.h>\fP \fBType-Generic\fP
|
|
\fBFunction\fP \fBFunction\fP \fBMacro\fP
|
|
\fIacos\fP() \fIcacos\fP() \fIacos\fP()
|
|
\fIasin\fP() \fIcasin\fP() \fIasin\fP()
|
|
\fIatan\fP() \fIcatan\fP() \fIatan\fP()
|
|
\fIacosh\fP() \fIcacosh\fP() \fIacosh\fP()
|
|
\fIasinh\fP() \fIcasinh\fP() \fIasinh\fP()
|
|
\fIatanh\fP() \fIcatanh\fP() \fIatanh\fP()
|
|
\fIcos\fP() \fIccos\fP() \fIcos\fP()
|
|
\fIsin\fP() \fIcsin\fP() \fIsin\fP()
|
|
\fItan\fP() \fIctan\fP() \fItan\fP()
|
|
\fIcosh\fP() \fIccosh\fP() \fIcosh\fP()
|
|
\fIsinh\fP() \fIcsinh\fP() \fIsinh\fP()
|
|
\fItanh\fP() \fIctanh\fP() \fItanh\fP()
|
|
\fIexp\fP() \fIcexp\fP() \fIexp\fP()
|
|
\fIlog\fP() \fIclog\fP() \fIlog\fP()
|
|
\fIpow\fP() \fIcpow\fP() \fIpow\fP()
|
|
\fIsqrt\fP() \fIcsqrt\fP() \fIsqrt\fP()
|
|
\fIfabs\fP() \fIcabs\fP() \fIfabs\fP()
|
|
.TE
|
|
.LP
|
|
If at least one argument for a generic parameter is complex, then
|
|
use of the macro invokes a complex function; otherwise, use of
|
|
the macro invokes a real function.
|
|
.LP
|
|
For each unsuffixed function in the \fI<math.h>\fP header without
|
|
a
|
|
\fIc\fP-prefixed counterpart in the \fI<complex.h>\fP header, the
|
|
corresponding
|
|
type-generic macro has the same name as the function. These type-generic
|
|
macros are:
|
|
.TS C
|
|
center; lw(19) lw(19) lw(19) lw(19).
|
|
T{
|
|
.br
|
|
\fIatan2\fP()
|
|
.br
|
|
\fIcbrt\fP()
|
|
.br
|
|
\fIceil\fP()
|
|
.br
|
|
\fIcopysign\fP()
|
|
.br
|
|
\fIerf\fP()
|
|
.br
|
|
\fIerfc\fP()
|
|
.br
|
|
\fIexp2\fP()
|
|
.br
|
|
\fIexpm1\fP()
|
|
.br
|
|
\fIfdim\fP()
|
|
.br
|
|
\fIfloor\fP()
|
|
.br
|
|
\
|
|
T} T{
|
|
.br
|
|
\fIfma\fP()
|
|
.br
|
|
\fIfmax\fP()
|
|
.br
|
|
\fIfmin\fP()
|
|
.br
|
|
\fIfmod\fP()
|
|
.br
|
|
\fIfrexp\fP()
|
|
.br
|
|
\fIhypot\fP()
|
|
.br
|
|
\fIilogb\fP()
|
|
.br
|
|
\fIldexp\fP()
|
|
.br
|
|
\fIlgamma\fP()
|
|
.br
|
|
\fIllrint\fP()
|
|
.br
|
|
\
|
|
T} T{
|
|
.br
|
|
\fIllround\fP()
|
|
.br
|
|
\fIlog10\fP()
|
|
.br
|
|
\fIlog1p\fP()
|
|
.br
|
|
\fIlog2\fP()
|
|
.br
|
|
\fIlogb\fP()
|
|
.br
|
|
\fIlrint\fP()
|
|
.br
|
|
\fIlround\fP()
|
|
.br
|
|
\fInearbyint\fP()
|
|
.br
|
|
\fInextafter\fP()
|
|
.br
|
|
\fInexttoward\fP()
|
|
.br
|
|
\
|
|
T} T{
|
|
.br
|
|
\fIremainder\fP()
|
|
.br
|
|
\fIremquo\fP()
|
|
.br
|
|
\fIrint\fP()
|
|
.br
|
|
\fIround\fP()
|
|
.br
|
|
\fIscalbn\fP()
|
|
.br
|
|
\fIscalbln\fP()
|
|
.br
|
|
\fItgamma\fP()
|
|
.br
|
|
\fItrunc\fP()
|
|
.br
|
|
\
|
|
T}
|
|
.TE
|
|
.LP
|
|
If all arguments for generic parameters are real, then use of the
|
|
macro invokes a real function; otherwise, use of the macro
|
|
results in undefined behavior.
|
|
.LP
|
|
For each unsuffixed function in the \fI<complex.h>\fP header that
|
|
is not a
|
|
\fIc\fP-prefixed counterpart to a function in the \fI<math.h>\fP header,
|
|
the
|
|
corresponding type-generic macro has the same name as the function.
|
|
These type-generic macros are:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fIcarg\fP()
|
|
\fIcimag\fP()
|
|
\fIconj\fP()
|
|
\fIcproj\fP()
|
|
\fIcreal\fP()
|
|
.fi
|
|
.RE
|
|
.LP
|
|
Use of the macro with any real or complex argument invokes a complex
|
|
function.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
With the declarations:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <tgmath.h>
|
|
int n;
|
|
float f;
|
|
double d;
|
|
long double ld;
|
|
float complex fc;
|
|
double complex dc;
|
|
long double complex ldc;
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
functions invoked by use of type-generic macros are shown in the following
|
|
table:
|
|
.TS C
|
|
center; l2 l.
|
|
\fBMacro\fP \fBUse Invokes\fP
|
|
\fIexp\fP(\fIn\fP) \fIexp\fP(\fIn\fP), the function
|
|
\fIacosh\fP(\fIf\fP) \fIacoshf\fP(\fIf\fP)
|
|
\fIsin\fP(\fId\fP) \fIsin\fP(\fId\fP), the function
|
|
\fIatan\fP(\fIld\fP) \fIatanl\fP(\fIld\fP)
|
|
\fIlog\fP(\fIfc\fP) \fIclogf\fP(\fIfc\fP)
|
|
\fIsqrt\fP(\fIdc\fP) \fIcsqrt\fP(\fIdc\fP)
|
|
\fIpow\fP(\fIldc,f\fP) \fIcpowl\fP(\fIldc, f\fP)
|
|
\fIremainder\fP(\fIn,n\fP) \fIremainder\fP(\fIn, n\fP), the function
|
|
\fInextafter\fP(\fId,f\fP) \fInextafter\fP(\fId, f\fP), the function
|
|
\fInexttoward\fP(\fIf,ld\fP) \fInexttowardf\fP(\fIf, ld\fP)
|
|
\fIcopysign\fP(\fIn,ld\fP) \fIcopysignl\fP(\fIn, ld\fP)
|
|
\fIceil\fP(\fIfc\fP) Undefined behavior
|
|
\fIrint\fP(\fIdc\fP) Undefined behavior
|
|
\fIfmax\fP(\fIldc,ld\fP) Undefined behavior
|
|
\fIcarg\fP(\fIn\fP) \fIcarg\fP(\fIn\fP), the function
|
|
\fIcproj\fP(\fIf\fP) \fIcprojf\fP(\fIf\fP)
|
|
\fIcreal\fP(\fId\fP) \fIcreal\fP(\fId\fP), the function
|
|
\fIcimag\fP(\fIld\fP) \fIcimagl\fP(\fIld\fP)
|
|
\fIcabs\fP(\fIfc\fP) \fIcabsf\fP(\fIfc\fP)
|
|
\fIcarg\fP(\fIdc\fP) \fIcarg\fP(\fIdc\fP), the function
|
|
\fIcproj\fP(\fIldc\fP) \fIcprojl\fP(\fIldc\fP)
|
|
.TE
|
|
.SH RATIONALE
|
|
.LP
|
|
Type-generic macros allow calling a function whose type is determined
|
|
by the argument type, as is the case for C operators such
|
|
as \fB'+'\fP and \fB'*'\fP . For example, with a type-generic \fIcos\fP()
|
|
macro, the
|
|
expression \fIcos\fP(( \fBfloat\fP) \fIx\fP) will have type \fBfloat\fP.
|
|
This feature enables writing more portably efficient
|
|
code and alleviates need for awkward casting and suffixing in the
|
|
process of porting or adjusting precision. Generic math functions
|
|
are a widely appreciated feature of Fortran.
|
|
.LP
|
|
The only arguments that affect the type resolution are the arguments
|
|
corresponding to the parameters that have type
|
|
\fBdouble\fP in the synopsis. Hence the type of a type-generic call
|
|
to \fInexttoward\fP(), whose second parameter is \fBlong double\fP
|
|
in the synopsis, is determined
|
|
solely by the type of the first argument.
|
|
.LP
|
|
The term "type-generic" was chosen over the proposed alternatives
|
|
of intrinsic and overloading. The term is more specific than
|
|
intrinsic, which already is widely used with a more general meaning,
|
|
and reflects a closer match to Fortran's generic functions
|
|
than to C++ overloading.
|
|
.LP
|
|
The macros are placed in their own header in order not to silently
|
|
break old programs that include the \fI<math.h>\fP header; for example,
|
|
with:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBprintf ("%e", sin(x))
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
\fImodf\fP( \fBdouble\fP, \fBdouble *\fP) is excluded because no way
|
|
was seen to make it safe without complicating the type
|
|
resolution.
|
|
.LP
|
|
The implementation might, as an extension, endow appropriate ones
|
|
of the macros that IEEE\ Std\ 1003.1-2001 specifies
|
|
only for real arguments with the ability to invoke the complex functions.
|
|
.LP
|
|
IEEE\ Std\ 1003.1-2001 does not prescribe any particular implementation
|
|
mechanism for generic macros. It could be
|
|
implemented simply with built-in macros. The generic macro for \fIsqrt\fP(),
|
|
for example,
|
|
could be implemented with:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#undef sqrt
|
|
#define sqrt(x) __BUILTIN_GENERIC_sqrt(x)
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
Generic macros are designed for a useful level of consistency with
|
|
C++ overloaded math functions.
|
|
.LP
|
|
The great majority of existing C programs are expected to be unaffected
|
|
when the \fI<tgmath.h>\fP header is included
|
|
instead of the \fI<math.h>\fP or \fI<complex.h>\fP headers. Generic
|
|
macros are similar to the ISO/IEC\ 9899:1999
|
|
standard library masking macros, though the semantic types of return
|
|
values differ.
|
|
.LP
|
|
The ability to overload on integer as well as floating types would
|
|
have been useful for some functions; for example, \fIcopysign\fP().
|
|
Overloading with different numbers of arguments would have allowed
|
|
reusing
|
|
names; for example, \fIremainder\fP() for \fIremquo\fP(). However,
|
|
these facilities would have complicated the specification; and their
|
|
natural consistent use, such as for a floating \fIabs\fP() or a two-argument
|
|
\fIatan\fP(), would have introduced further inconsistencies with the
|
|
ISO/IEC\ 9899:1999 standard
|
|
for insufficient benefit.
|
|
.LP
|
|
The ISO\ C standard in no way limits the implementation's options
|
|
for efficiency, including inlining library functions.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fI<math.h>\fP , \fI<complex.h>\fP , the System Interfaces
|
|
volume of IEEE\ Std\ 1003.1-2001, \fIcabs\fP(), \fIfabs\fP(), \fImodf\fP()
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|