Input/Output: Units and Files

module unit_utils
  implicit none
  private
  public :: free_unit
contains
  ! The pre-Fortran 2008 idiom, still common in old code: search for a unit that is not in use.
  ! New code should use NEWUNIT= instead, which cannot clash with a unit number a library picked.
  function free_unit() result(n)
    integer :: n
    logical :: is_open
    integer :: ios
    do n = 10, 99
      inquire (unit=n, opened=is_open, iostat=ios)
      if (ios == 0 .and. .not. is_open) return
    end do
    n = -1
  end function free_unit
end module unit_utils

program unit_numbers
  use unit_utils, only: free_unit
  implicit none
  integer :: u, v, w, ios
  character(len=100) :: msg
  character(len=20) :: line

  msg = ''
  u = free_unit()
  open (u, file='a.txt', status='replace')
  v = free_unit()
  print '(a, i0, a, i0)', 'first free unit was ', u, ', next free unit is ', v

  open (newunit=w, status='scratch')
  print '(a, l1)', 'a newunit value never equals a classic unit number: ', w < 0

  ! Connecting the same unit to another file closes the first file implicitly.
  write (u, '(a)') 'in a.txt'
  open (u, file='b.txt', status='replace')
  write (u, '(a)') 'in b.txt'
  close (u)
  open (u, file='a.txt', status='old')
  read (u, '(a)') line
  print '(a)', 'a.txt still contains: ' // trim(line)
  close (u, status='delete')

  ! Connecting one file to two units is processor dependent.
  open (10, file='b.txt', status='old')
  open (11, file='b.txt', status='old', iostat=ios, iomsg=msg)
  print '(a, i0, a)', 'second unit on the same file: iostat=', ios, ' iomsg=[' // trim(msg) // ']'
  close (10, status='delete')
  close (11)
end program unit_numbers

first free unit was 10, next free unit is 11
a newunit value never equals a classic unit number: T
a.txt still contains: in a.txt
second unit on the same file: iostat=0 iomsg=[]

first free unit was 10, next free unit is 11
a newunit value never equals a classic unit number: T
a.txt still contains: in a.txt
second unit on the same file: iostat=1037 iomsg=[OPEN(UNIT=11,FILE='b.txt'): file is already connected to unit 10]

! Writing to a unit that was never opened: not allowed by the standard, tolerated by compilers.
program implicit_open
  implicit none
  logical :: exists
  character(len=64) :: name
  write (23, '(a)') 'no OPEN statement for unit 23'
  inquire (unit=23, name=name)
  print '(a)', 'unit 23 is connected to: ' // trim(name)
  inquire (file='fort.23', exist=exists)
  print '(a, l1)', 'file fort.23 exists: ', exists
  close (23, status='delete')
end program implicit_open

unit 23 is connected to: fort.23
file fort.23 exists: T

module heatflow_csv_demo
  use, intrinsic :: iso_fortran_env, only: real64
  implicit none
  private
  public :: dp, write_csv, count_rows, read_csv
  integer, parameter :: dp = real64
contains
  subroutine write_csv(u, field)
    integer, intent(in) :: u
    real(dp), intent(in) :: field(:, :)
    integer :: j
    do j = 1, size(field, 2)
      write (u, '(*(es12.5, :, ","))') field(:, j)
    end do
  end subroutine write_csv

  ! Count the records of a connected sequential file by reading to end of file.
  function count_rows(u) result(n)
    integer, intent(in) :: u
    integer :: n, ios
    character(len=1) :: dummy
    n = 0
    rewind (u)
    do
      read (u, '(a)', iostat=ios) dummy
      if (ios /= 0) exit
      n = n + 1
    end do
    rewind (u)
  end function count_rows

  subroutine read_csv(u, field, ios, msg)
    integer, intent(in) :: u
    real(dp), intent(out) :: field(:, :)
    integer, intent(out) :: ios
    character(len=*), intent(out) :: msg
    integer :: j
    ios = 0
    msg = ''
    do j = 1, size(field, 2)
      read (u, *, iostat=ios, iomsg=msg) field(:, j)
      if (ios /= 0) return
    end do
  end subroutine read_csv
end module heatflow_csv_demo

program sequential_csv
  use heatflow_csv_demo
  implicit none
  real(dp) :: field(4, 3), back(4, 3), extra(4, 5)
  integer :: u, ios, i, j
  character(len=128) :: msg

  field = reshape([(real(i, dp) * 0.25_dp, i=1, 12)], [4, 3])

  open (newunit=u, file='field.csv', status='replace', action='readwrite')
  call write_csv(u, field)
  print '(a, i0)', 'rows written: ', count_rows(u)

  call read_csv(u, back, ios, msg)
  print '(a, i0, a, l1)', 'iostat=', ios, ' max difference < 1e-5: ', &
    maxval(abs(back - field)) < 1.0e-5_dp

  ! Ask for more rows than the file has: the end-of-file condition is reported, not fatal.
  rewind (u)
  call read_csv(u, extra, ios, msg)
  print '(a, i0, a, l1)', 'iostat=', ios, ' is_iostat_end: ', is_iostat_end(ios)
  print '(a)', 'iomsg: ' // trim(msg)

  ! Show the text of the file itself.
  rewind (u)
  do j = 1, 3
    read (u, '(a)') msg
    print '(a)', trim(msg)
  end do
  close (u, status='delete')
end program sequential_csv

rows written: 3
iostat=0 max difference < 1e-5: T
iostat=-1 is_iostat_end: T
iomsg: End of file
 2.50000E-01, 5.00000E-01, 7.50000E-01, 1.00000E+00
 1.25000E+00, 1.50000E+00, 1.75000E+00, 2.00000E+00
 2.25000E+00, 2.50000E+00, 2.75000E+00, 3.00000E+00

rows written: 3
iostat=0 max difference < 1e-5: T
iostat=-1 is_iostat_end: T
iomsg: End of file during input
 2.50000E-01, 5.00000E-01, 7.50000E-01, 1.00000E+00
 1.25000E+00, 1.50000E+00, 1.75000E+00, 2.00000E+00
 2.25000E+00, 2.50000E+00, 2.75000E+00, 3.00000E+00

program direct_access
  use, intrinsic :: iso_fortran_env, only: real64, int32, file_storage_size
  implicit none
  integer, parameter :: dp = real64
  integer, parameter :: nx = 5, ny = 4
  real(dp) :: field(nx, ny), row(nx)
  integer :: u, j, ios, reclen, next, sz
  character(len=100) :: msg

  field = reshape([(real(j, dp), j=1, nx*ny)], [nx, ny])

  ! IOLENGTH= gives the record length, in file storage units, for exactly this output list.
  inquire (iolength=reclen) row
  print '(a, i0, a, i0, a)', 'iolength of one row: ', reclen, ' file storage units (', &
    reclen * file_storage_size, ' bits)'

  ! Direct access requires RECL=; the file holds fixed-length, numbered records.
  open (newunit=u, file='rows.bin', status='replace', access='direct', form='unformatted', &
        recl=reclen, action='readwrite')

  ! Write the rows in reverse order: any record can be written at any time.
  do j = ny, 1, -1
    write (u, rec=j) field(:, j)
  end do

  inquire (unit=u, nextrec=next, recl=reclen, size=sz)
  print '(a, i0, a, i0, a, i0)', 'nextrec=', next, ' recl=', reclen, ' size=', sz

  ! Read row 3 first, then row 1: no sequential order is implied.
  read (u, rec=3) row
  print '(a, 5f5.1)', 'row 3: ', row
  read (u, rec=1) row
  print '(a, 5f5.1)', 'row 1: ', row

  ! Rewrite one record; a record cannot be deleted but can be replaced.
  write (u, rec=2) -row
  read (u, rec=2) row
  print '(a, 5f5.1)', 'row 2 after rewrite: ', row

  ! Record 9 was never written.
  read (u, rec=9, iostat=ios, iomsg=msg) row
  print '(a, i0, a)', 'read of record 9: iostat=', ios, ' iomsg=' // trim(msg)
  close (u, status='delete')
end program direct_access

iolength of one row: 40 file storage units (320 bits)
nextrec=2 recl=40 size=160
row 3:  11.0 12.0 13.0 14.0 15.0
row 1:   1.0  2.0  3.0  4.0  5.0
row 2 after rewrite:  -1.0 -2.0 -3.0 -4.0 -5.0
read of record 9: iostat=5002 iomsg=Non-existing record number

program stream_access
  use, intrinsic :: iso_fortran_env, only: real64, int32, iostat_end
  implicit none
  integer, parameter :: dp = real64, ip = int32
  integer(ip) :: nx, ny, nx_back, ny_back
  real(dp) :: dx, dy, dx_back, dy_back
  real(dp), allocatable :: u_field(:, :), back(:, :)
  integer :: u, ios, p, sz, i
  character(len=64) :: line

  nx = 4_ip; ny = 3_ip; dx = 0.25_dp; dy = 0.5_dp
  allocate (u_field(nx, ny))
  u_field = reshape([(real(i, dp), i=1, 12)], [4, 3])

  ! Unformatted stream: no record markers, exactly the bytes of the items, in order.
  open (newunit=u, file='field.bin', access='stream', form='unformatted', status='replace', &
        action='readwrite')
  write (u) nx, ny, dx, dy        ! 2 x 4 + 2 x 8 = 24 file storage units
  write (u) u_field               ! 12 x 8 = 96 file storage units
  inquire (unit=u, pos=p, size=sz)
  print '(a, i0, a, i0)', 'next position=', p, ' file size=', sz

  ! Read the header back, then jump straight to a single element with POS=.
  read (u, pos=1) nx_back, ny_back, dx_back, dy_back
  print '(a, 2(i0, 1x), 2f5.2)', 'header: ', nx_back, ny_back, dx_back, dy_back
  allocate (back(nx_back, ny_back))
  read (u) back
  print '(a, l1)', 'whole field read back identical: ', all(abs(back - u_field) < 1.0e-12_dp)

  ! Element (3, 2) is the 7th value of the field: 24 header units + 6 values x 8 units, so POS = 73.
  read (u, pos=24 + 6 * 8 + 1) back(1, 1)
  print '(a, f5.1)', 'element (3,2) read by position: ', back(1, 1)

  ! Overwrite that element in place; the rest of the file is untouched.
  write (u, pos=24 + 6 * 8 + 1) -1.0_dp
  read (u, pos=1 + 24) back
  print '(a, f5.1, a, f5.1)', 'after the update element (3,2) is ', back(3, 2), &
    ' and element (2,2) is still ', back(2, 2)

  ! Reading past the last item is an end-of-file condition.
  read (u, iostat=ios) back(1, 1)
  print '(a, i0, a, l1)', 'read past the end: iostat=', ios, ' is end-of-file: ', ios == iostat_end
  close (u, status='delete')

  ! Formatted stream: text with record markers (here, a line feed), but byte-addressable.
  open (newunit=u, file='note.txt', access='stream', form='formatted', status='replace', &
        action='readwrite')
  write (u, '(a)') 'first line'
  write (u, '(a)') 'second line'
  inquire (unit=u, pos=p, size=sz)
  print '(a, i0, a, i0)', 'formatted stream: next position=', p, ' size=', sz
  read (u, '(a)', pos=1) line
  print '(a)', 'read from position 1: ' // trim(line)
  read (u, '(a)') line
  print '(a)', 'next record: ' // trim(line)
  close (u, status='delete')
end program stream_access

next position=121 file size=120
header: 4 3  0.25 0.50
whole field read back identical: T
element (3,2) read by position:   7.0
after the update element (3,2) is  -1.0 and element (2,2) is still   6.0
read past the end: iostat=-1 is end-of-file: T
formatted stream: next position=24 size=23
read from position 1: first line
next record: second line

program unformatted_sequential
  use, intrinsic :: iso_fortran_env, only: int32
  implicit none
  integer(int32) :: data(3), raw(5), n
  integer :: u, sz, ios
  character(len=100) :: msg
  integer(int32) :: a, b

  data = [10_int32, 20_int32, 30_int32]

  ! One WRITE statement is one record, whatever the number of items.
  open (newunit=u, file='seq.dat', form='unformatted', access='sequential', status='replace')
  write (u) data
  write (u) 99_int32
  close (u)

  ! Look at the same file as raw bytes through stream access.
  open (newunit=u, file='seq.dat', form='unformatted', access='stream', status='old', action='read')
  inquire (unit=u, size=sz)
  print '(a, i0)', 'file size in bytes: ', sz
  read (u) raw
  print '(a, 5(i0, 1x))', 'first record as raw int32 words: ', raw
  close (u)

  ! Reading with a different list than the one written: fewer items is allowed ...
  open (newunit=u, file='seq.dat', form='unformatted', status='old', action='read')
  read (u) a, b
  print '(a, 2(i0, 1x))', 'two items from a three-item record: ', a, b
  ! ... and the rest of the record is skipped by the next READ. Asking for more is an error.
  read (u, iostat=ios, iomsg=msg) data, n
  print '(a, i0, a)', 'next record is shorter than the list: iostat=', ios, ' iomsg=' // trim(msg)
  close (u, status='delete')
end program unformatted_sequential

file size in bytes: 32
first record as raw int32 words: 12 10 20 30 12
two items from a three-item record: 10 20
next record is shorter than the list: iostat=5016 iomsg=I/O past end of record on unformatted file

! Non-standard but widely supported: CONVERT= selects the byte order of an unformatted file.
program convert_extension
  use, intrinsic :: iso_fortran_env, only: int32, int8
  implicit none
  integer(int8) :: b(4)
  integer :: u
  open (newunit=u, file='be.bin', form='unformatted', access='stream', convert='big_endian', &
        status='replace')
  write (u) 1_int32
  close (u)
  open (newunit=u, file='be.bin', form='unformatted', access='stream', status='old', &
        convert='native')
  read (u) b
  print '(a, 4(i0, 1x))', 'bytes of the integer 1 written with convert=big_endian: ', b
  close (u, status='delete')
end program convert_extension

bytes of the integer 1 written with convert=big_endian: 0 0 0 1

program roundtrip
  use, intrinsic :: iso_fortran_env, only: real64, int64
  implicit none
  integer, parameter :: dp = real64
  real(dp) :: x, y
  integer :: u
  character(len=40) :: text

  x = 1.0_dp / 3.0_dp
  open (newunit=u, status='scratch', form='formatted')

  ! 5 significant digits (the heatflow CSV format) is not enough to restore the value.
  write (u, '(es12.5)') x
  rewind (u); read (u, *) y
  print '(a, es10.2)', 'es12.5 round trip, |error| = ', abs(y - x)

  ! 17 significant digits restore every real(dp) exactly.
  rewind (u)
  write (u, '(es24.16e3)') x
  rewind (u); read (u, *) y
  print '(a, l1)', 'es24.16e3 round trip bit-identical: ', same_bits(x, y)

  ! g0 is compiler dependent in its choice of digits and in the leading zero.
  write (text, '(g0)') x
  print '(a)', 'g0 gives: ' // trim(text)
  close (u)

  ! An unformatted stream copies the bits.
  open (newunit=u, status='scratch', form='unformatted', access='stream')
  write (u) x
  read (u, pos=1) y
  print '(a, l1)', 'stream round trip bit-identical: ', same_bits(x, y)
  close (u)

contains

  logical function same_bits(a, b)
    real(dp), intent(in) :: a, b
    same_bits = transfer(a, 0_int64) == transfer(b, 0_int64)
  end function same_bits
end program roundtrip

es12.5 round trip, |error| =   3.33E-07
es24.16e3 round trip bit-identical: T
g0 gives: 0.33333333333333331
stream round trip bit-identical: T

module heatflow_io
  use heatflow_kinds, only: dp, ip
  use heatflow_grid, only: grid_t, make_grid
  implicit none
  private
  public :: write_csv, write_stream, read_stream

contains

  !> Write the temperature field as CSV (one row per j).
  subroutine write_csv(grid, file)
    type(grid_t), intent(in) :: grid
    character(len=*), intent(in) :: file
    integer :: unit, j
    open (newunit=unit, file=file, status='replace', action='write')
    do j = 1, grid%ny
      write (unit, '(*(es12.5,:,","))') grid%u(:, j)
    end do
    close (unit)
  end subroutine write_csv

  !> Unformatted stream: nx, ny, dx, dy, then the field.
  subroutine write_stream(grid, file)
    type(grid_t), intent(in) :: grid
    character(len=*), intent(in) :: file
    integer :: unit
    open (newunit=unit, file=file, access='stream', form='unformatted', &
          status='replace', action='write')
    write (unit) grid%nx, grid%ny, grid%dx, grid%dy
    write (unit) grid%u
    close (unit)
  end subroutine write_stream

  function read_stream(file) result(grid)
    character(len=*), intent(in) :: file
    type(grid_t) :: grid
    integer :: unit
    open (newunit=unit, file=file, access='stream', form='unformatted', &
          status='old', action='read')
    read (unit) grid%nx, grid%ny, grid%dx, grid%dy
    allocate (grid%u(grid%nx, grid%ny))
    read (unit) grid%u
    close (unit)
  end function read_stream
end module heatflow_io

steps=2000 residual= 1.38E-04
max temperature=   0.139
3552 heatflow.bin
5733 heatflow.csv
21
0000000          21          21
0000008                     0.05                     0.05
 0.00000E+00, 0.00000E+00, 0.00000E+00,

! INTENTIONAL RUNTIME ERROR: no IOSTAT=, ERR= or IOMSG= on the OPEN.
program fatal_open
  implicit none
  integer :: u
  open (newunit=u, file='does-not-exist.dat', status='old', action='read')
  print '(a)', 'not reached'
end program fatal_open

At line 5 of file 05a_fatal_open.f90
Fortran runtime error: Cannot open file 'does-not-exist.dat': No such file or directory

fatal Fortran runtime error(/work/05a_fatal_open.f90:5): I/O error (errno=2): No such file or directory
Aborted

! INTENTIONAL RUNTIME ERROR: reading past the end of a file without END= or IOSTAT=.
program fatal_read
  implicit none
  integer :: u, n
  open (newunit=u, status='scratch')
  write (u, '(i0)') 42
  rewind (u)
  read (u, *) n
  read (u, *) n
  print '(a)', 'not reached'
end program fatal_read

At line 9 of file 05b_fatal_read.f90
Fortran runtime error: End of file

fatal Fortran runtime error(/work/05b_fatal_read.f90:9): End of file during input
Aborted

! INTENTIONAL RUNTIME ERROR: a text field that is not an integer, no IOSTAT=.
program fatal_conversion
  implicit none
  integer :: n
  character(len=8) :: text
  text = '12x'
  read (text, '(i8)') n
  print '(a)', 'not reached'
end program fatal_conversion

At line 7 of file 05c_fatal_conversion.f90
Fortran runtime error: Bad value during integer read

fatal Fortran runtime error(/work/05c_fatal_conversion.f90:7): Bad character 'x' in INTEGER input field
Aborted

! Fortran 2023 LEADING_ZERO=: accepted by LLVM Flang 23, rejected by GNU Fortran 16.2.
program leading_zero_f2023
  implicit none
  integer :: u
  character(len=20) :: mode
  open (newunit=u, file='lz.txt', status='replace', action='readwrite', leading_zero='suppress')
  inquire (unit=u, leading_zero=mode)
  print '(a)', 'leading_zero mode of the connection: ' // trim(mode)
  write (u, '(f6.3)') 0.5
  write (u, '(f6.3)', leading_zero='print') 0.5       ! one statement overrides the mode
  write (u, '(lzp, f6.3)') 0.5                          ! so does a control edit descriptor
  rewind (u)
  read (u, '(a)') mode
  print '(a)', '|' // trim(mode) // '|'
  read (u, '(a)') mode
  print '(a)', '|' // trim(mode) // '|'
  read (u, '(a)') mode
  print '(a)', '|' // trim(mode) // '|'
  close (u, status='delete')
end program leading_zero_f2023

leading_zero mode of the connection: SUPPRESS
|  .500|
| 0.500|
| 0.500|

Error: Syntax error in OPEN statement at (1)
11_leading_zero_f2023.f90:7:19:

    7 |   inquire (unit=u, leading_zero=mode)
--
Error: Syntax error in INQUIRE statement at (1)
11_leading_zero_f2023.f90:10:22:

   10 |   write (u, '(f6.3)', leading_zero='print') 0.5       ! one statement overrides the mode
--
Error: Syntax error in WRITE statement at (1)
11_leading_zero_f2023.f90:11:16: