Sign in Join

Live chat for Free Pascal, Lazarus, Delphi and every Pascal programmer.

Catalog · How the catalog works
Anything · Lazarus or Delphi
Random projectRandom project

ErrInfo

View on GitHub

Member rating

No ratings yet.

Sign in to rate this project.

README

ErrInfo

ErrInfo is a Windows console (text-based, command-line) program that outputs details about Windows error codes.

Table of Contents

Author

Bill Stewart - bstewart at iname dot com

License

ErrInfo is covered by the GNU Public License (GPL). See the file LICENSE for details.

Download

You can download the latest version using the following link:

https://github.com/Bill-Stewart/ErrInfo/releases/latest/

Synopsis

Outputs details about Windows error codes.

Usage

ErrInfo [-c | -f | -m | -s | -t | -v] [-t type] [-n] value

Parameters

-c - Outputs whether the error code is Microsoft-defined or customer-defined

-f - Outputs the error's facility code

-m - Outputs the localized error message associated with the error code, if any

-s - Outputs the error code's severity (Success, Failure, Informational, Warning, or Error)

-v - Outputs verbose details about the error code (default)

-t type - Outputs the error code as the specified type (Win32, HRESULT or, NTSTATUS)

-n - Required before negative error code values (optional otherwise)

value is the error code, specified in one of the following formats:

  • No prefix: Unsigned decimal value in the range 0 to 4294967295 (inclusive)
  • - prefix: Negative signed decimal value in the range -2147483648 to -1 (inclusive); requires -n option before the value
  • 0x or $ prefix: Hexadecimal value in the range 0 through FFFFFFFF (inclusive)

If you specify a negative signed decimal value, you must prefix the error code with the -n parameter; otherwise, the -n parameter is optional.

If you don't specify -t, ErrInfo attempts to determine the error type using the following rules:

Condition Type
Error code is in the range 0 through 65535 (FFFF hex) Win32
Error code's N bit is not set HRESULT
Error code's N bit is set Interpret as NTSTAUS

The N bit is described in the section HRESULT Error Codes, below.

The -v parameter is assumed if not specified.

Exit Codes

The ErrInfo program's exit code depends on the parameter:

-c - 0 for Microsoft-defined, or 1 for customer-defined; Win32 error codes are always Microsoft-defined

-f - The facility code; always 0 for Win32 errors

-s - The exit code depends on the error type, as follows:

  • Win32 or HRESULT: 0 for success, or 1 for failure
  • NTSTATUS: 0 for Success, 1 for Informational, 2 for Warning, or 3 for Error

-m - 0 if Windows found an error message string corresponding to the error code, or 3871 if no message string was found

In all other cases, ErrInfo returns 0 for success or non-zero for failure.

Types of Windows Error Codes

Windows error codes are a maximum of 32 bits (4 bytes) in length, which equates to a signed decimal range of -2147483648 to 2147483647, an unsigned decimal range of 0 to 4294967295, or a hexadecimal range of 0 to FFFFFFFF. There are three types of Windows error codes:

  • Win32 - Win32 error codes fit in the 16 bit range 0 to 65535 (FFFF hex). The most significant 16 bits are not used in Win32 error codes.
  • HRESULT - HRESULT error codes are 32 bits in length. The most significant 16 bits are used to additional error information, such as the source of the error. If the N bit is set (see HRESULT Error Codes, below), the HRESULT respresents an NTSTATUS code, which is the same error code as the HRESULT but with the N bit cleared.
  • NTSTATUS - NTSTATUS error codes are also 32 bits. They are nearly the same as HRESULT error codes except that the 16 most significant bits are interpreted slightly differently.

The following sections briefly describe Windows error codes. For more comprehensive information, search for the topic MS-ERREF on Microsoft's web site.

NOTE: The bit position numbers in the bit pattern tables in this section are laid out in big endian order (31 down to 0), which corresponds to the bit positions used in the "Programmer" mode of the standard Windows calculator utility. Microsoft's documentation follows RFC conventions and numbers the bits in little endian order (i.e., host byte order for x86 and x86_64 processors). Regardless of numbering, the most significant bit is left-most (the 2^31 position) and the least-significant bit is right-most (the "ones" position).

Win32 Error Codes

As discussed in the previous section, Win32 error codes are 16 bits in length and are in the range 0 through 65535 (FFFF hex).

For Win32 errors, a 0 value indicates success, and a non-zero value indicates failure.

ErrInfo takes into account two error code ranges and gets messages from different system DLLs based on those error code ranges, as follows:

Error code range (decimal) System DLL
2100-2999 netmsg.dll
12000-12176 wininet.dll

If there are additional error code ranges that need to be added, please inform the author.

HRESULT Error Codes

Microsoft defines the 32 bits of the HRESULT error code using the following bit pattern table:

31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 to 0
S R C N X F F F F F F F F F F F Remainder of error code

The letters in the bit positions represent the following:

Bit Description
S Severity: 0 for success, 1 for failure
R Reserved: should be 0
C Customer: 0 if this error code is Microsoft-defined, or 1 if customer-defined
N NTSTATUS: 1 if this HRESULT should be interpreted as an NTSTATUS
X Reserved: should be 0
F Facility: these 11 bits define a facility code that indicates the source of the error

Programs that return an HRESULT error code usually set the least significant 16 bits (i.e., bits from 15 to 0) to the Win32 error code representing the error.

If the N bit is set, the error is to be interpreted as an NTSTATUS error code after clearing the bit.

NTSTATUS Error Codes

NTSTATUS error codes are also 32 bits in size, but the S (Severity) and F (Facility) bits are one bit longer than in HRESULT error codes.

Microsoft defines the 32 bits of an NTSTATUS error code using the following bit pattern table:

31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 to 0
S S C N F F F F F F F F F F F F Remainder of error code

The letters in the bit positions represent the following:

Bit Description
S Severity: These two bits indicate the error's severity (see below)
C Customer: 0 if this error code is Microsoft-defined, or 1 if customer-defined
N NTSTATUS: Always 0
F Facility: These 12 bits define a facility code that indicates the source of the error

The S bits can be interpreted as an integer value as follows:

31 30 Value Description
0 0 0 Success
0 1 1 Informational
1 0 2 Warning
1 1 3 Error

As with HRESULT error codes, the remaining 16 bits (15 to 0) are the remainder of the error code.

Sample Error Code

Let's consider the error code -2147024843.

If you open the Windows calculator program, switch to Programmer mode, select DWORD bit width, and enable the bit toggling keypad, you can paste in this value and view the bit pattern. The bits will match the pattern in the following bit pattern table:

31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
1 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 0 0 0 0 0 0 0 0 0 1 1 1 0 0 1

We can analyze this bit pattern as follows:

  • Error code type (WIN32, NTSTATUS, or HRESULT): The error code has one or more bits set in positions 31 to 16, so this is not a Win32 error code. In addition, the bit in position 28 is zero, so we can interpret the error code as an HRESULT error code.
  • Error severity: The bit in position 31 is set, so this indicates a failure.
  • Microsoft-defined or customer-defined: The bit in position 29 is zero, so this is a Micrsoft-defined error code.
  • Facility code: If we interpret bits 26-16 as a decimal value, we get a facility code of 7.
  • Remainder of error code: The final 16 bits of the error code are a Win32 error code that evaluate to the decimal value 53 (35 hex).

The localized error message string (in U.S. English) associated with this error code is The network path was not found.

Example ErrInfo Commands

This section provides examples of how to use the ErrInfo utility.

  1. ErrInfo -n -2147024843

    This command assumes the -v parameter and outputs details about the error code. The -n parameter is required because the error code is a negative value. Note that the message string will be localized to the current user's language settings:

    pascal
    Type     : HRESULT
Bin      : 1000 0000 0000 0111 0000 0000 0011 0101
Hex      : 0x80070035
Dec      : 2147942453
Signed   : -2147024843
Severity : Failure
Source   : Microsoft-defined
Facility : 7
Message  : The network path was not found.

    ErrInfo outputs the error code's numeric value in four different formats (binary, hexadecimal, unsigned decimal, and signed decimal) for reference.

  2. ErrInfo 1326

    This command produces the following output:

    pascal
    Type     : Win32
Bin      : 0000 0101 0010 1110
Hex      : 0x052E
Dec      : 1326
Signed   : 1326
Message  : The user name or password is incorrect.

  3. ErrInfo -m 5

    This command outputs the message string for error code 5. In U.S. English, the output is:

    pascal
    Access is denied.

  4. ErrInfo -v -t NTSTATUS -n 0xC0000043

    This command outputs details of the specified error code as an NTSTATUS error:

    pascal
    Type     : NTSTATUS
Bin      : 1100 0000 0000 0000 0000 0000 0100 0011
Hex      : 0xC0000043
Dec      : 3221225539
Signed   : -1073741757
Severity : Error
Source   : Microsoft-defined
Facility : 0
Message  : A file cannot be opened because the share access flags are incompatible.

  5. ErrInfo -t Win32 0x80070056

    This command produces the following output:

    pascal
    Type     : Win32
Bin      : 0000 0000 0101 0110
Hex      : 0x0056
Dec      : 86
Signed   : 86
Message  : The specified network password is not correct.

    The -t option tells ErrInfo to ignore the most significant 16 bits of the error code (i.e., 0x8007) and output it as a Win32 error.

  6. ErrInfo -f 0x80070005

    This command requests the facility code for the error and outputs the following:

    pascal
    Facility code for error code 0x80070005 = 7 (0x007)

    ErrInfo exits with exit code 7 to match the facility code (see Exit Codes, above).

  7. ErrInfo -m 990

    As of this writing, 990 is not Win32 error code, so this command outputs the following (U.S. English):

    pascal
    990 is not a valid Windows network message number. [3871]

    In addition, ErrInfo exits with error code 3871 (see Exit Codes, above).

  8. ErrInfo 0xD000014B

    This command produces the following output:

    pascal
    Type : HRESULT with "N" bit set
Bin  : 1101 0000 0000 0000 0000 0001 0100 1011
Hex  : 0xD000014B
    pascal
    Type     : NTSTATUS
Bin      : 1100 0000 0000 0000 0000 0001 0100 1011
Hex      : 0xC000014B
Dec      : 3221225803
Signed   : -1073741493
Severity : Error
Source   : Microsoft-defined
Facility : 0
Message  : The pipe operation has failed because the other end of the pipe has been closed.

    There are two numeric values in this output because the N bit is set (see HRESULT Error Codes, above). ErrInfo first outputs the HRESULT error code, then it clears the N bit (i.e., the fourth bit from the left in the binary output) and outputs the error as an NTSTATUS code.