| Category | Range (Hex) | Example | Meaning | |----------|-------------|---------|---------| | | 0x00000000–0x0000FFFF | 1 , 2 | Custom error (e.g., invalid input) | | Win32 Error Codes | 0x00000000–0x0000FFFF (overlap!) | ERROR_FILE_NOT_FOUND (2) | System API failure | | NTSTATUS Codes | 0xC0000000–0xFFFFFFFF | 0xC0000005 | Access violation (structured exception) | | HRESULT | 0x80070000–0x8007FFFF | 0x80070002 | COM error, wraps Win32 error 2 |
In the seemingly sterile output of a command-line program—a lone integer returned to the operating system—lies a sophisticated, often misunderstood contract between a process and its caller. On Windows, this integer is the exit code (or "return code"), and while the convention 0 for success and non-zero for failure is universal, the depth beneath is uniquely shaped by Windows' architecture, its legacy subsystems, and the perils of cross-platform assumptions. 1. The Kernel's Handshake: How Exit Codes Really Work When a Windows process terminates—whether by returning from main() , calling ExitProcess() , or suffering an unhandled exception—the kernel records a 32-bit unsigned integer inside the EPROCESS block. This value persists until the process object is reaped by WaitForSingleObject() or GetExitCodeProcess() . exit codes windows
If your main() throws an uncaught C++ exception, the CRT catches it, calls terminate() , and then ExitProcess(3) . The code 3 means nothing about your logic—it simply signals "CRT abnormal termination." | Category | Range (Hex) | Example |
> net helpmsg 2 The system cannot find the file specified. If the program is well-known (e.g., robocopy , xcopy ), consult its documentation—they reuse Win32 error codes with different meanings. The Kernel's Handshake: How Exit Codes Really Work
PowerShell-native commands return rich objects, not exit codes. When you run an external .exe , PowerShell captures its exit code in $LASTEXITCODE , but the PowerShell process's own exit code is set only by exit $n . A script that runs non-existent.exe will see $LASTEXITCODE = 0xC0000135 (STATUS_DLL_NOT_FOUND), but the PowerShell process itself exits with 0 unless you explicitly forward it. 4. The Debugger's Compass: Interpreting Exit Codes as Clues For a systems engineer, an unexpected exit code is a compressed diagnostic. Here’s how to decompress it:
> err 0xC0000005 # for hex 0xc0000005 / decimal -1073741819 STATUS_ACCESS_VIOLATION Check against Win32 error codes: