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

Exercises

  1. Change stop n to stop and run the program. What does the shell report?
  2. Change stop "finished early" to error stop "finished early". Which two things change?
  3. Make check return a logical instead of stopping, and let the program decide. How many lines does the change take?
  4. 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.

  1. 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.

  2. What does stop 3 do?

    Answer

    It ends the program with exit status 3 and prints "STOP 3" on standard error

    An integer stop code becomes the exit status.

  3. 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.

  4. Which statement guarantees a non-zero status with a message?

    Answer

    error stop

    ERROR STOP is the failure form and always reports failure.

  5. What does error stop 2 give?

    Answer

    The message "ERROR STOP 2" and exit status 2

    The integer code becomes the status and is also printed.

  6. Where does the STOP message go?

    Answer

    Standard error, while the program&#39;s own prints go to standard output

    The runtime writes the message to the error stream so a redirect keeps it visible.

  7. 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.

  8. 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.

  9. What does GFORTRAN_ERROR_BACKTRACE=0 change?

    Answer

    It stops the runtime from printing a backtrace with addresses

    The variable controls the extra backtrace, not the status or the message.

  10. Which pair of statements is equivalent in status?

    Answer

    Reaching the end of the program and stop with no code

    Both 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