How to understand the "NTSTATUS", "NT_SUCCESS" typedef in windows ddk?

Question

Two questions:

1.

In "ntdef.h" the NTSTATUS is defined as follow:

typedef __success(return >= 0) LONG NTSTATUS;

what the hell is the "__success(return >= 0)"?

2.

In "ntstatus.h", STATUS_SUCCESS is defined to 0.

#define STATUS_SUCCESS   ((NTSTATUS)0x00000000L) // ntsubauth

But the NT_SUCCESS macro in "ntdef.h" is:

#define NT_SUCCESS(Status) (((NTSTATUS)(Status)) >= 0)

Shouldn't it be "Status == 0" ?

Solution 1

__success is an "Advanced Annotation" defined in SpecStrings_strict.h, which defines it as follows.

*  __success(expr) T f() :  indicates whether function f succeeded or
*  not. If  is true at exit, all the function's guarantees (as given
*  by other annotations) must hold. If  is false at exit, the caller
*  should not expect any of the function's guarantees to hold. If not used,
*  the function must always satisfy its guarantees. Added automatically to
*  functions that indicate success in standard ways, such as by returning an
*  HRESULT.

The reason that NT_SUCCESS doesn't do a strict test against STATUS_SUCCESS (0) is probably that other codes like STATUS_PENDING aren't actually failures.

Solution 2

The fragment __success(return >= 0) is a SAL annotation, which gives a clue to the PreFast tool about what the intended semantics of the macro are. This is used to do static analysis and identify potential bugs.

The NT_SUCCESS macro tests for >= 0 because there are success codes other than STATUS_SUCCESS. Some success codes include extra information about the outcome of the operation, although at the moment I can only think of S_FALSE, which notifies the caller that the operation succeeded, but the result was false. As a rule, success codes are equal to or greater than zero, and failure codes are less than zero.

[Strictly speaking, S_FALSE is an HRESULT, not an NT_STATUS, though the two types have the same size and similar conventions.]

Solution 3

__success is described nicely in Annotating for __success() article by Michael Fourre (archived link).

Answer to 2 is No, all positive codes are non-failures. They may mean something other than OK though.