1/**
2@page libtalloc_debugging Chapter 6: Debugging
3
4Although talloc makes memory management significantly easier than the C standard
5library, developers are still only humans and can make mistakes. Therefore, it
6can be handy to know some tools for the inspection of talloc memory usage.
7
8@section log-abort Talloc log and abort
9
10We have already encountered the abort function in section @ref dts.
11In that case it was used when a type mismatch was detected. However, talloc
12calls this abort function in several more situations:
13
14- when the provided pointer is not a valid talloc context,
15- when the meta data is invalid - probably due to memory corruption,
16- and when an access after free is detected.
17
18The third one is probably the most interesting. It can help us with detecting
19an attempt to double-free a context or any other manipulation with it via
20talloc functions (using it as a parent, stealing it, etc.).
21
22Before the context is freed talloc sets a flag in the meta data. This is then
23used to detect the access after free. It basically works on the assumption that
24the memory stays unchanged (at least for a while) even when it is properly
25deallocated. This will work even if the memory is filled with the value
26specified in <code>TALLOC_FREE_FILL</code> environment variable, because it
27fills only the data part and leaves the meta data intact.
28
29Apart from the abort function, talloc uses a log function to provide additional
30information to the aforementioned violations. To enable logging we shall set the
31log function with one of:
32
33- talloc_set_log_fn()
34- talloc_set_log_stderr()
35
36The following code is a sample output of accessing a context after it has been
37freed:
38
39@code
40talloc_set_log_stderr();
41TALLOC_CTX *ctx = talloc_new(NULL);
42
43talloc_free(ctx);
44talloc_free(ctx);
45
46results in:
47talloc: access after free error - first free may be at ../src/main.c:55
48Bad talloc magic value - access after free
49@endcode
50
51Another example is an invalid context:
52
53@code
54talloc_set_log_stderr();
55TALLOC_CTX *ctx = talloc_new(NULL);
56char *str = strdup("not a talloc context");
57talloc_steal(ctx, str);
58
59results in:
60Bad talloc magic value - unknown value
61@endcode
62
63@section reports Memory usage reports
64
65Talloc can print reports of memory usage of a specified talloc context to a
66file (to <code>stdout</code> or <code>stderr</code>). The report can be
67simple or full. The simple report provides information only about the context
68itself and its direct descendants. The full report goes recursively through the
69entire context tree. See:
70
71- talloc_report()
72- talloc_report_full()
73
74We will use the following code to retrieve the sample report:
75
76@code
77struct foo {
78  char *str;
79};
80
81TALLOC_CTX *ctx = talloc_new(NULL);
82char *str =  talloc_strdup(ctx, "my string");
83struct foo *foo = talloc_zero(ctx, struct foo);
84foo->str = talloc_strdup(foo, "I am Foo");
85char *str2 = talloc_strdup(foo, "Foo is my parent");
86
87/* print full report */
88talloc_report_full(ctx, stdout);
89@endcode
90
91It will print a full report of <code>ctx</code> to the standard output.
92The message should be similar to:
93
94@code
95full talloc report on 'talloc_new: ../src/main.c:82' (total 46 bytes in 5 blocks)
96  struct foo contains 34 bytes in 3 blocks (ref 0) 0x1495130
97    Foo is my parent contains 17 bytes in 1 blocks (ref 0) 0x1495200
98    I am Foo contains 9 bytes in 1 blocks (ref 0) 0x1495190
99  my string contains 10 bytes in 1 blocks (ref 0) 0x14950c0
100@endcode
101
102We can notice in this report that something is wrong with the context containing
103<code>struct foo</code>. We know that the structure has only one string element.
104However, we can see in the report that it has two children. This indicates that
105we have either violated the memory hierarchy or forgotten to free it as
106temporary data. Looking into the code, we can see that <code>"Foo is my parent"
107</code> should be attached to <code>ctx</code>.
108
109See also:
110
111- talloc_enable_null_tracking()
112- talloc_disable_null_tracking()
113- talloc_enable_leak_report()
114- talloc_enable_leak_report_full()
115
116*/
117