Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CPP(1)				      GNU				CPP(1)

       cpp - The C Preprocessor

       cpp [-Dmacro[=defn]...] [-Umacro]
	   [-Idir...] [-iquotedir...]
	   [-M|-MM] [-MG] [-MF filename]
	   [-MP] [-MQ target...]
	   [-MT	target...]
	   [-P]	[-fno-working-directory]
	   [-x language] [-std=standard]
	   infile outfile

       Only the	most useful options are	listed here; see below for the

       The C preprocessor, often known as cpp, is a macro processor that is
       used automatically by the C compiler to transform your program before
       compilation.  It	is called a macro processor because it allows you to
       define macros, which are	brief abbreviations for	longer constructs.

       The C preprocessor is intended to be used only with C, C++, and
       Objective-C source code.	 In the	past, it has been abused as a general
       text processor.	It will	choke on input which does not obey C's lexical
       rules.  For example, apostrophes	will be	interpreted as the beginning
       of character constants, and cause errors.  Also,	you cannot rely	on it
       preserving characteristics of the input which are not significant to
       C-family	languages.  If a Makefile is preprocessed, all the hard	tabs
       will be removed,	and the	Makefile will not work.

       Having said that, you can often get away	with using cpp on things which
       are not C.  Other Algol-ish programming languages are often safe
       (Pascal,	Ada, etc.) So is assembly, with	caution.  -traditional-cpp
       mode preserves more white space,	and is otherwise more permissive.
       Many of the problems can	be avoided by writing C	or C++ style comments
       instead of native language comments, and	keeping	macros simple.

       Wherever	possible, you should use a preprocessor	geared to the language
       you are writing in.  Modern versions of the GNU assembler have macro
       facilities.  Most high level programming	languages have their own
       conditional compilation and inclusion mechanism.	 If all	else fails,
       try a true general text processor, such as GNU M4.

       C preprocessors vary in some details.  This manual discusses the	GNU C
       preprocessor, which provides a small superset of	the features of	ISO
       Standard	C.  In its default mode, the GNU C preprocessor	does not do a
       few things required by the standard.  These are features	which are
       rarely, if ever,	used, and may cause surprising changes to the meaning
       of a program which does not expect them.	 To get	strict ISO Standard C,
       you should use the -std=c89 or -std=c99 options,	depending on which
       version of the standard you want.  To get all the mandatory
       diagnostics, you	must also use -pedantic.

       This manual describes the behavior of the ISO preprocessor.  To
       minimize	gratuitous differences,	where the ISO preprocessor's behavior
       does not	conflict with traditional semantics, the traditional
       preprocessor should behave the same way.	 The various differences that
       do exist	are detailed in	the section Traditional	Mode.

       For clarity, unless noted otherwise, references to CPP in this manual
       refer to	GNU CPP.

       The C preprocessor expects two file names as arguments, infile and
       outfile.	 The preprocessor reads	infile together	with any other files
       it specifies with #include.  All	the output generated by	the combined
       input files is written in outfile.

       Either infile or	outfile	may be -, which	as infile means	to read	from
       standard	input and as outfile means to write to standard	output.	 Also,
       if either file is omitted, it means the same as if - had	been specified
       for that	file.

       Unless otherwise	noted, or the option ends in =,	all options which take
       an argument may have that argument appear either	immediately after the
       option, or with a space between option and argument: -Ifoo and -I foo
       have the	same effect.

       Many options have multi-letter names; therefore multiple	single-letter
       options may not be grouped: -dM is very different from -d -M.

       -D name
	   Predefine name as a macro, with definition 1.

       -D name=definition
	   The contents	of definition are tokenized and	processed as if	they
	   appeared during translation phase three in a	#define	directive.  In
	   particular, the definition will be truncated	by embedded newline

	   If you are invoking the preprocessor	from a shell or	shell-like
	   program you may need	to use the shell's quoting syntax to protect
	   characters such as spaces that have a meaning in the	shell syntax.

	   If you wish to define a function-like macro on the command line,
	   write its argument list with	surrounding parentheses	before the
	   equals sign (if any).  Parentheses are meaningful to	most shells,
	   so you will need to quote the option.  With sh and csh,
	   -D'name(args...)=definition'	works.

	   -D and -U options are processed in the order	they are given on the
	   command line.  All -imacros file and	-include file options are
	   processed after all -D and -U options.

       -U name
	   Cancel any previous definition of name, either built	in or provided
	   with	a -D option.

	   Do not predefine any	system-specific	or GCC-specific	macros.	 The
	   standard predefined macros remain defined.

       -I dir
	   Add the directory dir to the	list of	directories to be searched for
	   header files.

	   Directories named by	-I are searched	before the standard system
	   include directories.	 If the	directory dir is a standard system
	   include directory, the option is ignored to ensure that the default
	   search order	for system directories and the special treatment of
	   system headers are not defeated .

       -o file
	   Write output	to file.  This is the same as specifying file as the
	   second non-option argument to cpp.  gcc has a different
	   interpretation of a second non-option argument, so you must use -o
	   to specify the output file.

	   Turns on all	optional warnings which	are desirable for normal code.
	   At present this is -Wcomment, -Wtrigraphs, -Wmultichar and a
	   warning about integer promotion causing a change of sign in "#if"
	   expressions.	 Note that many	of the preprocessor's warnings are on
	   by default and have no options to control them.

	   Warn	whenever a comment-start sequence /* appears in	a /* comment,
	   or whenever a backslash-newline appears in a	// comment.  (Both
	   forms have the same effect.)

	   @anchor{Wtrigraphs} Most trigraphs in comments cannot affect	the
	   meaning of the program.  However, a trigraph	that would form	an
	   escaped newline (??/	at the end of a	line) can, by changing where
	   the comment begins or ends.	Therefore, only	trigraphs that would
	   form	escaped	newlines produce warnings inside a comment.

	   This	option is implied by -Wall.  If	-Wall is not given, this
	   option is still enabled unless trigraphs are	enabled.  To get
	   trigraph conversion without warnings, but get the other -Wall
	   warnings, use -trigraphs -Wall -Wno-trigraphs.

	   Warn	about certain constructs that behave differently in
	   traditional and ISO C.  Also	warn about ISO C constructs that have
	   no traditional C equivalent,	and problematic	constructs which
	   should be avoided.

	   Warn	the first time #import is used.

	   Warn	whenever an identifier which is	not a macro is encountered in
	   an #if directive, outside of	defined.  Such identifiers are
	   replaced with zero.

	   Warn	about macros defined in	the main file that are unused.	A
	   macro is used if it is expanded or tested for existence at least
	   once.  The preprocessor will	also warn if the macro has not been
	   used	at the time it is redefined or undefined.

	   Built-in macros, macros defined on the command line,	and macros
	   defined in include files are	not warned about.

	   Note: If a macro is actually	used, but only used in skipped
	   conditional blocks, then CPP	will report it as unused.  To avoid
	   the warning in such a case, you might improve the scope of the
	   macro's definition by, for example, moving it into the first
	   skipped block.  Alternatively, you could provide a dummy use	with
	   something like:

		   #if defined the_macro_causing_the_warning

	   Warn	whenever an #else or an	#endif are followed by text.  This
	   usually happens in code of the form

		   #if FOO
		   #else FOO
		   #endif FOO

	   The second and third	"FOO" should be	in comments, but often are not
	   in older programs.  This warning is on by default.

	   Make	all warnings into hard errors.	Source code which triggers
	   warnings will be rejected.

	   Issue warnings for code in system headers.  These are normally
	   unhelpful in	finding	bugs in	your own code, therefore suppressed.
	   If you are responsible for the system library, you may want to see

       -w  Suppress all	warnings, including those which	GNU CPP	issues by

	   Issue all the mandatory diagnostics listed in the C standard.  Some
	   of them are left out	by default, since they trigger frequently on
	   harmless code.

	   Issue all the mandatory diagnostics,	and make all mandatory
	   diagnostics into errors.  This includes mandatory diagnostics that
	   GCC issues without -pedantic	but treats as warnings.

       -M  Instead of outputting the result of preprocessing, output a rule
	   suitable for	make describing	the dependencies of the	main source
	   file.  The preprocessor outputs one make rule containing the	object
	   file	name for that source file, a colon, and	the names of all the
	   included files, including those coming from -include	or -imacros
	   command line	options.

	   Unless specified explicitly (with -MT or -MQ), the object file name
	   consists of the basename of the source file with any	suffix
	   replaced with object	file suffix.  If there are many	included files
	   then	the rule is split into several lines using \-newline.  The
	   rule	has no commands.

	   This	option does not	suppress the preprocessor's debug output, such
	   as -dM.  To avoid mixing such debug output with the dependency
	   rules you should explicitly specify the dependency output file with
	   -MF,	or use an environment variable like DEPENDENCIES_OUTPUT.
	   Debug output	will still be sent to the regular output stream	as

	   Passing -M to the driver implies -E,	and suppresses warnings	with
	   an implicit -w.

       -MM Like	-M but do not mention header files that	are found in system
	   header directories, nor header files	that are included, directly or
	   indirectly, from such a header.

	   This	implies	that the choice	of angle brackets or double quotes in
	   an #include directive does not in itself determine whether that
	   header will appear in -MM dependency	output.	 This is a slight
	   change in semantics from GCC	versions 3.0 and earlier.


       -MF file
	   When	used with -M or	-MM, specifies a file to write the
	   dependencies	to.  If	no -MF switch is given the preprocessor	sends
	   the rules to	the same place it would	have sent preprocessed output.

	   When	used with the driver options -MD or -MMD, -MF overrides	the
	   default dependency output file.

       -MG In conjunction with an option such as -M requesting dependency
	   generation, -MG assumes missing header files	are generated files
	   and adds them to the	dependency list	without	raising	an error.  The
	   dependency filename is taken	directly from the "#include" directive
	   without prepending any path.	 -MG also suppresses preprocessed
	   output, as a	missing	header file renders this useless.

	   This	feature	is used	in automatic updating of makefiles.

       -MP This	option instructs CPP to	add a phony target for each dependency
	   other than the main file, causing each to depend on nothing.	 These
	   dummy rules work around errors make gives if	you remove header
	   files without updating the Makefile to match.

	   This	is typical output:

		   test.o: test.c test.h


       -MT target
	   Change the target of	the rule emitted by dependency generation.  By
	   default CPP takes the name of the main input	file, including	any
	   path, deletes any file suffix such as .c, and appends the
	   platform's usual object suffix.  The	result is the target.

	   An -MT option will set the target to	be exactly the string you
	   specify.  If	you want multiple targets, you can specify them	as a
	   single argument to -MT, or use multiple -MT options.

	   For example,	-MT '$(objpfx)foo.o' might give

		   $(objpfx)foo.o: foo.c

       -MQ target
	   Same	as -MT,	but it quotes any characters which are special to
	   Make.  -MQ '$(objpfx)foo.o' gives

		   $$(objpfx)foo.o: foo.c

	   The default target is automatically quoted, as if it	were given
	   with	-MQ.

       -MD -MD is equivalent to	-M -MF file, except that -E is not implied.
	   The driver determines file based on whether an -o option is given.
	   If it is, the driver	uses its argument but with a suffix of .d,
	   otherwise it	take the basename of the input file and	applies	a .d

	   If -MD is used in conjunction with -E, any -o switch	is understood
	   to specify the dependency output file (but @pxref{dashMF,,-MF}),
	   but if used without -E, each	-o is understood to specify a target
	   object file.

	   Since -E is not implied, -MD	can be used to generate	a dependency
	   output file as a side-effect	of the compilation process.

	   Like	-MD except mention only	user header files, not system header

       -x c
       -x c++
       -x objective-c
       -x assembler-with-cpp
	   Specify the source language:	C, C++,	Objective-C, or	assembly.
	   This	has nothing to do with standards conformance or	extensions; it
	   merely selects which	base syntax to expect.	If you give none of
	   these options, cpp will deduce the language from the	extension of
	   the source file: .c,	.cc, .m, or .S.	 Some other common extensions
	   for C++ and assembly	are also recognized.  If cpp does not
	   recognize the extension, it will treat the file as C; this is the
	   most	generic	mode.

	   Note: Previous versions of cpp accepted a -lang option which
	   selected both the language and the standards	conformance level.
	   This	option has been	removed, because it conflicts with the -l

	   Specify the standard	to which the code should conform.  Currently
	   CPP knows about C and C++ standards;	others may be added in the

	   standard may	be one of:

	       The ISO C standard from 1990.  c89 is the customary shorthand
	       for this	version	of the standard.

	       The -ansi option	is equivalent to -std=c89.

	       The 1990	C standard, as amended in 1994.

	       The revised ISO C standard, published in	December 1999.	Before
	       publication, this was known as C9X.

	       The 1990	C standard plus	GNU extensions.	 This is the default.

	       The 1999	C standard plus	GNU extensions.

	       The 1998	ISO C++	standard plus amendments.

	       The same	as -std=c++98 plus GNU extensions.  This is the
	       default for C++ code.

       -I- Split the include path.  Any	directories specified with -I options
	   before -I- are searched only	for headers requested with
	   "#include "file""; they are not searched for	"#include <file_".  If
	   additional directories are specified	with -I	options	after the -I-,
	   those directories are searched for all #include directives.

	   In addition,	-I- inhibits the use of	the directory of the current
	   file	directory as the first search directory	for "#include "file"".

	   This	option has been	deprecated.

	   Do not search the standard system directories for header files.
	   Only	the directories	you have specified with	-I options (and	the
	   directory of	the current file, if appropriate) are searched.

	   Do not search for header files in the C++-specific standard
	   directories,	but do still search the	other standard directories.
	   (This option	is used	when building the C++ library.)

       -include	file
	   Process file	as if "#include	"file""	appeared as the	first line of
	   the primary source file.  However, the first	directory searched for
	   file	is the preprocessor's working directory	instead	of the
	   directory containing	the main source	file.  If not found there, it
	   is searched for in the remainder of the "#include "..."" search
	   chain as normal.

	   If multiple -include	options	are given, the files are included in
	   the order they appear on the	command	line.

       -imacros	file
	   Exactly like	-include, except that any output produced by scanning
	   file	is thrown away.	 Macros	it defines remain defined.  This
	   allows you to acquire all the macros	from a header without also
	   processing its declarations.

	   All files specified by -imacros are processed before	all files
	   specified by	-include.

       -idirafter dir
	   Search dir for header files,	but do it after	all directories
	   specified with -I and the standard system directories have been
	   exhausted.  dir is treated as a system include directory.

       -iprefix	prefix
	   Specify prefix as the prefix	for subsequent -iwithprefix options.
	   If the prefix represents a directory, you should include the	final

       -iwithprefix dir
       -iwithprefixbefore dir
	   Append dir to the prefix specified previously with -iprefix,	and
	   add the resulting directory to the include search path.
	   -iwithprefixbefore puts it in the same place	-I would; -iwithprefix
	   puts	it where -idirafter would.

       -isysroot dir
	   This	option is like the --sysroot option, but applies only to
	   header files.  See the --sysroot option for more information.

       -isystem	dir
	   Search dir for header files,	after all directories specified	by -I
	   but before the standard system directories.	Mark it	as a system
	   directory, so that it gets the same special treatment as is applied
	   to the standard system directories.

       -cxx-isystem dir
	   Search dir for C++ header files, after all directories specified by
	   -I but before the standard system directories.  Mark	it as a	system
	   directory, so that it gets the same special treatment as is applied
	   to the standard system directories.

       -iquote dir
	   Search dir only for header files requested with "#include "file"";
	   they	are not	searched for "#include <file_",	before all directories
	   specified by	-I and before the standard system directories.

       -iremap src:dst
	   Replace the prefix src in __FILE__ with dst at expansion time.
	   This	option can be specified	more than once.	 Processing stops at
	   the first match.

	   @anchor{fdollars-in-identifiers} Accept $ in	identifiers.

	   Accept universal character names in identifiers.  This option is
	   experimental; in a future version of	GCC, it	will be	enabled	by
	   default for C99 and C++.

	   Indicate to the preprocessor	that the input file has	already	been
	   preprocessed.  This suppresses things like macro expansion,
	   trigraph conversion,	escaped	newline	splicing, and processing of
	   most	directives.  The preprocessor still recognizes and removes
	   comments, so	that you can pass a file preprocessed with -C to the
	   compiler without problems.  In this mode the	integrated
	   preprocessor	is little more than a tokenizer	for the	front ends.

	   -fpreprocessed is implicit if the input file	has one	of the
	   extensions .i, .ii or .mi.  These are the extensions	that GCC uses
	   for preprocessed files created by -save-temps.

	   Set the distance between tab	stops.	This helps the preprocessor
	   report correct column numbers in warnings or	errors,	even if	tabs
	   appear on the line.	If the value is	less than 1 or greater than
	   100,	the option is ignored.	The default is 8.

	   Set the execution character set, used for string and	character
	   constants.  The default is UTF-8.  charset can be any encoding
	   supported by	the system's "iconv" library routine.

	   Set the wide	execution character set, used for wide string and
	   character constants.	 The default is	UTF-32 or UTF-16, whichever
	   corresponds to the width of "wchar_t".  As with -fexec-charset,
	   charset can be any encoding supported by the	system's "iconv"
	   library routine; however, you will have problems with encodings
	   that	do not fit exactly in "wchar_t".

	   Set the input character set,	used for translation from the
	   character set of the	input file to the source character set used by
	   GCC.	 If the	locale does not	specify, or GCC	cannot get this
	   information from the	locale,	the default is UTF-8.  This can	be
	   overridden by either	the locale or this command line	option.
	   Currently the command line option takes precedence if there's a
	   conflict.  charset can be any encoding supported by the system's
	   "iconv" library routine.

	   Enable generation of	linemarkers in the preprocessor	output that
	   will	let the	compiler know the current working directory at the
	   time	of preprocessing.  When	this option is enabled,	the
	   preprocessor	will emit, after the initial linemarker, a second
	   linemarker with the current working directory followed by two
	   slashes.  GCC will use this directory, when it's present in the
	   preprocessed	input, as the directory	emitted	as the current working
	   directory in	some debugging information formats.  This option is
	   implicitly enabled if debugging information is enabled, but this
	   can be inhibited with the negated form -fno-working-directory.  If
	   the -P flag is present in the command line, this option has no
	   effect, since no "#line" directives are emitted whatsoever.

	   Do not print	column numbers in diagnostics.	This may be necessary
	   if diagnostics are being scanned by a program that does not
	   understand the column numbers, such as dejagnu.

       -A predicate=answer
	   Make	an assertion with the predicate	predicate and answer answer.
	   This	form is	preferred to the older form -A predicate(answer),
	   which is still supported, because it	does not use shell special

       -A -predicate=answer
	   Cancel an assertion with the	predicate predicate and	answer answer.

	   CHARS is a sequence of one or more of the following characters, and
	   must	not be preceded	by a space.  Other characters are interpreted
	   by the compiler proper, or reserved for future versions of GCC, and
	   so are silently ignored.  If	you specify characters whose behavior
	   conflicts, the result is undefined.

	   M   Instead of the normal output, generate a	list of	#define
	       directives for all the macros defined during the	execution of
	       the preprocessor, including predefined macros.  This gives you
	       a way of	finding	out what is predefined in your version of the
	       preprocessor.  Assuming you have	no file	foo.h, the command

		       touch foo.h; cpp	-dM foo.h

	       will show all the predefined macros.

	   D   Like M except in	two respects: it does not include the
	       predefined macros, and it outputs both the #define directives
	       and the result of preprocessing.	 Both kinds of output go to
	       the standard output file.

	   N   Like D, but emit	only the macro names, not their	expansions.

	   I   Output #include directives in addition to the result of

       -P  Inhibit generation of linemarkers in	the output from	the
	   preprocessor.  This might be	useful when running the	preprocessor
	   on something	that is	not C code, and	will be	sent to	a program
	   which might be confused by the linemarkers.

       -C  Do not discard comments.  All comments are passed through to	the
	   output file,	except for comments in processed directives, which are
	   deleted along with the directive.

	   You should be prepared for side effects when	using -C; it causes
	   the preprocessor to treat comments as tokens	in their own right.
	   For example,	comments appearing at the start	of what	would be a
	   directive line have the effect of turning that line into an
	   ordinary source line, since the first token on the line is no
	   longer a #.

       -CC Do not discard comments, including during macro expansion.  This is
	   like	-C, except that	comments contained within macros are also
	   passed through to the output	file where the macro is	expanded.

	   In addition to the side-effects of the -C option, the -CC option
	   causes all C++-style	comments inside	a macro	to be converted	to
	   C-style comments.  This is to prevent later use of that macro from
	   inadvertently commenting out	the remainder of the source line.

	   The -CC option is generally used to support lint comments.

	   Try to imitate the behavior of old-fashioned	C preprocessors, as
	   opposed to ISO C preprocessors.

	   Process trigraph sequences.

	   Enable special code to work around file systems which only permit
	   very	short file names, such as MS-DOS.

	   Print text describing all the command line options instead of
	   preprocessing anything.

       -v  Verbose mode.  Print	out GNU	CPP's version number at	the beginning
	   of execution, and report the	final form of the include path.

       -H  Print the name of each header file used, in addition	to other
	   normal activities.  Each name is indented to	show how deep in the
	   #include stack it is.  Precompiled header files are also printed,
	   even	if they	are found to be	invalid; an invalid precompiled	header
	   file	is printed with	...x and a valid one with ...! .

	   Print out GNU CPP's version number.	With one dash, proceed to
	   preprocess as normal.  With two dashes, exit	immediately.

       This section describes the environment variables	that affect how	CPP
       operates.  You can use them to specify directories or prefixes to use
       when searching for include files, or to control dependency output.

       Note that you can also specify places to	search using options such as
       -I, and control dependency output with options like -M.	These take
       precedence over environment variables, which in turn take precedence
       over the	configuration of GCC.

	   Each	variable's value is a list of directories separated by a
	   special character, much like	PATH, in which to look for header
	   files.  The special character, "PATH_SEPARATOR", is target-
	   dependent and determined at GCC build time.	For Microsoft Windows-
	   based targets it is a semicolon, and	for almost all other targets
	   it is a colon.

	   CPATH specifies a list of directories to be searched	as if
	   specified with -I, but after	any paths given	with -I	options	on the
	   command line.  This environment variable is used regardless of
	   which language is being preprocessed.

	   The remaining environment variables apply only when preprocessing
	   the particular language indicated.  Each specifies a	list of
	   directories to be searched as if specified with -isystem, but after
	   any paths given with	-isystem options on the	command	line.

	   In all these	variables, an empty element instructs the compiler to
	   search its current working directory.  Empty	elements can appear at
	   the beginning or end	of a path.  For	instance, if the value of
	   CPATH is ":/special/include", that has the same effect as
	   -I. -I/special/include.

	   If this variable is set, its	value specifies	how to output
	   dependencies	for Make based on the non-system header	files
	   processed by	the compiler.  System header files are ignored in the
	   dependency output.

	   The value of	DEPENDENCIES_OUTPUT can	be just	a file name, in	which
	   case	the Make rules are written to that file, guessing the target
	   name	from the source	file name.  Or the value can have the form
	   file	target,	in which case the rules	are written to file file using
	   target as the target	name.

	   In other words, this	environment variable is	equivalent to
	   combining the options -MM and -MF, with an optional -MT switch too.

	   This	variable is the	same as	DEPENDENCIES_OUTPUT (see above),
	   except that system header files are not ignored, so it implies -M
	   rather than -MM.  However, the dependence on	the main input file is

	   If this variable is defined,	cpp will skip any include file which
	   is not a regular file, and will continue searching for the
	   requested name (this	is always done if the found file is a

       gpl(7), gfdl(7),	fsf-funding(7),	gcc(1),	as(1), ld(1), and the Info
       entries for cpp,	gcc, and binutils.

       Copyright (c) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997,
       1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software
       Foundation, Inc.

       Permission is granted to	copy, distribute and/or	modify this document
       under the terms of the GNU Free Documentation License, Version 1.1 or
       any later version published by the Free Software	Foundation.  A copy of
       the license is included in the man page gfdl(7).	 This manual contains
       no Invariant Sections.  The Front-Cover Texts are (a) (see below), and
       the Back-Cover Texts are	(b) (see below).

       (a) The FSF's Front-Cover Text is:

	    A GNU Manual

       (b) The FSF's Back-Cover	Text is:

	    You	have freedom to	copy and modify	this GNU Manual, like GNU
	    software.  Copies published	by the Free Software Foundation	raise
	    funds for GNU development.

gcc-4.1.3			  2011-06-23				CPP(1)


Want to link to this manual page? Use this URL:

home | help