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
- Open errors.f90 with status="old" and no iostat. What does the program print, and with which exit status?
- Add a close (u, iostat=ios) after a failed open. What status comes back?
- Inquire about q.txt while it is still open. Which keywords report the open unit?
- 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.
-
What does
iostat=iosgive after a successful read?Answer
Zero
Zero means the statement succeeded.
-
What does
iomsghold 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.
-
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 pAnswer
T
The open fails, so the status is not zero.
-
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.
-
Which statement asks whether a file exists without opening it?
Answer
INQUIRE (FILE=name, EXIST=flag)
INQUIRE only asks; the open changes the state.
-
What does
inquire (unit=u, number=n)return in n?Answer
The unit number of the open unit
NUMBER is the unit number itself.
-
What is wrong with the old
end=900form 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.
-
What should a program test the status against, in general?
Answer
Zero and the sign, never one exact number
The numbers are implementation-dependent.
-
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.
-
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