cpp

NAME
cpp - C Pre-Processor

SYNOPSIS
cpp [-options] files

DESCRIPTION
Cpp reads one or more files, expands macros and include files, and writes an input file for the C compiler. All output is to cpp.tmp (cpp.tmp.c on Unix).
The following options are supported. On non-Unix systems, options may be given in either case.

-Ofile
    Output to this file, instead of the default.

-S  Output to stdout, instead of the default.

-Idirectory
    Add this directory to the list of directories searched for #include "..." and #include <...> commands. Note that there is no space between the "-I" and the directory string. More than one -I command is permitted.

-L  Cpp transmits line number information to the C compiler by outputting "#line <number>" records. If the -L option is given, this record will be transmitted as "#", allowing the output of cpp to be input to a compiler without an intervening preprocessor without error.

-Dname=value
    Define the name as if the programmer wrote
        #define name value
    at the start of the first file. If "=value" is not given, a value of "1" will be used.
    On non-unix systems, all alphabetic text will be forced to upper-case.

-Uname
    Undefine the name as if
    	#undef name
    were given. On non-Unix systems, "name" will be forced to upper-case. The following names are always available unless undefined:

    __FILE__
        The input (or #include) file being compiled (as a quoted string).

    __LINE__
        The line number being compiled.

    __DATE__
        The date and time of compilation as a Unix ctime quoted string (the trailing newline is removed).
Thus,
    printf("Bug at line %s,", __LINE__);
    printf(" source file %s", __FILE__);
    printf(" compiled on %s", __DATE__);

    -Xnumber Enable debugging code. If no value is given, a value of 1 will be used. (For maintenence of cpp only.)

COMMENTS IN MACRO TEXT AND ARGUMENT CONCATENATION
Comments are removed from the input text. The comment characters serve as an invisible token delimiter. Thus, the macro
    #define CAT(a, b) b/**/a
    int value = CAT(1, 2);
Will generate "int value = 21;".
A better way of concatenating arguments is as follows:
    #define I(x)x
    #define CAT(x,y)I(x)y
    int value = CAT(1, 2);
If the above macros are defined without extraneous spaces, they will be transportable to other implementations.

DIFFERENCES
The following is a list of differences between this pre-processor and the Unix V7 preprocessor which was written by John Reiser. It is probably not complete.

o   Macro formal parameters are recognized within quoted strings and character constants in macro definitions. For example,
        #define foo(a) "Today is a"
        printf(foo(tuesday));
    Would print "Today is tuesday".
    Recognition of formal parameters in macro replacement strings is not permitted by the Draft ANSI C Standard. It is permitted in this implementation if cpp was compiled with the STRING_FORMAL parameter set appropriately.
    Unlike Reiser's implementation, the '\' "quote next character" does just that. I.e.
        #define foo(a) "Today is \a a"
        printf(foo(tuesday));
    Would print "Today is a tuesday". Note that this may not be portable.

o   Reiser's implementation removes "escaped" linefeeds (The two character sequence \<LF>) within macros. This implementation preserves them. For example, a macro which generates control commands might be written
        #define foo(a, b) \
        #define	a	b \
        foo(fubar, foobar)
        int		fubar;
    The above would generate "int foobar;" and a warning message. Reiser's scan is slightly different.

ANSI C STANDARD
Cpp implements most of the ANSI draft standard. You should be aware of the following:

o   In the draft standard, the \n (backslash-newline) character is "invisible" to all processing. In this implementation, it is invisible to strings, but acts a "whitespace" (token-delimiter) outside of strings. This considerably simplifies error message handling.

o   The following extensions to C are processed by cpp:

    	#elif expression	(#else #if)
    	'\xNNN'	(Hexadecimal constants)
    	'\a'	(Ascii BELL)
    	'\v'	(Ascii VT)
    	#if defined NAME	(1 if defined, 0 if not)
    	#if defined (NAME)	(1 if defined, 0 if not)
    	unary +	(gag me with a spoon)

o   The draft standard has extended C, adding a string concatenation operator, where
        "foo" "bar"
    is regarded as the single string "foobar". It is not clear from the draft standard whether this applies to pre-processing if macro formals are recognized in strings.

ERROR MESSAGES
Many.

AUTHOR
Martin Minow