Windows cmd return codes

• Overview
• Part 1 – Getting Started
• Part 2 – Variables
• Part 3 – Return Codes
• Part 4 – stdin, stdout, stderr
• Part 5 – If/Then Conditionals
• Part 6 – Loops
• Part 7 – Functions
• Part 8 – Parsing Input
• Part 9 – Logging
• Part 10 – Advanced Tricks

Today we’ll cover return codes as the right way to communicate the outcome of your script’s execution to the world. Sadly, even
skilled Windows programmers overlook the importance of return codes.

Return Code Conventions

By convention, command line execution should return zero when execution succeeds and non-zero when execution fails. Warning messages
typically don’t effect the return code. What matters is did the script work or not?

Checking Return Codes In Your Script Commands

The environmental variable %ERRORLEVEL% contains the return code of the last executed program or script. A very helpful feature is
the built-in DOS commands like ECHO, IF, and SET will preserve the existing value of %ERRORLEVEL%.

The conventional technique to check for a non-zero return code using the NEQ (Not-Equal-To) operator of the IF command:

IF %ERRORLEVEL% NEQ 0 (
  REM do something here to address the error
)

Another common technique is:

IF ERRORLEVEL 1 (
  REM do something here to address the error
)

The ERRORLEVEL 1 statement is true when the return code is any number equal to or greater than 1. However, I don’t use this technique because
programs can return negative numbers as well as positive numbers. Most programs rarely document every possible return code, so I’d rather explicity
check for non-zero with the NEQ 0 style than assuming return codes will be 1 or greater on error.

You may also want to check for specific error codes. For example, you can test that an executable program or script is in your PATH by simply
calling the program and checking for return code 9009.

SomeFile.exe
IF %ERRORLEVEL% EQU 9009 (
  ECHO error - SomeFile.exe not found in your PATH
)

It’s hard to know this stuff upfront – I generally just use trial and error to figure out the best way to check the return code of the program or
script I’m calling. Remember, this is duct tape programming. It isn’t always pretty, but, it gets the job done.

Conditional Execution Using the Return Code

There’s a super cool shorthand you can use to execute a second command based on the success or failure of a command. The first program/script must
conform to the convention of returning 0 on success and non-0 on failure for this to work.

To execute a follow-on command after sucess, we use the && operator:

SomeCommand.exe && ECHO SomeCommand.exe succeeded!

To execute a follow-on command after failure, we use the || operator:

SomeCommand.exe || ECHO SomeCommand.exe failed with return code %ERRORLEVEL%

I use this technique heavily to halt a script when any error is encountered. By default, the command processor will continue executing
when an error is raised. You have to code for halting on error.

A very simple way to halt on error is to use the EXIT command with the /B switch (to exit the current batch script context, and not the command
prompt process). We also pass a specific non-zero return code from the failed command to inform the caller of our script about the failure.

SomeCommand.exe || EXIT /B 1

A simliar technique uses the implicit GOTO label called :EOF (End-Of-File). Jumping to EOF in this way will exit your current script with
the return code of 1.

SomeCommand.exe || GOTO :EOF

Tips and Tricks for Return Codes

I recommend sticking to zero for success and return codes that are positive values for DOS batch files. The positive values are a good idea
because other callers may use the IF ERRORLEVEL 1 syntax to check your script.

I also recommend documenting your possible return codes with easy to read SET statements at the top of your script file, like this:

SET /A ERROR_HELP_SCREEN=1
SET /A ERROR_FILE_NOT_FOUND=2

Note that I break my own convention here and use uppercase variable names – I do this to denote that the variable is constant and should not
be modified elsewhere. Too bad DOS doesn’t support constant values like Unix/Linux shells.

Some Final Polish

One small piece of polish I like is using return codes that are a power of 2.

SET /A ERROR_HELP_SCREEN=1
SET /A ERROR_FILE_NOT_FOUND=2
SET /A ERROR_FILE_READ_ONLY=4
SET /A ERROR_UNKNOWN=8

This gives me the flexibility to bitwise OR multiple error numbers together if I want to record numerous problems in one error code.
This is rare for scripts intended for interactive use, but, it can be super helpful when writing scripts you support but you don’t
have access to the target systems.

@ECHO OFF
SETLOCAL ENABLEEXTENSIONS

SET /A errno=0
SET /A ERROR_HELP_SCREEN=1
SET /A ERROR_SOMECOMMAND_NOT_FOUND=2
SET /A ERROR_OTHERCOMMAND_FAILED=4

SomeCommand.exe
IF %ERRORLEVEL% NEQ 0 SET /A errno^|=%ERROR_SOMECOMMAND_NOT_FOUND%

OtherCommand.exe
IF %ERRORLEVEL% NEQ 0 (
    SET /A errno^|=%ERROR_OTHERCOMMAND_FAILED%
)

EXIT /B %errno%

If both SomeCommand.exe and OtherCommand.exe fail, the return code will be the bitwise combination of 0x1 and 0x2, or decimal 3. This return code tells
me that both errors were raised. Even better, I can repeatedly call the bitwise OR with the same error code and still interpret which errors were
raised.

<< Part 2 – Variables


Part 4 – stdin, stdout, stderr >>

Last Updated :
27 Jan, 2022

Return codes are the codes returned by programs when they are executed. If the command line is successful, it should return zero; if it is not successful, it should return non-zero. If the test fails, a non-zero value indicates the error number, and the user can attempt to resolve it by navigating to the error message.

The test may also return an exit code. A program’s or utility’s exit code usually appears when it finishes or terminates.

The list below includes some of the non-zero exit codes (with their respective errors) that programs may return

Batch file error level:

%ERRORLEVEL% is an environment variable that contains the last error level or return code in the batch file — that is, the last error code of the last command executed. Error levels may be checked by using the %ERRORLEVEL% variable as follows:

IF %ERRORLEVEL% NEQ 0 (
  DO_Something
)

A common method of returning error codes from batch files is to use the command EXIT /B %ERRORLEVEL%.

For custom return codes, use the EXIT /B <exitcodes> command.

Example:

 In the below example, if the condition is met, the script will terminate with the exit code 0. If the condition isn’t met, then the exit code will be 1.

if [[ "$(whoami)" != root ]]; then
   echo "Not root user."
   exit 1
fi
echo "root user"
exit 0

Output:

Картинка с сайта: www.geeksforgeeks.org

Loops:

There have been statements enacted sequentially in the decision-making chapter. Alternatively, Batch Script can also be used to alter the flow of control in a program’s logic. These statements are then organized into flow control statements.

Looping through Command Line Arguments

For checking command-line arguments, you can use the for statement. Here is an example of how to loop through the arguments of a command line using the ‘for’ statement.

for ((c=1; c<=7; c++))
do  
  echo "Welcome $c times"
done

Output:

Картинка с сайта: www.geeksforgeeks.org

Windows CMD exit codes indicate the success or failure of a command or script, providing a numeric status that can be used for error handling in batch files or scripts.

Here’s an example of checking the exit code after running a command:

echo off
your_command_here
if %errorlevel% neq 0 (
    echo Command failed with exit code %errorlevel%
) else (
    echo Command succeeded with exit code %errorlevel%
)

What Are Exit Codes?

Definition of Exit Codes

Windows CMD exit codes are numerical values returned by a command or script upon its completion. These codes provide insight into whether a command was successful or whether it encountered errors. Understanding exit codes is essential for diagnosing problems and improving the efficiency of your command-line operations.

Standard Exit Code Values

In CMD, exit codes typically adhere to a few standard values:

• 0: Indicates that the command was successful without any errors. This is the exit code of success.
• 1: Represents a general error. This code suggests that something went wrong, but it doesn’t specify the exact issue.
• Common Codes (2-255): Various other codes may indicate specific types of errors or warnings based on the command executed. Familiarity with these can greatly aid troubleshooting.

Картинка с сайта: cmdmastery.com

Mastering Windows Cmd Switches: A Concise Guide

How to Use Exit Codes in CMD

Basic Syntax for Checking Exit Codes

To check the exit code after running a command, you can use the built-in variable `%ERRORLEVEL%`. This variable holds the exit code of the last command executed. Here’s the basic syntax:

command
echo %ERRORLEVEL%

This simple approach allows you to receive immediate feedback on the success or failure of any command you’ve run.

Understanding Common CMD Commands and Their Exit Codes

Different commands in CMD can have their unique expected exit codes. Understanding these can help you troubleshoot effectively:

• COPY: The `COPY` command is used to copy files. A successful copy returns an exit code of 0, while a failure (like a non-existent source file) results in 1.
• DEL: The `DEL` command deletes files. Similar to `COPY`, success returns 0, and failure returns 1. If you try to delete a file that does not exist, you’ll receive an appropriate error code.
• PING: Used for testing network connections. A successful ping returns 0, while unreachable targets will return 1.

Картинка с сайта: cmdmastery.com

Windows Cmd Clear: Refresh Your Command Line Effortlessly

Practical Examples of Exit Codes

Example 1: A Simple File Copy Operation

When you execute a command to copy a file, it’s helpful to check the exit code to verify that the operation was successful.

copy file.txt destination.txt
echo %ERRORLEVEL%

If the copy command succeeds, the output will display 0. If `file.txt` doesn’t exist, you will get an exit code of 1, indicating an error.

Example 2: Deleting a Non-Existent File

Attempting to delete a file that does not exist will also provide valuable insight into how CMD handles errors.

del nonexistentfile.txt
echo %ERRORLEVEL%

In this case, you should see an exit code of 1, signaling that the file couldn’t be deleted because it was never there in the first place.

Example 3: Using PING Command to Check Connectivity

The `PING` command is a practical and frequently used command to test network availability.

ping google.com
echo %ERRORLEVEL%

If you receive a successful response from Google, the exit code will be 0. If your internet connection is down or Google is unreachable, you will receive an error code of 1, indicating a failed connection.

Картинка с сайта: cmdmastery.com

Mastering Windows Cmd Route: A Concise Guide

Custom Exit Codes in Batch Files

Creating a Batch File with Custom Exit Codes

You have the ability to create custom exit codes in batch files, which can help streamline error handling and troubleshooting in your scripts. Consider the example below:

@echo off
if exist myfile.txt (
    exit /b 0
) else (
    exit /b 1
)

In this script, if `myfile.txt` exists, the script exits with a code of 0. If it does not exist, it exits with a code of 1.

Best Practices for Using Exit Codes in Scripts

Using meaningful exit codes in your scripts enhances both clarity and usability. Documenting your exit codes helps not only you but also others who may use or modify your code in the future. Consider establishing a standard to ensure consistency across your scripts.

Картинка с сайта: cmdmastery.com

Windows Cmd Repair Commands: A Quick Guide

Troubleshooting Common Exit Code Issues

Diagnosing Problems Using Exit Codes

Interpreting exit codes is a crucial skill for troubleshooting. By analyzing the return value of commands, you can pinpoint specific issues, whether it’s syntax errors, unavailable files, or other problems.

Logging and Monitoring Exit Codes

Setting up logging to capture exit codes during script execution can be immensely beneficial for debugging. By saving exit codes to a log file, you can track the history of your script’s operation and quickly identify which parts may be failing. Consider using tools or frameworks designed for logging CMD operations for a more organized approach.

Картинка с сайта: cmdmastery.com

Mastering Windows Cmd Remote Desktop: Quick Command Guide

Conclusion

Understanding windows cmd exit codes is invaluable for anyone looking to master the command line or improve their scripting and automation capabilities. By familiarizing yourself with standard exit codes and employing them in your scripts, you increase your productivity and troubleshooting efficiency. Regular practice and exploration of CMD’s capabilities will help solidify this knowledge, making it a crucial part of your skill set.

Картинка с сайта: cmdmastery.com

Windows Cmd Set Env Variable in Just a Few Steps

Further Reading and Resources

For deeper exploration into CMD and batch file programming, consider visiting official documentation, online tutorials, and community forums. These resources can provide ongoing insight and additional support as you continue to learn and implement CMD commands effectively.

all DOS versions is the reverse order check.
Start checking the highest errorlevel that can be expected, then check for the one below, etcetera:
IF ERRORLEVEL 255 GOTO Label255
IF ERRORLEVEL 254 GOTO Label254
  •
  •
  •
IF ERRORLEVEL   2 GOTO Label2
IF ERRORLEVEL   1 GOTO Label1
GOTO Label0

This will result in many more lines of batch code, but at least it will work in any DOS version.
In Windows NT (Windows NT 4 … Windows 10) this may not suffice, though, because errorlevels can have negative integer values as well.