RtlStringCbPrintfA - NtDoc

#ifndef _NTSTRSAFE_H_INCLUDED_
#ifndef NTSTRSAFE_LIB_IMPL
#ifndef _M_CEE_PURE
#ifndef NTSTRSAFE_NO_CB_FUNCTIONS

/*++

  NTSTATUS
  RtlStringCbPrintf(
  _Out_writes_bytes_(cbDest) _Always_(_Post_z_) LPTSTR  pszDest,
  _In_ size_t  cbDest,
  _In_ _Printf_format_string_ LPCTSTR pszFormat,
  ...
  );

  Routine Description:

  This routine is a safer version of the C built-in function 'sprintf'.
  The size of the destination buffer (in bytes) is a parameter and
  this function will not write past the end of this buffer and it will
  ALWAYS null terminate the destination buffer (unless it is zero length).

  This function returns an NTSTATUS value, and not a pointer.  It returns
  STATUS_SUCCESS if the string was printed without truncation and null terminated,
  otherwise it will return a failure code. In failure cases it will return
  a truncated version of the ideal result.

Arguments:

pszDest     -  destination string

cbDest      -  size of destination buffer in bytes
length must be sufficient to hold the resulting formatted
string, including the null terminator.

pszFormat   -  format string which must be null terminated

...         -  additional parameters to be formatted according to
the format string

Notes:
Behavior is undefined if destination, format strings or any arguments
strings overlap.

pszDest and pszFormat should not be NULL.  See RtlStringCbPrintfEx if you
require the handling of NULL values.


Return Value:

STATUS_SUCCESS -   if there was sufficient space in the dest buffer for
the resultant string and it was null terminated.

failure        -   you can use the macro NTSTATUS_CODE() to get a win32
error code for all hresult failure cases

STATUS_BUFFER_OVERFLOW /
NTSTATUS_CODE(status) == ERROR_INSUFFICIENT_BUFFER
-   this return value is an indication that the print
operation failed due to insufficient space. When this
error occurs, the destination buffer is modified to
contain a truncated version of the ideal result and is
null terminated. This is useful for situations where
truncation is ok.

It is strongly recommended to use the NT_SUCCESS() macro to test the
return value of this function

--*/


NTSTRSAFEDDI
    RtlStringCbPrintfA(
            _Out_writes_bytes_(cbDest) _Always_(_Post_z_) NTSTRSAFE_PSTR pszDest,
            _In_ size_t cbDest,
            _In_ _Printf_format_string_ NTSTRSAFE_PCSTR pszFormat,
            ...)
{
    NTSTATUS status;
    size_t cchDest = cbDest / sizeof(char);

    status = RtlStringValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH);

    if (NT_SUCCESS(status))
    {
        va_list argList;

        va_start(argList, pszFormat);

        status = RtlStringVPrintfWorkerA(pszDest,
                cchDest,
                NULL,
                pszFormat,
                argList);

        va_end(argList);
    }
    else if (cchDest > 0)
    {
        *pszDest = '\0';
    }

    return status;
}

#endif
#endif
#endif
#endif
View code on GitHub