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.