cpp.doc

类PASCAL语言的编译器,LINUX环境的,我没试过是否正确.

  #endif        Ends a section of lines begun by a test directive (#if,
  #ifdef, or #ifndef).  Each test directive must have a matching
  #endif.
  
  #ifdef Name
  
          Places the subsequent lines in the output only if:
  
          Name has been defined by a previous #define
  
          or
  
          Name has been defined by the -D flag,
  
          or
  
          Name is a special name recognized by the cpp command,
  
          and
  
          Name has not been undefined by an intervening #undef,
  
          or
  
          Name has not been undefined with the -U flag.
  
  #ifndef Name
  
          Places the subsequent lines in the output only if:
  
          Name has never been defined by a previous #define,
  
          and
  
          Name is not a special name recognized by the cpp command,
  
          or
  
          Name has been  defined  by a previous  #define but  it  has been un-
          defined by an intervening #undef,
  
          or
  
          Name is a  special name  recognized  by the cpp command, but  it has
          been undefined with the -U flag.
  
  #if Expression
  
          Places subsequent lines in  the output  only  if  Expression  evalu-
          ates  to  nonzero.   All  the binary nonassignment C operators,  the
          ?:  operator, and  the unary  -, !,  and -  operators are  legal  in
          Expression.   The  precedence  of the operators is the  same as that
          defined  in  the  C  Language.   There  is  also  a  unary  operator
          defined, which can be used in Expression in these two forms:
  
          defined (Name) or defined Name
  
          This  allows the utility  of  #ifdef and #ifndef  in  a  #if  direc-
          tive.   Only these operators,  integer  constants,  and  names  that
          are known by cpp  should be used  in Expression.   The sizeof opera-
          tor is not available.
  
  #elif Expression
  
          Places  subsequent lines in the output only if the expression in the
          preceding #if or #elif directive evaluates to false or is undefined,
          and this Expression evaluates to true.
  
  #else

          Places subsequent lines in the output only if  the expression in the
          preceding #if or #elif directive evaluates  to false or is undefined
          (and hence the lines following the #if and preceding the  #else have
          been ignored).
  
          Each  test  directive's  condition  is  checked  in  order.   If  it
          evaluates to false (zero), the  group that it controls  is  skipped.
          Directives  are  processed  only through the  name  that  determines
          the directive  in  order to keep track of the  level of nested  con-
          ditionals;  the  rest  of the directives' preprocessing  tokens  are
          ignored,  as  are the  other  preprocessing  tokens  in  the  group.
          Only  the  first  group  whose control  condition evaluates  to true
          (nonzero)  is  processed.  If  none of the  conditions evaluates  to
          true, and  there  is  a  #else directive, the  group  controlled  by
          the  #else  is   processed;  lacking  a  #else  directive,  all  the
          groups until the #endif are skipped.
  

  Macros
     Formal  parameters  for  macros  are  recognized  in   #define  directive
     bodies, even  when they  occur  inside  character  constants  and  quoted
     strings.  For instance, the output from:

          #define abc(a) |\a|
          abc(xyz)

     is the seven characters ``  |`xyz|''  (SPACE, vertical-bar, backquote, x,
     y, z, vertical-bar). Macro  names  are  not recognized  within  character
     constants or quoted strings during the regular scan.  Thus:
          #define abc xyz
          printf("abc");

     does  not expand abc in the  second line,  since it is  inside  a  quoted
     string  that  is not part of a #define macro definition.

     Macros are  not  expanded while  processing a  #define  or #undef.  Thus:

          #define abc zingo
          #define xyz abc
          #undef abc
          xyz

     produces  abc. The token appearing immediately after an #ifdef or #ifndef
     is not expanded.

     Macros  are  not expanded during  the scan  which  determines the  actual
     parameters to another macro call.  Thus:

          #define reverse(first,second)second first
          #define greeting hello
          reverse(greeting,
          #define greeting goodbye
          )

     produces `` #define hello goodbye  hello''.

  Output
     Output consists of  a  copy of the  input  file, with modifications, plus
     lines of the form:

          #line <lineno> "filename"

     indicating  the original source line number and filename of the following
     output line.

  Details
  Directory Search Order
     #include files is:

          1.  The   directory   of  the  file   that  contains  the  #include
              request (that is, #include is relative to the file being scanned
              when the request is made).

          2.  The directories specified by -I options, in left-to-right order.

          3.  The standard  directory(s)  (/usr/include/ on  UNIX systems,
              INCLUDE: on Amiga systems and /dd/defs/ on OS/9(000) systems).

  Special Names
     Six special names are  understood by  cpp.  The name  __LINE__ is defined
     as the current line number (a decimal integer) as known by  cpp, __FILE__
     is defined as the current filename (a C string) as known by cpp, __DATE__
     is defined as  the current date  (a C string), __TIME__ is defined as the
     start  time of the preprocessing (a C string), __FUNCTION__ is defined as
     the function  the  C  source currently  is  defining  (a  C  string)  and
     __FUNC_LINE__ is  defined  as the beginning line  of  the function  the C
     source  currently is defining  (a  decimal  integer).   They  can be used
     anywhere (including in macros) just as any other defined name.

  Newline Characters
     A  NEWLINE character  terminates a character constant  or quoted  string.
     An escaped  NEWLINE (that  is,  a  backslash  immediately  followed  by a
     NEWLINE) may  be  used in  the body of a #define  statement  to  continue
     the  definition onto the next line.  The escaped NEWLINE is not  included
     in the macro value.

  Comments
     Comments  are removed  (unless  the  -C option  is  used  on the  command
     line).  Comments  are also ignored, except  that a  comment  terminates a
     token.


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


NOTES
     When NEWLINE characters were found  in  argument lists  for macros to  be
     expanded, some previous versions of cpp put out the NEWLINE characters as
     they were found and expanded.   The current version of cpp  replaces them
     with SPACE characters.

     Because  the  standard directory for  included files may be  different in
     different environments, this form of #include directive:

          #include <file.h>

     should be used, rather than one with an absolute path, like:

          #include "/usr/include/file.h"

SUN SPECIFIC: (Should this be implemented in 'cpp' ?)

     cpp warns about the use of the absolute pathname.


  EXAMPLES
  ========
  
  1.    To display the text that the preprocessor sends to the C compiler,
  enter:
  
  cpp  pgm.c
  
  This preprocesses pgm.c and displays the resulting text at the work station.
  You may want to see the preprocessor output when  looking for errors in your
  macro definitions.
  
  
  
  2.    To create a file containing more readable preprocessed text, enter:
  
  cpp  -C -L pgm.c pgm.i
  
  This preprocesses  pgm.c and  stores  the result  in  pgm.i.  It omits  line
  numbering  information intended  for  the  C  compiler  (-L),  and  includes
  program comments (-C).
  
  
  
  3.    To predefine macro identifiers, enter:
  
  cpp  -DBUFFERSIZE=512  -DDEBUG  pgm.c  pgm.i
  
  This defines BUFFERSIZE with the value 512 and DEBUG with the value 1 before
  preprocessing.
  
  
  
  4.    To use #include files located in nonstandard directories, enter:
  
  cpp  -I/home/jim/include  pgm.c
  
  This  looks in  the  current directory for quoted #include  files,  then  in
  /home/jim/include,  and then  in  the  standard  directories.  It  looks  in
  /home/jim/include for angle-bracketed #include  files (<  >) and then in the
  standard directories.
  

ERROR MESSAGES:

    Many. CPP prints warning or error messages if you try to use multiple-
    byte  character constants (non-transportable)  if  you #undef a symbol
    that  was not defined, or  if  your  program  has  potentially  nested
    comments.

AUTHORS:

     I received a great deal of  help from many people  in  debugging cpp.
    Alan Feuer  and Sam Kendall  used "state  of  the  art" run-time  code
    checkers to locate several  errors.   Ed Keiser  found  problems  when
    cpp  was  used  on machines  with different  int  and  pointer  sizes.
    Dave Conroy  helped  with the  initial  debugging,  while Arthur Olsen
    and  George  Rosenberg found  (and solved)  several  problems  in  the
    first USENET release.
                                                    Martin Minow

     After this, as can be seen in the source files, a lot of other people
    has been  improving  this  package. Among  others  the  guys  with the
    signatures: ado, george, RMS, FNF, Ois, Keie, ARF, SCK and gkr...
     I rewrote large parts of the code to adapt in to strict  ANSI C rules
    and to easier put it  into a  shared library.  I did  compile it to  a
    shared library. I added most of the features and options you see today
    (such  as  -L,  -P,  -V,  -l, -A,  -b, -l, -Q, -F,  -H  and  a  proper
    separation of  the -B and -N option). I fixed the -C  option to output
    the  comments more  like they appear  in  the source  (that  is _with_
    newlines between comments that had that in the source).
     I rewrote parts to enable all output through the user supplied output
    function.  I added  documentation  and  information  that really  were
    missing when  I  got this  in my hands. I changed  it to Freeware from
    being public  domain  since  I don't want anyone to earn  money on  my
    sweat. (If  you want  the  public domain version of  this  code,  mail
    me or the original author to get it.)
     Unfortunately, I never actually succeeded in my mission  to put 'cpp'
    in a  shared library under  AmigaDOS  although I did it under AIX, but
    instead I have managed to compile 'cpp' under DELL UNIX, AIX, OS/9000,
    SUN OS and AmigaDOS without errors (although warnings with gcc in the
    'cpp3.c' source file!).
     'cpp' most certainly  will  need  an ANSI C compilers to  be  able to
    compile  without  a  lot of troubles. Function  pointers as  structure
    members are not friends of K&R...
                                                      Daniel Stenberg
              (email: [e-mail] - FidoNet: 2:201/328)

BUGS:

      The #if expression processor uses signed integers only.
      I.e, #if 0xFFFFu < 0 may be TRUE.