Unformatted and stream I/O
A binary file stores the values themselves instead of their printed form. Fortran has two ways to write one: an unformatted sequential file, which is a sequence of records with a hidden length around each, and a stream file, which is the bytes and nothing else. The difference matters the moment a program needs the file size, a position, or another program to read it.
Unformatted sequential
The keyword is form="unformatted", and the write has no format and no edit descriptors: write (u) n, x writes the two values as they are in memory. One statement is one record, and a read takes the record back with the same list of values in the same order.
The file unformatted.f90:
program unformatted_demo
implicit none
integer :: u, ios, n
real :: x
open (newunit=u, file="data.bin", status="replace", form="unformatted", action="write")
write (u) 3, 1.5
write (u) 4, 2.5
close (u)
open (newunit=u, file="data.bin", status="old", form="unformatted", action="read")
do
read (u, iostat=ios) n, x
if (ios /= 0) exit
print *, "record :", n, x
end do
close (u)
inquire (file="data.bin", size=n)
print *, "bytes :", n
end program unformatted_demo
gfortran -Wall -Wextra -std=f2018 unformatted.f90 -o unformatted
./unformatted
record : 3 1.50000000
record : 4 2.50000000
bytes : 32
Two records of eight bytes of data take thirty-two bytes on disk. The extra sixteen are the record markers: a four-byte length in front of each record and the same length behind it, written by the runtime and invisible to the program.
The record markers
The markers exist so that a sequential unformatted file can be read forwards and backwards and so that the runtime can tell a program when it has read past the last record. They also mean the size of the file is not the size of the data, which surprises a program that has to estimate disk use.
A read must match the write exactly. The list of a read has to name the same types in the same order as the list of the write, or the program reads the bits as another type and gets a number that is not wrong but meaningless. Nothing in the file says what the record holds, which is the price of writing no format.
Stream access
access="stream" removes the records. A write appends its bytes, a read takes them from a position named in bytes with pos=, and the first byte of the file is position one. That is the layout a C program or a Python struct expects, with no markers to skip.
program stream_demo
implicit none
integer :: u, sz, i
real :: x
open (newunit=u, file="vec.bin", status="replace", access="stream", form="unformatted", action="write")
do i = 1, 3
write (u) real(i) * 0.5
end do
close (u)
inquire (file="vec.bin", size=sz)
print *, "size :", sz
open (newunit=u, file="vec.bin", status="old", access="stream", form="unformatted", action="read")
read (u, pos=9) x
print *, "third :", x
read (u, pos=1) x
print *, "first :", x
close (u)
end program stream_demo
gfortran -Wall -Wextra -std=f2018 stream.f90 -o stream
./stream
size : 12
third : 1.50000000
first : 0.500000000
Twelve bytes are three reals of four, with no markers at all. The third value starts at byte nine, which is 1 + 2 * 4, and reading from position one gives the first value again: a stream read does not have to be sequential.
Formatted against unformatted
The same value written both ways shows the cost of the two forms. The program below writes 1.5 as text and as a real, and asks the operating system for both sizes:
program sizes_demo
implicit none
integer :: u, fsz, usz
open (newunit=u, file="one.txt", status="replace", action="write")
write (u, '(f6.2)') 1.5
close (u)
open (newunit=u, file="one.bin", status="replace", form="unformatted", action="write")
write (u) 1.5
close (u)
inquire (file="one.txt", size=fsz)
inquire (file="one.bin", size=usz)
print *, "formatted :", fsz
print *, "unformatted :", usz
end program sizes_demo
gfortran -Wall -Wextra -std=f2018 sizes.f90 -o sizes
./sizes
formatted : 7
unformatted : 12
The text is seven bytes: six characters of the field and one line ending. The binary value is twelve: four bytes of a real plus the two markers of a record. For one number the text is smaller; for a million reals the binary is four bytes each and the text is ten or more, and the binary is read back exactly instead of to the digits that were printed.
Which form to use
Text is for people and for other programs that parse: it survives a change of compiler, a change of machine and a look in an editor, and a line-oriented tool can read it. Binary is for volume and for exactness: a large array, a checkpoint of a computation, data that only this program will read.
Within binary, stream is the form to choose for a new file. It is the plain bytes, another language can read it, and pos= makes a random access simple. Unformatted sequential stays where an old file already exists, and the markers are then part of the format whether the program wants them or not.
Exercises
- Write one record of ten reals and inquire the file size. How many bytes does the record cost, and how much of that is data?
- Read the stream file from position five and print the value. Which element do you get?
- Write an integer to data.bin and read it back as a real. What comes out, and why is the answer not a number to trust?
- Change the stream write to a formatted write of the same three values and compare the sizes. Which one would you use for a million of them?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does
form="unformatted"mean for a write?Answer
The values are written as they are in memory, with no text conversion
An unformatted transfer moves the binary representation.
-
What does an unformatted sequential file add around each record?
Answer
A record marker in front and the same marker behind
The runtime writes the record length before and after the data.
-
What does this program print?
program p implicit none integer :: u, sz open (newunit=u, file="two.bin", status="replace", form="unformatted", action="write") write (u) 100, 200 close (u) inquire (file="two.bin", size=sz) print *, sz end program pAnswer
16
Eight bytes of data plus two four-byte markers make sixteen.
-
What does
access="stream"change?Answer
The file is a plain sequence of bytes with no records
Stream access drops the record structure.
-
What does
read (u, pos=9) xdo on a stream file of four-byte reals?Answer
Reads the third real
Position nine is the first byte of the third four-byte value.
-
How large is one real written to a stream file?
Answer
Four bytes
A default real is a 32-bit value.
-
Why must the read of an unformatted record match the write?
Answer
The file holds no description of the types, so a mismatch reinterprets the bits
Without a format nothing says what a record contains.
-
Which of these is the argument for a text file?
Answer
Another program or a person can read it without knowing this program
Text is portable and self-describing.
-
Which form should a new binary file use?
Answer
Stream, because it is the plain bytes at a known position
Stream is the layout another language expects, with POS= for access.
-
How many bytes does the text
1.50plus a line ending take?Answer
7
Six characters of the field and one line ending, as the page measured.
The programs on this page were built with GNU Fortran (Alpine 15.2.0) 15.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev