CPP(1)

💅 CPP — the C preprocessor, but make it make sense

okay so bestie, welcome to cpp from the General Commands Manual (section 1, as the header up there says). she's the C preprocessor and she's lowkey iconic. let's get into it ✨

---

🌸 NAME 🌸

cpp — the C preprocessor. that's it, that's her. 👑

---

🎀 SYNOPSIS 🎀

cpp [-ACEMPtVv] [-D macro[=value]] [-d flags] [-I path] [-i file]
    [-S path] [-U macro] [infile | -] [outfile]

like look at all those flags. she's got range. 💅

---

🦋 DESCRIPTION 🦋

So cpp is a macro preprocessor — she's the one the pcc(1) compiler drags along to do the pre-work. Her main gigs are:

• including header files
• expanding macro definitions
• discarding comments
• doing conditional compilation

and she's written to comply with the ISO/IEC 9899:1999 spec (aka "ISO C99"). no cap, she follows the standard fr fr.

Now, the infile input file? totally optional. if you don't give her one, or if the file name is literally - (just a dash, the loneliest character), cpp reads her initial file from standard input. and the outfile output file? also optional. if you don't hand her one, output goes to standard output. she's flexible like that. 🫶

The options are as follows:

---

✨ OPTIONS ✨

• -A — for assembler-with-cpp input: treat non-directive lines that start with a # as comments. little assembler moment. 🛠️
• -C — do not discard comments. keep them! she's sentimental. 💬
• -D macro[=value] — create a macro definition before processing any input, exactly as if this directive had appeared in the source:

#define macro value

and if you don't set value on the command line? she just uses a value of 1. default queen. 1️⃣

• -d flags — modify output according to flags, which can be a list of character flags. the flags currently supported are:
  • M — do not process any input, but instead output a list of #define statements for all defined macros other than builtin macros (peep the builtin macros section below 👇).
  • any unknown flags are just ignored. she's not gonna fight you about it.
• -E — modify the exit code, if there were any warnings. yes this changes how she clocks out. see EXIT STATUS.
• -I path — add path to the list of directories searched by the #include directive. this can be used to override system include directories (see the -S option). -I can be specified multiple times and is cumulative. stack 'em up. 📚
• -i file — include a file before processing any input, as if this directive had appeared in the source:

#include "file"

-i can be specified multiple times to include several files. the more the merrier honestly.

• -M — instead of producing a processed C code file, output a list of dependencies for make(1), detailing the files that need to be processed when compiling the input. very build-system coded of her. 🏗️
• -P — inhibit generation of line markers. this is sometimes useful when running the preprocessor on something that is not C code. she's versatile bestie.
• -S path — add path to the list of system directories searched by the #include directive. the -S option may be specified multiple times and is cumulative.
• -t — traditional cpp syntax. this means she does not define the __TIME__, __DATE__, __STDC__, and __STDC_VERSION__ macros. going old school, vintage vibes. 🕰️
• -U macro — undefine a macro before processing any input, as if this directive had appeared in the source:

#undef macro

• -V — verbose debugging output. -V can be repeated for greater detail. (this is only available if the cpp program was built with PCC_DEBUG defined, which is the default). she will overshare, and honestly? we love that. 🗣️
• -v — display version.

The -D, -i and -U options are processed in the order that they appear on the command line, before any input is read but after the command line options have been scanned. order matters, bestie. don't @ me.

---

Files referenced by the #include directive as "..." are first looked for in the current directory, then as per ⟨...⟩ files. and ⟨...⟩ files are first looked for in the list of directories provided by any -I options, then in the list of system directories provided by any -S options.

⚠️ heads up though: cpp does not define any include directories by default. if no -I or -S options are given, then only the current directory will be searched and no system files will be found. so like... give her a map, okay? 🗺️

🔮 Builtin Macros 🔮

a few macros are interpreted inside the cpp program itself. she just knows these. built different.

• __DATE__ — expands to a quoted string literal containing the date in the form "Mmm dd yyyy", where the names of the months are the same as those generated by the asctime(3) function, and the first character of dd is a space character if the value is less than 10. tiny formatting detail, huge energy. 📅
• __FILE__ — expands to a quoted string literal containing the presumed name of the current source file. when reading source from standard input, it expands to "⟨stdin⟩".
• __LINE__ — expands to an integer constant representing the presumed line number of the source line containing the macro.
• __STDC__ — expands to the integer constant 1, meaning that the compiler conforms to ISO/IEC 9899:1990 (aka "ISO C90").
• __STDC_VERSION__ — expands to the integer constant 199901L, indicating that cpp conforms to ISO/IEC 9899:1999 (aka "ISO C99").
• __TIME__ — expands to a quoted string literal containing the time in the form "hh:mm:ss" as generated by the asctime(3) function. ⏰

also see the -t option, she mentioned it earlier for a reason.

---

💀 EXIT STATUS 💀

the cpp utility exits with one of the following values:

1. 0 — Successfully finished. she ate and left no crumbs. ✅
2. 1 — An error occurred. 😭
3. 2 — The -E option was given, and warnings were issued. the -E special. 🙈

---

🌈 SEE ALSO 🌈

as(1), ccom(1), make(1), pcc(1), asctime(3)

(the whole friend group, honestly. go say hi.)

---

📜 HISTORY 📜

The cpp command comes from the original Portable C Compiler by S. C. Johnson, written in the late 70's. the code originates from the V6 preprocessor with some additions from V7 cpp and ansi/c99 support. so she's got lore. deep lore. 🫡

A lot of the PCC code was rewritten by Anders Magnusson. king behavior.

This product includes software developed or owned by Caldera International, Inc.

---

okay and that's the whole page bestie!! this one shipped out under Debian, dated February 26, 2013 — so yeah, vintage, but she still runs circles around everybody. stan cpp. periodt. 💖✨🎀🦋🌸💅🫶