Edit on GitHub

Files

Terminology

When opening a file in Fortran, you can specify its access mode. The default and most commonly used mode is sequential access. This package additionally supports direct access mode. (If the Fortran program uses stream access mode, then the file contains plain binary data, which can be easily read with Julia's built-in facilities.)

In Fortran, files are organized into records. Each READ or WRITE statement in Fortran processes a complete record. This Julia package emulates this behavior, i.e. each call to read or write will process a whole record.

In sequential access mode, records can only be accessed sequentially, but they can be of variable length. The length of a record is determined by the amount of data passed to the WRITE statement. The length of the record is also written to the file, encoded in record markers which preceed and follow the record. Unfortunately, Fortran compilers have used various ways to encode the record markers (the following is from personal recollection and may be incorrect):

  • g77 used 4 bytes, so that records could be no longer than 2 GiB.
  • ifort uses 4 bytes, and uses the sign bit to signal that more data will follow. That is, the record is split into subrecords, where each subrecord has its own record markers. For records smaller than 2 GiB, this is compatible to g77.
  • gfortran 4.0 and 4.1 offered 8-byte record markers as an alternative to g77-style record markers, and used them by default (at least on 64-bit systems).
  • gfortran 4.2 introduced ifort-compatible record markers. These are now the default.

All these kinds of record markers are supported by this package.

In direct access mode, all records have the same, fixed size. This record size must be specified when opening the file. Records can be accessed in random order, by specifying the number of the record to be read/written in each READ or WRITE statement. Currently it is assumed that records are stored in the file without any header or record marker. This is compatible with the standard behaviour of gfortran and ifort.

Opening files

To open a file which contains Fortran unformatted data, use one of the following methods:

FortranFiles.FortranFile — Type
FortranFile(io::IO; kwargs...)

Wrap the given IO stream as a FortranFile containing Fortran "unformatted" (i.e. binary) data. The keyword arguments can be:

  • access for specifying the access mode; a String being one of
    • "sequential": sequential access as in Fortran, where records have leading and trailing record markers. This is the default.
    • "direct": direct access as in Fortran, where records have fixed length and can be accessed in random order. The "recl" keyword must be given to specify the record length. read and write operations on these files must use the rec keyword argument to specify which record to read/write.
  • marker: for specifying the type of record marker; one of
    • RECMRK4B: 4-byte record markers (with support for subrecords) [default]
    • RECMRK8B: 8-byte record markers
    This is ignored for direct access files.
  • recl: for specifying the record length if access=="direct". The record length is counted in bytes and must be specified as an Integer.
  • convert: for specifying the byte-order of the file data; one of
    • "native": use the host byte order [default]
    • "big-endian": use big-endian byte-order
    • "little-endian": use little-endian byte-order

The returned FortranFile can be used with Julia's read and write functions. See their documentation for more information.

source
FortranFile(fn::String [, mode="r" ]; kwargs...)

Open a file containing Fortran unformatted (i.e. binary) data for reading or writing, depending on mode which is used as in open. The keyword arguments are as in FortranFile(io::IO; kwargs...).

source

See Reading Data and Writing Data for how to read or write data to FortranFiles.

Other functions on FortranFiles

To close the file, use the standard Julia close function.

To test for EOF, use the standard Julia eof function.

The following functions are provided to emulate certain Fortran I/O statements:

Examples

The following examples show how to write Julia code that corresponds to certain Fortran OPEN statements.

Opening a file read-only

f = FortranFile("data.bin")

corresponds to

integer::lun
open(newunit=lun, file="data.bin", form="unformatted", action="read", status="old")

Opening a file for writing

f = FortranFile("data.bin", "w")

corresponds to

integer::lun
open(newunit=lun, file="data.bin", form="unformatted", action="write", status="replace")

Opening a file for reading and writing in append mode

f = FortranFile("data.bin", "a+")

probably corresponds to

integer::lun
open(newunit=lun, file="data.bin", form="unformatted", action="readwrite", position="append", status="unknown")

Opening a file read-only in direct access mode

f = FortranFile("data.bin", "r", access="direct", recl=640)

for reading a file containing 640-byte records, and corresponds to

integer::lun
open(newunit=lun, file="data.bin", form="unformatted", action="read", status="old", access="direct", recl=640)

if compiled with gfortran; ifort measures recl not in bytes, but in 4-byte longwords, unless the compiler switch -assume byterecl is used.