_CrtSetAllocHook_CrtSetAllocHook

C ランタイム デバッグ メモリ割り当てプロセスにフックして、クライアント定義割り当て関数をインストールします (デバッグ バージョンのみ)。Installs a client-defined allocation function by hooking it into the C run-time debug memory allocation process (debug version only).

構文Syntax

_CRT_ALLOC_HOOK _CrtSetAllocHook(
   _CRT_ALLOC_HOOK allocHook
);

パラメーターParameters

allocHookallocHook
C ランタイム デバッグ メモリ割り当てプロセスにフックする新しいクライアント定義割り当て関数。New client-defined allocation function to hook into the C run-time debug memory allocation process.

戻り値Return Value

以前に定義された割り当てフック関数を返します。 allocHooknullの場合はnullを返します。Returns the previously defined allocation hook function, or NULL if allocHook is NULL.

RemarksRemarks

_CrtSetAllocHookを使用すると、アプリケーションは独自の割り当て関数を C ランタイムデバッグライブラリのメモリ割り当てプロセスにフックできます。_CrtSetAllocHook allows an application to hook its own allocation function into the C run-time debug library memory allocation process. そのため、メモリ ブロックの割り当て、再割り当て、または解放を行うためのデバッグ割り当て関数へのすべての呼び出しは、アプリケーションのフック関数への呼び出しをトリガーします。As a result, every call to a debug allocation function to allocate, reallocate, or free a memory block triggers a call to the application's hook function. _CrtSetAllocHookは、アプリケーションがメモリ不足の状況をどのように処理するか、割り当てパターンを調べる機能、および後で分析するために割り当て情報を記録する機会をテストするための簡単な方法をアプリケーションに提供します。_CrtSetAllocHook provides an application with an easy method for testing how the application handles insufficient memory situations, the ability to examine allocation patterns, and the opportunity to log allocation information for later analysis. _Debugが定義されていない場合、 _CrtSetAllocHookの呼び出しはプリプロセス中に削除されます。When _DEBUG is not defined, calls to _CrtSetAllocHook are removed during preprocessing.

_CrtSetAllocHook関数は、 allocHookで指定された新しいクライアント定義割り当て関数をインストールし、以前に定義されたフック関数を返します。The _CrtSetAllocHook function installs the new client-defined allocation function specified in allocHook and returns the previously defined hook function. 次の例は、クライアント定義割り当てフックをどのようにプロトタイプ宣言するかを示しています。The following example demonstrates how a client-defined allocation hook should be prototyped:

int YourAllocHook( int allocType, void *userData, size_t size,
                   int blockType, long requestNumber,
                   const unsigned char *filename, int lineNumber);

Alloctype引数は、割り当てのフック関数への呼び出しをトリガーした割り当て操作 ( _HOOK_ALLOC_HOOK_REALLOC、および _HOOK_FREE) の種類を指定します。The allocType argument specifies the type of allocation operation (_HOOK_ALLOC, _HOOK_REALLOC, and _HOOK_FREE) that triggered the call to the allocation's hook function. トリガーの割り当ての種類が _HOOK_FREEである場合、 userDataは解放されるメモリブロックのユーザーデータセクションへのポインターです。When the triggering allocation type is _HOOK_FREE, userData is a pointer to the user data section of the memory block about to be freed. ただし、トリガーする割り当ての種類が _HOOK_ALLOCまたは _HOOK_REALLOCの場合、メモリブロックがまだ割り当てられていないため、 userDataNULLになります。However, when the triggering allocation type is _HOOK_ALLOC or _HOOK_REALLOC, userData is NULL because the memory block has not been allocated yet.

sizeは、メモリブロックのサイズをバイト単位で指定します。 blocktypeはメモリブロックの種類を示し、 requestnumberはメモリブロックのオブジェクト割り当て順序番号です。使用可能な場合は、 filenameと lineNumber を指定します。トリガーする割り当て操作が開始されたソースファイル名と行番号を指定します。size specifies the size of the memory block in bytes, blockType indicates the type of the memory block, requestNumber is the object allocation order number of the memory block, and, if available, filename and lineNumber specify the source file name and line number where the triggering allocation operation was initiated.

フック関数は処理の完了後、続行方法を主要な C ランタイム割り当てプロセスに伝えるブール値を返す必要があります。After the hook function has finished processing, it must return a Boolean value, which tells the main C run-time allocation process how to continue. フック関数が呼び出されたことがないかのようにメイン割り当てプロセスが続行されるようにする場合、フック関数はTRUEを返します。When the hook function wants the main allocation process to continue as if the hook function had never been called, then the hook function should return TRUE. このようにすると、元のトリガーする割り当て操作が実行されます。This causes the original triggering allocation operation to be executed. フック関数は、この実装を使用して、現在の割り当て操作またはデバッグ ヒープの状態に影響を与えずに、後で分析するための割り当て情報を収集および保存できます。Using this implementation, the hook function can gather and save allocation information for later analysis, without interfering with the current allocation operation or state of the debug heap.

トリガーされた割り当て操作が呼び出されて失敗したかのように、フック関数がメイン割り当てプロセスを続行する場合、フック関数はFALSEを返す必要があります。When the hook function wants the main allocation process to continue as if the triggering allocation operation was called and it failed, then the hook function should return FALSE. フック関数は、この実装を使用して、さまざまなメモリの状況とデバッグ ヒープの状態をシミュレートし、各状況をアプリケーションがどのように処理するかをテストできます。Using this implementation, the hook function can simulate a wide range of memory conditions and debug heap states to test how the application handles each situation.

フック関数をクリアするには、 NULL_CrtSetAllocHookに渡します。To clear the hook function, pass NULL to _CrtSetAllocHook.

_CrtSetAllocHookを他のメモリ管理関数と共に使用する方法、または独自のクライアント定義フック関数を記述する方法の詳細については、「デバッグ用フック関数の書き込み」を参照してください。For more information about how _CrtSetAllocHook can be used with other memory management functions or how to write your own client-defined hook functions, see Debug Hook Function Writing.

注意

_CrtSetAllocHook/clr: pureではサポートされていません。_CrtSetAllocHook is not supported under /clr:pure. /Clr: pureおよび /clr: safeコンパイラオプションは visual studio 2015 で非推奨とされており、visual studio 2017 では削除されています。The /clr:pure and /clr:safe compiler options are deprecated in Visual Studio 2015 and removed in Visual Studio 2017.

必要条件Requirements

ルーチンによって返される値Routine 必須ヘッダーRequired header
_CrtSetAllocHook_CrtSetAllocHook <crtdbg.h><crtdbg.h>

互換性の詳細については、「 互換性」を参照してください。For more compatibility information, see Compatibility.

ライブラリLibraries

C ランタイム ライブラリのデバッグ バージョンのみ。Debug versions of C run-time libraries only.

Example

_CrtSetAllocHookの使用例については、 crt_dbg2を参照してください。For a sample of how to use _CrtSetAllocHook, see crt_dbg2.

関連項目See also

デバッグ ルーチンDebug Routines
_CrtGetAllocHook_CrtGetAllocHook