_Deref_ and _Outptr_ sal annotations

Question

What is the difference between the Deref and Outptr SAL annotations? Also when do you use the different types of Outptr annotation like _Outptr_result_buffer_all_ and _Outptr_result_buffer_?

Answer 1

SAL is poorly documented. You need to look at the sal.h file.

What is the difference between the Deref and Outptr SAL annotations

They are the same, except that the Deref annotations are from SAL 1 and Outptr is from SAL 2 (which can express more). So Deref is deprecated.

Also when do you use the different types of Outptr annotation like _Outptr_result_buffer_all_ and _Outptr_result_buffer_?

Quoting from sal.h:

Outptr: Returned variable is a pointer type (so param is pointer-to-pointer type). Called function provides/allocated space.

Looking at the source, _Outptr_result_buffer_ and _Outptr_result_buffer_all_ are almost the same. You supply as parameter the number of elements which will be allocated (if it is exactly one element, use _Outptr_). The difference is that the former means that the elements are writeable by the caller (implicitly they are also readable), while the latter means that the elements are only readable.

Looking at the C runtime sources, only _Outptr_result_buffer_ is used in very few places, ex. for the buffer created in _dupenv_s:

_Check_return_opt_ _CRTIMP errno_t __cdecl _dupenv_s(
    Outptr_result_buffer_maybenull_(*_PBufferSizeInBytes) _Outptr_result_z_ char **_PBuffer,
    _Out_opt_ size_t * _PBufferSizeInBytes,
    _In_z_ const char * _VarName);

So this function creates a (null-terminated) buffer in _PBuffer. The size of the buffer is found in *_PBufferSizeInBytes.