Quick look at the C preprocessor

Introduction

Welcome to my blog post exploring the basics of the C preprocessor.
The C preprocessor is a macro processor which is used as part of the process of compiling C source code.
Macros are widely used when doing C programming, and a knowledge of how to use the C preprocessor will help you be a better C programmer.
All example code was testing used both GCC and Clang running on manjaro linux. Results may vary on other compilers and/or O.S.
From here on the C preprocessors will be abbreviated as 'CPP'

Basics

This first example will illustrate the very basics of macros.
This example has the preprocessor include a file, and also define two macros.

• #include <filename>
  • this has CPP include the contents of filename into the current file.
• #define macro body
  • The CPP replaces all occurrences of macro with body

In the follow example, we include stdio.h header into our file so that we have access to printf().
We also define a macro for PI which expands out into 3.14159 and one called str.
The code then shows a few examples of these macros being used. Nothing fancy or complicated but i think you get the idea.

Macros in C. code

Function like macros

We now move on to function like macros.
These are macros that we can use like functions.

• #define name(args) body defining a function like macro which can accept arguments.

To call a function like macro is very similar to calling a normal C function.

• name(args) calls a function like macro name with args.

In the example code, we create a function like macro which takes in a number and returns the square of it.

Function like macros in C. code

External files

This example we cover defining macros in another file and then using them in our current file.
We first define them in a file macros.h then include that in our file.
We can then use those macros in the current file just as before.

• #define "file" search for file in same directory as current file then include it into our current file.

Defining macros in an external file. code

External macros in macros.h. code

Conditional processing

We can use if like statements to conditionally control the CPP.
Depending on whether the conditions are true or false we can control how certain macros are handled or even if they exist in the file at all.
If you already understand if statements as they are regularly used in programming then this should be easy to understand.

• #if simple if statement. Checks for true/false
• #elifsame as an else if.
• #elsean else statement
• #ifdefif defined. Checks if a macro is defined, and if is, returns true,otherwise returns false.
• #ifndefif not defined. Checks to see if a macro is not defined.
• #endifEnds a if block.

In the example code we first create two macros to use.
We then use conditionals to conditionally define other macros which we then use in main()
In our code we also introduce #undef which undefines a macro.
try commenting out #undef X and also try defining a macro 'A' to see how this affects the output.

Conditional processing in C. code

Predefined macros

In this example I cover some common predefined macros.
These are macros which the complier already defines.
Some Caution, not every single one of these may be included in every single C compiler.

• __FILE__ returns the name of the file.
• __LINE__ returns the line number.
• __COUNTER__ a counter which starts at zero and increments by 1 on each call.
• __func__ returns the name of the function it is inside of.
• __DATE__ returns the current date.
• __TIME__ returns the time at which the CPP started running.

Predefined macros in C. code

Debugging using the CPP

This example will show a simple way to turn on/off debugging messages using conditionals and the CPP.
When DEBUG is defined as 1 and/or DEBUG_ALT is defined, debug messages get printed to STDERR.
Also shown is how to use a conditional to turn off a block of code without needing to delete it all or comment it all out.

Debugging using conditionals with the CPP. code

Macros with variable arguments

In this example we improve on our debugging by introducing variadic macros
These are macros which can take in a variable number of arguments.
We use them to handle the multiple arguments to a call to frpintf()

• #define macro(...) body
  • (...) this indicates that the macro can take variable arguments.
  • __VA_ARGS__ This represent the variable arguments.
    • this will expand out into each argument in the order that it was passed to the macro.

Using VA macro we can now call DEBUG_MSSG() with as many arguments as we need to handle our fprintf call.

macros with variable arguments. code

Using the CPP by itself

The CPP can be used as a standalone macro processor.
It is very limited in its functionality in this respect compared to a dedicated general purpose macro processor like m4.
But still, it can be put to some use.
Some reasons to use it as a standalone preprocessor:

• Debug your macros
  • you can view how your macros expand out so you can check for errors.
• learn more about macros
  • viewing how the CPP expands macros can help you learn about macro expansion.
• general macro processor
  • Use it in place of a dedicated general purpose macro processor.

There are a few ways to call the CPP by itself.
On a GNU/Linux system i know of three ways:

• CPP file
  • process file and prints result to stdout.
• gcc -E file
  • tells gcc to compile file but to stop after it runs the preprocessor.
• clang -E file
  • tell clang to compile file but to stop after running the preprocessor.

When using the CPP by itself, I recommend using the flags

• -P
  • This will stop the CPP from generating linemarkers.
• -C
  • this will keep comments. Normally CPP removes comments from files.

Comparing .c files to output of CPP

Below you can see the output of example1.c after running it through CPP.
You can see how the CPP expands the macros PI and str.
Compare this to the file example1.c to see how the CPP alters it.

output of CPP on example1.c

Using CPP as genreal purpose macro expander

In this example I use the CPP to exand macros into html tags.
This illustrates an example of how it can be used as a general purpose macro expander.
It also illustrates the weakness of using the CPP as such.
The CPP is designed for C code, when you try to use non standard C code with it, you can run into issues.

using CPP to expand macros into html tags. code

using the CPP for html tags

Run the CPP on this file and saving it as an .html file.
Inspecting the file reveals it to generate a valid html file. all macros expand properly.

html file generated by the CPP. code

You can then open the saved .html file in a browser to verify that it works.
So you see, it can be done, it's just not the best tool for the job.

opening the html file in a browser

Final remarks

The CPP provides some neat functionality to C programming.
In this post I have show the basics of its use when doing C programming, but also how it can be by itself.
To go further, I recommend you read the guide on the GCC preprocessor here.
All example code featured here can be found on github.