Page History

An unsafe function-like macro is one that evaluates a parameter whose expansion results in evaluating one of its parameters more than once in the code expansion or never evaluates the parameter or not at all. Never invoke an unsafe macro with arguments containing an assignment, increment, decrement, volatile access, input/output, or other expressions with side effects (including function calls, which may cause side effects).

The documentation for unsafe macros must warn about putting should warn against invoking them with arguments with side effects on the invocation, but the responsibility is on the programmer using the macro. Because of the risks associated with their use, it is recommended that you avoid the creation of unsafe macro functionsfunction-like macros be avoided. (See See PRE00-C. Prefer inline or static functions to function-like macros.)

The assert() macro is an excellent example of an unsafe macro. Its argument may be evaluated once or not at all, depending on the NDEBUG macro. For more information, see EXP31-C. Avoid side effects in assertionsThis rule is similar to EXP44-C. Do not rely on side effects in operands to sizeof, _Alignof, or _Generic.

Noncompliant Code Example

One problem with unsafe macros is is side effects on macro arguments, as shown by this noncompliant code example:

#define ABS(x) (((x) < 0) ? -(x) : (x))
 
void func(int n) {
  /* ... Validate that n is within the desired range */
  int m = ABS(++n);

  /* ... */
}

The invocation of the ABS() macro in this example expands to

...

The resulting code is well defined but causes n to be incremented twice rather than once.

Compliant Solution

One In this compliant solution is simply not to invoke an unsafe macro with arguments containing an assignment, increment, decrement, or function call, as in the following example:, the increment operation ++n is performed before the call to the unsafe macro.

#define ABS(x) (((x) < 0) ? -(x) : (x)) /* UNSAFE */
 
void func(int n) {
  /* ... Validate that n is within the desired range */
  ++n;
  int m = ABS(n);

  /* ... */
}

Note the comment declaring warning programmers that the macro is unsafe as a warning for programmers. Alternatively, the . The macro can also be renamed ABS_UNSAFE() to make it painfully apparent clear that the macro is unsafe.

Compliant Solution

...

This compliant solution, like all the compliant solutions for this rule, has undefined behavior if the argument to ABS() is equal to the minimum (most negative) value for the signed integer type. (See INT32-C. Ensure that operations on signed integers do not result in overflow for more information.)

Compliant Solution

This compliant solution follows the guidance of PRE00-C. Prefer inline or static functions to function-like macros

...

by defining an inline function iabs() to replace the ABS() macro. Unlike the ABS() macro, which operates on operands of any type, the iabs() function will truncate arguments of types wider than int whose value is not in range of the latter type.

#include <complex.h>
#include <math.h>
 
static inline int absiabs(int x) {
  return (((x) < 0) ? -(x) : (x));
}
 
void func(int n) {
  /* ... Validate that n is within the desired range */

int m = absiabs(++n);

  /* ... */
}

Compliant Solution

A more flexible compliant solution is to declare the This solution eliminates the problem of recalling which macros are safe and which are not. Unlike the ABS() macro , which operates on operands of any type, the abs() function accepts arguments only of type int. C11 provides a way to overload expressions with arguments of different types, but C99 provides no such mechanism. Consequently, there is no way to achieve such genericity using the facilities of the standard C99 language. However, some C implementations provide extensions that make it possible to solve the original problem without using functionsusing a _Generic selection. To support all arithmetic data types, this solution also makes use of inline functions to compute integer absolute values. (See PRE00-C. Prefer inline or static functions to function-like macros and PRE12-C. Do not define unsafe macros.)

According to the C Standard, 6.5.1.1, paragraph 3 [ISO/IEC 9899:2011]:

The controlling expression of a generic selection is not evaluated. If a generic selection has a generic association with a type name that is compatible with the type of the controlling expression, then the result expression of the generic selection is the expression in that generic association. Otherwise, the result expression of the generic selection is the expression in the default generic association. None of the expressions from any other generic association of the generic selection is evaluated.

Because the expression is not evaluated as part of the generic selection, the use of a macro in this solution is guaranteed to evaluate the macro parameter v only once.

#include <complex.h>
#include <math.h>
 
static inline long long llabs(long long v) {
  return v < 0 ? -v : v;
}
static inline long labs(long v) {
  return v < 0 ? -v : v;
}
static inline int iabs(int v) {
  return v < 0 ? -v : v;
}
static inline int sabs(short v) {
  return v < 0 ? -v : v;
}
static inline int scabs(signed char v) {
  return v < 0 ? -v : v;
}
 
#define ABS(v)  _Generic(v, signed char : scabs, \
                            short : sabs, \
                            int : iabs, \
                            long : labs, \
                            long long : llabs, \
                            float : fabsf, \
                            double : fabs, \
                            long double : fabsl, \
                            double complex : cabs, \
                            float complex : cabsf, \
                            long double complex : cabsl)(v)
 
void func(int n) {
  /* Validate that n is within the desired range */
  int m = ABS(++n);
  /* ... */
}

Generic selections were introduced in C11 and are not available in C99 and earlier editions of the C Standard.

Compliant Solution (GCC)

GCC's Statement Expressions along with the s __typeof extension make makes it possible to declare and assign the value of the macro operand to a temporary of the same type and perform the computation on the temporary, thus consequently guaranteeing that the operand will be evaluated exactly once. Another GCC extension, known as statement expression, makes it possible for the block statement to appear where an expression is expected:

#define ABS(x)  __extension__ ({ __typeof (x) __tmp = x; __ \
                    tmp < 0 ? -__tmp : __tmp; })

Note that relying on such extensions makes code nonportable and goes against violates MSC14-C. Do not introduce unnecessary platform dependencies.

This code comes very close to violating DCL37-C. Do not declare or define a reserved identifier. It technically complies with this rule because it falls under exception DCL37-EX1. However, this code is potentially unsafe if it were invoked with a variable named __tmp. Such calling code would constitute a genuine violation of DCL37-C. Finally, this code is unsafe if it is ever invoked on a platform where __tmp actually has special meaning (see DCL37-C for more information). These are considered acceptable problems, as C provides no mechanism to declare a variable in a scope that is guaranteed to be distinct from all other variables in the same scope.

Exceptions

Noncompliant Code Example (assert())

The assert() macro is a convenient mechanism for incorporating diagnostic tests in code. (See MSC11-C. Incorporate diagnostic tests using assertions.) Expressions used as arguments to the standard assert() macro should not have side effects. The behavior of the assert() macro depends on the definition of the object-like macro NDEBUG. If the macro NDEBUG is undefined, the assert() macro is defined to evaluate its expression argument and, if the result of the expression compares equal to 0, call the abort() function. If NDEBUG is defined, assert is defined to expand to ((void)0). Consequently, the expression in the assertion is not evaluated, and no side effects it may have had otherwise take place in non-debugging executions of the code.

This noncompliant code example includes an assert() macro containing an expression (index++) that has a side effect:

#include <assert.h>
#include <stddef.h>
  
void process(size_t index) {
  assert(index++ > 0); /* Side effect */
  /* ... */
}

Compliant Solution (assert())

This compliant solution avoids the possibility of side effects in assertions by moving the expression containing the side effect outside of the assert() macro.

#include <assert.h>
#include <stddef.h>
  
void process(size_t index) {
  assert(index > 0); /* No side effect */
  ++index;
  /* ... */
}

Exceptions

PRE31-C-PRE31-EX1: An exception can be made for invoking an unsafe macro with a function call argument provided that the function has no side effects. However, it is easy to forget about obscure side effects that a function might have, especially library functions for which source code is not available; even changing errno is a side effect. Unless the function is user-written and does nothing but perform a computation and return its result without calling any other functions, it is likely that many developers will forget about some side effect. Consequently, although this exception is allowed, it is not recommendedmust be used with great care.

Risk Assessment

Invoking an unsafe macro with an argument that has side effects may cause those side effects to occur more than once. This practice can lead to unexpected program behavior.

Automated Detection

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

Related Guidelines

 Bibliography

Key here (explains table format and definitions)

Key here (explains table format and definitions)

Taxonomy	Taxonomy item	Relationship

Bibliography

...

...

Image Modified Image Modified Image Modified