Command-line arguments

A Fortran program receives its arguments as strings, and the two intrinsics that reach them are in the language since Fortran 2003. There is no array of arguments to index: a program asks how many there are and then asks for each one by number. This lesson reads the count, reads each argument, converts the numbers with an internal read, and turns a wrong invocation into a usage message with a status.

COMMAND_ARGUMENT_COUNT

command_argument_count() returns the number of arguments after the program name. It is the whole command line minus the name, so ./args 2.5 hello -3 gives three and a bare ./args gives zero. The function is what a program calls before it allocates anything.

GET_COMMAND_ARGUMENT

call get_command_argument(n, value) copies the n-th argument into a character variable. Two optional arguments make it exact: a third integer receives the length of the argument, which may be larger than the variable, and a fourth receives a status that is non-zero when the variable was too short.

The file args.f90:

program args implicit none integer :: nargs, i, ios real :: x character(len=64) :: arg nargs = command_argument_count() print *, "arguments:", nargs do i = 1, nargs call get_command_argument(i, arg) read (arg, *, iostat=ios) x if (ios == 0) then print *, trim(arg), " -> ", x else print *, trim(arg), " is not a number" end if end do end program args

gfortran -Wall -Wextra -std=f2018 args.f90 -o args
./args 2.5 hello -3

arguments: 3
2.5 -> 2.50000000
hello is not a number
-3 -> -3.00000000

The loop is the whole pattern: count, get, convert, decide. Two details are worth copying. The variable is declared with a fixed length of 64, so an argument longer than that is truncated, which the optional length and status arguments would report. And the copy is trimmed before it is printed, because the variable is padded to 64 and the print would otherwise end in 60 blanks.

From text to number

The conversion is a read from an internal file: the character variable is the unit and the list is the variable to fill. read (arg, *, iostat=ios) x reads one real in list-directed form and reports whether it worked, which a formatted read would do the same way with a format instead of the star.

The iostat is what makes this a parser rather than a crash: a non-zero value means the text did not convert, and the program chooses what to do. A program that reads without it gets a runtime error on the first bad argument, which is not the message a user needs.

Two conversions follow from the same pattern. read (arg, *, iostat=ios) n for an integer, and read (arg, *, iostat=ios) w for a threshold where w is declared with a kind. A value with a suffix the type cannot take, such as 2.5 read into an integer, also reports a status rather than truncating silently.

A usage message

A tool that needs exactly one argument must say so when it does not get one, and the message belongs on standard output with a failure status. The program below is that shape, and the status is error stop 2 so a shell can tell a usage error from a failed computation.

The file usage.f90:

program usage implicit none integer :: ios, count character(len=32) :: name if (command_argument_count() /= 1) then call get_command_argument(0, name) print *, "usage: ", trim(name), " COUNT" error stop 2 end if call get_command_argument(1, name) read (name, *, iostat=ios) count if (ios /= 0) then print *, "not a number: ", trim(name) error stop 2 end if print *, "count:", count end program usage

gfortran -Wall -Wextra -std=f2018 usage.f90 -o usage
GFORTRAN_ERROR_BACKTRACE=0 ./usage

usage: ./usage COUNT
ERROR STOP 2

The run stops with exit status 2. With one number the program does its work, and with something that is not a number it reports the argument instead:

GFORTRAN_ERROR_BACKTRACE=0 ./usage 4
GFORTRAN_ERROR_BACKTRACE=0 ./usage nine

count: 4
not a number: nine
ERROR STOP 2

The program name

Argument 0 is the name the program was started with, exactly as the shell passed it: ./usage when it was started that way and /usr/local/bin/usage when it was started by its full path. A usage message that prints it is right in both cases, which is why the example asks for argument 0 instead of writing the name into the string.

Words with spaces are the shell's business, not the program's: ./args "two words" arrives as one argument whose value has a space in it, and ./args two words arrives as two. A Fortran program never sees the quotes.

Exercises

  1. Run ./args with no arguments. What does the count line print?
  2. Add a status argument to get_command_argument and pass an argument of 100 characters. What status do you get, and what does the value hold?
  3. Change the read in args to an integer and pass 2.5. What does the program print?
  4. Make usage accept a second, optional argument. How do you tell whether it was given?

Questions

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

  1. What does command_argument_count() count?

    Answer

    The arguments after the program name

    The program name is argument 0 and is not counted.

  2. Which argument number is the program name?

    Answer

    0

    Argument 0 holds the name the program was started with.

  3. How does a Fortran program convert an argument to a number?

    Answer

    With an internal READ of the character variable

    The character variable acts as an internal file for the read.

  4. What does the IOSTAT argument of an internal READ report?

    Answer

    Zero when the text converted, non-zero when it did not

    It is the status of the conversion, which the program can test.

  5. What does this program print when run as ./p 5 6? program p implicit none print *, command_argument_count() end program p

    Answer

    2

    Two arguments follow the program name.

  6. Which status should a usage error give?

    Answer

    A non-zero status, so the shell sees the failure

    A usage error is a failure, and error stop makes it visible.

  7. What is in argument 0 when the program is started as /usr/local/bin/tool?

    Answer

    The full path used to start it

    The value is the name as the shell passed it, which may be a path.

  8. Why trim the argument before printing it?

    Answer

    The variable is padded to its declared length with blanks

    A 64 character variable holding three characters has 61 blanks.

  9. How many arguments does ./args "two words" pass?

    Answer

    One, whose value contains a space

    The shell removes the quotes and passes one word.

  10. Which intrinsic returns the whole command line?

    Answer

    get_command

    get_command returns the entire line, name included, as one string.

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