Man Page fpp.1


     fpp - the Fortran language preprocessor for FORTRAN 77 and
     Fortran 95.


     fpp [ options ] [ input-file [ output-file ] ]


     fpp is the  preprocessor  for FORTRAN 77 and Fortran 95.
     fpp optionally  accepts  two  filenames  as   arguments.
     input-file and output-file  are, respectively, the  input
     file read and the output file written by the preprocessor.
     By default standard input and output are used.  fpp can be
     used instead of the cpp preprocessor with the Sun Fortran 95


          By default, C style comments are recognized. Turn this
          off by specifying -c_com=no

          Define the preprocessor variable name as 1 (one). This
          is the same as if a -Dname=1 option appeared on the fpp
          command line, or as if a

               #define name 1

          line appeared in the source file, which is processed by

          Define name as if by a #define directive.  This is the
          same as if a

               #define name def

          line appeared in the source file that fpp is process-
          ing.  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.

          Assumes fixed format input source.

          Assumes free format input source.

          Insert directory into the search path for #include
          files with names not beginning with `/'.  directory is
          inserted ahead of the standard list of ``include''
          directories.  Thus, #include files with names enclosed
          in double-quotes (") are searched for first in the
          directory of the file with the #include line, then in
          directories named with -I options, and lastly, in
          directories from the standard list.  For #include files
          with names enclosed in angle-brackets (<>), the direc-
          tory of the file with the #include line is not

     -M   Generate a list of makefile dependencies and write them
          to the standard output. This list indicates that the
          object file which would be generated  from the input
          file depends on the input file  as  well  as  the
          include  files referenced.

          By default, macros are expanded everywhere. Turn off
          macro expansion in comments by specifying -macro=no_com
          and turn off macro expansion all together by specifying

     -P   Do not put line numbering directives to the output
          file. This directive appears as
          #line-number file-name

          Remove any initial definition of name, where name is a
          fpp variable that is predefined by a particular prepro-
          cessor.  Here is a partial list of symbols that may be
          predefined, depending upon the architecture of the sys-

               Operating System:   unix, __unix, and__SVR4
               Hardware:           sun, __sun, sparc, and__sparc

          Remove initial definitions for all predefined symbols.

     -w0  Don't output warnings from fpp to stderr.

     -Xu  Convert upper-case letters to lower-case, except within
          character-string constants. The default is to not con-
          vert upper-case letters  to  lower-case.

     -Xw  For fixed form source files (See below) fpp assumes
          that the symbol ' ' (space) is insignificant.  By
          default for this form the 'space' symbol is the delim-
          iter of tokens.

          Use the specified  directory in place of the standard
          list of directories when searching for files.

     fpp  also understands some f95 compiler options (See

     -e   Accept extended source lines, up to 132 characters

     -w   Do not output warnings to stderr.


  Source files
     fpp operates on both fixed and free form source files. Files
     with '.F' extension are assumed to be in fixed form, and
     files with '.F90' and '.F95' extensions (and all others) are
     assumed to be in free form by default. There is the '-fixed'
     option for using fixed form in Fortran 95. fpp recognizes
     the tab format of a source line when in fixed mode.

     A source file may contain fpp tokens. fpp tokens are close
     to those of Fortran. They are:

          -    fpp directive names.

          -    symbolic names including Fortran keywords. fpp
               permits all symbols in names that Fortran does.

          -    constants. Integer, real, double and quadruple
               precision, binary, octal, hexadecimal including
               alternate notation, character and hollerith.

          -    comments. There are Fortran comments and fpp com-

          -    others. Special characters, space, tab, newline,

     Output consists of a modified copy of the input, plus lines
     of the form:

          #line_number  file_name

     inserted to indicate the original source line number and
     filename of the output line that follows.  There is the '-P'
     option (See above) which disables the generation of these

     Syntax and semantics of fpp directives are the same as cpp
     directives (See cpp(1)).
     All fpp directives  start with the hash symbol (#)  as the
     first character on a line. White space (SPACE or TAB charac-
     ters) can  appear after the initial '#' for proper indenta-
     tion.  The  directives can be divided  into the following

     - macro definitions;

     - conditional source code selection;

     - inclusion of external files;

     - line control.

  Macro definition.
     The #define directive is used to define both simple string
     variables and more complicated macros:

     #define name  token-string

     This is the definition of a fpp variable. Wherever 'name'
     appears in the source lines following the definition,
     'token-string' will be substituted for 'name'.

     #define name(argument [, argument] ...  )  token-string

     This is the definition of a function-like macro.
     Occurrences of the macro 'name' followed by the comma-
     separated list of arguments within parentheses are substi-
     tuted by the token string produced from the macro defini-
     tion. Every occurrence of an argument identifier from the
     macro definition's arguments list is substituted by the
     token sequence representing the corresponding macro actual

     Macro arguments other than those that are operands of the
     macro substitution operators # and ## are expanded recur-
     sively prior to their substitution in the replacement token

     To allow argument substitution in string literals, use the #
     macro substitution operator:

        #define a(x)  #x
              a(actual argument)


              'actual argument'

     To combine two tokens in a macro definition, one or both of
     which is an argument, use the  ##  macro substitution opera-

        #define cat(x,y)  x##y x##b a##y
        #define ab ok


                ok ok ok

     In these definitions, spaces between the macro name and the
     '(' symbol are prohibited to prevent the directive being
     interpreted as a fpp variable definition with the rest of
     the line beginning with the '(' symbol being interpreted as
     a token-string.

     #undef name

     Remove any definition for 'name' (produced by 'D' options,
     #define directives or by default). No additional tokens are
     permitted on the directive line after the name.

  Including External Files.
     There are two forms of file inclusion:

     #include "filename"

     #include <filename>

     Read in the contents of filename at this location. The lines
     read in from the file are processed by fpp as  if it were a
     part of the current file.

     When the  <filename> notation is  used, filename is only
     searched for in the standard ``include'' directories.  See
     the 'I' and 'Y' options above for more detail.  No addi-
     tional tokens are permitted in the directive line after the
     final  `"'  or `>'.

  Line control.
     #line-number "filename"  or
     #line line-number "filename"

     Generate line control information for the next  pass of the
     compiler. The integer-constant is  interpreted as the line
     number of  the next line and the filename is  interpreted
     as the name of the file from where it comes.  If "filename"
     is not given, the current filename is unchanged.

  Conditional selection of source text.
     There are two forms of conditional selection of source text

     1)         #if condition_1
                #elif condition_2

     2)         #ifdef name
                #elif condition

     or         #ifndef name
                #elif condition

     else- and elif-part are optional.  There may be more than
     one elif-part. Condition is an expression involving fpp con-
     stants, macros  and intrinsic  functions. Condition expres-
     sions are similar to  cpp expressions, and may contain any
     cpp operations and operands with the exception of c long,
     octal and hexadecimal constants. Additionally, fpp will
     accept and evaluate Fortran logical operations .NOT. .AND.
     .OR. .EQV. .NEQV. .GT. .LT. .LE. .GE. etc. and logical con-
     stants .TRUE. .FALSE.


  Scope of macro or variable definitions.
     The scope of a definition begins from the place of its
     definition and encloses all the source lines (and source
     lines from included files) from that definition line to the
     end of the current file.

     There are the following exceptions to the scope effected by
     an fpp definition:

     - files included by Fortran INCLUDE statements;

     - fpp and Fortran comments;

     - IMPLICIT single letter specifications;

     - FORMAT specifications;

     - numeric, typeless and character constants.

     The scope of the macro effect can be limited by means of the
     #undef directive.

  End of macro definition
     Macro definition can be of any length and is limited only by
     the 'newline' symbol. A Macro can be defined in multiple
     lines. A Macro can be continued to the next line with the
     insertion of '\'. So, the occurrence of a 'newline' without
     a macro-continuation signifies the end of the macro defini-

     For example:
     #define long_macro_name(x,\
     y) x*y

     With Fortran 77 fixed form source files, there may be a need
     to produce more than one line or statement as the expansion
     of a macro. Use the ';' to separate statements that are to
     be produced on separate lines:

        #define init_i_j(x,y) i=x; j=y



  Function-like macro definition
     The number of macro call arguments should be the same as the
     number of arguments in the corresponding macro definition.
     An error is flagged if they don't.

  Cancelling macro definitions of both kinds
     #undef name

     After this directive,  'name' would not interpreted by fpp
     as a macro or variable name. If this name has not been
     defined earlier as a macro name, then the given directive
     has no effect

  Conditional source code selection
     - Constant-expression

     Subsequent lines up to the matching #else, #elif, or #endif
     directive, appear in the output only if their constant-
     expression yields a true value.

     The lines following the #elif directive appear in the output
     only if all of the following conditions hold:

          -    The constant-expression  in the   preceding #if
               directive evaluated to .FALSE.  or the name in the
               preceding #ifdef directive is not defined or the
               name in the preceding #ifndef directive is

          -    The constant-expression in all intervening #elif
               directives  evaluated to .FALSE.

          -    The  current constant-expression   evaluates to

     If  the  constant-expression  evaluates to .TRUE., subse-
     quent #elif  and  #else directives are ignored up to the
     matching #endif.  Any  constant-expression allowed in an #if
     directive is allowed in  an #elif directive.

     The intrinsic function `defined' can be used in a constant-
     expression also.

     The following items are permitted:

          -    C language operations: <, >, ==, !=, >=, <=, +, -,
               /, *, %, <<, >>, &,  ~, |, &&, || They are inter-
               preted by fpp in accordance to the C language
               semantics (this facility is provided for compati-
               bility with "old" Fortran programs using cpp)

          -    Fortran language operations: .AND., .OR., .NEQV.,
               .XOR., .EQV., .NOT.  , .GT., .LT., .LE., .GE.,
               .NE., .EQ., ** (power).

          -    Fortran logical constants: .TRUE. , .FALSE.

          Only these items, integer constants, and names can be
          used within a constant-expression. Names which have not
          been defined with the help of the 'D' option, a #define
          directive or by default, get 0 as the value.  The C
          operation '!=' (not equal) can be used in #if or #elif
          directive, but NOT in #define directive, where the sym-
          bol '!' is considered as the Fortran comment symbol.

     #ifdef name
          Subsequent lines up to the matching  #else, #elif, or
          #endif appear in the output only if the name has been
          defined, either by a #define directive or by the 'D'
          option, and in the absence of an intervening #undef
          directive. No additional tokens are permitted on the
          directive line after name.

     #ifndef name
          Subsequent lines up to the matching  #else,   #elif, or
          #endif appear in the output only  if name has not been
          defined, or if its definition has been removed with an
          #undef directive. No additional tokens  are permitted
          on the directive line after name.

     #elif constant-expression .
          Any number of #elif directives may  appear   between an
          #if,  #ifdef, or #ifndef directive and a matching #else
          or #endif  directive.

          This inverts the sense of the conditional directive
          otherwise in effect. If the preceding conditional would
          indicate that lines are to be included, then lines
          between the #else and the matching #endif are ignored.
          If the preceding conditional indicates that lines would
          be ignored, subsequent lines are included in the out-
          put.   Conditional directives and corresponding #else
          directives can be nested.

          End a section of lines begun by one of the conditional
          directives  #if, #ifdef, or #ifndef.  Each such direc-
          tive must have a matching #endif.

  Including External Files
     Is the same as it is for cpp.  Files are searched as fol-

     for  #include "file_name":

          -    in the directory, in which the processed file has
               been found;

          -    in the directories specified by the -I option;

          -    in the default directory.

     for #include <file_name>:

          -    in the directories specified by the -I option;

          -    in the default directory.

     fpp directives (beginning with the # symbol in the first
     position of lines) can be placed anywhere in a source code,
     in particular before a Fortran continuation line.  The only
     exception is the prohibition of fpp directives within a
     macro call divided on several lines by means of continuation

     fpp permits comments of two kinds:

     1) Fortran language comments.  A source line containing one
     of the symbols 'C', 'c', '*', 'd' or 'D' in the first posi-
     tion, is considered as a comment line. Within such lines
     macro expansions are not performed.  The '!' symbol is
     interpreted as the beginning of a comment extending to the
     end of the line. The only exception is the case when this
     symbol occurs within a constant-expression in #if and #elif
     directives (See above).

     2) fpp comments enclosed in the '/*' and '*/' parasymbols.
     They are excluded from the output and macro expansions are
     not performed within these symbols. fpp comments can be
     nested and for each parasymbol '/*' there must be a
     corresponding parasymbol '*/'.  fpp comments are suitable
     for excluding the compilation of large portions of source
     instead of commenting every line with Fortran comment sym-

  Intrinsic functions
     The intrinsic function

     defined(name)   or defined name


       .TRUE. - if name is defined as a macro.

       .FALSE.- if the name is not defined.

  Macro expansion
     If, during expansion of a macro, the column width of a line
     exceeds column 72 (for the fixed format) or column 132 (for
     the free format), fpp inserts appropriate continuation

     In the fixed form there is limitation on macro expansions in
     label fields (positions 1-5):

          -    a macro call (together with possible arguments)
               should not extend more than the column 5 position;

          -    a macro call whose name begins with one of the
               Fortran comment symbols is considered as a part of
               a comment;

          -    a macro expansion may produce a text extending
               beyond the column 5 position. In such a case a
               warning will be issued.

     In the fixed form when the '-Xw' option has been specified
     an ambiguity may appear if a macro call occurs in a state-
     ment position and a macro name begins or coincides with a
     Fortran keyword. For example, in the following text:

       #define callp(x)   call f(x)
               call p(0)

     fpp can not determine with certainty how to interpret the
     'call p' token sequence. It could be considered as a macro
     name. The current implementation does the following:

          -    the longer identifier is chosen (callp in this

          -    from this identifier the longest macro name or
               keyword is extracted;

          -    if a macro name has been extracted a macro expan-
               sion is performed. If the name begins with some
               keyword fpp outputs an appropriate warning;

          -    the rest of the identifier is considered as a
               whole identifier.

     In the above example the macro expansion would be performed
     and the following warning would be output:

     warning: possibly incorrect substitution of macro callp

     It should be noted that this situation appears only when
     preprocessing a fixed format source code and when the space
     symbol is not interpreted as a token delimiter.  It should
     be said also that if a macro name coincides with a keyword
     beginning part, as in the following case:

          #define INT    INTEGER*8
                  INTEGER k

     then in accordance with the described algorithm, the INTEGER
     keyword will be found earlier than the INT macro name. Thus,
     there will be no warning when preprocessing such a macro


     There are three kinds of diagnostic messages:

          -    warnings.  preprocessing of source code is contin-
               ued and the return value remains to be 0.

          -    errors.  fpp continues preprocessing but sets the
               return code to a nonzero value, namely number of

          -    fatal error.  fpp cancels preprocessing and
               returns a nonzero return value.

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


     cpp(1), f95(1)

     The source code for fpp is downloadable from NetLib