Share via

HeapSetInformation 関数 (heapapi.h)

  • [アーティクル]

指定したヒープの機能を有効にします。

構文

BOOL HeapSetInformation(
  [in, optional] HANDLE                 HeapHandle,
  [in]           HEAP_INFORMATION_CLASS HeapInformationClass,
  [in]           PVOID                  HeapInformation,
  [in]           SIZE_T                 HeapInformationLength
);

パラメーター

[in, optional] HeapHandle

情報を設定するヒープへのハンドル。 このハンドルは、 HeapCreate 関数または GetProcessHeap 関数によって返されます。

[in] HeapInformationClass

設定する情報のクラス。 このパラメーターには、 HEAP_INFORMATION_CLASS 列挙型の次のいずれかの値を指定できます。

値 意味
HeapCompatibilityInformation
0
 ヒープ機能を有効にします。 低断片化ヒープ (LFH) のみがサポートされています。 ただし、システムは必要に応じて LFH を使用してメモリ割り当て要求をサービスするため、アプリケーションで LFH を有効にする必要はありません。

Windows XP および Windows Server 2003: LFH は既定では有効になっていません。 指定したヒープに対して LFH を有効にするには、 HeapInformation パラメーターが指す変数を 2 に設定します。 ヒープに対して LFH を有効にすると、無効にすることはできません。

LFH は、HEAP_NO_SERIALIZEで作成されたヒープまたは固定サイズで作成されたヒープでは有効にできません。 LFH は、 Windows 用デバッグ ツール または Microsoft アプリケーション検証ツールのヒープ デバッグ ツールを使用している場合にも有効にできません。

プロセスがデバッガーで実行されると、プロセス内のすべてのヒープに対して特定のヒープ デバッグ オプションが自動的に有効になります。 これらのヒープ デバッグ オプションを使用すると、LFH が使用できなくなります。 デバッガーで実行するときに断片化の少ないヒープを有効にするには、_NO_DEBUG_HEAP環境変数を 1 に設定します。
HeapEnableTerminationOnCorruption
1
 破損時の終了機能を有効にします。 ヒープ マネージャーは、プロセスで使用されているヒープ内のエラーを検出すると、Windows エラー報告 サービスを呼び出してプロセスを終了します。

プロセスでこの機能を有効にした後は、無効にすることはできません。

Windows Server 2003 および Windows XP: この値は、Windows Vista および Windows XP と SP3 までサポートされません。 関数は成功しますが、 HeapEnableTerminationOnCorruption 値は無視されます。
HeapOptimizeResources
3
 HeapSetInformation が HeapHandle を NULL に設定して呼び出された場合、 低断片化ヒープ (LFH) を持つプロセス内のすべてのヒープはキャッシュが最適化され、可能であればメモリはコミット解除されます。

HeapHandle でヒープ ポインターが指定されている場合、そのヒープのみが最適化されます。

HeapInformation で渡されるHEAP_OPTIMIZE_RESOURCES_INFORMATION構造体は適切に初期化する必要があることに注意してください。

メモこの値は、Windows 8.1で追加されました。

[in] HeapInformation

ヒープ情報バッファー。 このデータの形式は、 HeapInformationClass パラメーターの値によって異なります。

HeapInformationClass パラメーターが HeapCompatibilityInformation の場合、HeapInformation パラメーターは ULONG 変数へのポインターです。

HeapInformationClass パラメーターが HeapEnableTerminationOnCorruption の場合、HeapInformation パラメーターは NULL、HeapInformationLength は 0 にする必要があります

[in] HeapInformationLength

HeapInformation バッファーのサイズ (バイト単位)。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

ヒープの現在の設定を取得するには、 HeapQueryInformation 関数を使用します。

HeapEnableTerminateOnCorruption オプションを設定することを強くお勧めします。これは、破損したヒープを利用するセキュリティ上の悪用に対するアプリケーションの露出を減らすためです。

例

次の例では、断片化の少ないヒープを有効にする方法を示します。

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

#define HEAP_LFH 2

int __cdecl _tmain()
{
    BOOL bResult;
    HANDLE hHeap;
    ULONG HeapInformation;

    //
    // Enable heap terminate-on-corruption. 
    // A correct application can continue to run even if this call fails, 
    // so it is safe to ignore the return value and call the function as follows:
    // (void)HeapSetInformation(NULL, HeapEnableTerminationOnCorruption, NULL, 0);
    // If the application requires heap terminate-on-corruption to be enabled, 
    // check the return value and exit on failure as shown in this example.
    //
    bResult = HeapSetInformation(NULL,
                                 HeapEnableTerminationOnCorruption,
                                 NULL,
                                 0);

    if (bResult != FALSE) {
        _tprintf(TEXT("Heap terminate-on-corruption has been enabled.\n"));
    }
    else {
        _tprintf(TEXT("Failed to enable heap terminate-on-corruption with LastError %d.\n"),
                 GetLastError());
        return 1;
    }

    //
    // Create a new heap with default parameters.
    //
    hHeap = HeapCreate(0, 0, 0);
    if (hHeap == NULL) {
        _tprintf(TEXT("Failed to create a new heap with LastError %d.\n"),
                 GetLastError());
        return 1;
    }

    //
    // Enable the low-fragmentation heap (LFH). Starting with Windows Vista, 
    // the LFH is enabled by default but this call does not cause an error.
    //
    HeapInformation = HEAP_LFH;
    bResult = HeapSetInformation(hHeap,
                                 HeapCompatibilityInformation,
                                 &HeapInformation,
                                 sizeof(HeapInformation));
    if (bResult != FALSE) {
        _tprintf(TEXT("The low-fragmentation heap has been enabled.\n"));
    }
    else {
        _tprintf(TEXT("Failed to enable the low-fragmentation heap with LastError %d.\n"),
                 GetLastError());
        return 1;
    }

    return 0;
}

要件

要件 値
サポートされている最小のクライアント Windows XP [デスクトップ アプリ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー heapapi.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

GetProcessHeap

ヒープ関数

HeapCreate

HeapQueryInformation

メモリ管理関数