README.md
1 Malloc Hooks
2 ============
3
4 Malloc hooks allows a program to intercept all allocation/free calls that
5 happen during execution. It is only available in Android P and newer versions
6 of the OS.
7
8 There are two ways to enable these hooks, set a special system
9 property, or set a special environment variable and run your app/program.
10
11 When malloc hooks is enabled, it works by adding a shim layer that replaces
12 the normal allocation calls. The replaced calls are:
13
14 * `malloc`
15 * `free`
16 * `calloc`
17 * `realloc`
18 * `posix_memalign`
19 * `memalign`
20 * `aligned_alloc`
21 * `malloc_usable_size`
22
23 On 32 bit systems, these two deprecated functions are also replaced:
24
25 * `pvalloc`
26 * `valloc`
27
28 These four hooks are defined in malloc.h:
29
30 void* (*volatile __malloc_hook)(size_t, const void*);
31 void* (*volatile __realloc_hook)(void*, size_t, const void*);
32 void (*volatile __free_hook)(void*, const void*);
33 void* (*volatile __memalign_hook)(size_t, size_t, const void*);
34
35 When malloc is called and \_\_malloc\_hook has been set, then the hook
36 function is called instead.
37
38 When realloc is called and \_\_realloc\_hook has been set, then the hook
39 function is called instead.
40
41 When free is called and \_\_free\_hook has been set, then the hook
42 function is called instead.
43
44 When memalign is called and \_\_memalign\_hook has been set, then the hook
45 function is called instead.
46
47 For posix\_memalign, if \_\_memalign\_hook has been set, then the hook is
48 called, but only if alignment is a power of 2.
49
50 For aligned\_alloc, if \_\_memalign\_hook has been set, then the hook is
51 called, but only if alignment is a power of 2.
52
53 For calloc, if \_\_malloc\_hook has been set, then the hook function is
54 called, then the allocated memory is set to zero.
55
56 For the two deprecated functions pvalloc and valloc, if \_\_memalign\_hook
57 has been set, then the hook is called with an appropriate alignment value.
58
59 There is no hook for malloc\_usable\_size as of now.
60
61 These hooks can be set at any time, but there is no thread safety, so
62 the caller must guarantee that it does not depend on allocations/frees
63 occurring at the same time.
64
65 Implementation Details
66 ======================
67 When malloc hooks is enabled, then the hook pointers are set to
68 the current default allocation functions. It is expected that if an
69 app does intercept the allocation/free calls, it will eventually call
70 the original hook function to do allocations. If the app does not do this,
71 it runs the risk of crashing whenever a malloc\_usable\_size call is made.
72
73 Example Implementation
74 ======================
75 Below is a simple implementation intercepting only malloc/calloc calls.
76
77 void* new_malloc_hook(size_t bytes, const char* arg) {
78 return orig_malloc_hook(bytes, arg);
79 }
80
81 void orig_malloc_hook = __malloc_hook;
82 __malloc_hook = new_malloc_hook;
83
84 Enabling Examples
85 =================
86
87 ### For platform developers
88
89 Enable the hooks for all processes:
90
91 adb shell stop
92 adb shell setprop libc.debug.hooks.enable 1
93 adb shell start
94
95 Enable malloc hooks using an environment variable:
96
97 adb shell
98 # export LIBC_HOOKS_ENABLE=1
99 # ls
100
101 Any process spawned from this shell will run with malloc hooks enabled.
102
103 ### For app developers
104
105 Enable malloc hooks for a specific program/application:
106
107 adb shell setprop wrap.<APP> '"LIBC_HOOKS_ENABLE=1"'
108
109 For example, to enable malloc hooks for the google search box:
110
111 adb shell setprop wrap.com.google.android.googlequicksearchbox '"LIBC_HOOKS_ENABLE=1 logwrapper"'
112 adb shell am force-stop com.google.android.googlequicksearchbox
113
114 NOTE: On pre-O versions of the Android OS, property names had a length limit
115 of 32. This meant that to create a wrap property with the name of the app, it
116 was necessary to truncate the name to fit. On O, property names can be
117 an order of magnitude larger, so there should be no need to truncate the name
118 at all.
119