RtlInitString - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers 
#ifndef _NTRTL_H
#ifndef PHNT_NO_INLINE_INIT_STRING

FORCEINLINE
VOID
NTAPI_INLINE
RtlInitString(
    _Out_ PSTRING DestinationString,
    _In_opt_z_ PCSTR SourceString
    )
{
    if (SourceString)
        DestinationString->MaximumLength = (DestinationString->Length = (USHORT)strlen(SourceString)) + sizeof(ANSI_NULL);
    else
        DestinationString->MaximumLength = DestinationString->Length = 0;

    DestinationString->Buffer = (PCHAR)SourceString;
}

#endif
#endif

View code on GitHub
#ifndef _NTRTL_H
#ifndef PHNT_NO_INLINE_INIT_STRING
// ...
#else

NTSYSAPI
VOID
NTAPI
RtlInitString(
    _Out_ PSTRING DestinationString,
    _In_opt_z_ PCSTR SourceString
    );

#endif
#endif

View code on GitHub
// wdm.h

NTSYSAPI VOID RtlInitString(
  [out]          PSTRING               DestinationString,
  [in, optional] __drv_aliasesMem PCSZ SourceString
);
View the official Windows Driver Kit DDI reference
// winternl.h

VOID RtlInitString(
  [in, out] PSTRING DestinationString,
  [in]      PCSZ    SourceString
);
View the official Win32 API reference

NtDoc

This function is documented in Windows Driver Kit.

Edit description on GitHub

Windows Driver Kit DDI reference (nf-wdm-rtlinitstring)

Description

The RtlInitString routine initializes a counted string of 8-bit characters.

Parameters

DestinationString [out]

A pointer to the STRING structure to be initialized. The Ntdef.h header file defines this structure to be identical to the ANSI_STRING structure.

SourceString [in, optional]

A pointer to a null-terminated character string. This string is used to initialize the counted string pointed to by DestinationString.

Return value

Remarks

This routine initializes a counted character string.

The routine copies the SourceString pointer value to the Buffer member of the STRING structure pointed to by DestinationString. The Length member of this structure is set to the length, in bytes, of the source string, excluding the terminating null. The MaximumLength member of the structure is set to the length, in bytes, of the source string, including the terminating null. If SourceString is NULL, Length and MaximumLength are both set to zero.

RtlInitString does not alter the source string pointed to by SourceString.

If the source string is longer than MAXUSHORT - 1 bytes, RtlInitString sets the Length member of the STRING structure pointed to by DestinationString to MAXUSHORT - 1, and sets the MaximumLength member of this structure to MAXUSHORT. In this case, the Length and MaximumLength values misrepresent the length of the null-terminated source string, and relying on the accuracy of these values is potentially dangerous.

Callers of RtlInitString can be running at IRQL <= DISPATCH_LEVEL if the DestinationString buffer is nonpageable. Usually, callers run at IRQL = PASSIVE_LEVEL because most other RtlXxxString routines cannot be called at IRQL > PASSIVE_LEVEL.

The RTL_CONSTANT_STRING macro creates a string or Unicode string structure to hold a counted string.

STRING RTL_CONSTANT_STRING(
  [in]  PCSZ SourceString
);

UNICODE_STRING RTL_CONSTANT_STRING(
  [in]  PCWSTR SourceString
);

RTL_CONSTANT_STRING returns either a string structure or Unicode string structure.

The RTL_CONSTANT_STRING macro replaces the RtlInitAnsiString, RtlInitString, and RtlInitUnicodeString routines when passing a constant string.

You can use RTL_CONSTANT_STRING to initialize global variables.

See also

ANSI_STRING

View the official Windows Driver Kit DDI reference

Edit description on GitHub

Win32 API reference (nf-winternl-rtlinitstring)

RtlInitString function

Description

Initializes a counted string.

Parameters

DestinationString [in, out]

The counted string to be initialized. The DestinationString is initialized to point to the SourceString. The Length and MaximumLength fields of the DestinationString are initialized to the length of the SourceString.

SourceString [in]

A pointer to a null-terminated string. If the SourceString is not specified, the Length and MaximumLength fields of the DestinationString are initialized to zero.

Remarks

Security Warning: Do not allow the SourceString parameter size to exceed MAX_USHORT characters.

Because there is no import library for this function, you must use GetProcAddress.

Note RtlInitString is available in Windows XP. It might be altered or unavailable in subsequent versions.

View the official Win32 API reference

Edit description on GitHub