IOSTAT, IOMSG and file inquiry

Every input and output statement can carry an iostat, and almost every one can carry an iomsg: the first turns a failure into a number the program tests, the second into a sentence a person can read. This lesson opens a file that is not there, reads past the end of a file that is, and asks the runtime what it knows about a unit, without any of the three stopping the program.

A file that is not there

status="old" promises that the file exists, and the promise fails here. Without iostat the program would stop with a runtime error; with it, the failure is a number.

The file errors.f90:

program errors_demo implicit none integer :: u, ios character(len=100) :: msg msg = "" open (newunit=u, file="missing.txt", status="old", action="read", iostat=ios, iomsg=msg) print *, "ios :", ios print *, "msg : [", trim(msg), "]" end program errors_demo

gfortran -Wall -Wextra -std=f2018 errors.f90 -o errors
./errors

ios : 2
msg : [Cannot open file 'missing.txt': No such file or directory]

The status is two and the message is the operating system one, with the file name in it. The program carries on, and the unit variable u holds nothing a program may use: after a failed open the unit does not exist, which is why the newunit form and a status go together.

An end of file with a message

The end of a file is not an error in the sense of the previous paragraph: the status is negative and the message says so. The program below writes two records and reads one too many on purpose, and prints the status and the message of the read that found nothing.

program readerr_demo implicit none integer :: u, ios character(len=80) :: msg, line open (newunit=u, file="data.txt", status="replace", action="write") write (u, '(a)') "alpha" write (u, '(a)') "beta" close (u) open (newunit=u, file="data.txt", status="old", action="read") do msg = "" read (u, '(a)', iostat=ios, iomsg=msg) line if (ios /= 0) then print *, "status :", ios print *, "message : [", trim(msg), "]" exit end if print *, "line :", trim(line) end do close (u) end program readerr_demo

gfortran -Wall -Wextra -std=f2018 readerr.f90 -o readerr
./readerr

line : alpha
line : beta
status : -1
message : [End of file]

The message is set only when the status is not zero, which is why the program clears it before every read: a stale message from the previous attempt would otherwise still be sitting in the variable. A program that reports a failure to a person prints the two together.

INQUIRE about a unit and a file

The inquire statement answers a question without changing anything. With unit= it describes an open unit, with file= it describes a name on disk, and the keywords may be combined as the program needs.

program inquire_demo implicit none integer :: u, sz logical :: ex, op character(len=40) :: nm open (newunit=u, file="q.txt", status="replace", action="write") write (u, '(a)') "data" inquire (unit=u, opened=op, number=sz, name=nm) print *, "opened :", op print *, "number :", sz print *, "name : [", trim(nm), "]" close (u) inquire (file="q.txt", exist=ex, size=sz) print *, "exists :", ex print *, "size :", sz end program inquire_demo

gfortran -Wall -Wextra -std=f2018 inquire2.f90 -o inquire2
./inquire2

opened : T
number : -10
name : [q.txt]
exists : T
size : 5

The unit is open, its number is minus ten because newunit returned a negative one, and its name is the one the program gave. Five bytes are four letters and a line ending. The same question before the open would report the file as existing and the unit as not open, which is the test a program makes before it creates a file it must not overwrite.

ERR, END and the old labels

Before the status keywords there were labels: read (u, '(a)', end=900) line jumps to statement 900 at the end of the file, and err=800 jumps there on an error. Both specifiers are still in the standard and still common in old code, and both are worse than a status: the label can leave a do loop from the middle, the two kinds of failure are distinguished by two labels instead of one sign, and a program never learns the number.

The translation is mechanical. An end= label becomes if (ios < 0) exit, an err= label becomes if (ios > 0) error stop "read failed", and the loop stays a loop. The labels lesson has the goto itself.

The rule of the status

Three values cover everything a program can learn from an input or output statement: zero for success, a negative number for the end of the input, and a positive number for a condition that spoiled the transfer. The numbers themselves are the compiler choice, and a program never tests for one, only for the sign and for zero.

The lesson that follows this one applies the same rule to records that are already in memory: an internal file parses a line, and the status of the parse says whether the line was the shape the program expected.

Exercises

  1. Open errors.f90 with status="old" and no iostat. What does the program print, and with which exit status?
  2. Add a close (u, iostat=ios) after a failed open. What status comes back?
  3. Inquire about q.txt while it is still open. Which keywords report the open unit?
  4. Write the end-of-file loop of the second program with end=900 and a labelled continue. Does it build with -std=f2018?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does iostat=ios give after a successful read?

    Answer

    Zero

    Zero means the statement succeeded.

  2. What does iomsg hold when the status is zero?

    Answer

    Nothing defined: the standard only sets it for a nonzero status

    A program initialises the message variable before the statement.

  3. What does this program print when no file named nothing.txt exists? program p implicit none integer :: u, ios open (newunit=u, file="nothing.txt", status="old", iostat=ios) print *, ios /= 0 end program p

    Answer

    T

    The open fails, so the status is not zero.

  4. What is the status of a read that reaches the end of the file?

    Answer

    Negative

    An end of file condition is a negative status.

  5. Which statement asks whether a file exists without opening it?

    Answer

    INQUIRE (FILE=name, EXIST=flag)

    INQUIRE only asks; the open changes the state.

  6. What does inquire (unit=u, number=n) return in n?

    Answer

    The unit number of the open unit

    NUMBER is the unit number itself.

  7. What is wrong with the old end=900 form compared with IOSTAT?

    Answer

    It jumps with a label, cannot tell the failures apart by a value, and hides the status

    The status is a value a program can test and report.

  8. What should a program test the status against, in general?

    Answer

    Zero and the sign, never one exact number

    The numbers are implementation-dependent.

  9. What does a failed OPEN with IOSTAT leave in the unit variable of NEWUNIT=?

    Answer

    Nothing the program may use, because the unit was not opened

    The unit exists only after a successful open.

  10. What does the message of a failed open in this lesson contain?

    Answer

    The name of the file and the operating system reason

    gfortran passes the system error text with the file name.

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