*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->FreeBSD man pages -> cpp (1)              



NAME    [Toc]    [Back]

       cpp - The GNU C-Compatible Compiler Preprocessor.

SYNOPSIS    [Toc]    [Back]

       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|-]

DESCRIPTION    [Toc]    [Back]

       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	directives,
 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 `cpp.info', 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 commonly
 used by today's C programs.  Such incompatibility would be inconvenient
	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.

OPTIONS    [Toc]    [Back]

       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-character
 sequences, all starting with `??', that are defined by ANSI
  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  enabled).


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

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

	      Warn  about certain constructs that behave differently in traditional
 and ANSI C.

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

       -I-    Any directories specified with `-I' options before the `-I-' option
  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' directives.

	      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  requested
  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 directories,
 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  characters
  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	predefined.

       -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 predefined
 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 object
  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' command.

       -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, before
 processing the regular input file.

       -idirafter dir
	       Add the directory dir to the second include path.  The directories
 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'  options.

       -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  comments,
  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  required
 for strict conformance to the C Standard before the standard
 was corrected.   This option is  available  only  when  you
	      call cpp directly; gcc will not pass it from its command line.

SEE ALSO    [Toc]    [Back]

       `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.

COPYING    [Toc]    [Back]

       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 entire
 resulting derived work is distributed under the terms of a permission
 notice identical to this one.

       Permission is granted to copy and distribute translations of this manual
 into another language, under the above conditions for modified  versions,
  except  that this permission notice may be included in translations
 approved by the Free Software Foundation instead of in the original

FreeBSD 			April 30, 1993				cpp(1)
[ Back ]
 Similar pages
Name OS Title
cpp-2.96 Linux The C Preprocessor
mmroff FreeBSD reference preprocessor
cpp IRIX the C language preprocessor
lesspipe Linux "input preprocessor" for less.
cpp Tru64 the C language preprocessor
cpp HP-UX the C language preprocessor
sysmonpp IRIX System Monitor Preprocessor
gasp FreeBSD the GNU Assembler Macro Preprocessor
gasp Linux a preprocessor for assembly programs
unifdef HP-UX remove preprocessor lines
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service