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

__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.


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.]


__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.

Tags:

C

Driver

Wdk