STOP, ERROR STOP and exit codes
A Fortran program ends in one of three ways: it reaches the end of the main program and returns zero, it calls stop, or it calls error stop. The three differ in the status the shell sees and in what is printed, and the differences are large enough that a build script can tell them apart. This lesson shows each one with its real status.
STOP
stop on its own ends the program normally. It is the explicit form of reaching the end of the main program, and a reader who sees it knows that the statement below is not reached on purpose. A program that ends through stop returns zero, the same status as a program that falls off its last line.
STOP with a code
The statement takes a scalar integer expression, and that value becomes the exit status. The compiler also prints a line naming it, so a terminal shows the reason and a script reads the number.
The file stopcode.f90:
program stopcode
implicit none
integer :: n
n = 3
print *, "about to stop with code", n
stop n
end program stopcode
gfortran -Wall -Wextra -std=f2018 stopcode.f90 -o stopcode
./stopcode
about to stop with code 3
STOP 3
The first line is the program's own output on standard output. The second is the runtime's, on standard error, and the run stops with exit status 3: echo $? prints 3, and a test runner treats the program as failed. A status other than zero is the portable way for a program to say that it did not do its work.
STOP with a message
A character value is also allowed, and it is printed as the reason. What it does to the status is the detail that costs an afternoon: on this compiler a character stop code still exits zero.
The file stopmsg.f90:
program stopmsg
implicit none
print *, "starting"
stop "finished early"
end program stopmsg
gfortran -Wall -Wextra -std=f2018 stopmsg.f90 -o stopmsg
./stopmsg
starting
STOP finished early
The message appears and the run succeeds. A build script that keys on the status cannot tell this program from one that finished its work, which is exactly why a message belongs in error stop and not in stop.
ERROR STOP
error stop takes the same two kinds of code and always ends with a status that says failure: 1 for a message, and the integer for an integer code. It also prints the message with ERROR STOP in front, so a terminal shows at a glance that the run failed.
The file errstop.f90:
program errstop
implicit none
integer :: n
n = -1
print *, "checking n =", n
if (n < 0) error stop "n must not be negative"
print *, "never reached"
end program errstop
gfortran -Wall -Wextra -std=f2018 errstop.f90 -o errstop
GFORTRAN_ERROR_BACKTRACE=0 ./errstop
checking n = -1
ERROR STOP n must not be negative
The run stops with exit status 1. Without GFORTRAN_ERROR_BACKTRACE=0 the runtime also prints a backtrace, whose inner frames are addresses that change on every run; the setting is the one the debugger lesson used for the same reason.
An integer code is passed through in the same way. error stop 2 prints ERROR STOP 2 and exits 2, which is the shape a command-line tool uses for a usage error: the shell can tell a usage error from a failed computation.
STOP inside a procedure
Both statements end the whole program, not the procedure that called them. A subroutine that stops returns to nobody: the stack is unwound by the runtime, no cleanup in the callers runs, and the status is the one the statement gave.
The file proc_stop.f90:
module stopper
implicit none
contains
subroutine check(x)
real, intent(in) :: x
if (x < 0.0) then
print *, "check called with", x
stop 4
end if
print *, "check ok with", x
end subroutine check
end module stopper
program proc_stop
use stopper, only: check
implicit none
call check(2.0)
call check(-1.0)
print *, "never reached"
end program proc_stop
gfortran -Wall -Wextra -std=f2018 proc_stop.f90 -o proc_stop
./proc_stop
check ok with 2.00000000
check called with -1.00000000
STOP 4
The run stops with exit status 4 and the last print never happens. That is a reasonable design for a fatal error in a small program and a poor one in a library: a library that stops a program cannot be used by a service that wanted to report the error and continue. The alternative is to return a status and let the caller decide, which is what the lessons on procedures and on error handling build.
Which one to use
- Reach the end of the program when the work is done. A trailing stop adds nothing.
- stop with an integer when the program must end before its last statement and the reason matters to the caller.
- error stop for anything a reader would call a failure: a missing input, a failed invariant, a usage error. It is the only form that guarantees a non-zero status with a message.
- Never stop "message" in a batch program: the message is printed and the status says success.
Exercises
- Change stop n to stop and run the program. What does the shell report?
- Change stop "finished early" to error stop "finished early". Which two things change?
- Make check return a logical instead of stopping, and let the program decide. How many lines does the change take?
- Run ./stopcode; echo $? and compare it with ./stopmsg; echo $?.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What exit status does a program give when it reaches the end of the main program?
Answer
0
Normal termination returns zero, which the shell reports as success.
-
What does
stop 3do?Answer
It ends the program with exit status 3 and prints "STOP 3" on standard error
An integer stop code becomes the exit status.
-
What status does
stop "done"give on this compiler?Answer
0: the message is printed and the run counts as a success
A character stop code prints a message and still exits zero here.
-
Which statement guarantees a non-zero status with a message?
Answer
error stop
ERROR STOP is the failure form and always reports failure.
-
What does
error stop 2give?Answer
The message "ERROR STOP 2" and exit status 2
The integer code becomes the status and is also printed.
-
Where does the STOP message go?
Answer
Standard error, while the program's own prints go to standard output
The runtime writes the message to the error stream so a redirect keeps it visible.
-
What does STOP inside a subroutine do?
Answer
It ends the whole program with that status
STOP terminates the program; a return ends the procedure.
-
Why is STOP a poor choice inside a library?
Answer
The caller cannot report the error and continue
A library that stops the process takes the decision away from its caller.
-
What does
GFORTRAN_ERROR_BACKTRACE=0change?Answer
It stops the runtime from printing a backtrace with addresses
The variable controls the extra backtrace, not the status or the message.
-
Which pair of statements is equivalent in status?
Answer
Reaching the end of the program and
stopwith no codeBoth end the program normally with status zero.
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