# man > cpp(1)

yaml
---
type: CommandReference
command: cpp
mode: man
section: 1
source: man-pages
---
## Quick Reference

- `cpp input.c output.i` — Preprocess input to output
- `cpp -DNAME=value input.c` — Define a macro
- `cpp -UNAME input.c` — Undefine a macro
- `cpp -I/path/to/headers input.c` — Add include search path
- `cpp -M input.c` — Generate Make dependencies
- `cpp -MM input.c` — Generate dependencies for user headers only
- `cpp -M -MF deps.d input.c` — Write dependencies to file
- `cpp -C input.c` — Preserve comments in output

## Name

cpp — The C Preprocessor (GNU)

## Synopsis

`cpp [options] infile [[-o] outfile]`

Options: `-Dmacro[=defn]`, `-Umacro`, `-Idir`, `-iquote dir`, `-M`, `-MM`, `-MG`, `-MF file`, `-MP`, `-MQ target`, `-MT target`, `-include file`, `-imacros file`, `-undef`, `-pthread`, `-traditional-cpp`, `-trigraphs`, `-P`, `-C`, `-CC`, `-H`, `-dM`, `-dD`, `-dN`, `-dI`, `-dU`, `-fpreprocessed`, `-fdirectives-only`, `-ftabstop=n`, `-ftrack-macro-expansion[=level]`, `-Wcomment`, `-Wtrigraphs`, `-Wundef`, `-Wunused-macros`, `-nostdinc`, `-nostdinc++`, `-iprefix prefix`, `-iwithprefix dir`, `-iwithprefixbefore dir`, `-isysroot dir`, `-imultilib dir`, `-fworking-directory`, `-fno-working-directory`, `-fmacro-prefix-map=old=new`, `-fexec-charset=charset`, `-fwide-exec-charset=charset`, `-finput-charset=charset`, `-fdollars-in-identifiers`, `-fextended-identifiers`, `-fno-canonical-system-headers`, `-fmax-include-depth=n`, `-fdebug-cpp`, `-A predicate=answer`, `-A -predicate`, `-remap`, `-I-`, `-Mno-modules`, `-MD`, `-MMD`, `-Wno-endif-labels`, `-Wexpansion-to-defined`.

## Description

The C preprocessor (`cpp`) is a macro processor used automatically by the C compiler to transform programs before compilation. It allows definition of macros (abbreviations for longer constructs). Intended for C, C++, and Objective-C source; may choke on non‑C lexical rules. GNU CPP provides a superset of ISO Standard C features. For strict ISO C, use `-std=c90`, `-std=c99`, `-std=c11`, `-std=c17` together with `-pedantic`. The preprocessor reads `infile` and all `#include`d files, writing output to `outfile`. If `-` is used for either file, standard input/output is assumed. The `-o outfile` option can specify the output file.

## Options

### Macro Definition

- `-D name` — Predefine `name` as macro with definition `1`.
- `-D name=definition` — Predefine with given definition (tokenized; truncated by embedded newlines). For function‑like macros, quote the argument list: `-D'name(args...)=definition'`.
- `-U name` — Cancel any previous definition of `name`.
- `-undef` — Do not predefine system‑specific or GCC‑specific macros (standard predefined macros remain).
- `-pthread` — Define additional macros for POSIX threads (supported on GNU/Linux, most Unix, Cygwin, MinGW).

### Include Path

- `-I dir` — Add directory to search for `#include "..."` and `#include <...>`.
- `-iquote dir` — Add directory to search only for `#include "..."`.
- `-isystem dir` — Add directory as a system include directory (searched after `-I`, before standard system dirs).
- `-idirafter dir` — Add directory to search after standard system directories.
- `-include file` — Process `file` as if `#include "file"` appeared as first line of source (searched in working directory first).
- `-imacros file` — Like `-include` but discard output; only macros defined remain.
- `-nostdinc` — Do not search standard system directories.
- `-nostdinc++` — Do not search C++‑specific standard directories.
- `-iprefix prefix` — Specify prefix for subsequent `-iwithprefix` options.
- `-iwithprefix dir` — Append `dir` to prefix, add to include search path (after `-idirafter`).
- `-iwithprefixbefore dir` — Append `dir` to prefix, add to include search path (before `-I`).
- `-isysroot dir` — Like `--sysroot` but only for headers (except Darwin).
- `-imultilib dir` — Use `dir` as subdirectory of target‑specific C++ headers.
- `-I-` — Split `-I` directories: those before `-I-` are only for `#include "..."`, those after for all `#include`; also inhibits search of current file directory for `#include "..."`.

### Dependency Output

- `-M` — Generate Make rule for dependencies (including system headers). Implies `-E` and suppresses warnings with `-w`.
- `-MM` — Like `-M` but only user headers (not system headers).
- `-MF file` — Write dependency rules to `file` (with `-M`/`-MM`). If `file` is `-`, write to stdout.
- `-MG` — Treat missing headers as generated files; add to dependency list without error.
- `-MP` — Add a dummy rule for each dependency header (no prerequisites).
- `-MT target` — Set the target of the dependency rule (exact string).
- `-MQ target` — Like `-MT` but quote Make‑special characters.
- `-MD` — Equivalent to `-M -MF file` where `file` is derived from `-o` or input filename with `.d` suffix. Does not imply `-E`.
- `-MMD` — Like `-MD` but only user headers.
- `-Mno-modules` — Disable dependency generation for compiled module interfaces.

### Output Control

- `-C` — Preserve comments in output (except in directives). Comments become tokens; may affect directive recognition.
- `-CC` — Like `-C` but also preserve comments inside macros (converts C++‑style to C‑style).
- `-P` — Do not generate `#line` directives.
- `-traditional` / `-traditional-cpp` — Imitate pre‑standard C preprocessors. Only supported with `-E` or when invoking CPP explicitly.
- `-trigraphs` — Support ISO C trigraphs (e.g., `??/` becomes `\`).
- `-fpreprocessed` — Indicate input is already preprocessed (suppress macro expansion, trigraphs, etc.). Implicit for `.i`, `.ii`, `.mi` files.
- `-fdirectives-only` — Handle directives only, no macro expansion (with `-E`). With `-fpreprocessed`, disables most builtin macros.
- `-ftabstop=n` — Set tab stop distance (1–100; default 8).
- `-ftrack-macro-expansion[=level]` — Track token locations across macro expansions. Level 0: off, 1: degraded (minimal memory), 2: full (default).
- `-fmacro-prefix-map=old=new` — Map `__FILE__` and `__BASE_FILE__` paths (replace `old` with `new`).
- `-fexec-charset=charset` — Execution character set (default UTF‑8).
- `-fwide-exec-charset=charset` — Wide execution character set (default UTF‑32/16 based on `wchar_t` width and endianness).
- `-finput-charset=charset` — Input character set (default UTF‑8; overrides locale).
- `-fworking-directory` — Emit linemarker with current working directory (enabled by default with debug info; use `-fno-working-directory` to disable; no effect with `-P`).
- `-fdollars-in-identifiers` — Accept `$` in identifiers.
- `-fextended-identifiers` — Accept universal character names and extended characters (default for C99+ and C++).
- `-fno-canonical-system-headers` — Do not shorten system header paths with canonicalization.
- `-fmax-include-depth=n` — Maximum depth of nested `#include` (default 200).
- `-remap` — Work around file systems with very short file names (e.g., MS‑DOS).
- `-A predicate=answer` — Make an assertion (preferred form).
- `-A -predicate` — Cancel an assertion.

### Debugging

- `-H` — Print names of included files, indented by depth. Precompiled headers: `...!` for valid, `...x` for invalid.
- `-dM` — List all `#define` directives (including predefined) instead of normal output.
- `-dD` — Like `-dM` but also include preprocessing output; predefined macros excluded.
- `-dN` — Like `-dD` but emit only macro names, not expansions.
- `-dI` — Output `#include` directives in addition to preprocessing output.
- `-dU` — Like `-dD` but only macros that are expanded or tested; `#undef` directives also output.
- `-fdebug-cpp` — Dump debugging information about location maps (only with `-E` or CPP).

### Warnings

- `-Wcomment` / `-Wcomments` — Warn on `/*` inside `/*` comment or backslash‑newline in `//` comment. Enabled by `-Wall`.
- `-Wtrigraphs` — Warn if trigraphs change meaning. Implied by `-Wall`; overridden by `-trigraphs -Wno-trigraphs` to get conversion without warnings.
- `-Wundef` — Warn if undefined identifier is evaluated in `#if`.
- `-Wexpansion-to-defined` — Warn when `defined` is encountered in macro expansion. Enabled by `-Wpedantic` and `-Wextra`.
- `-Wunused-macros` — Warn about macros defined in main file that are unused (except built‑in, command‑line, and include‑file macros). A dummy use like `#if defined the_macro` can suppress.
- `-Wno-endif-labels` — Do not warn when `#else` or `#endif` are followed by text (on by default).

## Environment

- `CPATH` — List of directories (colon‑separated on Unix, semicolon on Windows) to search as with `-I`, after command‑line `-I` options.
- `C_INCLUDE_PATH` — List of directories for C, searched as with `-isystem`, after command‑line `-isystem`.
- `CPLUS_INCLUDE_PATH` — List of directories for C++.
- `OBJC_INCLUDE_PATH` — List of directories for Objective‑C.
- `DEPENDENCIES_OUTPUT` — Set to `file` or `file target` to output Make dependencies (equivalent to `-MM -MF` with optional `-MT`). System headers ignored.
- `SUNPRO_DEPENDENCIES` — Like `DEPENDENCIES_OUTPUT` but includes system headers (implies `-M`). Main input file omitted.
- `SOURCE_DATE_EPOCH` — UNIX timestamp (seconds since 1970‑01‑01) to replace `__DATE__` and `__TIME__` for reproducible builds.

## See Also

- [gcc(1)](http://localhost/phpMan.php/man/gcc/1/markdown)
- [gpl(7)](http://localhost/phpMan.php/man/gpl/7/markdown)
- [gfdl(7)](http://localhost/phpMan.php/man/gfdl/7/markdown)
- [fsf-funding(7)](http://localhost/phpMan.php/man/fsf-funding/7/markdown)
- Info entries for `cpp` and `gcc`