cpp man page on BSDi

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDi logo
[printable version]



cpp(1)			    GNU Tools			   cpp(1)

NAME
       cccp, cpp - The GNU C-Compatible Compiler Preprocessor.

SYNOPSIS
       cccp   [-$] [-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] [-Wtraditional]
	      [infile|-] [outfile|-]

DESCRIPTION
       The C preprocessor is a macro processor that is used auto-
       matically  by the C compiler to transform your program be-
       fore 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 dec-
	      larations that can be substituted	 into  your  pro-
	      gram.

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

       o      Conditional compilation.	Using special preprocess-
	      ing 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 orig-
	      inally came from.

       C preprocessors vary in some details.  For a full explana-
       tion  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  in-

GNU Tools		    30apr1993				1

cpp(1)			    GNU Tools			   cpp(1)

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

       When  you  call the preprocessor individually, either name
       (cpp or cccp) will do--they are completely synonymous.

       The C preprocessor expects two file  names  as  arguments,
       infile and outfile.  The preprocessor reads infile togeth-
       er with any other files it specifies with `#include'.  All
       the  output generated by the combined input files is writ-
       ten 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
       Here is a table of command options accepted by the C  pre-
       processor.  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 `#'-lines.

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

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

       -trigraphs
	      Process ANSI standard  trigraph  sequences.   These
	      are  three-character  sequences,	all starting with
	      `??', that are defined by ANSI C to stand for  sin-
	      gle characters.  For example, `??/' stands for `\',
	      so `'??/n'' is a character constant for a	 newline.

GNU Tools		    30apr1993				2

cpp(1)			    GNU Tools			   cpp(1)

	      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.

       -pedantic
	      Issue warnings required by the ANSI C  standard  in
	      certain  cases  such as when text other than a com-
	      ment follows `#else' or `#endif'.

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

       -Wtrigraphs
	      Warn  if	any  trigraphs	are encountered (assuming
	      they are enabled).

       -Wcomment

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

       -Wall  Requests	both  `-Wtrigraphs'  and `-Wcomment' (but
	      not `-Wtraditional').

       -Wtraditional
	      Warn about certain constructs that  behave  differ-
	      ently 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 directo-
	      ries are searched before the system header file di-
	      rectories.  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  `#in-
	      clude <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

GNU Tools		    30apr1993				3

cpp(1)			    GNU Tools			   cpp(1)

	      for  `#include  file"'.  Therefore, the current di-
	      rectory is searched only if it is requested explic-
	      itly  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.

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

       -nostdinc++
	      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 defini-
	      tion.  There are no restrictions on the contents of
	      definition, but if you are invoking the  preproces-
	      sor 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 ef-
	      fect.

       -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 asser-
	      tions; 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  prepro-
	      cessor,  including  predefined  macros.  This gives
	      you a way of finding out what is predefined in your

GNU Tools		    30apr1993				4

cpp(1)			    GNU Tools			   cpp(1)

	      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  in-
	      clude  the  predefined  macros, and it outputs both
	      the `#define' directives and the result of  prepro-
	      cessing.	 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 de-
	      pendencies of the main source file.  The preproces-
	      sor  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 gener-
	      ated files and assume they live in the same  direc-
	      tory  as	the source file.  It must be specified in
	      addition to `-M'.

	      This feature is used in automatic updating of make-
	      files.

       -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'  argu-
	      ment.  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 multi-
	      ple 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.

GNU Tools		    30apr1993				5

cpp(1)			    GNU Tools			   cpp(1)

       -H     Print the name of each header file used,	in  addi-
	      tion 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 discard-
	      ed, 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 pro-
	      cessing `-imacros file' .

       -include file
	      Process file as input, and include all the  result-
	      ing  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'.

       -lang-c

       -lang-c++

       -lang-objc

       -lang-objc++
	      Specify the source language.  `-lang-c++' makes the
	      preprocessor  handle  C++	 comment  syntax, and in-
	      cludes 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 em-
	      bedded in	 comments,  and	 emit  them  preceded  by

GNU Tools		    30apr1993				6

cpp(1)			    GNU Tools			   cpp(1)

	      `#pragma	lint'.	 For  example,	the  comment  `/*
	      NOTREACHED */' becomes `#pragma lint NOTREACHED'.

	      This option is available only when you call cpp di-
	      rectly; 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 direct-
	      ly; gcc will not pass it from its command line.

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

COPYING
       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 ver-
       sions 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 con-
       ditions for modified versions, except that this permission
       notice may be included in  translations	approved  by  the
       Free  Software  Foundation  instead of in the original En-
       glish.

GNU Tools		    30apr1993				7

[top]

List of man pages available for BSDi

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net