Keil™, An ARM® Company

RealView Compiler User's Guide

Library features

1.4.2. Library features

The C99 standard introduces several new library features of interest to programmers, including:

  • Some features similar to extensions to the C90 standard libraries offered in UNIX standard libraries, for example, the snprintf family of functions.

  • Some entirely new library features, for example the standardized floating‑point environment offered in <fenv.h>.

A selection of new library features of C99 that might be of particular interest are discussed in the following sections.

Additional math library functions in <math.h>

C99 supports additional macros, types, and functions in the standard header <math.h> that are not found in the corresponding C90 standard header.

New macros found in C99 that are not found in C90 include:

INFINITY // positive infinity
NAN      // IEEE not‑a‑number

New generic function macros found in C99 that are not found in C90 include:

#define isinf(x) // non‑zero only if x is positive or negative infinity
#define isnan(x) // non‑zero only if x is NaN
#define isless(x, y) // 1 only if x < y and x and y are not NaN, and 0 otherwise
#define isunordered(x, y) // 1 only if either x or y is NaN, and 0 otherwise

New mathematical functions found in C99 that are not found in C90 include:

double acosh(double x); // hyperbolic arccosine of x
double asinh(double x); // hyperbolic arcsine of x
double atanh(double x); // hyperbolic arctangent of x
double erf(double x); // returns the error function of x
double round(double x); // returns x rounded to the nearest integer
double tgamma(double x); // returns the gamma function of x

C99 supports the new mathematical functions for all real floating‑point types.

Single precision versions of all existing <math.h> functions are also supported.

Boolean type and <stdbool.h>

C99 introduces the native type _Bool. The associated standard header <stdbool.h> introduces the macros bool, true and false for Boolean tests. For example:

#include <stdbool.h>

bool foo(FILE *str)
{
    bool err = false;

    ...
    if (!fflush(str))
    {
        err = true;
    }
    ...
    return err;
}

Note

The C99 semantics for bool are intended to match those of C++.

Extended integer types and functions in <inttypes.h> and <stdint.h>

In C90, the long data type can serve both as the largest integral type, and as a 32‑bit container. C99 removes this ambiguity through the new standard library header files <inttypes.h> and <stdint.h>.

The header file <stdint.h> introduces the new types:

  • intmax_t and uintmax_t, which are maximum width signed and unsigned integer types

  • intptr_t and unintptr_t, which are integer types capable of holding signed and unsigned object pointers.

The header file <inttypes.h> provides library functions for manipulating values of type intmax_t, including:

intmax_t imaxabs(intmax_t x); // absolute value of x
imaxdiv_t imaxdiv(intmax_t x, intmax_t y) // returns the quotient and remainder
                                          // of x / y

Floating-point environment access in <fenv.h>

The C99 standard header file <fenv.h> provides access to an IEEE 754‑compliant floating‑point environment for numerical programming. The library introduces two types and numerous macros and functions for managing and controlling floating‑point state.

The new types supported are:

  • fenv_t, representing the entire floating‑point environment

  • fexcept_t, representing the floating‑point state.

New macros supported include:

  • FE_DIVBYZERO, FE_INEXACT, FE_INVALID, FE_OVERFLOW and FE_UNDERFLOW for managing floating‑point exceptions

  • FE_DOWNWARD, FE_TONEAREST, FE_TOWARDZERO, FE_UPWARD for managing rounding in the represented rounding direction

  • FE_DFL_ENV, representing the default floating‑point environment.

New functions include:

int feclearexcept(int ex); // clear floating‑point exceptions selected by ex
int feraiseexcept(int ex); // raise floating point exceptions selected by ex
int fetestexcept(int ex); // test floating point exceptions selected by x
int fegetround(void); // return the current rounding mode
int fesetround(int mode); // set the current rounding mode given by mode
int fegetenv(fenv_t *penv); return the floating‑point environment in penv
int fesetenv(const fenv_t *penv); // set the floating‑point environment to penv

snprintf family of functions in <stdio.h>

Using the sprintf family of functions found in the C90 standard header <stdio.h> can be dangerous. In the statement:

sprintf(buffer, size, "Error %d: Cannot open file '%s'", errno, filename);

the variable size specifies the minimum number of characters to be inserted into buffer. Consequently, more characters can be output than might fit in the memory allocated to the string.

The snprintf functions found in the C99 version of <stdio.h> are safe versions of the sprintf functions that prevent buffer overrun. In the statement:

snprintf(buffer, size, "Error %d: Cannot open file '%s'", errno, filename);

the variable size specifies the maximum number of characters that can be inserted into buffer. The buffer can never be overrun, provided its size is always greater than the size specified by size.

Type-generic math macros in <tgmath.h>

The new standard header <tgmath.h> defines several families of mathematical functions that are type generic in the sense that they are overloaded on floating‑point types. For example, the trigonometric function cos works as if it has the overloaded declaration:

extern float cos(float x);
extern double cos(double x);
extern long double cos(long double x);
...

A statement such as:

p = cos(0.78539f); // p = cos(pi / 4)

calls the single‑precision version of the cos function, as determined by the type of the literal 0.78539f.

Note

Type‑generic families of mathematical functions can be defined in C++ using the operator overloading mechanism. The semantics of type-generic families of functions defined using operator overloading in C++ are different from the semantics of the corresponding families of type‑generic functions defined in <tgmath.h>.

Copyright © 2007 ARM Limited. All rights reserved.ARM DUI 0375A