RtlUnalignedStringCbLengthW - 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
RtlUnalignedStringCbLength(
_In_reads_or_z_(cbMax) LPCUTSTR 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 version of RtlStringCbLength that accepts an unaligned string pointer.
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.
--*/
#ifdef ALIGNMENT_MACHINE
_Must_inspect_result_
NTSTRSAFEDDI
RtlUnalignedStringCbLengthW(
_In_reads_or_z_(cbMax / sizeof(wchar_t)) STRSAFE_PCUNZWCH psz,
_In_ _In_range_(1, NTSTRSAFE_MAX_CCH * sizeof(wchar_t)) size_t cbMax,
_Out_opt_ _Deref_out_range_(<, cbMax - 1) size_t* pcbLength)
{
NTSTATUS status;
size_t cchMax = cbMax / sizeof(wchar_t);
size_t cchLength = 0;
if ((psz == NULL) || (cchMax > NTSTRSAFE_MAX_CCH))
{
status = STATUS_INVALID_PARAMETER;
}
else
{
status = RtlUnalignedStringLengthWorkerW(psz, cchMax, &cchLength);
}
if (pcbLength)
{
if (NT_SUCCESS(status))
{
// safe to multiply cchLength * sizeof(wchar_t) since cchLength < NTSTRSAFE_MAX_CCH and sizeof(wchar_t) is 2
*pcbLength = cchLength * sizeof(wchar_t);
}
else
{
*pcbLength = 0;
}
}
return status;
}
View code on GitHub#ifndef _NTSTRSAFE_H_INCLUDED_
#ifndef NTSTRSAFE_LIB_IMPL
#ifndef NTSTRSAFE_NO_CB_FUNCTIONS
/*++
NTSTATUS
RtlUnalignedStringCbLength(
_In_reads_or_z_(cbMax) LPCUTSTR 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 version of RtlStringCbLength that accepts an unaligned string pointer.
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.
--*/
#ifdef ALIGNMENT_MACHINE
// ...
#else
#define RtlUnalignedStringCbLengthW RtlStringCbLengthW
View code on GitHub// ntstrsafe.h
NTSTRSAFEDDI RtlUnalignedStringCbLengthW(
[in] STRSAFE_PCUNZWCH psz,
[in] size_t cbMax,
[out, optional] size_t *pcbLength
);
View the official Windows Driver Kit DDI referenceNo description available.
The RtlUnalignedStringCbLengthW function is a version of the RtlStringCbLength function that accepts an unaligned pointer to a string of Unicode characters.
psz [in]Supplies a pointer to a buffer that contains a null-terminated string whose length RtlUnalignedStringCbLengthW will check.
cbMax [in]Supplies the maximum number of bytes that are allowed in the buffer that psz points to, including the terminating NULL character. This value cannot exceed NTSTRSAFE_MAX_CCH * sizeof(WCHAR).
pcbLength [out, optional]Optional. 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 that psz points to. The length does not include the string's terminating NULL character.
RtlUnalignedStringCbLengthW returns one of the following NTSTATUS values.
| Return code | Description |
|---|---|
| STATUS_SUCCESS | This success status means the string that the psz parameter specified was not NULL, and the length of the string (including the terminating NULL character) was less than or equal to cbMax bytes. |
| STATUS_INVALID_PARAMETER | This error status means the value in psz is NULL, cbMax is larger than NTSTRSAFE_MAX_CCH * sizeof(WCHAR, or psz is longer than cbMax. |
For information about how to test NTSTATUS values, see Using NTSTATUS Values.
The RtlUnalignedStringCbLengthW function is available for processor architectures, such as Itanium-based and x64-based, that cause alignment exceptions when software attempts to access unaligned data. On those processors, you can use RtlUnalignedStringCbLengthW instead of the RtlStringCbLength function to avoid alignment exceptions. (For processors that do not cause alignment exceptions, RtlUnalignedStringCbLengthW is equivalent to RtlStringCbLength.)
For more information about the safe string functions, see Using Safe String Functions.