iso_fortran_env and the named kinds
iso_fortran_env is the one standard module that a program should use on its first line. It holds the named kinds, so a declaration can say real(real64) instead of guessing 8; it holds the unit numbers of the three standard streams; it holds the constants a read or write returns; and it lets a program print the compiler that built it.
The module
Every compiler that follows Fortran 2003 ships this module, and it is not a file of the program: it is part of the compiler and needs no build step. The program below uses the module without an only list, which is fine for a tour and bad for a real project, where the explicit list is what keeps a name from arriving by accident.
The file env.f90:
program env
use iso_fortran_env
implicit none
print *, "int8/int16/int32/int64:", int8, int16, int32, int64
print *, "real32/real64 :", real32, real64
print *, "real128 :", real128
print *, "character_storage_size:", character_storage_size
print *, "numeric_storage_size :", numeric_storage_size
print *, "output_unit/error_unit:", output_unit, error_unit
print *, "compiler_version:", compiler_version()
print *, "compiler_options:", compiler_options()
end program env
gfortran -Wall -Wextra -std=f2018 env.f90 -o env
./env
int8/int16/int32/int64: 1 2 4 8
real32/real64 : 4 8
real128 : 16
character_storage_size: 8
numeric_storage_size : 32
output_unit/error_unit: 6 0
compiler_version:GCC version 15.2.0
compiler_options:-mtune=generic -march=x86-64 -Wall -Wextra -std=f2018
Each line answers a question a portable program has to ask. The kinds are numbers again, and on this compiler they happen to equal the byte counts; the standard promises only that they are distinct kinds. The storage sizes are 8 bits for a character and 32 bits for a numeric storage unit.
The named kinds
- int8, int16, int32, int64 are the integer kinds with that many bits, when the machine has them. A machine without a 64-bit integer does not offer int64, and a program that needs it fails to compile rather than silently using a narrower type.
- real32, real64, real128 are the real kinds. On this compiler real128 is a genuine quad: 113 binary digits, 33 decimal digits and a decimal range of 4931, stored in 16 bytes. A compiler that does not offer it leaves the name out of the module, and a program that needs it then fails to compile instead of quietly using a narrower type.
- logical8 through logical64 exist for interoperability, and almost no program needs them.
The file quad.f90 asks the module and the inquiry intrinsics about that last kind:
program quad
use iso_fortran_env, only: real128
implicit none
print *, "kind :", real128
print *, "digits :", digits(1.0_real128)
print *, "precision :", precision(1.0_real128)
print *, "range :", range(1.0_real128)
print *, "storage_size:", storage_size(1.0_real128) / 8
end program quad
gfortran -Wall -Wextra -std=f2018 quad.f90 -o quad
./quad
kind : 16
digits : 113
precision : 33
range : 4931
storage_size: 16
Using these names rather than the numbers is the whole point: real(real64) says what the program wants, while real(8) says what one compiler chose in 1995.
Storage sizes
character_storage_size is the number of bits in a character storage unit, 8 here, and numeric_storage_size the number of bits in a numeric storage unit, 32. The standard uses them to define the size of a file record and the unit of inquire, and a program that reads or writes binary data in fixed-size records needs them.
A variable's own size in bytes is not a number the language gives directly. The way to get it is storage_size(x) / 8, which is a standard intrinsic and works for any type including a derived one.
Units and the two streams
output_unit is 6 and error_unit is 0 on this compiler, which are the traditional Unix file descriptors for standard output and standard error. A program that prints an error should write it to error_unit, so a shell that redirects the standard output still shows the message.
The second program writes one line to each stream and then opens a file that does not exist, which is the other use of this module: the iostat values.
The file streams.f90:
program streams
use iso_fortran_env, only: error_unit, output_unit, iostat_end
implicit none
integer :: unit, stat
write (error_unit, "(a)") "this line goes to standard error"
write (output_unit, "(a)") "this line goes to standard output"
open (newunit=unit, file="no_such_file.txt", status="old", action="read", iostat=stat)
print *, "open iostat:", stat
print *, "iostat_end :", iostat_end
if (stat == iostat_end) print *, "the open reported end of file"
end program streams
gfortran -Wall -Wextra -std=f2018 streams.f90 -o streams
./streams
this line goes to standard error
this line goes to standard output
open iostat: 2
iostat_end : -1
The open failed with status 2, which is the system error for a missing file, and it is not the end of file value, so the last line is not printed. A program that treats every nonzero iostat as a fatal error would be right here, and wrong at the end of a normal file.
IOSTAT constants
Three constants in the module are the values a read or write returns for the three outcomes that are not an error:
- iostat_end is -1 here: the end of the file was reached.
- iostat_eor is -2 here: the end of a record was reached while reading a formatted file with a non-advancing read.
- iostat_inquire_internal_unit reports a bad unit number in an inquire.
They are negative so that a program can test stat < 0 for "not an error" and stat > 0 for "the system refused", without knowing the numbers. The lesson on text files uses them in a read loop.
Compiler version and options
compiler_version() returns a string with the compiler and its version, and compiler_options() a string with the options it was called with. Both are functions, not constants, and both return a character value of the length the compiler decided.
Printing them at the start of a run is the cheapest reproducibility measure a numerical program has: a table of results whose first line names the compiler and the flags can be reproduced, and one without it cannot. The options it reports are the driver options of that compile, and a flag that only affects the debug information, such as -g, is not among them here.
Exercises
- Print storage_size(1) and storage_size(1_int64). What is the unit of the answer?
- Change the first program to use an only list with exactly the names it prints.
- Write a line to error_unit and run the program as ./streams 2>/dev/null. Which lines disappear?
- Print iostat_eor and iostat_inquire_internal_unit. Are they negative?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which module provides the named kinds real32 and real64?
Answer
iso_fortran_env
iso_fortran_env holds the named kinds and the storage sizes.
-
What is
output_uniton this compiler?Answer
6
It is the traditional file descriptor of standard output.
-
What is
error_uniton this compiler?Answer
0
A Fortran unit of 0 is the standard error stream here.
-
What does
iostat_endmean?Answer
The read reached the end of the file
It is the negative status a read returns at end of file.
-
What does
real128give on this compiler?Answer
113 binary digits, 33 decimal digits and a range of 4931
kind 16 is the IEEE quad: 16 bytes, 113 bits of mantissa and 33 decimal digits.
-
What does this program print?
program p use iso_fortran_env, only: int32 implicit none print *, storage_size(0_int32) / 8 end program pAnswer
4
storage_size counts bits, and 32 bits are 4 bytes.
-
What does
compiler_options()return?Answer
A string with the options of the compile that called it
It is a character function that reports the flags the compiler was given.
-
Why write a program error to
error_unit?Answer
A shell that redirects standard output still shows the message
Separating the two streams is what lets a user redirect one and keep the other.
-
What is
character_storage_sizeon this compiler?Answer
8 bits
A character storage unit is one byte here.
-
Which names does
iso_fortran_envNOT provide?Answer
The C types c_int and c_double
The C types come from iso_c_binding, which is the lesson on interoperability.
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