StartHeapTrace

  • [アーティクル]

この関数は、指定された一連の PID のヒープ トレース セッションを登録して開始します。 この関数を使用して、割り当てや削除などの特定のヒープ イベントに対してスタックのウォーキングを有効にすることもできます。

この関数を呼び出す前に、ヒープ トレースを有効にするプロセスを作成する必要があります。 プログラムの最初からヒープ イベントをキャプチャするには、プロセスを CREATE_SUSPENDED フラグで開始してから、PID に対してヒープ トレースを有効にし、プロセスを再開することをお勧めします。

ヒープ トレースは非常に詳細であり、非常に大きなトレース ファイルをすばやく生成できます。 セッションのバッファーが小さすぎたり、少なすぎると、イベントが簡単に失われる可能性があります。 イベントを失わないようにするには、ヒープ トレースが有効になっているプロセスの数を制限することをお勧めします。 ヒープ トレースを有効にすると、トレースされるプロセスにパフォーマンスが影響を与える可能性があります。

ULONG
WINAPI
StartHeapTrace(
    _Out_ PTRACEHANDLE TraceHandle,
    _Inout_ PEVENT_TRACE_PROPERTIES Properties,
    _In_z_ LPCWSTR wszSessionName,
    _In_reads_opt_(cPids) const ULONG Pids[],
    _In_  ULONG cPids,
    _In_reads_opt_(cStackTracingEventIds) const STACK_TRACING_EVENT_ID StackTracingEventIds[],
    _In_  ULONG cStackTracingEventIds
    );

パラメーター

TraceHandle [out]
イベント トレース セッションへのハンドルを格納します。 ハンドルが無効な場合、このパラメーターは 0 に設定されます。 このパラメーターは、INVALID_HANDLE_VALUE と比較する事はできません。 関数が失敗した場合は、このハンドルを使用しないでください。

Properties [in, out]
EVENT_TRACE_PROPERTIES 構造体へのポインターを格納します。 EVENT_TRACE_PROPERTIESは、セッション動作の特定の側面を構成します。

この関数では常に独自の値が使用されるので、Guid メンバーを設定する必要はありません。 GUID を指定した場合は使用されません。

wszSessionName [in]
StartTrace に渡すセッション名。

Pids [in]
ヒープ トレースを有効にするプロセス ID の配列。

cPids [in]
Pids 配列のサイズ。

cStackTracingEventIds [in]
StackTracingEventIds 配列のサイズ。

戻り値

ERROR_SUCCESS は成功を示します。

次の表に、このオプションでエラーの可能性な値を示します。

エラー値 説明

ERROR_ALREADY_EXISTS

システム上で実行されるカーネル ロガーのインスタンスは 1 つのみです。 別のコンポーネントがカーネル ログを開始した後にこの関数を開始しようとすると、このエラーが返される可能性があります。

ERROR_INVALID_FLAGS

Properties.EnableFlagsに無効なトレース フラグが含まれている可能性があります。

ERROR_OUT_OF_MEMORY

EVENT_TRACE_PROPERTIES に対してメモリの割り当てに失敗した可能性があります。

一覧以外の理由で失敗した場合は、システム エラー コードが返されます。

解説

なし

関数

UpdateHeapTrace