INTENT and the dummy argument rules

Every dummy argument of a procedure can say what the procedure intends to do with it: read it, write it, or both. The attribute is called intent, and it is the cheapest documentation a Fortran program has, because the compiler enforces it. This lesson writes the three kinds, shows what each promises to the caller, and reads the error a write to an input produces.

INTENT(IN)

intent(in) says the procedure reads the argument and never assigns it. The value arrives from the caller, the procedure may use it in any expression, and a statement that writes it is a compile error. It is the attribute of every function argument and of most subroutine arguments that only supply data.

The file intent.f90 uses all three attributes in one program:

program intent_demo implicit none integer :: a, b a = 3 b = 10 call bump(a) print *, "after inout :", a call reset(b) print *, "after out :", b print *, "read only :", twice(a) contains subroutine bump(x) integer, intent(inout) :: x x = x + 1 end subroutine bump subroutine reset(x) integer, intent(out) :: x x = 0 end subroutine reset function twice(x) result(y) integer, intent(in) :: x integer :: y y = 2 * x end function twice end program intent_demo

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

after inout : 4
after out : 0
read only : 8

Three calls, three rules. bump read the three and wrote the four, because it promised to do both. reset ignored the ten and wrote a zero. twice read the four and gave eight, and its argument could not have been written by anything inside the function.

INTENT(OUT)

intent(out) says the procedure writes the argument and does not read it first. The consequence is the part a beginner trips over: on entry the dummy argument is undefined, not a copy of the caller value. A procedure that wants the old value must say inout, and one that reads an out argument before assigning it reads whatever the memory held.

The compiler uses the promise: it may pass an uninitialised temporary, and it may drop the copy that would have brought the caller value in. That is why the rule is absolute and why a subroutine that both reads and writes an argument is declared inout even when it only reads one field of a derived type.

INTENT(INOUT)

intent(inout) is the general case: the dummy is a copy of the caller value on entry, the procedure may read it and write it, and the final value goes back to the caller. An array that is updated in place, a counter that is incremented, a record whose one field is changed: all of them are inout.

A dummy argument with no intent at all is legal and has the rules of inout without the promise. Writing the keyword is still the right habit: it tells a reader what the procedure does, and it lets the compiler catch a write that a function should not make.

OUT and an allocatable

An allocatable dummy with intent(out) is deallocated on entry, which is a defined and visible effect of the attribute. The procedure is then free to allocate a new shape, and the caller receives exactly that array.

program alloc_out_demo implicit none integer, allocatable :: v(:) allocate(v(2)) v = [9, 9] call fill(v) print *, "size :", size(v), " v =", v contains subroutine fill(a) integer, allocatable, intent(out) :: a(:) allocate(a(3)) a = [1, 2, 3] end subroutine fill end program alloc_out_demo

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

size : 3 v = 1 2 3

The caller had two elements of nine and got three of one, two and three: the old array was deallocated by the call, and the shape the subroutine chose is the shape the caller now has. With intent(inout) the array would have arrived allocated and the subroutine would have had to deal with the old shape, which is the other thing a procedure sometimes needs.

The error the compiler gives

The promise is checked. The procedure below declares its argument intent(in) and then assigns it:

program badintent implicit none integer :: a a = 1 call oops(a) contains subroutine oops(x) integer, intent(in) :: x x = 2 end subroutine oops end program badintent

gfortran -Wall -Wextra -std=f2018 badintent.f90 -o badintent

badintent.f90:10:5:

10 | x = 2
| 1~
Error: Dummy argument 'x' with INTENT(IN) in variable definition context (assignment) at (1)

The wording is worth reading once: the argument is in a variable definition context, which is the standard phrase for "something writes it". The fix is to change the declaration to intent(inout) or, if the procedure only needs the value, to write a local variable instead.

The rule of the argument list

Read an argument list as a list of promises. An in argument is data the procedure may trust and must not change; an out argument is a place the procedure fills; an inout argument is a value the procedure updates. A caller that knows the three knows what survives the call without opening the procedure.

The attribute also decides what a caller may pass. A literal, an expression or a constant may go to an in argument and nothing else; a variable is needed for the other two, because a value the procedure writes has to have somewhere to go.

Exercises

  1. Change bump to intent(in) and rebuild. Which line does the compiler name?
  2. Call reset(5) instead of reset(b). What does the compiler say, and why?
  3. Give fill a second argument with the new size and use it instead of the constant three. Which intent do the two arguments need?
  4. Write a subroutine that takes an array in and returns its mean through an out scalar. Which promise does each argument carry?

Questions

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

  1. What does intent(in) promise?

    Answer

    The procedure reads the argument and never assigns it

    The compiler rejects any write to it.

  2. What is an INTENT(OUT) argument on entry?

    Answer

    Undefined: the caller value is not available

    OUT means the procedure supplies the value.

  3. What does this program print? program p implicit none integer :: n n = 7 call zero(n) print *, n contains subroutine zero(x) integer, intent(out) :: x x = 0 end subroutine zero end program p

    Answer

    0

    The subroutine sets the argument to zero and the caller sees it.

  4. Which intent do you need for an argument the procedure both reads and changes?

    Answer

    INTENT(INOUT)

    INOUT is the read-and-write promise.

  5. What happens to an allocatable INTENT(OUT) argument at the start of the call?

    Answer

    It is deallocated, so the procedure starts with no array

    OUT discards the incoming value, allocation included.

  6. Which argument may receive a literal such as call f(3.0)?

    Answer

    An INTENT(IN) dummy

    A literal is a value with no variable to write back to.

  7. What does gfortran report for a write to an INTENT(IN) dummy?

    Answer

    Error: Dummy argument ... with INTENT(IN) in variable definition context

    The context phrase is the standard wording for a write.

  8. Why is writing the intent worth the effort even when it is optional?

    Answer

    It documents the argument and lets the compiler catch a wrong write

    The attribute is both a comment and a check.

  9. What does an argument with no intent behave like?

    Answer

    INOUT, without the promise

    The procedure may read and write it.

  10. Which of these is the reason a function argument should be INTENT(IN)?

    Answer

    A function is a value, so it must not change what it is given

    A function used inside an expression must not have side effects.

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