Environment variables
A command-line argument is the wrong place for a setting a user wants to give once: the shell has a mechanism for that, the environment variable, and Fortran can read it. The intrinsic is get_environment_variable, and its three optional arguments are what turn a missing variable into a decision instead of a crash. This lesson reads one, handles the missing case and the short buffer, and builds a default.
GET_ENVIRONMENT_VARIABLE
call get_environment_variable("NAME", value) copies the value into a character variable. When the variable is not set, the copy is the empty string and the program has no way to tell that from a variable set to nothing, which is why the status argument exists.
The file env.f90:
program env
implicit none
character(len=64) :: value
integer :: status, length
call get_environment_variable("FORTRAN_DEMO", value, length, status)
print *, "status:", status
print *, "length:", length
if (status == 0) then
print *, "value :", trim(value)
else
print *, "value : not set, using default"
end if
end program env
Run once without the variable and once with it set for that command only:
gfortran -Wall -Wextra -std=f2018 env.f90 -o env
./env
FORTRAN_DEMO=hello ./env
status: 1
length: 0
value : not set, using default
status: 0
length: 5
value :hello
The status argument
The fourth argument is the status, and it has three values worth knowing:
- 0 means the variable is set and its value fitted in the variable.
- 1 means the variable is not set at all.
- -1 means the variable is set but its value was longer than the character variable, so what arrived is truncated.
Treating 1 and -1 as the same thing is a bug waiting for a long value: a path of 100 characters read into a 64 character variable is not the path, and a program that uses it opens the wrong file. The third program shows the difference with one variable and two buffer sizes.
A default value
The pattern for a setting with a sensible default is four lines: read into a variable that already holds the default, and overwrite it only when the status says the value arrived.
character(len=64) :: path
integer :: status
path = "output.dat"
call get_environment_variable("FORTRAN_OUTPUT", path, status=status)
if (status /= 0) path = "output.dat"
The initialisation is repeated after the call on purpose: when the variable is unset, gfortran writes blanks into the argument, so a program that relied on the initial value alone would lose it. Writing the default twice is the price of the semantics, and one line is cheaper than a branch that repeats it.
The same pattern with a number needs the internal read of the previous lesson after the environment read, and the same iostat decides whether the text was a number.
The length argument
The third argument receives the length of the value, which may be longer than the variable. That is the number a program needs to allocate a buffer of the right size: call once with a one-character variable to learn the length, allocate, and call again. For a setting read at start-up the fixed buffer of 64 or 256 characters is simpler, and the status tells the program when it was not enough.
A value that does not fit
The file statuses.f90:
program statuses
implicit none
character(len=4) :: short
character(len=64) :: full
integer :: status, length
call get_environment_variable("FORTRAN_LONG", short, length, status)
print *, "short status:", status, " length:", length
call get_environment_variable("FORTRAN_LONG", full, length, status)
print *, "full status:", status, " length:", length
print *, "full value :", trim(full)
call get_environment_variable("FORTRAN_MISSING", full, length, status)
print *, "missing status:", status, " length:", length
end program statuses
gfortran -Wall -Wextra -std=f2018 statuses.f90 -o statuses
FORTRAN_LONG=abcdefghij ./statuses
short status: -1 length: 10
full status: 0 length: 10
full value :abcdefghij
missing status: 1 length: 0
The first call reports -1 and still says the value is ten characters long, so a program can print a message that names the size it needed. The second call fits and reports zero. The third names a variable that does not exist and reports 1 with a length of zero.
Exercises
- Set FORTRAN_DEMO to an empty string and run the first program. Which status do you get, and what is the length?
- Read FORTRAN_LONG into a 10 character variable and print the status. Is it 0 or -1?
- Add an environment variable that holds a number, read it, and convert it with an internal read and an iostat.
- Use the "call once for the length, then allocate" pattern for FORTRAN_LONG. How many calls does it take?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which intrinsic reads an environment variable?
Answer
get_environment_variable
It is the standard Fortran intrinsic, with a value, length and status argument.
-
What status means the variable is not set?
Answer
1
Zero is success, one is not set, and minus one is a truncated value.
-
What status means the value did not fit in the variable?
Answer
-1
A truncated value reports -1 and a length longer than the variable.
-
What does the length argument report?
Answer
The length of the value in the environment, which may exceed the variable
It is the true length of the value, useful for sizing a buffer.
-
What does this program print when FORTRAN_X is unset?
program p implicit none character(len=8) :: v integer :: s call get_environment_variable("FORTRAN_X", v, status=s) print *, s end program pAnswer
1
An unset variable reports status 1.
-
Why write the default value twice?
Answer
The call overwrites the variable with blanks when the variable is unset
The argument is written by the call, so the default must be restored after it.
-
How does a program get a number from an environment variable?
Answer
Read the text and convert it with an internal READ and IOSTAT
The value arrives as text, so the conversion is a read with a status.
-
Why is a value of 100 characters in a 64 character variable a bug?
Answer
The program receives a truncated value and may open the wrong file
The status is -1 and what arrived is only a prefix.
-
Which is a good use of an environment variable?
Answer
A setting a user gives once, such as an output directory
Per-run data belongs on the command line; persistent configuration belongs in the environment.
-
What does
trim(v)do to an environment value?Answer
It removes the padding the character variable added
The value is padded to the declared length of the variable.
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