Macros

Macros - C Preprocessor Macro language

C's preprocessor language is an important feature and tool in the development space of C language projects. This local wiki page captures some references to preprocessor macro language.

^ General Articles about Macros

Some general and comprehensive discussions of C macros can be found at:

1. https://home.cs.colorado.edu/~main/cs1300/doc/gnu/cpp_1.html
2. https://stackoverflow.com/questions/4674480/do-whilefalse-pattern
   
3. https://www.mikeash.com/pyblog/friday-qa-2010-12-31-c-macro-tips-and-tricks.html
   
4. https://en.wikipedia.org/wiki/C_preprocessor#X-Macros
   
5. https://en.wikipedia.org/wiki/X_macro
   

^ do while(0)

Articles on the use of C language 'do while(0)' construct in macros. The do while(0) construct is the only C syntax which expands correctly from C macros regardless of the use of curly braces and semicolons around the given macro.

• https://hownot2code.wordpress.com/2016/12/05/do-while-0-in-macros/

^ stringification macro pair

A useful macro pair, and this must be a macro pair, is the following set of defines. These defines will accept a string and put double quotes around it:

  #define TO_QUOTE_STRING(string) #string
  #define WRAPPER_TO_QUOTE_STRING(token) TO_QUOTE_STRING(string)

Guy Rutenberg explains this C pre-processor pattern:

• https://www.guyrutenberg.com/2008/12/20/expanding-macros-into-string-constants-in-c/

The core rule at play is that C preprocessor does not expand macros preceded by the `#` preprocessor directive, the directive to quote a token. By creating a wrapping macro which does not call the `#` directive, the argument to the wrapper is expanded and then passed to the quoting directive.

^ fallthrough macro

The `__fallthrough()` macro appears to be a C++ macro. It may be found among Zephyr RTOS 3.4.0 source tree contents. An article on the concept of "fall through" in C switch statements:

• https://www.quora.com/What-is-the-fall-through-behavior-in-C-programming-languages-switch-case-statements

^ X macro idiom

X macros in C, a pattern involving nested macros makes use of nesting an initially declared and not defined macro within another macro. Danilafe and Phillip Trudeau offer the following blog posts on this topic:

• https://danilafe.com/blog/chapel_x_macros/
• https://philliptrudeau.com/blog/x-macro

Macro tips and idioms:

• https://github.com/pfultz2/Cloak/wiki/C-Preprocessor-tricks,-tips,-and-idioms

^ FOREACH macro implementations (may not be fully possible)

• https://dev.to/sgf4/foreach-macro-in-c-48ic

• https://dev.to/sgf4/repeat-macro-in-c-2hh0

Macro examples from Zephyr RTOS release 3.7.1:

``` ./include/zephyr/devicetree.h:4527:#define DT_INST_FOREACH_STATUS_OKAY(fn) \ ./include/zephyr/devicetree.h:4544:#define DT_INST_FOREACH_STATUS_OKAY_VARGS(fn, ...) \ ```

Related to Zephyr RTOS sys util macros and Zephyr's _COND_CODE_1 and _COND_CODE_0 macros:

• Jens Gustedt Wordpress article Empty Macro Detection

^ CONTAINER_OF macro

Helpful blogpost by Radek Pazdera, full-stack software engineer based in London . . .

• https://radek.io/posts/magical-container_of-macro/

See also 2026 Q1 local page on developers.

^ To use GCC to see macro expansion

Here is an example shell script which invokes gcc on a single C source file, and causes only the preprocessor to execute. This results in a display of all preprocessor macros:

#!/bin/bash

# References:
#   * https://gcc.gnu.org/onlinedocs/gcc-3.2.2/cpp/Search-Path.html

# $workspace/zephyr/subsys/testsuite/include/zephyr/fff.h

gcc -E \
-I../../../../../zephyr/subsys/testsuite/include \
-I../../../../../zephyr/include \
./unit-test-mocked-functions.h

exit $?