RtlStringCchCopyA - NtDoc

#ifndef _NTSTRSAFE_H_INCLUDED_
#ifndef NTSTRSAFE_LIB_IMPL
#ifndef NTSTRSAFE_NO_CCH_FUNCTIONS

/*++

  NTSTATUS
  RtlStringCchCopy(
  _Out_writes_(cchDest) _Always_(_Post_z_) LPTSTR  pszDest,
  _In_  size_t  cchDest,
  _In_  LPCTSTR pszSrc
  );

  Routine Description:

  This routine is a safer version of the C built-in function 'strcpy'.
  The size of the destination buffer (in characters) 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 routine is not a replacement for strncpy.  That function will pad the
  destination string with extra null termination characters if the count is
  greater than the length of the source string, and it will fail to null
  terminate the destination string if the source string length is greater
  than or equal to the count. You can not blindly use this instead of strncpy:
  it is common for code to use it to "patch" strings and you would introduce
  errors if the code started null terminating in the middle of the string.

  This function returns an NTSTATUS value, and not a pointer.  It returns
  STATUS_SUCCESS if the string was copied without truncation and null terminated,
  otherwise it will return a failure code. In failure cases as much of
  pszSrc will be copied to pszDest as possible, and pszDest will be null
  terminated.

Arguments:

pszDest        -   destination string

cchDest        -   size of destination buffer in characters.
length must be = (_tcslen(src) + 1) to hold all of the
source including 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 RtlStringCchCopyEx if you require
the handling of NULL values.

Return Value:

STATUS_SUCCESS -   if there was source data and it was all copied 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 copy
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
    RtlStringCchCopyA(
            _Out_writes_(cchDest) _Always_(_Post_z_) NTSTRSAFE_PSTR pszDest,
            _In_ size_t cchDest,
            _In_ NTSTRSAFE_PCSTR pszSrc)
{
    NTSTATUS status;

    status = RtlStringValidateDestA(pszDest, cchDest, NTSTRSAFE_MAX_CCH);

    if (NT_SUCCESS(status))
    {
        status = RtlStringCopyWorkerA(pszDest,
                cchDest,
                NULL,
                pszSrc,
                NTSTRSAFE_MAX_LENGTH);
    }
    else if (cchDest > 0)
    {
        *pszDest = '\0';
    }

    return status;
}

#endif
#endif
#endif
View code on GitHub