RtlStringCbLengthW function (ntstrsafe.h)

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


  [in] size_t          cbMax,
       size_t          *pcbLength


[in] psz

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

[in] cbMax

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).


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
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.
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.


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.


Minimum supported client Available in Windows XP with Service Pack 1 (SP1) and later versions of Windows.
Target Platform Desktop
Header ntstrsafe.h (include Ntstrsafe.h)
Library Ntstrsafe.lib

See also