1.. _malloc_replacement_log:
2
3TBB_malloc_replacement_log Function
4===================================
5
6.. note:: This function is for Windows* OS only.
7
8Summary
9*******
10
11Provides information about the status of dynamic memory allocation replacement.
12
13Syntax
14*******
15
16::
17
18   extern "C" int TBB_malloc_replacement_log(char *** log_ptr);
19
20
21Header
22******
23
24::
25
26   #include "oneapi/tbb/tbbmalloc_proxy.h"
27
28
29Description
30***********
31
32Dynamic replacement of memory allocation functions on Windows* OS uses in-memory binary instrumentation techniques.
33To make sure that such instrumentation is safe, oneTBB first searches for a subset of replaced functions in the Visual C++* runtime DLLs
34and checks if each one has a known bytecode pattern. If any required function is not found or its bytecode pattern is unknown, the replacement is skipped,
35and the program continues to use the standard memory allocation functions.
36
37The ``TBB_malloc_replacement_log`` function allows the program to check if the dynamic memory replacement happens and to get a log of the performed checks.
38
39**Returns:**
40
41* 0, if all necessary functions are successfully found and the replacement takes place.
42* 1, otherwise.
43
44The ``log_ptr`` parameter must be an address of a char** variable or be ``NULL``. If it is not ``NULL``, the function writes there the address of an array of
45NULL-terminated strings containing detailed information about the searched functions in the following format:
46
47::
48
49   search_status: function_name (dll_name), byte pattern: <bytecodes>
50
51
52For more information about the replacement of dynamic memory allocation functions, see :ref:`Windows_C_Dynamic_Memory_Interface_Replacement`.
53
54
55Example
56*******
57
58::
59
60   #include "oneapi/tbb/tbbmalloc_proxy.h"
61   #include <stdio.h>
62
63   int main(){
64       char **func_replacement_log;
65       int func_replacement_status = TBB_malloc_replacement_log(&func_replacement_log);
66
67       if (func_replacement_status != 0) {
68           printf("tbbmalloc_proxy cannot replace memory allocation routines\n");
69           for (char** log_string = func_replacement_log; *log_string != 0; log_string++) {
70               printf("%s\n",*log_string);
71            }
72       }
73
74       return 0;
75   }
76
77
78Example output:
79
80::
81
82   tbbmalloc_proxy cannot replace memory allocation routines
83   Success: free (ucrtbase.dll), byte pattern: <C7442410000000008B4424>
84   Fail: _msize (ucrtbase.dll), byte pattern: <E90B000000CCCCCCCCCCCC>
85