1.. _Linux_C_Dynamic_Memory_Interface_Replacement:
2
3Linux\* OS C/C++ Dynamic Memory Interface Replacement
4=====================================================
5
6
7Release version of the proxy library is ``libtbbmalloc_proxy.so``,
8debug version is ``libtbbmalloc_proxy_debug.so``.
9
10
11The following dynamic memory functions are replaced:
12
13
14-  Standard C library functions: ``malloc``, ``calloc``, ``realloc``,
15   ``free``, (added in C11) ``aligned_alloc``
16
17
18-  Standard POSIX\* function: ``posix_memalign``
19
20
21-  Obsolete functions: ``valloc``, ``memalign``, ``pvalloc``,
22   ``mallopt``
23
24
25-  Replaceable global C++ operators ``new`` and ``delete``
26
27
28-  GNU C library (glibc) specific functions: ``malloc_usable_size``,
29   ``__libc_malloc``, ``__libc_calloc``, ``__libc_memalign``,
30   ``__libc_free``, ``__libc_realloc``, ``__libc_pvalloc``,
31   ``__libc_valloc``
32
33
34You can do the replacement either by loading the proxy library at
35program load time using the ``LD_PRELOAD`` environment variable (without
36changing the executable file), or by linking the main executable file
37with the proxy library.
38
39
40The OS program loader must be able to find the proxy library and the
41scalable memory allocator library at program load time. For that you may
42include the directory containing the libraries in the
43``LD_LIBRARY_PATH`` environment variable or add it to
44``/etc/ld.so.conf``.
45
46
47There are limitations for dynamic memory replacement:
48
49
50-  glibc memory allocation hooks, such as ``__malloc_hook``, are not
51   supported.
52
53
54-  Mono is not supported.
55
56
57.. container:: section
58
59
60   .. rubric:: Examples
61      :class: sectiontitle
62
63   These examples show how to set ``LD_PRELOAD`` and how to link a
64   program to use the memory allocation replacements.
65
66
67   ::
68
69
70      # Set LD_PRELOAD to load the release version of the proxy library
71      LD_PRELOAD=libtbbmalloc_proxy.so
72      # Link with the release version of the proxy library
73      g++ foo.o bar.o -ltbbmalloc_proxy -o a.out
74
75
76   To use the debug version of the library, replace *tbbmalloc_proxy*
77   with *tbbmalloc_proxy_debug* in the above examples.
78
79