Return to x CVS log

Up to [Research Unix] / researchv10no / cmd / f2c / doc

Annotation of researchv10no/cmd/f2c/doc/x, revision 1.1

1.1     ! root        1: . \"define f2c % "\f(CWf2c\fP" %
        !             2: . \"define F2c % "\f(CWF2c\fP" %
        !             3: .de Bp
        !             4: .ft R
        !             5: .sp .5
        !             6: .in \w'\(bu\ 'u
        !             7: .ti 0
        !             8: \(bu\ \c
        !             9: ..
        !            10: .EQ
        !            11: define dollar % "\f(CW$\fP" %
        !            12: delim $$
        !            13: define f2c % "f\|2c" %
        !            14: define F2c % "F\^2c" %
        !            15: define libF77 % "libF77" %
        !            16: define libI77 % "libI77" %
        !            17: define LibF77 % "LibF77" %
        !            18: define LibI77 % "LibI77" %
        !            19: .EN
        !            20: .TL
        !            21: A Fortran to C Converter
        !            22: .AU
        !            23: S. I. Feldman
        !            24: .AI
        !            25: Bellcore
        !            26: Morristown, NJ 07960
        !            27: .AU
        !            28: D. M. Gay
        !            29: .AI
        !            30: .MH
        !            31: .AU
        !            32: M. W. Maimone
        !            33: .AI
        !            34: Carnegie-Mellon University
        !            35: Pittsburgh, PA 15213
        !            36: .AU
        !            37: N. L. Schryer
        !            38: .AI
        !            39: .MH
        !            40: .AB
        !            41: We describe $f2c$, a program that translates Fortran 77
        !            42: into C or C++.  $F2c$ lets one portably mix C and Fortran
        !            43: and makes a large body of well-tested Fortran
        !            44: source code available to C environments.
        !            45: .AE
        !            46: .SH
        !            47: 1. INTRODUCTION
        !            48: .PP
        !            49: Automatic conversion of Fortran 77
        !            50: .[ [
        !            51: ANSI FORTRAN 1978
        !            52: .]]
        !            53: to C
        !            54: .[ [
        !            55: Kernighan Ritchie 1978
        !            56: .]
        !            57: .[
        !            58: Kernighan Ritchie 1988
        !            59: .]]
        !            60: is desirable for
        !            61: several reasons.  Sometimes it is useful to run a
        !            62: well-tested Fortran program on a machine that has a C
        !            63: compiler but no Fortran compiler.  At other times, it
        !            64: is convenient to mix C and Fortran.  Some things are
        !            65: impossible to express in Fortran 77 or are harder
        !            66: to express in Fortran than in C
        !            67: (e.g. storage management, some character operations,
        !            68: arrays of functions, heterogeneous data structures,
        !            69: and calls that depend on the operating system),
        !            70: and some programmers simply prefer C to Fortran.
        !            71: There is a large body of well tested
        !            72: Fortran source code for carrying out a wide variety of
        !            73: useful calculations, and it is sometimes desirable to
        !            74: exploit some of this Fortran source in a C environment.
        !            75: Many vendors provide some way of mixing C and Fortran, but
        !            76: the details vary from system to system.
        !            77: Automatic Fortran to C conversion lets one create a
        !            78: .I portable
        !            79: C program that exploits Fortran source code.
        !            80: .PP
        !            81: A side benefit of automatic Fortran 77 to C conversion is that
        !            82: it allows such tools as
        !            83: .I cyntax (1)
        !            84: and
        !            85: .I lint (1)
        !            86: \ 
        !            87: .[[
        !            88: v101
        !            89: .]]
        !            90: to provide Fortran 77 programs with some of the consistency
        !            91: and portability checks that the Pfort Verifier
        !            92: .[ [
        !            93: Ryder 1974
        !            94: .]]
        !            95: provided to Fortran 66 programs.
        !            96: The consistency checks
        !            97: detect errors in calling sequences
        !            98: and are thus a boon to debugging.
        !            99: .PP
        !           100: This paper describes $f2c$, a Fortran 77 to C converter
        !           101: based on Feldman's original $f77$ compiler
        !           102: .[ [
        !           103: Feldman Weinberger Portable Fortran
        !           104: .]].
        !           105: We have used $f2c$ to convert various large programs and
        !           106: subroutine libraries to C automatically (i.e., with no manual intervention);
        !           107: these include the \s-2PORT3\s+2 subroutine library (\s-2PORT1\s+2
        !           108: is described in
        !           109: .[ [
        !           110: Fox Hall Schryer Algorithm 1978
        !           111: .]
        !           112: .[
        !           113: Fox Hall Schryer port 1978
        !           114: .]]),
        !           115: MINOS
        !           116: .[ [
        !           117: Murtagh Saunders 1987
        !           118: .]],
        !           119: and Schryer's floating-point test
        !           120: .[ [
        !           121: Schryer floating
        !           122: .]].
        !           123: The floating-point test is of particular interest, as it relies
        !           124: heavily on correct evaluation of parenthesized expressions and
        !           125: is bit-level self-testing.
        !           126: .PP
        !           127: As a debugging aid, we sought bit-level compatibility between
        !           128: objects compiled from the C produced by $f2c$ and objects
        !           129: produced by our local $f77$ compiler.  That is, on the VAX
        !           130: where we developed $f2c$, we sought to make it impossible to
        !           131: tell by running a Fortran program whether some of its
        !           132: modules had been compiled by $f2c$ or
        !           133: all had been compiled by $f77$.  This meant that $f2c$
        !           134: should follow the same calling conventions as $f77$
        !           135: .[ [
        !           136: Feldman Weinberger Portable Fortran
        !           137: .]]
        !           138: and should use $f77$'s support libraries, $libF77$ and $libI77$.
        !           139: .PP
        !           140: Although we have tried to make $f2c$'s output reasonably readable,
        !           141: our goal of strict compatibility with $f77$ implies some nasty
        !           142: looking conversions.  Input/output statements, in particular,
        !           143: generally get expanded into
        !           144: a series of calls on routines in $libI77$, $f77$'s I/O library.
        !           145: Thus the C output of $f2c$ would probably be something of a nightmare
        !           146: to maintain as C; it would be much more sensible to maintain the original
        !           147: Fortran, translating it anew each time it changed.  Some commercial
        !           148: vendors, e.g., those listed in Appendix A,
        !           149: seek to perform translations yielding C that one
        !           150: might reasonably maintain directly; these translations generally
        !           151: require some manual intervention.
        !           152: .PP
        !           153: The rest of this paper is organized as follows.
        !           154: Section 2 describes the interlanguage conventions used by $f2c$ (and $f77$).
        !           155: \(sc3 summarizes some extensions to Fortran 77 that $f2c$ recognizes.
        !           156: . \"The extensions to Fortran 77 that $f2c$ recognizes are summarized in \(sc3.
        !           157: Example invocations of $f2c$ appear in \(sc4.
        !           158: \(sc5 illustrates various details of $f2c$'s translations, and
        !           159: \(sc6 considers portability issues.
        !           160: \(sc7 discusses the generation and use of
        !           161: .I prototypes ,
        !           162: which can be used both by C++ and ANSI C compilers and by
        !           163: $f2c$ to check consistency of calling sequences.
        !           164: \(sc8 describes our experience with
        !           165: an experimental $f2c$ service provided by $netlib$
        !           166: .[ [
        !           167: Dongarra Grosse 1987
        !           168: .]],
        !           169: and \(sc9 considers possible extensions.
        !           170: Appendix A lists some vendors who offer
        !           171: conversion of Fortran to C that one might maintain as C.
        !           172: Finally, Appendix B contains a $man$ page telling how to use $f2c$.
        !           173: .SH
        !           174: 2. INTERLANGUAGE CONVENTIONS
        !           175: .PP
        !           176: Much of the material in this section is taken from
        !           177: .[ [
        !           178: Feldman Weinberger Portable Fortran
        !           179: .]].
        !           180: .SH
        !           181: Names
        !           182: .PP
        !           183: An $f2c$ extension
        !           184: inspired by Fortran 8x
        !           185: .[ [
        !           186: Fort8x
        !           187: .]]
        !           188: is that long names are allowed ($f2c$ truncates names that are longer
        !           189: than 50 characters), and names may contain underscores.  To avoid conflict
        !           190: with the names of library routines and with names that $f2c$ generates,
        !           191: Fortran names may have one or two underscores appended.
        !           192: Fortran names are forced to lower case (unless the
        !           193: .CW \%-U
        !           194: option described in Appendix B is in effect); external names, i.e., the names
        !           195: of Fortran procedures and common blocks, have a single underscore appended
        !           196: if they do not contain any underscores and have a pair of underscores
        !           197: appended if they do contain underscores.
        !           198: Thus Fortran subroutines named
        !           199: .CW ABC ,
        !           200: .CW A_B_C ,
        !           201: and
        !           202: .CW A_B_C_
        !           203: result in C functions named
        !           204: .CW abc_ ,
        !           205: .CW a_b_c_\|\^_ ,
        !           206: and
        !           207: .CW a_b_c_\|\^_\|\^_ .
        !           208: .SH
        !           209: Types
        !           210: .PP
        !           211: The table below shows
        !           212: corresponding Fortran and C declarations;
        !           213: the C declarations use types defined in
        !           214: .CW f2c.h ,
        !           215: a header file upon which $f2c$'s translations rely.
        !           216: The table also shows the C types defined in the standard
        !           217: version of
        !           218: .CW f2c.h .
        !           219: .KS
        !           220: .TS
        !           221: center box;
        !           222: c c c
        !           223: l l l.
        !           224: Fortran        C       standard \f(CWf2c.h\fP
        !           225: .sp .5
        !           226: integer\(**2 x shortint x;     short int x;
        !           227: integer x      integer x;      long int x;
        !           228: logical x      long int x;     long int x;
        !           229: real x real x; float x;
        !           230: double precision x     doublereal x;   double x;
        !           231: complex x      complex x;      struct { float r, i; } x;
        !           232: double complex x       doublecomplex x;        struct { double r, i; } x;
        !           233: character\(**6 x       char x[6];      char x[6];
        !           234: .TE
        !           235: .KE
        !           236: By the rules of Fortran,
        !           237: .CW integer,
        !           238: .CW logical,
        !           239: and
        !           240: .CW real
        !           241: data occupy the same amount of memory, and
        !           242: .CW "double precision"
        !           243: and
        !           244: .CW complex
        !           245: occupy twice this amount; $f2c$
        !           246: assumes that the types in the C column above are
        !           247: chosen (in
        !           248: .CW f2c.h )
        !           249: so that these assumptions are valid.
        !           250: The translations of the Fortran
        !           251: .CW equivalence
        !           252: and
        !           253: .CW data
        !           254: statements depend on these assumptions.
        !           255: On some machines, one must modify
        !           256: .CW f2c.h
        !           257: to make these assumptions hold.  See \(sc6 for examples
        !           258: and further discussion.
        !           259: .SH
        !           260: Return Values
        !           261: .PP
        !           262: A function of type
        !           263: .CW integer ,
        !           264: .CW logical ,
        !           265: or
        !           266: .CW "double precision"
        !           267: must be declared as a C function that returns the corresponding type.
        !           268: If the
        !           269: .CW \%-R
        !           270: option is in effect (see Appendix B), the same is true
        !           271: of a function of type
        !           272: .CW real ;
        !           273: otherwise, a
        !           274: .CW real
        !           275: function must be declared as a C function that returns
        !           276: .CW doublereal ;
        !           277: this hack facilitates our VAX regression testing, as it
        !           278: duplicates the behavior of our local Fortran compiler ($f77$).
        !           279: A
        !           280: .CW complex
        !           281: or
        !           282: .CW "double complex"
        !           283: function is equivalent to a C routine
        !           284: with an additional
        !           285: initial argument that points to the place where the return value is to be stored.
        !           286: Thus,
        !           287: .P1
        !           288: complex function f( . . . )
        !           289: .P2
        !           290: is equivalent to
        !           291: .P1
        !           292: void f_(temp, . . .)
        !           293: complex \(**temp;
        !           294:  . . .
        !           295: .P2
        !           296: A character-valued function is equivalent to a C routine with
        !           297: two extra initial arguments:
        !           298: a data address and a length.
        !           299: Thus,
        !           300: .P1
        !           301: character\(**15 function g( . . . )
        !           302: .P2
        !           303: is equivalent to
        !           304: .P1
        !           305: g_(result, length, . . .)
        !           306: char \(**result;
        !           307: ftnlen length;
        !           308:  . . .
        !           309: .P2
        !           310: and could be invoked in C by
        !           311: .P1
        !           312: char chars[15];
        !           313:  . . .
        !           314: g_(chars, 15L, . . . );
        !           315: .P2
        !           316: Subroutines are invoked as if they were
        !           317: .CW int -valued
        !           318: functions whose value specifies which alternate return to use.
        !           319: Alternate return arguments (statement labels) are not passed to the function,
        !           320: but are used to do an indexed branch in the calling procedure.
        !           321: (If the subroutine has no entry points with alternate return arguments,
        !           322: the returned value is undefined.)
        !           323: The statement
        !           324: .P1
        !           325: call nret(\(**1, \(**2, \(**3)
        !           326: .P2
        !           327: is treated exactly as if it were the Fortran computed
        !           328: .CW goto
        !           329: .P1
        !           330: goto (1, 2, 3),  nret( )
        !           331: .P2
        !           332: .SH
        !           333: Argument Lists
        !           334: .PP
        !           335: All Fortran arguments are passed by address.
        !           336: In addition,
        !           337: for every non-function argument that is of type character,
        !           338: an argument giving the length of the value is passed.
        !           339: (The string lengths are
        !           340: .CW ftnlen
        !           341: values, i.e.,
        !           342: .CW "long int"
        !           343: quantities passed by value).  In summary, the order of arguments is:
        !           344: extra arguments for complex and character functions,
        !           345: an address for each datum or function, and a
        !           346: .CW ftnlen
        !           347: for each character argument (other than character-valued functions).
        !           348: Thus, the call in
        !           349: .P1
        !           350: external f
        !           351: character\(**7 s
        !           352: integer b(3)
        !           353:  . . .
        !           354: call sam(f, b(2), s)
        !           355: .P2
        !           356: is equivalent to that in
        !           357: .P1
        !           358: int f();
        !           359: char s[7];
        !           360: long int b[3];
        !           361:  . . .
        !           362: sam_(f, &b[1], s, 7L);
        !           363: .P2
        !           364: Note that the first element of a C array always has subscript zero,
        !           365: but Fortran arrays begin at 1 by default.
        !           366: Because Fortran arrays are stored in column-major order, whereas
        !           367: C arrays are stored in row-major order,
        !           368: $f2c$ translates multi-dimensional Fortran arrays into one-dimensional
        !           369: C arrays and issues appropriate subscripting expressions.
        !           370: .SH
        !           371: 3. EXTENSIONS TO FORTRAN 77
        !           372: .PP
        !           373: Since it is derived from $f77$, $f2c$ supports all of the $f77$ extensions
        !           374: described in
        !           375: .[ [
        !           376: Feldman Weinberger Portable Fortran
        !           377: .]].
        !           378: $F2c$'s extensions include the following.
        !           379: .Bp
        !           380: Type
        !           381: .CW "double complex"
        !           382: (alias
        !           383: .CW "complex*16" )
        !           384: is a double-precision version of
        !           385: .CW complex .
        !           386: Specific intrinsic functions for
        !           387: .CW "double complex"
        !           388: have names that start with
        !           389: .CW z
        !           390: rather than
        !           391: .CW c .
        !           392: .Bp
        !           393: The ``types'' that may appear in an
        !           394: .CW implicit
        !           395: statement include
        !           396: .CW undefined ,
        !           397: which implies that variables
        !           398: whose names begin with the associated letters
        !           399: must be explicitly declared in a type statement.  $F2c$ also
        !           400: recognizes the Fortran 8x statement
        !           401: .P1
        !           402: implicit none
        !           403: .P2
        !           404: as equivalent to
        !           405: .P1
        !           406: implicit undefined(a-z)
        !           407: .P2
        !           408: The command-line option
        !           409: .CW \%-u
        !           410: has the effect of inserting
        !           411: .P1
        !           412: implicit none
        !           413: .P2
        !           414: at the beginning of each Fortran procedure.
        !           415: .Bp
        !           416: Procedures may call themselves recursively, i.e.,
        !           417: may call themselves either directly or indirectly
        !           418: through a chain of other calls.
        !           419: .Bp
        !           420: The keywords
        !           421: .CW static
        !           422: and
        !           423: .CW automatic
        !           424: act as ``types'' in type and implicit statements;
        !           425: they specify storage classes.
        !           426: There is exactly one copy of each
        !           427: .CW static
        !           428: variable, and such variables retain their values between
        !           429: invocations of the procedure in which they appear.
        !           430: On the other hand, each invocation of a procedure gets
        !           431: new copies of the procedure's
        !           432: .CW automatic
        !           433: variables.
        !           434: .CW Automatic
        !           435: variables may not appear in
        !           436: .CW equivalence ,
        !           437: .CW data ,
        !           438: .CW namelist ,
        !           439: or
        !           440: .CW save
        !           441: statements.  The command-line option
        !           442: .CW \%-a
        !           443: changes the default storage class from
        !           444: .CW static
        !           445: to
        !           446: .CW automatic
        !           447: (for all variables except those that appear in
        !           448: .CW common ,
        !           449: .CW data ,
        !           450: .CW equivalence ,
        !           451: .CW namelist ,
        !           452: or
        !           453: .CW save
        !           454: statements).
        !           455: .Bp
        !           456: A tab in the first 6 columns signifies that the current line is
        !           457: a free-format line, which may extend beyond column 72.
        !           458: An ampersand
        !           459: .CW &
        !           460: in column 1 indicates that the current line is a free-format
        !           461: continuation line.  Lines that have neither an ampersand in column 1
        !           462: nor a tab in the first 6 columns are treated as Fortran 77 fixed-format
        !           463: lines:  if shorter than 72 characters, they are padded on the right
        !           464: with blanks until they are 72 characters long; if longer than 72
        !           465: characters, the characters beyond column 72 are discarded.
        !           466: After taking continuations into account,
        !           467: statements may be up to 1320 characters long; this is the only
        !           468: constraint on the length of free-format lines.  (This limit is
        !           469: implied by the Fortran 77 standard, which allows at most 19 continuation lines;
        !           470: $1320 ~=~ (1^+^19) ~times~ 66$.)
        !           471: .Bp
        !           472: Aside from quoted strings, $f2c$ ignores case (unless the
        !           473: .CW \%-U
        !           474: option is in effect).
        !           475: .Bp
        !           476: The statement
        !           477: .P1
        !           478: include stuff
        !           479: .P2
        !           480: is replaced by the contents of the file
        !           481: .CW stuff.
        !           482: .CW Include s
        !           483: may be nested to a reasonable depth, currently ten.
        !           484: The command-line option
        !           485: .CW \%-!I
        !           486: disables
        !           487: .CW include s;
        !           488: this option is used by the $netlib$ $f2c$
        !           489: service described in \(sc8 (for which
        !           490: .CW include
        !           491: obviously makes no sense).
        !           492: .Bp
        !           493: $F77$ allows binary, octal, and hexadecimal constants
        !           494: to appear in
        !           495: .CW data
        !           496: statements; $f2c$ goes somewhat further, allowing
        !           497: such constants to appear anywhere; they are treated just
        !           498: like a decimal integer constant having the equivalent value.
        !           499: Binary, octal, and hexadecimal constants may assume one of
        !           500: two forms: a letter followed by a quoted string of digits,
        !           501: or a decimal base, followed by a sharp sign
        !           502: .CW # ,
        !           503: followed by a string of digits (not quoted).  The letter is
        !           504: .CW b
        !           505: or
        !           506: .CW B
        !           507: for binary constants,
        !           508: .CW o
        !           509: or
        !           510: .CW O
        !           511: for octal constants, and
        !           512: .CW x ,
        !           513: .CW X ,
        !           514: .CW z ,
        !           515: or
        !           516: .CW Z
        !           517: for hexadecimal constants.  Thus, for example,
        !           518: .CW z'a7' ,
        !           519: .CW 16#a7 ,
        !           520: .CW o'247' ,
        !           521: .CW 8#247 ,
        !           522: .CW b'10100111'
        !           523: and
        !           524: .CW 2#10100111
        !           525: are all treated just like the integer
        !           526: .CW 167 .
        !           527: .Bp
        !           528: For compatibility with C, quoted strings may contain the following
        !           529: escapes:
        !           530: .TS
        !           531: center box;
        !           532: aFCW a a aFCW a.
        !           533: \e0    null    \       \en     newline
        !           534: \e\e   \e      \       \er     carriage return
        !           535: \eb    backspace       \       \et     tab
        !           536: \ef    form feed       \       \ev     vertical tab
        !           537: .T&
        !           538: aFCW a s s s.
        !           539: \e'    apostrophe (does not terminate a string)
        !           540: \e"    quotation mark (does not terminate a string)
        !           541: \e\fIx\fP      \fIx\fR, where \fIx\fR is any other character
        !           542: .TE
        !           543: The
        !           544: .CW \%-!bs
        !           545: option tells $f2c$ not to recognize these escapes.
        !           546: Quoted strings may be delimited either by double quotes (\ \f(CW"\fR\ )
        !           547: or by single quotes (\ \f(CW\(fm\fR\ ); if a string starts with
        !           548: one kind of quote, the other kind may be embedded in the string
        !           549: without being repeated or quoted by a backslash escape.
        !           550: Where possible, translated strings are null-terminated.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.