diff options
Diffstat (limited to 'man0p/tgmath.h.0p')
| -rw-r--r-- | man0p/tgmath.h.0p | 345 |
1 files changed, 345 insertions, 0 deletions
diff --git a/man0p/tgmath.h.0p b/man0p/tgmath.h.0p new file mode 100644 index 000000000..e2c7083ae --- /dev/null +++ b/man0p/tgmath.h.0p @@ -0,0 +1,345 @@ +.\" 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 . |