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:

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

  1. Set FORTRAN_DEMO to an empty string and run the first program. Which status do you get, and what is the length?
  2. Read FORTRAN_LONG into a 10 character variable and print the status. Is it 0 or -1?
  3. Add an environment variable that holds a number, read it, and convert it with an internal read and an iostat.
  4. 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.

  1. Which intrinsic reads an environment variable?

    Answer

    get_environment_variable

    It is the standard Fortran intrinsic, with a value, length and status argument.

  2. What status means the variable is not set?

    Answer

    1

    Zero is success, one is not set, and minus one is a truncated value.

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

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

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

    Answer

    1

    An unset variable reports status 1.

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

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

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

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

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

Banner image