Home | History | Annotate | Download | only in malloc_hooks 
      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.malloc.hooks 1
     93     adb shell start
     94 
     95 Enable malloc debug using an environment variable:
     96 
     97     adb shell
     98     # export LIBC_HOOK_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