Accessing Program Exit Codes in Windows Command Prompt

Understanding Exit Codes

When you run a program from the command line, it often signals its completion status using an exit code. A successful execution typically returns an exit code of 0, while non-zero values indicate errors or specific conditions. This information is crucial for scripting and automating tasks, allowing you to react to a program’s outcome. This tutorial explains how to access these exit codes in the Windows command prompt (cmd.exe).

The errorlevel Variable

The Windows command prompt provides a built-in variable called errorlevel that holds the exit code of the most recently executed command. You can display the current value of errorlevel by simply typing:

echo %errorlevel%

This will print the integer value currently stored in the errorlevel variable.

Using errorlevel in Conditional Statements

The real power of errorlevel comes from using it in conditional statements. The if command allows you to check the value of errorlevel and execute code blocks accordingly.

The basic syntax is:

if errorlevel n (
  commands_to_execute
)

Important: This statement checks if errorlevel is greater than or equal to n. This can be a common point of confusion. For example, if errorlevel 1 will execute the commands_to_execute if errorlevel is 1 or greater.

Here’s an example:

my_program.exe

if errorlevel 1 (
  echo Program failed with error code %errorlevel%
) else (
  echo Program executed successfully.
)

In this example, if my_program.exe returns an exit code of 1 or higher, the first echo statement will be executed. Otherwise, the second echo statement will run.

Matching Exact Exit Codes

To match a specific exit code exactly, you need to use a combination of conditional statements or the EQU operator.

Using Multiple if Statements:

my_program.exe

if %errorlevel% EQU 0 (
    echo Program completed successfully.
) else if %errorlevel% EQU 1 (
    echo Error: File not found.
) else (
    echo Unknown error occurred: %errorlevel%
)

Using EQU:

my_program.exe

if %errorlevel% EQU 0 (
  echo Success!
) else (
  echo Failure. Error code: %errorlevel%
)

Using NEQ for "Not Equal"

You can also use NEQ to check if the errorlevel is not equal to a specific value:

if %errorlevel% NEQ 0 (
  echo Program failed with error code %errorlevel%
)

Dealing with Batch File Differences (.BAT vs .CMD)

Historically, there have been subtle differences in how .BAT and .CMD batch files handle errorlevel. Older .BAT files might not consistently update errorlevel after each command, potentially leading to inaccurate results. .CMD batch files are generally more consistent in this regard. For modern scripting, it’s recommended to use .CMD files.

Launching Windowed Applications

If you’re launching a GUI (windowed) application from the command prompt, simply running the executable might not give you the exit code immediately. The application runs in the background, and the command prompt returns with an errorlevel of 0 (indicating successful launching of the process, not the completion of the application).

To wait for the application to complete and obtain its exit code, use the START /WAIT command:

start /wait my_windowed_app.exe
echo %errorlevel%

This command will start the application, wait for it to exit, and then set errorlevel to the application’s exit code.

Avoiding Conflicts with Environment Variables

Be cautious about defining environment variables named ERRORLEVEL. If you do, they will override the built-in errorlevel variable, potentially leading to incorrect results. Avoid creating environment variables with the same name as system variables.