unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



cpp(1)								       cpp(1)



NAME

  cpp -	the C language preprocessor

SYNOPSIS

  /usr/lib/cpp [option...] [ifile[ofile]]

OPTIONS

  The cpp command recognizes the following options:

  -P  Preprocess the input without producing the line control information
      used by the next pass of the C compiler.

  -C  By default, cpp strips C-style comments.	If the -C option is speci-
      fied, all	comments (except those found on	cpp directive lines) are
      passed along.

  -w  Tell cpp not to issue warning messages.

  -nestlevel=n
      Set the limit of nesting levels for include files. The default is	50.

  -[no]error_limit nn
      Sets a limit on the number of errors that	the compiler will flag.	The
      default is 30.

  -oldcomment
      Treat comments in	the old	way; delete them and replace them with noth-
      ing. This	is the default in -std0	mode.

      The default in -std or -std0 mode	is to replace comments with a space.

  -Q  Cause cpp	to expand __FILE__ to 'filename' instead of to "filename"
      (the default).

  -Uname
      Remove any definition of name that was previously	defined	with the -D
      option. The -U option is ignored if it is	specified without a name.

  -Dname[=def]
      Define name as if	by a #define directive.	If the def argument is not
      specified, name is defined as 1.	If name	is not specified, the -D
      option is	ignored. The -D	option has lower precedence than the -U
      option. That is, if the same name	is used	in both	a -U option and	a -D
      option, the name will be undefined regardless of the order of the
      options.

  -I[dir]
      Specify a	search path for	include	files whose names do not indicate a
      specific directory path (that is,	include	files whose names do not
      begin with a /).	The actual search path depends upon the	form of	the
      #include directive used for the file:

	+  If the #include" filename" form of the directive is used, the C
	   macro preprocessor searches for the file at the following loca-
	   tions: first	in the directory in which it found the file that con-
	   tains the directive,	then in	the search path	indicated by the -I
	   option, and finally in the standard directory, /usr/include.

	+  If the include <&lt;filename>&gt; form of the directive is used, the
	   preprocessor	searches for the file first in the search path indi-
	   cated by the	-I option, and then in the standard directory,
	   /usr/include.

      You can specify multiple iterations of the -I[dir] option	in the cc
      command line. If no dir is specified in any iteration of the -I[dir]
      option, the C macro preprocessor never searches the standard directory,
      /usr/include, for	#include files.

      The -nocurrent_include option can	also modify the	search path.

  -nocurrent_include
      Change the behavior of the #include "filename" directive to not search
      the source file's	directory for filename.	 This option causes the
      #include "filename" directives to	behave like #include <&lt;filename>&gt;
      directives.  This	option allows makefiles	to control the search order
      for header files by using	-I options.

  -M  Print, one per line on standard output, the path names of	included
      files.  Each is prefixed with the	last component name of ifile and the
      suffix is	changed	to .o followed by a colon (:) and a space (for exam-
      ple, hello.o: /usr/include/stdio.h). The cpp command indents lines, as
      appropriate, to indicate where an	included file itself includes another
      included file.

  -MD Produce a	dependency file, which has the suffix .d appended to the
      object file name.	 This dependency file is created even if the object
      file is not.  The	information and	the format in the dependency file is
      identical	to that	produced by the	-M option. This	option allows depen-
      dency information	to be generated	at the same time that a	compilation
      is occurring.

  -protect_headers keyword
      Ensures that the compiler's assumptions about pointer sizes and data
      alignments are not in conflict with the data values that were in effect
      when the system libraries	were created.

      The keywords for the -protect_headers option are as follows:

      all Enables the protect headers feature.

      none
	  Disables the protect headers feature.	 This is the default for all
	  inputs.

      default
	  Cancels any previous -protect_headers	options	and places the
	  compiler's default behavior in effect.

      If more than one such switch appears on the command line,	only the last
      one is applied. See protect_headers_setup(8) for details.

  Two special names are	understood by cpp. The name __LINE__ is	defined	as
  the current line number (as a	decimal	integer) as known by cpp, and
  __FILE__ is defined as the current file name (as a C string) as known	by
  cpp. They can	be used	anywhere (including in macros) just as any other
  defined name.	 In addition, cpp reserves the names __DATE__ and __TIME__
  for future use.

  All cpp directives start with	lines beginning	with #.	The directives are:

  #define name token-string
      Replace subsequent instances of name with	token-string.

  #define name(arg, ..., arg) token-string
      Notice that no space can be inserted between name	and the	"(" that fol-
      lows it. Replace subsequent instances of name followed by	a "(", a
      comma-separated list of unique identifiers, and a	")" with token-
      string, where each occurrence of an arg in the token-string is replaced
      by the corresponding identifier in the comma-separated list. When	a
      macro with arguments is expanded,	the arguments are placed into the
      expanded token-string unchanged. After the entire	token-string has been
      expanded,	cpp re-starts its scan for names to expand at the beginning
      of the newly created token-string.

  #undef name
      Cause the	definition of name (if any) to be forgotten from this point.

  #ident "string"
      This directive is	transformed by the preprocessor	into the form
      __pragma(6, "string").

  #include filename

  #include<&lt;filename>&gt;
      Include at this point the	contents of filename (which will then be run
      through cpp). When the <filename>	notation is used, filename is only
      searched for in the standard places. See the description of the -I
      option for more details.

  #line	integer-constant filename
      Cause cpp	to generate line control information for the next pass of the
      C	compiler.  The integer-constant	is the line number of the next line
      and filename is the file where it	comes from.  If	filename is not
      specified, the current file name is unchanged.

  #endif
      End a section of lines that begin	with a test directive  (#if, #ifdef,
      or #ifndef). Each	test directive must have a matching #endif.

  #ifdef name
      Lines following this directive will appear in the	output only if name
      has been the subject of a	previous #define without being the subject of
      an intervening #undef.

  #ifndef name
      Lines following this directive will not appear in	the output if name
      has been the subject of a	previous #define without being the subject of
      an intervening #undef.

  #if constant-expression
      Lines following this directive will appear in the	output only if the
      constant-expression evaluates to non-zero.  All binary non-assignment C
      operators, the ?:	operator, and the unary	-, !, and ~ operators are all
      legal in constant-expression.

      The precedence of	the operators is the same as defined by	the C
      language.	 The unary operator defined can	also be	used in	constant-
      expression in either of the following forms: defined(name) or defined
      name. This allows	the utility of #ifdef and #ifndef in a #if directive.

      Only those operators, integer constants, and names that are known	by
      cpp should be used in constant-expression.  In particular, the sizeof
      operator is not available.

      For example, to test whether either of two symbols, foo and fum, are
      defined, use the following directive:


	   #if defined(foo) || defined(fum)

  #else
      Reverses the notion of the test directive	that matches this directive.
      For example, if lines previous to	this directive are ignored, the	lines
      following	will appear in the output.

  #elif	constant-expression
      Similar to #else followed	by #if,	except does not	introduce another
      conditional level.  The same restrictions	to the constant-expression
      for #if apply. For example:


	   #if foo==4
	   a="foo is four";
	   #elif foo==2
	   a="foo is two";
	   #else a="foo	is not four nor	two";
	   #endif

      The test directives and the possible #else directives can	be nested.
      Any number of #elif directives may occur between a test directive	and
      the corresponding	#else or #endif.

DESCRIPTION

  The cpp C language preprocessor performs initial text	substitutions, mani-
  pulations, conditional inclusion, and	various	other activities as described
  by the C standard.

  The preferred	way to invoke cpp on C files is	through	the cc(1) command.
  See m4(1) for	a general macro	processor.

  The cpp preprocessor optionally accepts two file names as arguments:

  ifile
      Input to the preprocessor

  ofile
      Output from the preprocessor

  These	files default to standard input	and standard output if not supplied.
  Unless directed to do	otherwise, cpp places the output file (ofile) in the
  same directory in which the input file (ifile) resides.

  The cpp preprocessor accepts C++-style end-of-line comments (//). This
  means	that everything	following the two slashes (//) to the end of the line
  in which they	appear is considered to	be a comment.

  The cpp command does not predefine any macros	other than the standard	C
  macros __LINE__, __FILE__, __DATE__, __TIME__, (and __STDC__ if appropri-
  ate).









NOTES

  When newline characters were found in	argument lists for macros to be
  expanded, previous versions of cpp put out the newlines as they were found
  and expanded.	The current version of cpp replaces these newlines with
  blanks to alleviate problems that the	previous versions had when this
  occurred.

ERRORS

  The error messages produced by cpp are intended to be	self-explanatory.
  The line number and file name	where the error	occurred are printed along
  with the diagnostic.

FILES

  /usr/include
      Standard directory for include files

SEE ALSO

  Commands:  cc(1), as(1), m4(1)