I've been modifying some code written by a previous employee and came across a function with the following signature:

BOOL WINAPI PrependPadding(
    _In_ SIZE_T cbPadding,
    _In_ SIZE_T cbRow,
    _Out_writes_bytes_(cbPadding) _On_failure_(_Post_null_) BYTE *bRow

For those of you unfamiliar with Microsoft's SAL annotation meta-language, the annotations on this function basically state that should the function fail for whatever reason, the pointer bRow will be NULL after execution of this function.

I find this interesting because it enforces that the caller must check the return value for success/failure - if you try and do anything with bRow after this function fails, it will obviously crash.

However, is this generally a good practice? I've never seen this used before and I'm wondering if it's for a reason.

  • Is this a complete function signature? I would expect success criteria to be specified (e.g. _Success_(return != FALSE)) and I'm not sure it makes sense to specify bRow will be set to null when it is a pointer? Would make more sense (if it was BYTE **?) – Steve Oct 20 '17 at 21:09

Indicating failures by means of the return value is entirely normal in C, especially as there is no real good alternative for reporting errors.

On the other hand, setting an out-parameter to NULL is far less common and the validity of that would depend, in my opinion, on who is responsible for providing the memory.

If the caller of PrependPadding is supposed to provide a large enough buffer as the bRow parameter, then I would find it very strange if the function could change that to a NULL pointer. That would make it easy to introduce a memory leak by taking away what could be my only reference to that memory block.
If, on the other hand, PrependPadding is responsible for allocating the memory that bRow refers to after the function returns, then it would be fairly natural to have bRow be a NULL pointer in the case of a failure.


Except for setjmp()/longjmp(), C doesn't provide a built in exception handling mechanism. Indicating errors in return values is by far the most common way of handling errors in C.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.