Intrinsic Modules and iso_fortran_env

The use statement is USE [ [ , module-nature ] :: ] module-name (S 14.2.2, R1409), where the module nature is intrinsic or non_intrinsic (R1410). The constraints that matter are:

The last rule is why the nature should always be written. If a project has a file defining module iso_fortran_env (a "compatibility" shim from the Fortran 90 days is the usual origin), a bare use iso_fortran_env silently picks the shim and the program gets different kinds. use, intrinsic :: iso_fortran_env cannot be hijacked in that way. Modules, submodules and the nature rules are explained with a working example in Modules and Submodules.

The recommendation this page follows, and the one the Fortran community’s best-practice guide makes, is to write all three parts: the nature, the module name and an only list. The only list documents what the unit needs, keeps the names out of the way of local names, and makes unused imports visible to a reader and to a linter.

Asking for something that is not an intrinsic module is an error with a clear message. A misspelled name:

gfortran 16.2 (the real diagnostic):

Flang 23 does not distinguish the two cases: it looks for a module file and reports that it cannot find one.

And asking for the nonintrinsic version of an intrinsic module fails for the opposite reason: no module file of that name exists on the machine. With use, non_intrinsic :: iso_fortran_env, only: int32 (file 23_nonintrinsic_env.f90, a four-line program) gfortran 16.2 reports:

and Flang 23 reports that it cannot parse the module file iso_fortran_env.mod.

Source: J3/23-007r1: 14.2.2 The USE statement and use association, R1409 to R1411 and C1404 to C1406; 16.10.1 Standard intrinsic modules, General

int8, int16, int32 and int64 (S 16.10.2.14) are the kind type parameters of integers whose storage size is 8, 16, 32 and 64 bits. real16, real32, real64 and real128 (S 16.10.2.27) do the same for reals, and logical8, logical16, logical32 and logical64 (S 16.10.2.21) for logicals. The rules are the same for all three families:

gfortran 16.2:

Flang 23 supports half precision, so its real16 is a real kind:

On these two compilers the kind numbers equal the number of bytes, but that is a convention of the compilers and not of the language: other a compiler is free to number kinds differently (the standard only says that the numbers are processor dependent), which is exactly why a program should write real64, a named constant from a kinds module, or selected_real_kind, and never a literal 8. The comparison between the two compilers above is also a reminder that real16 is new: F2023 added real16, logical8, logical16, logical32 and logical64 to the module (S, Introduction, "Intrinsic modules"); int8 to int64 and real32 to real128 come from Fortran 2008.

Source: J3/23-007r1: 16.10.2.14 INT8, INT16, INT32, and INT64; 16.10.2.21 LOGICAL8, LOGICAL16, LOGICAL32, and LOGICAL64; 16.10.2.27 REAL16, REAL32, REAL64, and REAL128

integer_kinds, real_kinds, logical_kinds and character_kinds (S 16.10.2.15, 16.10.2.26, 16.10.2.20, 16.10.2.4) are rank-one default-integer array constants with lower bound 1 whose elements are all the kinds the processor supports. The order is processor dependent, so a program must not assume that the elements are sorted. They answer questions that int8 and friends cannot: "which kinds exist?", "how many?", "is kind 3 supported?".

gfortran 16.2:

Flang 23 reports the same integer kinds but different sets for the others:

The differences are genuine: Flang offers a half-precision real (kind 2) and a bfloat16 real (kind 3), and wider character kinds 2 and 4 (kind 4 is the one selected_char_kind('ISO_10646') returns), while gfortran offers kinds 1 and 4 only; gfortran has a 16-byte logical, Flang does not. (The three kinds in gfortran’s real_kinds are the 4-, 8- and 16-byte reals; this aarch64 build has no 80-bit extended type, and x86-64 builds of gfortran typically list a kind 10 in addition.) The arrays are named constants but they list kinds that vary by compiler, so they are mostly used in tests, in select case dispatch, in table-driven code and for diagnostics (an is_supported(kind) helper is one line with any).

Source: J3/23-007r1: 16.10.2.4 CHARACTER_KINDS, 16.10.2.15 INTEGER_KINDS, 16.10.2.20 LOGICAL_KINDS and 16.10.2.26 REAL_KINDS

character_storage_size, numeric_storage_size and file_storage_size (S 16.10.2.5, 16.10.2.23, 16.10.2.11) give, in bits, the size of the character storage unit, of the numeric storage unit (the size of a default integer, default real and default logical) and of the file storage unit (what inquire(iolength=) and recl= count). The numeric storage unit is the one that matters for equivalence, common and sequence types (S 19.5.3.2), and the file storage unit is what makes recl= and unformatted stream sizes portable.

Both compilers print this. The intrinsic storage_size returns the size of one element of its argument in bits, and for a default integer it equals numeric_storage_size. Do not use character_storage_size to compute the size of a record of text that you intend to write to a file: use inquire(iolength=n) item instead, which answers in file storage units.

Source: J3/23-007r1: 16.10.2.5 CHARACTER_STORAGE_SIZE, 16.10.2.11 FILE_STORAGE_SIZE and 16.10.2.23 NUMERIC_STORAGE_SIZE

input_unit, output_unit and error_unit (S 16.10.2.13, 16.10.2.24, 16.10.2.9) identify the preconnected units. input_unit is the unit that a read with no unit and the asterisk unit * in a read denote, output_unit is the asterisk unit of write and the unit of print, and error_unit is the unit "used for the purpose of error reporting"; it may be the same as output_unit. The standard fixes the roles but not the numbers, except that none of them is -1. The common values are 5, 6 and 0.

Standard output (identical on gfortran 16.2 and Flang 23):

Standard error:

Notes:

Source: J3/23-007r1: 16.10.2.9 ERROR_UNIT, 16.10.2.13 INPUT_UNIT and 16.10.2.24 OUTPUT_UNIT

iostat_end, iostat_eor and iostat_inquire_internal_unit (S 16.10.2.16, 16.10.2.17, 16.10.2.18) are the values assigned to the variable of an iostat= specifier. iostat_end is assigned when an end-of-file condition occurs and no error occurs; iostat_eor is assigned for an end-of-record condition (as in the non-advancing read below) when neither end-of-file nor an error occurs. Both are negative, they are different, and a successful statement returns zero. The consequence is a test that does not depend on any compiler-specific value:

gfortran 16.2:

Source: J3/23-007r1: 16.10.2.16 IOSTAT_END

Flang 23 prints the same lines except iostat_inquire_internal_unit=256. iostat_end and iostat_eor are -1 and -2 on both compilers, but neither number is required by the standard; positive values mean an error and their values are processor dependent. Never compare ios to a literal -1: write ios == iostat_end.

iostat_inquire_internal_unit is the value an inquire statement assigns to its iostat= variable when the unit it names is an internal unit. It only occurs inside a defined derived-type input/output procedure that was called while the parent statement was reading or writing an internal file, because that procedure receives the internal file as its unit argument. A DTIO routine that wants to behave differently for files and strings can therefore ask:

Both compilers print this. Observed on gfortran 16.2: asking for name= of the internal unit in the same inquire makes the program stop with a segmentation fault, so the example asks for form=, which every unit has. Derived-type I/O is covered in Derived-Type and Asynchronous I/O.

Source: J3/23-007r1: 16.10.2.16 IOSTAT_END

compiler_version() and compiler_options() (S 16.10.2.7 and 16.10.2.6) are transformational functions with no arguments that return a default character scalar of processor-dependent length. The first identifies the translation phase of the processor (name and version) and the second the options that controlled it; the standard says both "should include relevant information that could be useful for diagnosing problems at a later date". They are specification inquiries (S 10.1.11), so they may be used in specification and constant expressions, as in the parameter below, and they are evaluated at translation time, not when the program runs: they describe the compiler that built the program, not the machine it runs on.

Built with -std=f2023 -Wall -Wextra -pedantic -fimplicit-none -fcheck=all -g, gfortran 16.2 prints:

and Flang 23:

Rebuilt with -O2, both report -O2 in compiler_options(). The first Flang line shows that its string is simply the driver command line as given (no -std was passed to it). The strings are not meant to be parsed: they differ between compilers, versions and distributions (the Flang string above names the Debian package), and compiler_options() can be long. Use them in log files, bug reports and --version output of command-line tools.

Source: J3/23-007r1: 16.10.2.6 COMPILER_OPTIONS, 16.10.2.7 COMPILER_VERSION and 10.1.11 Specification expression, GNU Fortran manual: COMPILER_VERSION and COMPILER_OPTIONS

The rest of the module supports coarray programs. They are reference material here; the statements that use them are explained on the two coarray pages.

The types have private components, are extensible and have no type parameters. The restrictions that make them safe are constraints of the language (C1603 to C1614): a variable of such a type shall be a coarray, shall not be used in a variable definition context except in the statement that belongs to the type (lock/unlock for locks, event post/event wait for events) or as an allocate-object, and may be passed only to an intent(inout) dummy argument of a procedure with an explicit interface. S 16.10.2.35 requires the values of iostat_inquire_internal_unit, stat_failed_image, stat_locked, stat_locked_other_image, stat_stopped_image, stat_unlocked and stat_unlocked_failed_image to be distinct, so one select case can test the result of any image-control statement.

The processors disagree on the values, which is the reason to compare against the names:

Source: J3/23-007r1: 16.10.2.2 to 16.10.2.3, 16.10.2.8, 16.10.2.10, 16.10.2.12, 16.10.2.19, 16.10.2.22, 16.10.2.25 to 16.10.2.35, with constraints C1603 to C1614

Two observations. First, stat_unlocked is 0 in gfortran, the same number that means "success" in any other stat= variable. Second, Flang’s team constants are negative; Flang rejects a program that declares a coarray unless it is built with the experimental -fcoarray option (Multi-image features are experimental and are disabled by default), so the examples that need coarrays were run on gfortran only.

A program that declares the synchronization types needs a coarray build. With gfortran, -fcoarray=single is enough on one image (without any -fcoarray option the compiler stops at the first coarray declaration with Fatal Error: Coarrays disabled at (1), use '-fcoarray=' to enable), while -fcoarray=lib links against libcaf_shmem or OpenCoarrays for several images:

Compiled with gfortran -std=f2023 -Wall -Wextra -pedantic -fimplicit-none -fcheck=all -fcoarray=single:

This page does not show failure behaviour (a second lock by the same image, an unlock of an unlocked lock): the two gfortran runtimes tried, -fcoarray=single and -fcoarray=lib with libcaf_shmem, returned stat=0 for a repeated lock, and OpenCoarrays returned its own code 99 where the standard names stat_locked, so a portable program cannot yet rely on them. Team statements were also incomplete: a test program that called get_team and form team compiled with -fcoarray=single and then ended silently after its first output line, so the team constants above are shown as values only. The coarray pages treat these statements and these limits in detail.

Source: J3/23-007r1: 16.10.2.2 to 16.10.2.3, 16.10.2.8, 16.10.2.10, 16.10.2.12, 16.10.2.19, 16.10.2.22, 16.10.2.25 to 16.10.2.35, with constraints C1603 to C1614, GNU Fortran manual: ISO_FORTRAN_ENV

The provenance below combines the Fortran 2023 text (which lists the F2023 additions in its Introduction) with what gfortran -std= itself reports: each constant was imported alone under -std=f2003, -std=f2008 and -std=f2018, and the first level that accepted it is shown. gfortran 16.2 rejects real16, logical8 to logical64 and notify_type below -std=f2023 (they are F2023 names), and its module does not have stat_unlocked_failed_image or notify_type at all (real16 exists there but has the value -2).

The checks behind the table are cheap to repeat. With -std=f95 the intrinsic nature itself is rejected:

and with -std=f2003 the Fortran 2008 names are rejected with a message that names the edition:

(These are lines of the real output of 16_std_levels.f90, a program that imports int64, real128, compiler_version, atomic_int_kind and logical32.) The same flag therefore doubles as a portability test: building with the oldest -std the project promises to support shows the first entity that the older compilers do not have.

Importing a name that the module does not provide is a compile-time error, on both compilers, even though the module as a whole exists:

gfortran 16.2:

Source: J3/23-007r1: 14.2.2 The USE statement and use association, R1409 to R1411 and C1404 to C1406; 16.10.1 Standard intrinsic modules, General and GNU Fortran manual: ISO_FORTRAN_ENV

Flang 23 accepts this program and prints 106 (its value of stat_unlocked_failed_image). With only the error appears at the use line with the module name in it; without only, the same missing name appears only where it is used and, in a program without implicit none, as the unrelated "has no IMPLICIT type". Another reason to write both only and implicit none. A compile-time failure is also the correct way to learn that a compiler lacks a feature: a program that must run on both can guard the import in a preprocessed module (as in the vendor-module section below), or not use the feature.

The Fortran 2028 working draft J3/26-007r1 (a draft that will change) adds, in its 17.10.2:

None of them exists yet in the two compilers used here. The program below imports procedure_name, max_rank, source_file, source_line and double_precision:

gfortran 16.2 reports Error: Symbol 'procedure_name' referenced at (1) not found in intrinsic module ISO_FORTRAN_ENV once per name (five errors), and Flang 23 reports error: 'procedure_name' not found in module 'iso_fortran_env' for each of them as well.

Use these names only after the compiler documentation says it implements them. The page What’s New and Fortran 2028 Preview tracks the draft.

Source: J3/26-007r1: 17.10.2 The ISO_FORTRAN_ENV intrinsic module (Fortran 2028 draft)

A use statement without only imports every public entity of the module, which for iso_fortran_env is more than forty names. Declaring a local entity with one of those names in the same scope is an error:

gfortran 16.2:

Source: J3/23-007r1: 14.2.2 The USE statement and use association, R1409 to R1411 and C1404 to C1406; 16.10.1 Standard intrinsic modules, General

Flang 23: error: 'output_unit' is use-associated from module 'iso_fortran_env' and cannot be re-declared.

The program unit wide in the same file shows the other half of the rule. The subroutine report declares a local integer :: int32 although int32 is use-associated into its host module, and both compilers accept it: a declaration in an inner scope hides the host-associated name, and only a conflict in the same scope is an error. That is legal and hard to read, and it is why an only list (or private in the module plus explicit public statements) is better than relying on the scoping rules. If a processor extends iso_fortran_env with a new public name (S 16.10.1 allows it), a program that imports everything can start failing to compile after a compiler upgrade, and a program that imports with only cannot.

omp_lib compiles without -fopenmp but does not link, because the runtime library is only linked with the flag:

Source: GNU Fortran manual: OpenMP Modules OMP_LIB and OMP_LIB_KINDS

That is the gfortran 16.2 link error without -fopenmp (the object file name varies from run to run); Flang 23 gives the same kind of error (undefined reference to 'omp_get_max_threads'). With -fopenmp the program prints max threads: 3 for OMP_NUM_THREADS=3. Without the variable the runtime picks the thread count itself (the number of cores, in our container).

A module that is simply absent gives a different failure, at compile time. This is ifport on gfortran 16.2 (the program is 26_ifport.f90, a five-line program that imports sleepqq):

and Flang 23: error: Cannot parse module file for module 'ifport': Source file 'ifport.mod' was not found. ifport was not run with Intel ifx, which was not available, and the text above does not claim anything about what it provides beyond its role.

For mpi_f08 the compile line is the whole story. The module is provided by the MPI installation, and the MPI Forum defines its contents (the mpi_f08 Fortran binding is part of the MPI standard):

Built with mpifort -std=f2023 (the wrapper uses gfortran 16.2 here) and run with mpirun -n 3:

Source: MPI Forum: MPI documents

It also builds warning-free with -std=f2018 -Wall -Wextra -pedantic. Notice that the strict -std flag does not reject the module: standard conformance checks apply to the source, not to the vendor module it imports. The program does not need mpi_f08 to be intrinsic, and it is not; the compiler finds mpi_f08.mod through the wrapper’s -I flags. Parallel programming is covered in OpenMP and OpenACC and MPI with mpi_f08.

Because these modules are not portable, the practical rule is that only one module in the project may import each of them, and everything else imports that module. The rest of the program then compiles on a machine without OpenMP, MPI or the vendor library, and a port to another compiler changes one file. In heatflow the idea looks like this:

heatflow_threads is the only module that knows about omp_lib. It compiles in two configurations: with OpenMP, where it forwards to the runtime, and without, where it provides serial stand-ins with the same interface. The choice is made by the preprocessor macro _OPENMP that compilers define under -fopenmp. The file needs a preprocessed extension (.F90):

The program runs unchanged in four configurations:

The same pattern isolates mpi_f08 in a heatflow_parallel module (not shown) and any vendor library: public procedures with standard types in the signature, vendor types private to the module, and a serial fallback or a clear error when the capability is absent. Points that make the pattern work:

Source: J3/23-007r1: 16.10.1 Standard intrinsic modules, General, GNU Fortran manual: OpenMP Modules OMP_LIB and OMP_LIB_KINDS, MPI Forum: MPI documents