* Previous contents of gcc/f/runtime moved into toplevel

[gcc.git] / 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., netlib@netlib.bell-labs.com) 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

        If you have trouble generating gram.c, you can ask netlib to
                send gram.c from f2c/src
        Then `xsum gram.c` should report
                gram.c  5529f4f 58745
        Alternatively, if you have bison, you might get a working
        gram.c by saying
                make gram.c YACC=bison YFLAGS=-y
        (but please do not complain if this gives a bad gram.c).

NOTE:   For now, you may exercise f2c by sending netlib 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 dmg@bell-labs.com .  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 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 *.Z

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

                uncompress *.Z

        Subdirectory msdos contains two PC versions of f2c,
        f2c.exe.Z and f2cx.exe.Z; 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 netlib@netlib.bell-labs.com.  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 netlib@netlib.bell-labs.com 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
long ints having NBITS bits.

Mon Jun 24 07:58:53 EDT 1996
  Adjust struct Literal and newlabel() function to accommodate huge
source files (with more than 32767 newlabel() invocations).
  Omit .c file when the .f file has a missing final end statement.

Wed Jun 26 14:00:02 EDT 1996
  libi77: Add discussion of MXUNIT (highest allowed Fortran unit number)
to libI77/README.

Fri Jun 28 14:16:11 EDT 1996
  Fix glitch with -onetrip: the temporary variable used for nonconstant
initial loop variable values was recycled too soon.  Example:
        do i = j+1, k
                call foo(i+1)   ! temp for j+1 was reused here
                enddo
        end

Tue Jul  2 16:11:27 EDT 1996
  formatdata.c: add a 0 to the end of the basetype array (for TYBLANK)
(an omission that was harmless on most machines).
  expr.c: fix a dereference of NULL that was only possible with buggy
input, such as
        subroutine $sub(s)      ! the '$' is erroneous
        character s*(*)
        s(1:) = ' '
        end

Sat Jul  6 00:44:56 EDT 1996
  Fix glitch in the intrinsic "real" function when applied to a
complex (or double complex) variable and passed as an argument to
some intrinsic functions.  Example:
        complex a
        b = sqrt(real(a))
        end
  Fix glitch (only visible if you do not use f2c's malloc and the
malloc you do use is defective in the sense that malloc(0) returns 0)
in handling include files that end with another include (perhaps
followed by comments).
  Fix glitch with character*(*) arguments named "h" and "i" when
the body of the subroutine invokes the intrinsic LEN function.
  Arrange that after a previous "f2c -P foo.f" has produced foo.P,
running "f2c foo.P foo.f" will produce valid C when foo.f contains
        call sub('1234')
        end
        subroutine sub(msg)
        end
Specifically, the length argument in "call sub" is now suppressed.
With or without foo.P, it is also now suppressed when the order of
subprograms in file foo.f is reversed:
        subroutine sub(msg)
        end
        call sub('1234')
        end
  Adjust copyright notices to reflect AT&T breakup.

Wed Jul 10 09:25:49 EDT 1996
  Fix bug (possible memory fault) in handling erroneously placed
and inconsistent declarations.  Example that faulted:
        character*1 w(8)
        call foo(w)
        end
        subroutine foo(m)
        data h /0.5/
        integer m(2)    ! should be before data
        end
  Fix bug (possible fault) in handling illegal "if" constructions.
Example (that faulted):
        subroutine foo(i,j)
        if (i) then             ! bug: i is integer, not logical
        else if (j) then        ! bug: j is integer, not logical
        endif
        end
  Fix glitch with character*(*) argument named "ret_len" to a
character*(*) function.

Wed Jul 10 23:04:16 EDT 1996
  Fix more glitches in the intrinsic "real" function when applied to a
complex (or double complex) variable and passed as an argument to
some intrinsic functions.  Example:
        complex a, b
        r = sqrt(real(conjg(a))) + sqrt(real(a*b))
        end

Thu Jul 11 17:27:16 EDT 1996
  Fix a memory fault associated with complicated, illegal input.
Example:
        subroutine goo
        character a
        call foo(a)     ! inconsistent with subsequent def and call
        end
        subroutine foo(a)
        end
        call foo(a)
        end

Wed Jul 17 19:18:28 EDT 1996
  Fix yet another case of intrinsic "real" applied to a complex
argument.  Example:
        complex a(3)
        x = sqrt(real(a(2)))    ! gave error message about bad tag
        end

Mon Aug 26 11:28:57 EDT 1996
  Tweak sysdep.c for non-Unix systems in which process ID's can be
over 5 digits long.

Tue Aug 27 08:31:32 EDT 1996
  Adjust the ishft intrinsic to use unsigned right shifts.  (Previously,
a negative constant second operand resulted in a possibly signed shift.)

Thu Sep 12 14:04:07 EDT 1996
  equiv.c: fix glitch with -DKR_headers.
  libi77: fmtlib.c: fix bug in printing the most negative integer.

Fri Sep 13 08:54:40 EDT 1996
  Diagnose some illegal appearances of substring notation.

Tue Sep 17 17:48:09 EDT 1996
  Fix fault in handling some complex parameters.  Example:
        subroutine foo(a)
        double complex a, b
        parameter(b = (0,1))
        a = b   ! f2c faulted here
        end

Thu Sep 26 07:47:10 EDT 1996
  libi77:  fmt.h:  for formatted writes of negative integer*1 values,
make ic signed on ANSI systems.  If formatted writes of integer*1
values trouble you when using a K&R C compiler, switch to an ANSI
compiler or use a compiler flag that makes characters signed.

Tue Oct  1 14:41:36 EDT 1996
  Give a better error message when dummy arguments appear in data
statements.

Thu Oct 17 13:37:22 EDT 1996
  Fix bug in typechecking arguments to character and complex (or
double complex) functions; the bug could cause length arguments
for character arguments to be omitted on invocations appearing
textually after the first invocation.  For example, in
        subroutine foo
        character c
        complex zot
        call goo(zot(c), zot(c))
        end
the length was omitted from the second invocation of zot, and
there was an erroneous error message about inconsistent calling
sequences.

Wed Dec  4 13:59:14 EST 1996
  Fix bug revealed by
        subroutine test(cdum,rdum)
        complex cdum
        rdum=cos(real(cdum))    ! "Unexpected tag 3 in opconv_fudge"
        end
  Fix glitch in parsing "DO 10 D0 = 1, 10".
  Fix glitch in parsing
        real*8 x
        real*8 x        ! erroneous "incompatible type" message
        call foo(x)
        end
  lib[FI]77/makefile: add comment about omitting -x under Solaris.

Mon Dec  9 23:15:02 EST 1996
  Fix glitch in parameter adjustments for arrays whose lower
bound depends on a scalar argument.  Example:
        subroutine bug(p,z,m,n)
        integer z(*),m,n
        double precision p(z(m):z(m) + n)       ! p_offset botched
        call foo(p(0), p(n))
        end
  libi77: complain about non-positive rec= in direct read and write
statements.
  libf77: trivial adjustments; Version.c not changed.

Wed Feb 12 00:18:03 EST 1997
  output.c: fix (seldom problematic) glitch in out_call: put parens
around the ... in a test of the form "if (q->tag == TADDR && ...)".
  vax.c: fix bug revealed in the "psi_offset =" assignment in the
following example:
        subroutine foo(psi,m)
        integer z(100),m
        common /a/ z
        double precision psi(z(m):z(m) + 10)
        call foo(m+1, psi(0),psi(10))
        end

Mon Feb 24 23:44:54 EST 1997
  For consistency with f2c's current treatment of adjacent character
strings in FORMAT statements, recognize a Hollerith string following
a string (and merge adjacent strings in FORMAT statements).

Wed Feb 26 13:41:11 EST 1997
  New libf2c.zip, a combination of the libf77 and libi77 bundles (and
available only by ftp).
  libf77: adjust functions with a complex output argument to permit
aliasing it with input arguments.  (For now, at least, this is just
for possible benefit of g77.)
  libi77: tweak to ftell_.c for systems with strange definitions of
SEEK_SET, etc.

Tue Apr  8 20:57:08 EDT 1997
  libf77: [cz]_div.c: tweaks invisible on most systems (that may
improve things slightly with optimized compilation on systems that use
gratuitous extra precision).
  libi77: fmt.c: adjust to complain at missing numbers in formats
(but still treat missing ".nnn" as ".0").

Fri Apr 11 14:05:57 EDT 1997
  libi77: err.c: attempt to make stderr line buffered rather than
fully buffered.  (Buffering is needed for format items T and TR.)

Thu Apr 17 22:42:43 EDT 1997
 libf77: add F77_aloc.o to makefile (and makefile.u in libf2c.zip).

Fri Apr 25 19:32:09 EDT 1997
 libf77: add [de]time_.c (which may give trouble on some systems).

Tue May 27 09:18:52 EDT 1997
 libi77: ftell_.c: fix typo that caused the third argument to be
treated as 2 on some systems.

Mon Jun  9 00:04:37 EDT 1997
 libi77 (and libf2c.zip): adjust include order in err.c lread.c wref.c
rdfmt.c to include fmt.h (etc.) after system includes.  Version.c not
changed.

Mon Jun  9 14:29:13 EDT 1997
 src/gram.c updated; somehow it did not reflect the change of
19961001 to gram.dcl.

Mon Jul 21 16:04:54 EDT 1997
  proc.c: fix glitch in logic for "nonpositive dimension" message.
  libi77: inquire.c: always include string.h (for possible use with
-DNON_UNIX_STDIO); Version.c not changed.

Thu Jul 24 17:11:23 EDT 1997
  Tweak "Notice" to reflect the AT&T breakup -- we missed it when
updating the copyright notices in the source files last summer.
  Adjust src/makefile so malloc.o is not used by default, but can
be specified with "make MALLOC=malloc.o".
  Add comments to src/README about the "CRAY" T3E.

Tue Aug  5 14:53:25 EDT 1997
  Add definition of calloc to malloc.c; this makes f2c's malloc
work on some systems where trouble hitherto arose because references
to calloc brought in the system's malloc.  (On sensible systems,
calloc is defined separately from malloc.  To avoid confusion on
other systems, f2c/malloc.c now defines calloc.)
  libi77: lread.c: adjust to accord with a change to the Fortran 8X
draft (in 1990 or 1991) that rescinded permission to elide quote marks
in namelist input of character data; to get the old behavior, compile
with F8X_NML_ELIDE_QUOTES #defined.  wrtfmt.o: wrt_G: tweak to print
the right number of 0's for zero under G format.

Sat Aug 16 05:45:32 EDT 1997
  libi77: iio.c: fix bug in internal writes to an array of character
strings that sometimes caused one more array element than required by
the format to be blank-filled.  Example: format(1x).

Wed Sep 17 00:39:29 EDT 1997
  libi77: fmt.[ch] rdfmt.c wrtfmt.c: tweak struct syl for machines
with 64-bit pointers and 32-bit ints that did not 64-bit align
struct syl (e.g., Linux on the DEC Alpha).  This change should be
invisible on other machines.

Sun Sep 21 22:05:19 EDT 1997
  libf77: [de]time_.c (Unix systems only): change return type to double.

Current timestamps of files in "all from f2c/src", sorted by time,
appear below (mm/dd/year hh:mm:ss).  To bring your source up to date,
obtain source files with a timestamp later than the time shown in your
version.c.  Note that the time shown in the current version.c is the
timestamp of the source module that immediately follows version.c below:

 8/05/1997  14:51:56  xsum0.out
 8/05/1997  14:42:48  version.c
 8/05/1997  10:31:26  malloc.c
 7/24/1997  17:10:55  README
 7/24/1997  17:00:57  makefile
 7/24/1997  16:06:19  Notice
 7/21/1997  12:58:44  proc.c
 2/19/1997  13:34:09  lex.c
 2/11/1997  23:39:14  vax.c
12/22/1996  11:51:22  output.c
12/04/1996  13:07:53  gram.exec
10/17/1996  13:10:40  putpcc.c
10/01/1996  14:36:18  gram.dcl
10/01/1996  14:36:18  init.c
10/01/1996  14:36:18  defs.h
10/01/1996  14:36:17  data.c
 9/17/1996  17:29:44  expr.c
 9/12/1996  12:12:46  equiv.c
 8/27/1996   8:30:32  intr.c
 8/26/1996   9:41:13  sysdep.c
 7/09/1996  10:41:13  format.c
 7/09/1996  10:40:45  names.c
 7/04/1996   9:58:31  formatdata.c
 7/04/1996   9:55:45  sysdep.h
 7/04/1996   9:55:43  put.c
 7/04/1996   9:55:41  pread.c
 7/04/1996   9:55:40  parse_args.c
 7/04/1996   9:55:40  p1output.c
 7/04/1996   9:55:38  niceprintf.c
 7/04/1996   9:55:37  misc.c
 7/04/1996   9:55:36  memset.c
 7/04/1996   9:55:36  mem.c
 7/04/1996   9:55:35  main.c
 7/04/1996   9:55:33  io.c
 7/04/1996   9:55:30  exec.c
 7/04/1996   9:55:29  error.c
 7/04/1996   9:55:27  cds.c
 7/03/1996  15:47:49  xsum.c
 6/19/1996   7:04:27  f2c.h
 6/19/1996   2:52:05  defines.h
 5/13/1996   0:40:32  gram.head
 5/12/1996  23:37:11  f2c.1
 5/12/1996  23:37:02  f2c.1t
 2/25/1994   2:07:19  parse.h
 2/22/1994  19:07:20  iob.h
 2/22/1994  18:56:53  p1defs.h
 2/22/1994  18:53:46  output.h
 2/22/1994  18:51:14  names.h
 2/22/1994  18:30:41  format.h
 1/18/1994  18:12:52  tokens
 3/06/1993  14:13:58  gram.expr
 1/28/1993   9:03:16  ftypes.h
 4/06/1990   0:00:57  gram.io
 2/03/1990   0:58:26  niceprintf.h
 1/07/1990   1:20:01  usignal.h
11/27/1989   8:27:37  machdefs.h
 7/01/1989  11:59:44  pccdefs.h