args, exit codes and System.exit

A Java program has no argv of its own: the launcher builds an array of strings and passes it to main. Everything a program reads from the command line comes from that array, and everything it reports back to the shell comes from the exit status, which a program sets with System.exit.

The args array

The words after the class name are the elements of args, one per word. The class name, the -cp option and the JVM options in front of it are not part of the array, so java Args one two gives two elements.

The file Args.java:

public class Args { public static void main(String[] args) { System.out.println("count: " + args.length); for (int i = 0; i < args.length; i++) { System.out.println(i + ": " + args[i]); } } }

javac -Xlint:all Args.java
java Args one two

count: 2
0: one
1: two

The array is never null, even with no arguments, so args.length is always safe. A word that contains a space is one element when it is quoted in the shell, and two when it is not: the launcher does no parsing of its own.

What is not in args

The class name is not an element, and neither are the JVM options: java -Xmx256m Args a gives one element, a. A program that needs the name it was started with reads it from the launcher, not from args, and a program that needs options of its own parses them from the array with a library or by hand.

A usage message and System.exit

A program that needs an argument checks the length first, prints a usage message and sets a status other than 0. The status is a number from 0 to 255, and by convention 0 means success, 1 means a general failure and 2 means a wrong usage.

public class Usage { public static void main(String[] args) { if (args.length == 0) { System.out.println("usage: Usage NAME..."); System.exit(2); } System.out.println("hello, " + args[0]); } }

javac -Xlint:all Usage.java
java Usage
echo "status: $?"

usage: Usage NAME...
status: 2

System.exit ends the JVM at the call: no code after it runs, and no finally block of an enclosing try runs either. A program that must release a resource before it exits returns from main instead, or sets a status through a variable it checks at the end.

The status the shell sees

A program that reaches the end of main returns 0. An uncaught exception returns 1, and System.exit(n) returns n modulo 256. A script that runs the program reads $? and decides, which is the whole contract between a command-line program and its caller.

The same status is what a test runner or a build tool reads. A test that asserts on the output of a program should also assert on its status, because a program that prints the right line and then fails still failed.

Parsing numbers from args

Every element is a string, so a number must be parsed with Integer.parseInt or Double.parseDouble. The parse throws NumberFormatException for a word that is not a number, and a command-line program turns that into a message and a status rather than a stack trace.

public class Sum { public static void main(String[] args) { int total = 0; for (String arg : args) { total += Integer.parseInt(arg); } System.out.println("sum: " + total); } }

javac -Xlint:all Sum.java
java Sum 1 2 3

sum: 6

With no arguments the loop does not run and the sum is 0, which is the right answer for an empty list and a poor answer for a program that expected input. The usage check of Usage is what distinguishes the two cases.

Exercises

  1. Run Args.java with a quoted argument that contains a space. How many elements does it count?
  2. Add a second required argument to Usage.java and report status 2 when either one is missing.
  3. Make Sum.java print a usage line and exit with status 2 when an argument is not a number.
  4. Print the status of a program that throws an uncaught exception and of one that returns normally.

Questions

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

  1. What does the launcher put into args?

    Answer

    The words after the class name, one per element

    The class name selects the class and the JVM options are consumed by the launcher, so neither is an element.

  2. What is args.length when a program is started with no words after the class name?

    Answer

    0

    The launcher passes an empty array, not null, so length is 0.

  3. What status does System.exit(2) give the shell?

    Answer

    2

    The number is the exit status, taken modulo 256.

  4. This program is run with java Q1 a b c. What does it print? public class Q1 { public static void main(String[] args) { System.out.println(args.length + " " + args[1]); } }

    Answer

    3 b

    Three words are three elements, and index 1 is the second word, b.

  5. What does this program print? public class Q2 { public static void main(String[] args) { int total = 0; for (String arg : args) { total += Integer.parseInt(arg); } System.out.println(total); } } when it is run as java Q2 4 5?

    Answer

    9

    The two arguments are parsed as 4 and 5 and added.

  6. What does this program print, and what is its status? public class Q3 { public static void main(String[] args) { if (args.length == 0) { System.out.println("need a name"); System.exit(2); } System.out.println("ok"); } } run as java Q3?

    Answer

    need a name / status: 2

    The array is empty, the message is printed and System.exit sets status 2.

  7. What does Integer.parseInt("12") return?

    Answer

    The int 12

    parseInt returns a primitive int; the wrapper is returned by valueOf.

  8. What is the status of a program that dies of an uncaught exception?

    Answer

    1

    The JVM returns 1 after printing the stack trace of an uncaught exception.

  9. What does this program print? public class Q4 { public static void main(String[] args) { System.out.println(args.length); } } run as java Q4 "one two"?

    Answer

    1

    The shell passes a quoted string as one word, so the array has one element.

  10. Why is a usage message printed before System.exit?

    Answer

    Nothing runs after System.exit, so the message must come first

    System.exit ends the JVM at the call, so the program writes its message and then exits.

The code on this page was built with OpenJDK 21.0.13 (javac and java) and run on Alpine Linux in a Docker container.

Article author: Arthur Isaev