Arguments and exit codes

The arguments of a program

A program receives its arguments as a list of strings, with the name of the program already removed. They arrive in an IO action because the operating system hands them over when the process starts:

getArgs :: IO [String] getProgName :: IO String

The list is only strings. Turning the third argument into a number is the program's job, and the program decides what an argument it cannot parse means: a usage message, a default, or an error. The shell passes the arguments, so quoting and globbing are decided before the program runs.

getArgs and a usage message

The smallest useful shape is a program that requires at least one argument and prints what it got:

module Main (main) where import System.Environment (getArgs) import System.Exit (ExitCode (ExitFailure), exitWith) import System.IO (hPutStrLn, stderr) main :: IO () main = do args <- getArgs case args of [] -> do hPutStrLn stderr "usage: args NAME..." exitWith (ExitFailure 2) _ -> do putStrLn ("arguments: " ++ show (length args)) mapM_ putStrLn args

ghc -Wall -O1 -o args args.hs
./args one two

arguments: 2
one
two

With no arguments the same binary writes its usage line to standard error and leaves with status 2:

./args
echo "status: $?"

usage: args NAME...
status: 2

The usage goes to stderr on purpose: a caller that reads the standard output of the program should not find a usage message mixed into the data. For the same reason the message names the program as args and not as an absolute path.

exitWith and the status

exitWith ends the program at once with a status and does not run anything after it. The two values are ExitSuccess and ExitFailure n, and exitSuccess and exitFailure are the shortcuts for 0 and 1:

module Main (main) where import System.Environment (getArgs) import System.Exit (ExitCode (ExitFailure), exitSuccess, exitWith) main :: IO () main = do args <- getArgs case args of ["ok"] -> do putStrLn "the check passed" exitSuccess [code] -> case reads code :: [(Int, String)] of [(n, "")] -> do putStrLn ("the check failed with " ++ show n) exitWith (ExitFailure n) _ -> badUsage _ -> badUsage where badUsage = do putStrLn "usage: leave ok | leave CODE" exitWith (ExitFailure 64)

ghc -Wall -O1 -o leave leave.hs
./leave ok
echo "status: $?"
./leave 3
echo "status: $?"

the check passed
status: 0
the check failed with 3
status: 3

reads returns a list of the values it could parse together with the rest of the string, so [(n, "")] means "one number and nothing left over" and any other result falls through to the usage branch. That is the same pattern the lesson on Text.Read used, and it keeps a bad argument from becoming a crash.

Status zero and everything else

The status is one byte, so 0 to 255. Zero means success and every other value means a kind of failure, and the shell reports it in $?:

A program that an error call kills also leaves a non-zero status, which is why a script can treat an uncaught exception and a deliberate failure the same way. The next lesson is about modules, and the program there is built from several files; these two are still one file each, which is the point of getArgs: a single small executable that a shell can call.

Exercises

  1. Print the program name from getProgName before the arguments.
  2. Accept a --verbose flag and print more lines when it is present.
  3. Read two numbers from the arguments and print their sum, with a usage line when one is missing.
  4. Write a program that always exits with the code given as its first argument, and check it from a shell loop.
  5. Explain why a usage message belongs on standard error.
  6. Explain what the shell does with the status when it runs a pipeline.

Questions

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

  1. What does getArgs return?

    Answer

    IO [String], the arguments without the program name

    The arguments arrive as an IO action, as a list of strings, and argv[0] is already removed.

  2. Where should a usage message go?

    Answer

    Standard error

    The standard output carries the data of the program, so diagnostics go to stderr.

  3. What does exitWith (ExitFailure 2) do?

    Answer

    Ends the program at once with status 2

    exitWith ends the process with the given status; nothing after it runs.

  4. What does this program print? module Main (main) where import System.Environment (getArgs) main :: IO () main = do args <- getArgs putStrLn (show (length args)) Run as ./count one two three.

    Answer

    3

    Three arguments were given and the program name is not part of the list.

  5. Which status means success?

    Answer

    0

    Zero is the conventional success status and what exitSuccess uses.

  6. Which function is the shortcut for exitWith ExitSuccess?

    Answer

    exitSuccess

    exitSuccess leaves status 0 and exitFailure leaves 1.

  7. What does reads code :: [(Int, String)] give for "3"?

    Answer

    [(3,"")]

    The value 3 was parsed and nothing of the string was left over.

  8. Why is [(n, "")] a good pattern for an argument?

    Answer

    It accepts a number only when the whole argument was consumed

    A pattern that ignores the rest would accept 3x as 3, which hides a bad argument.

  9. What does an uncaught error call leave as the status?

    Answer

    A non-zero status, so a script sees a failure

    The runtime exits with a failure status after printing the exception, as the earlier lessons showed.

  10. How many arguments does ./copy a "b c" pass?

    Answer

    2

    The quotes are removed by the shell, so the second argument is the single string b c.

The code on this page was built with GHC 9.10.3 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev