RtlStringCbLengthA - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers 
#ifndef _NTSTRSAFE_H_INCLUDED_
#ifndef NTSTRSAFE_LIB_IMPL
#ifndef NTSTRSAFE_NO_CB_FUNCTIONS

/*++

  NTSTATUS
  RtlStringCbLength(
  _In_reads_or_z_(cbMax) LPCTSTR psz,
  _In_ _In_range_(1, NTSTRSAFE_MAX_CCH * sizeof(TCHAR)) size_t  cbMax,
  _Out_opt_ _Deref_out_range_(<, cbMax) size_t* pcbLength   OPTIONAL
  );

  Routine Description:

  This routine is a safer version of the C built-in function 'strlen'.
  It is used to make sure a string is not larger than a given length, and
  it optionally returns the current length in bytes not including
  the null terminator.

  This function returns an NTSTATUS value, and not a pointer.  It returns
  STATUS_SUCCESS if the string is non-null and the length including the null
  terminator is less than or equal to cbMax bytes.

Arguments:

psz         -   string to check the length of

cbMax       -   maximum number of bytes including the null terminator
that psz is allowed to contain

pcb         -   if the function succeeds and pcb is non-null, the current length
in bytes of psz excluding the null terminator will be returned.
This out parameter is equivalent to the return value of strlen(psz) * sizeof(TCHAR)

Notes:
psz can be null but the function will fail

cbMax should be greater than or equal to sizeof(TCHAR) or the function will fail

Return Value:

STATUS_SUCCESS -   psz is non-null and the length including the null
terminator is less than or equal to cbMax bytes

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

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

--*/


_Must_inspect_result_
NTSTRSAFEDDI
    RtlStringCbLengthA(
            _In_reads_or_z_(cbMax) STRSAFE_PCNZCH psz,
            _In_ _In_range_(1, NTSTRSAFE_MAX_CCH * sizeof(char)) size_t cbMax,
            _Out_opt_ _Deref_out_range_(<, cbMax) size_t* pcbLength)
{
    NTSTATUS status;
    size_t cchMax = cbMax / sizeof(char);
    size_t cchLength = 0;

    if ((psz == NULL) || (cchMax > NTSTRSAFE_MAX_CCH))
    {
        status = STATUS_INVALID_PARAMETER;
    }
    else
    {
        status = RtlStringLengthWorkerA(psz, cchMax, &cchLength);
    }

    if (pcbLength)
    {
        if (NT_SUCCESS(status))
        {
            // safe to multiply cchLength * sizeof(char) since cchLength < NTSTRSAFE_MAX_CCH and sizeof(char) is 1
            *pcbLength = cchLength * sizeof(char);
        }
        else
        {
            *pcbLength = 0;
        }
    }

    return status;
}

#endif
#endif
#endif

View code on GitHub
// ntstrsafe.h

NTSTRSAFEDDI RtlStringCbLengthA(
  [in] STRSAFE_PCNZCH psz,
  [in] size_t         cbMax,
       size_t         *pcbLength
);
View the official Windows Driver Kit DDI reference

NtDoc

No description available.

Edit description on GitHub

Windows Driver Kit DDI reference (nf-ntstrsafe-rtlstringcblengtha)

RtlStringCbLengthA function

Description

The RtlStringCbLengthW and RtlStringCbLengthA functions determine the length, in bytes, of a supplied string.

Parameters

psz [in]

A pointer to a buffer that contains a null-terminated string, the length of which will be checked.

cbMax [in]

The maximum number of bytes allowed in the buffer that is pointed to by psz, including the terminating null character.

For Unicode strings, the maximum number of bytes is NTSTRSAFE_MAX_CCH * sizeof(WCHAR).

For ANSI strings, the maximum number of bytes is NTSTRSAFE_MAX_CCH * sizeof(char).

pcbLength

If the caller supplies a non-NULL address pointer, the function loads the address with the length, in bytes, of the string that is contained in the buffer. The length does not include the string's terminating null character.

Return value

The function returns one of the NTSTATUS values that are listed in the following table. For information about how to test NTSTATUS values, see Using NTSTATUS Values.

Return code Description
STATUS_SUCCESS This success status means the string at psz was not NULL, and the length of the string (including the terminating null character) is less than or equal to cbMax characters.
STATUS_INVALID_PARAMETER This error status means the value in psz is NULL, cbMax is larger than NTSTRSAFE_MAX_CCH * sizeof(TCHAR), or psz is longer than cbMax.

Remarks

RtlStringCbLengthW and RtlStringCbLengthA should be used instead of strlen. Use these functions to ensure that a string is not larger than a given length, in bytes. If that condition is met, RtlStringCbLengthW and RtlStringCbLengthA return the current length of the string in bytes, not including those bytes used for the terminating null character.

Use RtlStringCbLengthW to handle Unicode strings and RtlStringCbLengthA to handle ANSI strings. The form you use depends on your data, as shown in the following table.

String data type String literal Function
WCHAR L"string" RtlStringCbLengthW
char "string" RtlStringCbLengthA

For more information about the safe string functions, see Using Safe String Functions.

See also

RtlStringCchLength

View the official Windows Driver Kit DDI reference

Edit description on GitHub