tgmath.h

tgmath.h
Name	tgmath.h
Type	Header file
Standard	ISO/IEC 9899
Introduced	C99

tgmath.h

tgmath.h is a C standard library header that provides type-generic macros for mathematical functions. Originating in the ISO/IEC 9899:1999 (C99) revision, it interacts with implementations such as GNU Compiler Collection, Clang (compiler), and Microsoft Visual C++ runtime environments while relating to other headers like math.h, complex.h, and stdint.h. The header's design links to standards bodies and organizations including International Organization for Standardization, International Electrotechnical Commission, and committees like ANSI and ISO/IEC JTC 1/SC 22.

Overview

tgmath.h supplies a set of macros that dispatch calls to the appropriate mathematical functions depending on operand types, bridging interfaces defined in math.h and complex.h. Its presence in C99 aimed to provide behavior resembling function overloading found in languages such as C++ and to harmonize usage across real and complex arithmetic where functions in POSIX and implementations like BSD and glibc differ. Key stakeholders in its standardization include participants from ISO, compiler vendors such as Red Hat, and projects like LLVM.

Purpose and Design

The primary purpose of tgmath.h is to enable generic programming patterns in C99 without explicit casts or manual selection of float-, double-, or long double-variants of mathematical functions. The design leverages preprocessor macros combined with type-generic selection semantics influenced by proposals from standards meetings in WG14 and authors with affiliations to institutions like Bell Labs and universities such as Massachusetts Institute of Technology and Stanford University. The API intentionally maps to existing symbols—e.g., sin, cos, exp—while dispatching to sinf, sinl, csin, or csinf as appropriate, facilitating portable code bases used by projects like LLVM libc++ and NetBSD libraries.

Functionality and Macros

tgmath.h defines macros for a wide range of numeric operations: trigonometric, hyperbolic, exponential, logarithmic, power, absolute value, and complex conversions. Implementations rely on the underlying function family defined in math.h and the complex types from complex.h such as double _Complex. The macros evaluate expressions using type-generic selection rules similar to those discussed in standards work by ISO/IEC JTC 1/SC 22/WG 14 and used in runtime libraries like glibc and musl libc. Because macros perform token substitution, interactions with macros in projects like Boost (C++) library or language standards such as C11 and C17 must be considered, and toolchains like GCC and Clang implement behavior consistent with committee directives from ISO.

Type Generic Mathematics in C Standard

C standard text in C99 and later revisions codifies type-generic math via tgmath.h, embedding normative language that ties macros to function overload resolution rules and complex type promotions defined elsewhere in the standard. Debates in standards meetings involving delegates from Microsoft, IBM, Intel, and academic contributors influenced wording that impacts implementations in platforms like FreeBSD and OpenBSD. Subsequent corrections and defect reports tracked by committees such as WG14 and edits coordinated with bodies like ISO and IEC shaped behavior preserved into C11 and C17.

Examples and Usage

Common usage patterns demonstrate calling generic functions without caring for float or complex variants. For instance, calling the macro-named sin on a float, double, long double, or complex operand dispatches to sinf, sin, sinl, csin, or csinf appropriately; similar behavior applies to exp, log, pow and hypot. Popular codebases from organizations such as NASA, Google, Facebook, and academic software from University of California, Berkeley exploit this to reduce boilerplate. Care must be taken with macros in contexts involving inline functions, linkage in POSIX threads, and name collision with user-defined symbols in projects like Apache Software Foundation offerings.

Compatibility and Portability

Portability concerns center on availability and precise dispatch semantics across implementations like glibc, musl libc, Newlib, and vendor runtimes including Microsoft Visual C++ Runtime Library. Some environments historically omitted tgmath.h or provided limited support, prompting portability layers in cross-platform projects such as CMake-managed builds and portability libraries maintained by GNU and LLVM ecosystems. Interaction with language bindings—e.g., Python (programming language) C extensions, R (programming language) native code, and Julia (programming language) wrappers—requires attention to header availability and calling conventions specified by compilers such as GCC and Clang (compiler). Implementers must also consider changes in later C revisions and vendor-specific extensions documented by entities like ISO.

Category:C (programming language) headers