source: branches/libc-0.6/src/gcc/libf2c/readme.netlib

====== old index for f2c, now "readme from f2c" ============

FILES:

f2c.h   Include file necessary for compiling output of the converter.
        See the second NOTE below.

f2c.1   Man page for f2c.

f2c.1t  Source for f2c.1 (to be processed by troff -man or nroff -man).

libf77  Library of non I/O support routines the generated C may need.
        Fortran main programs result in a C function named MAIN__ that
        is meant to be invoked by the main() in libf77.

libi77  Library of Fortran I/O routines the generated C may need.
        Note that some vendors (e.g., BSD, Sun and MIPS) provide a
        libF77 and libI77 that are incompatible with f2c -- they
        provide some differently named routines or routines with the
        names that f2c expects, but with different calling sequences.
        On such systems, the recommended procedure is to merge
        libf77 and libi77 into a single library, say libf2c, and to
        install it where you can access it by specifying -lf2c .  The
        definition of link_msg in sysdep.c assumes this arrangement.

        Both libf77 and libi77 are bundles, meant to be unpacked by the
        Bourne (or Korn) shell.  MS-DOS users can use the MKS Toolkit
        to unpack libf77 and libi77.

libf2c.zip
        Only available by ftp: combination of libf77 and libi77, with
        Unix and PC makefiles.

f2c.ps  Postscript for a technical report on f2c.  After you strip the
        mail header, the first line should be "%!PS".

fixes   The complete change log, reporting bug fixes and other changes.
        (Some recent change-log entries are given below).

fc      A shell script that uses f2c and imitates much of the behavior
        of commonly found f77 commands.  You will almost certainly
        need to adjust some of the shell-variable assignments to make
        this script work on your system.


SUBDIRECTORY:

f2c/src Source for the converter itself, including a file of checksums
        and source for a program to compute the checksums (to verify
        correct transmission of the source), is available: ask netlib
        (e.g., [email protected]) to
                send all from f2c/src
        If the checksums show damage to just a few source files, or if
        the change log file (see "fixes" below) reports corrections to
        some source files, you can request those files individually
        "from f2c/src".  For example, to get defs.h and xsum0.out, you
        would ask netlib to
                send defs.h xsum0.out from f2c/src
        "all from f2c/src" is about 640 kilobytes long; for convenience
        (and checksums), it includes copies of f2c.h, f2c.1, and f2c.1t.

        Tip: if asked to send over 99,000 bytes in one request, netlib
        breaks the shipment into 1000 line pieces and sends each piece
        separately (since otherwise some mailers might gag).  To avoid
        the hassle of reassembling the pieces, try to keep each request
        under 99,000 bytes long.  The final number in each line of
        xsum0.out gives the length of each file in f2c/src.  For
        example,
                send exec.c expr.c from f2c/src
                send format.c format_data.c from f2c/src
        will give you slightly less hassle than
                send exec.c expr.c format.c format_data.c from f2c/src
        Alternatively, if all the mailers in your return path allow
        long messages, you can supply an appropriate mailsize line in
        your netlib request, e.g.
                mailsize 200k
                send exec.c expr.c format.c format_data.c from f2c/src

        The makefile used to generate gram.c; now we distribute a
        working gram.c, and you must say
                make gram1.c
                mv gram1.c gram.c
        if you want to generate your own gram.c -- there are just too
        many broken variants of yacc floating around nowadays for
        generation of gram.c to be the default.

NOTE:   You may exercise f2c by sending [email protected]
        a message whose first line is "execute f2c" and whose remaining
        lines are the Fortran 77 source that you wish to have converted.
        Return mail brings you the resulting C, with f2c's error
        messages between #ifdef uNdEfInEd and #endif at the end.
        (To understand line numbers in the error messages, regard
        the "execute f2c" line as line 0.  It is stripped away by
        the netlib software before f2c sees your Fortran input.)
        Options described in the man page may be transmitted to
        netlib by having the first line of input be a comment
        whose first 6 characters are "c$f2c " and whose remaining
        characters are the desired options, e.g., "c$f2c -R -u".

        You may say "execute f2c" in the Subject line instead of (but
        *not* in addition to) in the first line of the message body.

        The incoming Fortran is saved, at least for a while.  Don't
        send any secrets!


BUGS:   Please send bug reports (including the shortest example
        you can find that illustrates the bug) to research!dmg
        or [email protected] .  You might first check whether
        the bug goes away when you turn optimization off.


NOTE:   f2c.h defines several types, e.g., real, integer, doublereal.
        The definitions in f2c.h are suitable for most machines, but if
        your machine has sizeof(double) > 2*sizeof(long), you may need
        to adjust f2c.h appropriately.  f2c assumes
                sizeof(doublecomplex) = 2*sizeof(doublereal)
                sizeof(doublereal) = sizeof(complex)
                sizeof(doublereal) = 2*sizeof(real)
                sizeof(real) = sizeof(integer)
                sizeof(real) = sizeof(logical)
                sizeof(real) = 2*sizeof(shortint)
        EQUIVALENCEs may not be translated correctly if these
        assumptions are violated.

        On machines, such as those using a DEC Alpha processor, on
        which sizeof(short) == 2, sizeof(int) == sizeof(float) == 4,
        and sizeof(long) == sizeof(double) == 8, it suffices to
        modify f2c.h by removing the first occurrence of "long "
        on each line containing "long ", e.g., by issuing the
        commands
                mv f2c.h f2c.h0
                sed 's/long //' f2c.h0 >f2c.h
        On such machines, one can enable INTEGER*8 by uncommenting
        the typedef of longint in f2c.h, so it reads
                typedef long longint;
        by compiling libI77 with -DAllow_TYQUAD, and by adjusting
        libF77/makefile as described in libF77/README.

        Some machines may have sizeof(int) == 4, sizeof(float) == 8,
        and sizeof(long long) == 8.  On such machines, adjust f2c.h
        by changing "long int " to "long long ", e.g., by saying
                mv f2c.h f2c.h0
                sed 's/long int /long long /' f2c.h0 >f2c.h
        One can enable INTEGER*8 on such machines as described
        above, but with
                typedef long long longint;

        There exists a C compiler that objects to the lines
                typedef VOID C_f;       /* complex function */
                typedef VOID H_f;       /* character function */
                typedef VOID Z_f;       /* double complex function */
        in f2c.h .  If yours is such a compiler, do two things:
        1. Complain to your vendor about this compiler bug.
        2. Find the line
                #define VOID void
           in f2c.h and change it to
                #define VOID int
        (For readability, the f2c.h lines shown above have had two
        tabs inserted before their first character.)

FTP:    All the material described above is now available by anonymous
        ftp from netlib.bell-labs.com (login: anonymous; Password: your
        E-mail address; cd netlib/f2c).  Note that you can say, e.g.,

                cd /netlib/f2c/src
                binary
                prompt
                mget *.gz

        to get all the .gz files in src.  You must uncompress the .gz
        files once you have a copy of them, e.g., by

                gzip -dN *.gz

        You can also get the entire f2c tree as a tar file:

                ftp://netlib.bell-labs.com/netlib/f2c.tar

        (which is a synthetic file -- created on the fly and not visible
        to ftp's "ls" or "dir" commands).

        Subdirectory msdos contains two PC versions of f2c,
        f2c.exe.gz and f2cx.exe.gz; the latter uses extended memory.
        The README in that directory provides more details.

        Changes appear first in the f2c files available by E-mail
        from [email protected].  If the deamons work right,
        changed files are available the next day by ftp from
        netlib.bell-labs.com.  In due course, they reach other netlib servers.

CHANGE NOTIFICATION:
        Send the E-mail message
                subscribe f2c
        to [email protected] to request notification of new and
        changed f2c files.  (Beware that automatically sent change
        notifications may reach you before changes have reached
        ftp://netlib.bell-labs.com/netlib/f2c or to other netlib servers.)
        Send the E-mail message
                unsubscribe f2c
        to recant your notification request.

-----------------
Recent change log (partial)
-----------------

Mon May 13 23:35:26 EDT 1996
  Recognize Fortran 90's /= as a synonym for .NE..  (<> remains a
synonym for .NE..)
  Emit an empty int function of no arguments to supply an external
name to named block data subprograms (so they can be called somewhere
to force them to be loaded from a library).
  Fix bug (memory fault) in handling the following illegal Fortran:
        parameter(i=1)
        equivalence(i,j)
        end
  Treat cdabs, cdcos, cdexp, cdlog, cdsin, and cdsqrt as synonyms for
the double complex intrinsics zabs, zcos, zexp, zlog, zsin, and zsqrt,
respectively, unless -cd is specified.
  Recognize the Fortran 90 bit-manipulation intrinsics btest, iand,
ibclr, ibits, ibset, ieor, ior, ishft, and ishftc, unless -i90 is
specified.  Note that iand, ieor, and ior are thus now synonyms for
"and", "xor", and "or", respectively.
  Add three macros (bit_test, bit_clear, bit_set) to f2c.h for use
with btest, ibclr, and ibset, respectively.  Add new functions
[lq]bit_bits, [lq]bit_shift, and [lq]_bit_cshift to libF77 for
use with ibits, ishft, and ishftc, respectively.
  Add integer function ftell(unit) (returning -1 on error) and
subroutine fseek(unit, offset, whence, *) to libI77 (with branch to
label * on error).

Tue May 14 23:21:12 EDT 1996
  Fix glitch (possible memory fault, or worse) in handling multiple
entry points with names over 28 characters long.

Mon Jun 10 01:20:16 EDT 1996
  Update netlib E-mail and ftp addresses in f2c/readme and
f2c/src/readme (which are different files) -- to reflect the upcoming
breakup of AT&T.
  libf77: trivial tweaks to F77_aloc.c and system_.c; Version.c not
changed.
  libi77: Adjust rsli.c and lread.c so internal list input with too
few items in the input string will honor end= .

Mon Jun 10 22:59:57 EDT 1996
  Add Bits_per_Byte to sysdep.h and adjust definition of Table_size
to depend on Bits_per_Byte (forcing Table_size to be a power of 2); in
lex.c, change "comstart[c & 0xfff]" to "comstart[c & (Table_size-1)]"
to avoid an out-of-range subscript on end-of-file.

Wed Jun 12 00:24:28 EDT 1996
  Fix bug in output.c (dereferencing a freed pointer) revealed in
        print *         !np in out_call in output.c clobbered by free
        end             !during out_expr.

Wed Jun 19 08:12:47 EDT 1996
  f2c.h: add types uinteger, ulongint (for libF77); add qbit_clear
and qbit_set macros (in a commented-out section) for integer*8.
  For integer*8, use qbit_clear and qbit_set for ibclr and ibset.
  libf77: add casts to unsigned in [lq]bitshft.c.

Thu Jun 20 13:30:43 EDT 1996
  Complain at character*(*) in common (rather than faulting).
  Fix bug in recognizing hex constants that start with "16#" (e.g.,
16#1234abcd, which is a synonym for z'1234abcd').
  Fix bugs in constant folding of expressions involving btest, ibclr,
and ibset.
  Fix bug in constant folding of rshift(16#80000000, -31) (on a 32-bit
machine; more generally, the bug was in constant folding of
rshift(ibset(0,NBITS-1), 1-NBITS) when f2c runs on a machine with