contrib/libf2c/libI77/README.netlib

   1 If your compiler does not recognize ANSI C headers,
   2 compile with KR_headers defined:  either add -DKR_headers
   3 to the definition of CFLAGS in the makefile, or insert
   4
   5 #define KR_headers
   6
   7 at the top of f2c.h and fmtlib.c .
   8
   9
  10 If you have a really ancient K&R C compiler that does not understand
  11 void, add -Dvoid=int to the definition of CFLAGS in the makefile.
  12
  13 If you use a C++ compiler, first create a local f2c.h by appending
  14 f2ch.add to the usual f2c.h, e.g., by issuing the command
  15         make f2c.h
  16 which assumes f2c.h is installed in /usr/include .
  17
  18 If your system lacks /usr/include/fcntl.h , then you
  19 should simply create an empty fcntl.h in this directory.
  20 If your compiler then complains about creat and open not
  21 having a prototype, compile with OPEN_DECL defined.
  22 On many systems, open and creat are declared in fcntl.h .
  23
  24 If your system has /usr/include/fcntl.h, you may need to add
  25 -D_POSIX_SOURCE to the makefile's definition of CFLAGS.
  26
  27 If your system's sprintf does not work the way ANSI C
  28 specifies -- specifically, if it does not return the
  29 number of characters transmitted -- then insert the line
  30
  31 #define USE_STRLEN
  32
  33 at the end of fmt.h .  This is necessary with
  34 at least some versions of Sun and DEC software.
  35 In particular, if you get a warning about an improper
  36 pointer/integer combination in compiling wref.c, then
  37 you need to compile with -DUSE_STRLEN .
  38
  39 If your system's fopen does not like the ANSI binary
  40 reading and writing modes "rb" and "wb", then you should
  41 compile open.c with NON_ANSI_RW_MODES #defined.
  42
  43 If you get error messages about references to cf->_ptr
  44 and cf->_base when compiling wrtfmt.c and wsfe.c or to
  45 stderr->_flag when compiling err.c, then insert the line
  46
  47 #define NON_UNIX_STDIO
  48
  49 at the beginning of fio.h, and recompile everything (or
  50 at least those modules that contain NON_UNIX_STDIO).
  51
  52 Unformatted sequential records consist of a length of record
  53 contents, the record contents themselves, and the length of
  54 record contents again (for backspace).  Prior to 17 Oct. 1991,
  55 the length was of type int; now it is of type long, but you
  56 can change it back to int by inserting
  57
  58 #define UIOLEN_int
  59
  60 at the beginning of fio.h.  This affects only sue.c and uio.c .
  61
  62 On VAX, Cray, or Research Tenth-Edition Unix systems, you may
  63 need to add -DVAX, -DCRAY, or -DV10 (respectively) to CFLAGS
  64 to make fp.h work correctly.  Alternatively, you may need to
  65 edit fp.h to suit your machine.
  66
  67 You may need to supply the following non-ANSI routines:
  68
  69   fstat(int fileds, struct stat *buf) is similar
  70 to stat(char *name, struct stat *buf), except that
  71 the first argument, fileds, is the file descriptor
  72 returned by open rather than the name of the file.
  73 fstat is used in the system-dependent routine
  74 canseek (in the libI77 source file err.c), which
  75 is supposed to return 1 if it's possible to issue
  76 seeks on the file in question, 0 if it's not; you may
  77 need to suitably modify err.c .  On non-UNIX systems,
  78 you can avoid references to fstat and stat by compiling
  79 with NON_UNIX_STDIO defined; in that case, you may need
  80 to supply access(char *Name,0), which is supposed to
  81 return 0 if file Name exists, nonzero otherwise.
  82
  83   char * mktemp(char *buf) is supposed to replace the
  84 6 trailing X's in buf with a unique number and then
  85 return buf.  The idea is to get a unique name for
  86 a temporary file.
  87
  88 On non-UNIX systems, you may need to change a few other,
  89 e.g.: the form of name computed by mktemp() in endfile.c and
  90 open.c; the use of the open(), close(), and creat() system
  91 calls in endfile.c, err.c, open.c; and the modes in calls on
  92 fopen() and fdopen() (and perhaps the use of fdopen() itself
  93 -- it's supposed to return a FILE* corresponding to a given
  94 an integer file descriptor) in err.c and open.c (component ufmt
  95 of struct unit is 1 for formatted I/O -- text mode on some systems
  96 -- and 0 for unformatted I/O -- binary mode on some systems).
  97 Compiling with -DNON_UNIX_STDIO omits all references to creat()
  98 and almost all references to open() and close(), the exception
  99 being in the function f__isdev() (in open.c).
 100
 101 For MS-DOS, compile all of libI77 with -DMSDOS (which implies
 102 -DNON_UNIX_STDIO).  You may need to make other compiler-dependent
 103 adjustments; for example, for Turbo C++ you need to adjust the mktemp
 104 invocations and to #undef ungetc in lread.c and rsne.c .
 105
 106 If you want to be able to load against libI77 but not libF77,
 107 then you will need to add sig_die.o (from libF77) to libI77.
 108
 109 If you wish to use translated Fortran that has funny notions
 110 of record length for direct unformatted I/O (i.e., that assumes
 111 RECL= values in OPEN statements are not bytes but rather counts
 112 of some other units -- e.g., 4-character words for VMS), then you
 113 should insert an appropriate #define for url_Adjust at the
 114 beginning of open.c .  For VMS Fortran, for example,
 115 #define url_Adjust(x) x *= 4
 116 would suffice.
 117
 118 To check for transmission errors, issue the command
 119         make check
 120 This assumes you have the xsum program whose source, xsum.c,
 121 is distributed as part of "all from f2c/src".  If you do not
 122 have xsum, you can obtain xsum.c by sending the following E-mail
 123 message to netlib@netlib.bell-labs.com
 124         send xsum.c from f2c/src
 125
 126 The makefile assumes you have installed f2c.h in a standard
 127 place (and does not cause recompilation when f2c.h is changed);
 128 f2c.h comes with "all from f2c" (the source for f2c) and is
 129 available separately ("f2c.h from f2c").
 130
 131 By default, Fortran I/O units 5, 6, and 0 are pre-connected to
 132 stdin, stdout, and stderr, respectively.  You can change this
 133 behavior by changing f_init() in err.c to suit your needs.
 134 Note that f2c assumes READ(*... means READ(5... and WRITE(*...
 135 means WRITE(6... .  Moreover, an OPEN(n,... statement that does
 136 not specify a file name (and does not specify STATUS='SCRATCH')
 137 assumes FILE='fort.n' .  You can change this by editing open.c
 138 and endfile.c suitably.
 139
 140 Unless you adjust the "#define MXUNIT" line in fio.h, Fortran units
 141 0, 1, ..., 99 are available, i.e., the highest allowed unit number
 142 is MXUNIT - 1.
 143
 144 Lines protected from compilation by #ifdef Allow_TYQUAD
 145 are for a possible extension to 64-bit integers in which
 146 integer = int = 32 bits and longint = long = 64 bits.
 147
 148 Extensions (Feb. 1993) to NAMELIST processing:
 149  1. Reading a ? instead of &name (the start of a namelist) causes
 150 the namelist being sought to be written to stdout (unit 6);
 151 to omit this feature, compile rsne.c with -DNo_Namelist_Questions.
 152  2. Reading the wrong namelist name now leads to an error message
 153 and an attempt to skip input until the right namelist name is found;
 154 to omit this feature, compile rsne.c with -DNo_Bad_Namelist_Skip.
 155  3. Namelist writes now insert newlines before each variable; to omit
 156 this feature, compile xwsne.c with -DNo_Extra_Namelist_Newlines.
 157  4. (Sept. 1995) When looking for the &name that starts namelist
 158 input, lines whose first non-blank character is something other
 159 than &, $, or ? are treated as comment lines and ignored, unless
 160 rsne.c is compiled with -DNo_Namelist_Comments.
 161
 162 Nonstandard extension (Feb. 1993) to open: for sequential files,
 163 ACCESS='APPEND' (or access='anything else starting with "A" or "a"')
 164 causes the file to be positioned at end-of-file, so a write will
 165 append to the file.
 166
 167 Some buggy Fortran programs use unformatted direct I/O to write
 168 an incomplete record and later read more from that record than
 169 they have written.  For records other than the last, the unwritten
 170 portion of the record reads as binary zeros.  The last record is
 171 a special case: attempting to read more from it than was written
 172 gives end-of-file -- which may help one find a bug.  Some other
 173 Fortran I/O libraries treat the last record no differently than
 174 others and thus give no help in finding the bug of reading more
 175 than was written.  If you wish to have this behavior, compile
 176 uio.c with -DPad_UDread .
 177
 178 If you want to be able to catch write failures (e.g., due to a
 179 disk being full) with an ERR= specifier, compile dfe.c, due.c,
 180 sfe.c, sue.c, and wsle.c with -DALWAYS_FLUSH.  This will lead to
 181 slower execution and more I/O, but should make ERR= work as
 182 expected, provided fflush returns an error return when its
 183 physical write fails.
 184
 185 Carriage controls are meant to be interpreted by the UNIX col
 186 program (or a similar program).  Sometimes it's convenient to use
 187 only ' ' as the carriage control character (normal single spacing).
 188 If you compile lwrite.c and wsfe.c with -DOMIT_BLANK_CC, formatted
 189 external output lines will have an initial ' ' quietly omitted,
 190 making use of the col program unnecessary with output that only
 191 has ' ' for carriage control.
 192
 193 The Fortran 77 Standard leaves it up to the implementation whether
 194 formatted writes of floating-point numbers of absolute value < 1 have
 195 a zero before the decimal point.  By default, libI77 omits such
 196 superfluous zeros, but you can cause them to appear by compiling
 197 lwrite.c, wref.c, and wrtfmt.c with -DWANT_LEAD_0 .
 198
 199 If your system lacks a ranlib command, you don't need it.
 200 Either comment out the makefile's ranlib invocation, or install
 201 a harmless "ranlib" command somewhere in your PATH, such as the
 202 one-line shell script
 203
 204         exit 0
 205
 206 or (on some systems)
 207
 208         exec /usr/bin/ar lts $1 >/dev/null
 209
 210 Most of the routines in libI77 are support routines for Fortran
 211 I/O.  There are a few exceptions, summarized below -- I/O related
 212 functions and subroutines that appear to your program as ordinary
 213 external Fortran routines.
 214
 215 1.      CALL FLUSH flushes all buffers.
 216
 217 2.      FTELL(i) is an INTEGER function that returns the current
 218         offset of Fortran unit i (or -1 if unit i is not open).
 219
 220 3.      CALL FSEEK(i, offset, whence, *errlab) attemps to move
 221         Fortran unit i to the specified offset: absolute offset
 222         if whence = 0; relative to the current offset if whence = 1;
 223         relative to the end of the file if whence = 2.  It branches
 224         to label errlab if unit i is not open or if the call
 225         otherwise fails.