RtlStringCbCatA - NtDoc

#ifndef _NTSTRSAFE_H_INCLUDED_
#ifndef NTSTRSAFE_LIB_IMPL
#ifndef NTSTRSAFE_NO_CB_FUNCTIONS

/*++

  NTSTATUS
  RtlStringCbCat(
  _Inout_updates_bytes_(cbDest) _Always_(_Post_z_) LPTSTR  pszDest,
  _In_     size_t  cbDest,
  _In_     LPCTSTR pszSrc
  );

  Routine Description:

  This routine is a safer version of the C built-in function 'strcat'.
  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 concatenated without truncation and null terminated,
  otherwise it will return a failure code. In failure cases as much of pszSrc
  will be appended to pszDest as possible, and pszDest will be null
  terminated.

Arguments:

pszDest     -  destination string which must be null terminated

cbDest      -  size of destination buffer in bytes.
length must be = ((_tcslen(pszDest) + _tcslen(pszSrc) + 1) * sizeof(TCHAR)
to hold all of the combine string plus the null
terminator

pszSrc      -  source string which must be null terminated

Notes:
Behavior is undefined if source and destination strings overlap.

pszDest and pszSrc should not be NULL.  See RtlStringCbCatEx if you require
the handling of NULL values.

Return Value:

STATUS_SUCCESS -   if there was source data and it was all concatenated and
the resultant dest string 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 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
    RtlStringCbCatA(
            _Inout_updates_bytes_(cbDest) _Always_(_Post_z_) NTSTRSAFE_PSTR pszDest,
            _In_ size_t cbDest,
            _In_ NTSTRSAFE_PCSTR pszSrc)
{
    NTSTATUS status;
    size_t cchDestLength;
    size_t cchDest = cbDest / sizeof(char);

    status = RtlStringValidateDestAndLengthA(pszDest,
            cchDest,
            &cchDestLength,
            NTSTRSAFE_MAX_CCH);

    if (NT_SUCCESS(status))
    {
        status = RtlStringCopyWorkerA(pszDest + cchDestLength,
                cchDest - cchDestLength,
                NULL,
                pszSrc,
                NTSTRSAFE_MAX_LENGTH);
    }

    return status;
}

#endif
#endif
#endif
View code on GitHub