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

FreeBSD Manual Pages


home | help
cpp(1)				   GNU Tools				cpp(1)

       cpp - The GNU C-Compatible Compiler Preprocessor.

       cpp    [-$] [-Apredicate[(value)]] [-C] [-Dname[=definition]] [-dD]
	      [-dM] [-I	directory] [-H]	[-I-] [-imacros	file] [-include	file]
	      [-idirafter dir] [-iprefix prefix] [-iwithprefix dir] [-lang-c]
	      [-lang-c++] [-lang-objc] [-lang-objc++] [-lint] [-M [-MG]]
	      [-MM [-MG]] [-MD file ] [-MMD file ] [-nostdinc] [-nostdinc++]
	      [-P] [-pedantic] [-pedantic-errors] [-traditional] [-trigraphs]
	      [-Uname] [-undef]	[-Wtrigraphs] [-Wcomment] [-Wall]
	      [infile|-] [outfile|-]

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

       The  C  preprocessor provides four separate facilities that you can use
       as you see fit:

       o      Inclusion	of header files.  These	are files of declarations that
	      can be substituted into your program.

       o      Macro expansion.	You can	define macros, which are abbreviations
	      for arbitrary fragments of C code, and then the  C  preprocessor
	      will  replace  the  macros with their definitions	throughout the

       o      Conditional compilation.	 Using	special	 preprocessing	direc-
	      tives, you can include or	exclude	parts of the program according
	      to various conditions.

       o      Line control.  If	you use	a  program  to	combine	 or  rearrange
	      source  files  into an intermediate file which is	then compiled,
	      you can use line control to inform the compiler  of  where  each
	      source line originally came from.

       C  preprocessors	 vary  in some details.	 For a full explanation	of the
       GNU C preprocessor, see the info	file `', or the	manual	The  C
       Preprocessor.   Both  of	 these	are  built from	the same documentation
       source file, `cpp.texinfo'.  The	GNU C preprocessor provides a superset
       of the features of ANSI Standard	C.

       ANSI Standard C requires	the rejection of many harmless constructs com-
       monly used by today's C programs.  Such incompatibility would be	incon-
       venient	for  users,  so	the GNU	C preprocessor is configured to	accept
       these constructs	by default.  Strictly speaking,	to get	ANSI  Standard
       C, you must use the options `-trigraphs', `-undef' and `-pedantic', but
       in practice the consequences of having strict ANSI Standard C  make  it
       undesirable to do this.

       Most  often when	you use	the C preprocessor you will not	have to	invoke
       it explicitly: the C compiler will do so	automatically.	 However,  the
       preprocessor is sometimes useful	individually.

       The C preprocessor expects two file names as arguments, infile and out-
       file.  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 outfile or both file names are  omitted,  the	 standard  output  and
       standard	input are used for the omitted file names.

       Here  is	 a  table  of  command options accepted	by the C preprocessor.
       These options can also be given when compiling a	C  program;  they  are
       passed  along  automatically  to	the preprocessor when it is invoked by
       the compiler.

       -P     Inhibit generation of `#'-lines with line-number information  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

       -C     Do not discard comments: pass them through to the	 output	 file.
	      Comments	appearing  in arguments	of a macro call	will be	copied
	      to the output before the expansion of the	macro call.

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

	      Process ANSI standard trigraph sequences.	 These are three-char-
	      acter sequences, all starting with `??', that are	defined	by AN-
	      SI  C to stand for single	characters.  For example, `??/'	stands
	      for `\', so `'??/n'' is a	 character  constant  for  a  newline.
	      Strictly	speaking,  the GNU C preprocessor does not support all
	      programs in ANSI Standard	C unless `-trigraphs' is used, but  if
	      you ever notice the difference it	will be	with relief.

	      You don't	want to	know any more about trigraphs.

	      Issue  warnings required by the ANSI C standard in certain cases
	      such as when text	other than a comment follows `#else' or	 `#en-

	      Like  `-pedantic',  except  that errors are produced rather than

	      Warn if any trigraphs are	encountered  (assuming	they  are  en-


	      Warn  whenever  a	 comment-start sequence	`/*' appears in	a com-
	      ment.  (Both forms have the same effect).

       -Wall  Requests both `-Wtrigraphs' and `-Wcomment' (but	not  `-Wtradi-

	      Warn  about certain constructs that behave differently in	tradi-
	      tional and ANSI C.

       -I directory
	      Add the directory	directory to the end of	the list  of  directo-
	      ries to be searched for header files.  This can be used to over-
	      ride a system header file, substituting your own version,	 since
	      these directories	are searched before the	system header file di-
	      rectories.  If you use more than one `-I'	option,	 the  directo-
	      ries are scanned in left-to-right	order; the standard system di-
	      rectories	come after.

       -I-    Any directories specified	with `-I' options before the `-I-' op-
	      tion  are	 searched  only	for the	case of	`#include file"'; they
	      are not searched for `#include <file_'.

	      If additional directories	are specified with `-I'	options	 after
	      the `-I-', these directories are searched	for all	`#include' di-

	      In addition, the `-I-' option inhibits the use  of  the  current
	      directory	 as  the  first	search directory for `#include file"'.
	      Therefore, the current directory is searched only	if it  is  re-
	      quested  explicitly with `-I.'.  Specifying both `-I-' and `-I.'
	      allows you to control precisely which directories	 are  searched
	      before the current one and which are searched after.

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

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

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

       -D name=definition
		Predefine  name	as a macro, with definition definition.	 There
	      are no restrictions on the contents of definition,  but  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	 char-
	      acters  such  as spaces that have	a meaning in the shell syntax.
	      If you use more than one `-D' for	the same name,	the  rightmost
	      definition takes effect.

       -U name
	      Do  not predefine	name.  If both `-U' and	`-D' are specified for
	      one name,	the `-U' beats the `-D'	and the	 name  is  not	prede-

       -undef Do not predefine any nonstandard macros.

       -A name(value)
	      Assert  (in the same way as the #assert directive) the predicate
	      name with	tokenlist value.  Remember  to	escape	or  quote  the
	      parentheses on shell command lines.

	      You  can use `-A-' to disable all	predefined assertions; it also
	      undefines	all predefined macros.

       -dM    Instead of outputting the	result of preprocessing, output	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	the values of any predefined macros.

       -dD    Like  `-dM' except in two	respects: it does not include the pre-
	      defined macros, and it outputs both the `#define'	directives and
	      the  result  of  preprocessing.	Both kinds of output go	to the
	      standard output file.

       -M [-MG]
	      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 ob-
	      ject  file  name for that	source file, a colon, and the names of
	      all the included files.  If there	are many included  files  then
	      the rule is split	into several lines using `\'-newline.

	      `-MG'  says to treat missing header files	as generated files and
	      assume they live in the same directory as	the source  file.   It
	      must be specified	in addition to `-M'.

	      This feature is used in automatic	updating of makefiles.

       -MM [-MG]
	      Like  `-M'  but  mention	only the files included	with `#include
	      "file"'.	System header files included  with  `#include  <file_'
	      are omitted.

       -MD file
	      Like  `-M'  but the dependency information is written to `file'.
	      This is in addition to compiling the  file  as  specified--`-MD'
	      does not inhibit ordinary	compilation the	way `-M' does.

	      When invoking gcc, do not	specify	the `file' argument.  Gcc will
	      create file names	made by	replacing `.c' with `.d' at the	end of
	      the input	file names.

	      In Mach, you can use the utility md to merge multiple files into
	      a	single dependency file suitable	for using with the `make' com-

       -MMD file
	      Like  `-MD'  except  mention  only user header files, not	system
	      header files.

       -H     Print the	name of	each header file used, in  addition  to	 other
	      normal activities.

       -imacros	file
	      Process  file  as	input, discarding the resulting	output,	before
	      processing the regular input file.  Because the output generated
	      from file	is discarded, the only effect of `-imacros file' is to
	      make the macros defined in file available	for use	 in  the  main
	      input.   The preprocessor	evaluates any `-D' and `-U' options on
	      the command line before processing `-imacros file' .

       -include	file
	      Process file as input, and include all the resulting output, be-
	      fore processing the regular input	file.

       -idirafter dir
	      Add  the directory dir to	the second include path.  The directo-
	      ries on the second include path are searched when	a header  file
	      is  not found in any of the directories in the main include path
	      (the one that `-I' adds to).

       -iprefix	prefix
	      Specify prefix as	the prefix for subsequent  `-iwithprefix'  op-

       -iwithprefix dir
	      Add  a  directory	 to  the second	include	path.  The directory's
	      name is made by concatenating prefix and dir, where  prefix  was
	      specified	previously with	`-iprefix'.




	      Specify the source language.  `-lang-c++'	makes the preprocessor
	      handle C++ comment syntax, and includes  extra  default  include
	      directories  for	C++,  and `-lang-objc' enables the Objective C
	      `#import'	directive.  `-lang-c' explicitly  turns	 off  both  of
	      these extensions,	and `-lang-objc++' enables both.

	      These  options are generated by the compiler driver gcc, but not
	      passed from the `gcc' command line.

       -lint  Look for commands	to the program checker lint embedded  in  com-
	      ments,  and  emit	them preceded by `#pragma lint'.  For example,
	      the  comment  `/*	  NOTREACHED   */'   becomes   `#pragma	  lint

	      This  option  is	available only when you	call cpp directly; gcc
	      will not pass it from its	command	line.

       -$     Forbid the use of	`$' in identifiers.   This  was	 formerly  re-
	      quired for strict	conformance to the C Standard before the stan-
	      dard was corrected.   This option	is  available  only  when  you
	      call cpp directly; gcc will not pass it from its command line.

       `Cpp' entry in info; The	C Preprocessor,	Richard	M. Stallman.
       gcc(1);	`Gcc'  entry  in  info;	 Using and Porting GNU CC (for version
       2.0), Richard M.	Stallman.

       Copyright (c) 1991, 1992, 1993 Free Software Foundation,	Inc.

       Permission is granted to	make and distribute verbatim  copies  of  this
       manual  provided	 the  copyright	 notice	and this permission notice are
       preserved on all	copies.

       Permission is granted to	copy and distribute modified versions of  this
       manual under the	conditions for verbatim	copying, provided that the en-
       tire resulting derived work is distributed under	the terms of a permis-
       sion notice identical to	this one.

       Permission is granted to	copy and distribute translations of this manu-
       al into another language, under the above conditions for	modified  ver-
       sions,  except  that this permission notice may be included in transla-
       tions approved by the Free Software Foundation instead of in the	origi-
       nal English.

FreeBSD				April 30, 1993				cpp(1)


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

home | help