lib/talloc/doc/tutorial_debugging.dox

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