r17886: add talloc_ptrtype() and talloc_array_ptrtype(),
[samba.git] / source / lib / talloc / talloc_guide.txt
1 Using talloc in Samba4
2 ----------------------
3
4 Andrew Tridgell
5 September 2004
6
7 The most current version of this document is available at
8    http://samba.org/ftp/unpacked/samba4/source/lib/talloc/talloc_guide.txt
9
10 If you are used to the "old" talloc from Samba3 before 3.0.20 then please read
11 this carefully, as talloc has changed a lot. With 3.0.20 (or 3.0.14?) the
12 Samba4 talloc has been ported back to Samba3, so this guide applies to both.
13
14 The new talloc is a hierarchical, reference counted memory pool system
15 with destructors. Quite a mounthful really, but not too bad once you
16 get used to it.
17
18 Perhaps the biggest change from Samba3 is that there is no distinction
19 between a "talloc context" and a "talloc pointer". Any pointer
20 returned from talloc() is itself a valid talloc context. This means
21 you can do this:
22
23   struct foo *X = talloc(mem_ctx, struct foo);
24   X->name = talloc_strdup(X, "foo");
25
26 and the pointer X->name would be a "child" of the talloc context "X"
27 which is itself a child of mem_ctx. So if you do talloc_free(mem_ctx)
28 then it is all destroyed, whereas if you do talloc_free(X) then just X
29 and X->name are destroyed, and if you do talloc_free(X->name) then
30 just the name element of X is destroyed.
31
32 If you think about this, then what this effectively gives you is an
33 n-ary tree, where you can free any part of the tree with
34 talloc_free().
35
36 If you find this confusing, then I suggest you run the testsuite to
37 watch talloc in action. You may also like to add your own tests to
38 testsuite.c to clarify how some particular situation is handled.
39
40
41 Performance
42 -----------
43
44 All the additional features of talloc() over malloc() do come at a
45 price. We have a simple performance test in Samba4 that measures
46 talloc() versus malloc() performance, and it seems that talloc() is
47 about 4% slower than malloc() on my x86 Debian Linux box. For Samba,
48 the great reduction in code complexity that we get by using talloc
49 makes this worthwhile, especially as the total overhead of
50 talloc/malloc in Samba is already quite small.
51
52
53 talloc API
54 ----------
55
56 The following is a complete guide to the talloc API. Read it all at
57 least twice.
58
59
60 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
61 (type *)talloc(const void *context, type);
62
63 The talloc() macro is the core of the talloc library. It takes a
64 memory context and a type, and returns a pointer to a new area of
65 memory of the given type.
66
67 The returned pointer is itself a talloc context, so you can use it as
68 the context argument to more calls to talloc if you wish.
69
70 The returned pointer is a "child" of the supplied context. This means
71 that if you talloc_free() the context then the new child disappears as
72 well. Alternatively you can free just the child.
73
74 The context argument to talloc() can be NULL, in which case a new top
75 level context is created. 
76
77
78 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
79 void *talloc_size(const void *context, size_t size);
80
81 The function talloc_size() should be used when you don't have a
82 convenient type to pass to talloc(). Unlike talloc(), it is not type
83 safe (as it returns a void *), so you are on your own for type checking.
84
85 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
86 (typeof(ptr)) talloc_ptrtype(const void *ctx, ptr);
87
88 The talloc_ptrtype() macro should be used when you have a pointer and
89 want to allocate memory to point at with this pointer. When compiling
90 with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size()
91 and talloc_get_name() will return the current location in the source file.
92 and not the type.
93
94 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
95 int talloc_free(void *ptr);
96
97 The talloc_free() function frees a piece of talloc memory, and all its
98 children. You can call talloc_free() on any pointer returned by
99 talloc().
100
101 The return value of talloc_free() indicates success or failure, with 0
102 returned for success and -1 for failure. The only possible failure
103 condition is if the pointer had a destructor attached to it and the
104 destructor returned -1. See talloc_set_destructor() for details on
105 destructors.
106
107 If this pointer has an additional parent when talloc_free() is called
108 then the memory is not actually released, but instead the most
109 recently established parent is destroyed. See talloc_reference() for
110 details on establishing additional parents.
111
112 For more control on which parent is removed, see talloc_unlink()
113
114 talloc_free() operates recursively on its children.
115
116
117 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
118 int talloc_free_children(void *ptr);
119
120 The talloc_free_children() walks along the list of all children of a
121 talloc context and talloc_free()s only the children, not the context
122 itself.
123
124
125 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
126 void *talloc_reference(const void *context, const void *ptr);
127
128 The talloc_reference() function makes "context" an additional parent
129 of "ptr".
130
131 The return value of talloc_reference() is always the original pointer
132 "ptr", unless talloc ran out of memory in creating the reference in
133 which case it will return NULL (each additional reference consumes
134 around 48 bytes of memory on intel x86 platforms).
135
136 If "ptr" is NULL, then the function is a no-op, and simply returns NULL.
137
138 After creating a reference you can free it in one of the following
139 ways:
140
141   - you can talloc_free() any parent of the original pointer. That
142     will reduce the number of parents of this pointer by 1, and will
143     cause this pointer to be freed if it runs out of parents.
144
145   - you can talloc_free() the pointer itself. That will destroy the
146     most recently established parent to the pointer and leave the
147     pointer as a child of its current parent.
148
149 For more control on which parent to remove, see talloc_unlink()
150
151
152 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
153 int talloc_unlink(const void *context, const void *ptr);
154
155 The talloc_unlink() function removes a specific parent from ptr. The
156 context passed must either be a context used in talloc_reference()
157 with this pointer, or must be a direct parent of ptr. 
158
159 Note that if the parent has already been removed using talloc_free()
160 then this function will fail and will return -1.  Likewise, if "ptr"
161 is NULL, then the function will make no modifications and return -1.
162
163 Usually you can just use talloc_free() instead of talloc_unlink(), but
164 sometimes it is useful to have the additional control on which parent
165 is removed.
166
167
168 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
169 void talloc_set_destructor(const void *ptr, int (*destructor)(void *));
170
171 The function talloc_set_destructor() sets the "destructor" for the
172 pointer "ptr". A destructor is a function that is called when the
173 memory used by a pointer is about to be released. The destructor
174 receives the pointer as an argument, and should return 0 for success
175 and -1 for failure.
176
177 The destructor can do anything it wants to, including freeing other
178 pieces of memory. A common use for destructors is to clean up
179 operating system resources (such as open file descriptors) contained
180 in the structure the destructor is placed on.
181
182 You can only place one destructor on a pointer. If you need more than
183 one destructor then you can create a zero-length child of the pointer
184 and place an additional destructor on that.
185
186 To remove a destructor call talloc_set_destructor() with NULL for the
187 destructor.
188
189 If your destructor attempts to talloc_free() the pointer that it is
190 the destructor for then talloc_free() will return -1 and the free will
191 be ignored. This would be a pointless operation anyway, as the
192 destructor is only called when the memory is just about to go away.
193
194
195 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
196 void talloc_increase_ref_count(const void *ptr);
197
198 The talloc_increase_ref_count(ptr) function is exactly equivalent to:
199
200   talloc_reference(NULL, ptr);
201
202 You can use either syntax, depending on which you think is clearer in
203 your code.
204
205
206 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
207 void talloc_set_name(const void *ptr, const char *fmt, ...);
208
209 Each talloc pointer has a "name". The name is used principally for
210 debugging purposes, although it is also possible to set and get the
211 name on a pointer in as a way of "marking" pointers in your code.
212
213 The main use for names on pointer is for "talloc reports". See
214 talloc_report() and talloc_report_full() for details. Also see
215 talloc_enable_leak_report() and talloc_enable_leak_report_full().
216
217 The talloc_set_name() function allocates memory as a child of the
218 pointer. It is logically equivalent to:
219   talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));
220
221 Note that multiple calls to talloc_set_name() will allocate more
222 memory without releasing the name. All of the memory is released when
223 the ptr is freed using talloc_free().
224
225
226 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
227 void talloc_set_name_const(const void *ptr, const char *name);
228
229 The function talloc_set_name_const() is just like talloc_set_name(),
230 but it takes a string constant, and is much faster. It is extensively
231 used by the "auto naming" macros, such as talloc_p().
232
233 This function does not allocate any memory. It just copies the
234 supplied pointer into the internal representation of the talloc
235 ptr. This means you must not pass a name pointer to memory that will
236 disappear before the ptr is freed with talloc_free().
237
238
239 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
240 void *talloc_named(const void *context, size_t size, const char *fmt, ...);
241
242 The talloc_named() function creates a named talloc pointer. It is
243 equivalent to:
244
245    ptr = talloc_size(context, size);
246    talloc_set_name(ptr, fmt, ....);
247
248
249 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
250 void *talloc_named_const(const void *context, size_t size, const char *name);
251
252 This is equivalent to:
253
254    ptr = talloc_size(context, size);
255    talloc_set_name_const(ptr, name);
256
257
258 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
259 const char *talloc_get_name(const void *ptr);
260
261 This returns the current name for the given talloc pointer. See
262 talloc_set_name() for details.
263
264
265 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
266 void *talloc_init(const char *fmt, ...);
267
268 This function creates a zero length named talloc context as a top
269 level context. It is equivalent to:
270
271   talloc_named(NULL, 0, fmt, ...);
272
273
274 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
275 void *talloc_new(void *ctx);
276
277 This is a utility macro that creates a new memory context hanging
278 off an exiting context, automatically naming it "talloc_new: __location__"
279 where __location__ is the source line it is called from. It is
280 particularly useful for creating a new temporary working context.
281
282
283 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
284 (type *)talloc_realloc(const void *context, void *ptr, type, count);
285
286 The talloc_realloc() macro changes the size of a talloc
287 pointer. The "count" argument is the number of elements of type "type"
288 that you want the resulting pointer to hold. 
289
290 talloc_realloc() has the following equivalences:
291
292   talloc_realloc(context, NULL, type, 1) ==> talloc(context, type);
293   talloc_realloc(context, NULL, type, N) ==> talloc_array(context, type, N);
294   talloc_realloc(context, ptr, type, 0)  ==> talloc_free(ptr);
295
296 The "context" argument is only used if "ptr" is NULL, otherwise it is
297 ignored.
298
299 talloc_realloc() returns the new pointer, or NULL on failure. The call
300 will fail either due to a lack of memory, or because the pointer has
301 more than one parent (see talloc_reference()).
302
303
304 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
305 void *talloc_realloc_size(const void *context, void *ptr, size_t size);
306
307 the talloc_realloc_size() function is useful when the type is not 
308 known so the typesafe talloc_realloc() cannot be used.
309
310
311 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
312 void *talloc_steal(const void *new_ctx, const void *ptr);
313
314 The talloc_steal() function changes the parent context of a talloc
315 pointer. It is typically used when the context that the pointer is
316 currently a child of is going to be freed and you wish to keep the
317 memory for a longer time. 
318
319 The talloc_steal() function returns the pointer that you pass it. It
320 does not have any failure modes.
321
322 NOTE: It is possible to produce loops in the parent/child relationship
323 if you are not careful with talloc_steal(). No guarantees are provided
324 as to your sanity or the safety of your data if you do this.
325
326 talloc_steal (new_ctx, NULL) will return NULL with no sideeffects.
327
328 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
329 size_t talloc_total_size(const void *ptr);
330
331 The talloc_total_size() function returns the total size in bytes used
332 by this pointer and all child pointers. Mostly useful for debugging.
333
334 Passing NULL is allowed, but it will only give a meaningful result if
335 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
336 been called.
337
338
339 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
340 size_t talloc_total_blocks(const void *ptr);
341
342 The talloc_total_blocks() function returns the total memory block
343 count used by this pointer and all child pointers. Mostly useful for
344 debugging.
345
346 Passing NULL is allowed, but it will only give a meaningful result if
347 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
348 been called.
349
350
351 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
352 void talloc_report(const void *ptr, FILE *f);
353
354 The talloc_report() function prints a summary report of all memory
355 used by ptr. One line of report is printed for each immediate child of
356 ptr, showing the total memory and number of blocks used by that child.
357
358 You can pass NULL for the pointer, in which case a report is printed
359 for the top level memory context, but only if
360 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
361 been called.
362
363
364 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
365 void talloc_report_full(const void *ptr, FILE *f);
366
367 This provides a more detailed report than talloc_report(). It will
368 recursively print the ensire tree of memory referenced by the
369 pointer. References in the tree are shown by giving the name of the
370 pointer that is referenced.
371
372 You can pass NULL for the pointer, in which case a report is printed
373 for the top level memory context, but only if
374 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
375 been called.
376
377
378 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
379 void talloc_enable_leak_report(void);
380
381 This enables calling of talloc_report(NULL, stderr) when the program
382 exits. In Samba4 this is enabled by using the --leak-report command
383 line option.
384
385 For it to be useful, this function must be called before any other
386 talloc function as it establishes a "null context" that acts as the
387 top of the tree. If you don't call this function first then passing
388 NULL to talloc_report() or talloc_report_full() won't give you the
389 full tree printout.
390
391 Here is a typical talloc report:
392
393 talloc report on 'null_context' (total 267 bytes in 15 blocks)
394         libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
395         libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
396         iconv(UTF8,CP850)              contains     42 bytes in   2 blocks
397         libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
398         iconv(CP850,UTF8)              contains     42 bytes in   2 blocks
399         iconv(UTF8,UTF-16LE)           contains     45 bytes in   2 blocks
400         iconv(UTF-16LE,UTF8)           contains     45 bytes in   2 blocks
401
402
403 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
404 void talloc_enable_leak_report_full(void);
405
406 This enables calling of talloc_report_full(NULL, stderr) when the
407 program exits. In Samba4 this is enabled by using the
408 --leak-report-full command line option.
409
410 For it to be useful, this function must be called before any other
411 talloc function as it establishes a "null context" that acts as the
412 top of the tree. If you don't call this function first then passing
413 NULL to talloc_report() or talloc_report_full() won't give you the
414 full tree printout.
415
416 Here is a typical full report:
417
418 full talloc report on 'root' (total 18 bytes in 8 blocks)
419     p1                             contains     18 bytes in   7 blocks (ref 0)
420         r1                             contains     13 bytes in   2 blocks (ref 0)
421             reference to: p2
422         p2                             contains      1 bytes in   1 blocks (ref 1)
423         x3                             contains      1 bytes in   1 blocks (ref 0)
424         x2                             contains      1 bytes in   1 blocks (ref 0)
425         x1                             contains      1 bytes in   1 blocks (ref 0)
426
427
428 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
429 void talloc_enable_null_tracking(void);
430
431 This enables tracking of the NULL memory context without enabling leak
432 reporting on exit. Useful for when you want to do your own leak
433 reporting call via talloc_report_null_full();
434
435
436 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
437 (type *)talloc_zero(const void *ctx, type);
438
439 The talloc_zero() macro is equivalent to:
440
441   ptr = talloc(ctx, type);
442   if (ptr) memset(ptr, 0, sizeof(type));
443
444
445 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
446 void *talloc_zero_size(const void *ctx, size_t size)
447
448 The talloc_zero_size() function is useful when you don't have a known type
449
450
451 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
452 void *talloc_memdup(const void *ctx, const void *p, size_t size);
453
454 The talloc_memdup() function is equivalent to:
455
456   ptr = talloc_size(ctx, size);
457   if (ptr) memcpy(ptr, p, size);
458
459
460 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
461 char *talloc_strdup(const void *ctx, const char *p);
462
463 The talloc_strdup() function is equivalent to:
464
465   ptr = talloc_size(ctx, strlen(p)+1);
466   if (ptr) memcpy(ptr, p, strlen(p)+1);
467
468 This functions sets the name of the new pointer to the passed
469 string. This is equivalent to:
470    talloc_set_name_const(ptr, ptr)
471
472 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
473 char *talloc_strndup(const void *t, const char *p, size_t n);
474
475 The talloc_strndup() function is the talloc equivalent of the C
476 library function strndup()
477
478 This functions sets the name of the new pointer to the passed
479 string. This is equivalent to:
480    talloc_set_name_const(ptr, ptr)
481
482
483 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
484 char *talloc_vasprintf(const void *t, const char *fmt, va_list ap);
485
486 The talloc_vasprintf() function is the talloc equivalent of the C
487 library function vasprintf()
488
489
490 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
491 char *talloc_asprintf(const void *t, const char *fmt, ...);
492
493 The talloc_asprintf() function is the talloc equivalent of the C
494 library function asprintf()
495
496 This functions sets the name of the new pointer to the passed
497 string. This is equivalent to:
498    talloc_set_name_const(ptr, ptr)
499
500
501 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
502 char *talloc_asprintf_append(char *s, const char *fmt, ...);
503
504 The talloc_asprintf_append() function appends the given formatted 
505 string to the given string. 
506
507
508 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
509 (type *)talloc_array(const void *ctx, type, uint_t count);
510
511 The talloc_array() macro is equivalent to:
512
513   (type *)talloc_size(ctx, sizeof(type) * count);
514
515 except that it provides integer overflow protection for the multiply,
516 returning NULL if the multiply overflows.
517
518
519 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
520 void *talloc_array_size(const void *ctx, size_t size, uint_t count);
521
522 The talloc_array_size() function is useful when the type is not
523 known. It operates in the same way as talloc_array(), but takes a size
524 instead of a type.
525
526 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
527 (typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, uint_t count);
528
529 The talloc_ptrtype() macro should be used when you have a pointer to an array
530 and want to allocate memory of an array to point at with this pointer. When compiling
531 with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_array_size()
532 and talloc_get_name() will return the current location in the source file.
533 and not the type.
534
535 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
536 void *talloc_realloc_fn(const void *ctx, void *ptr, size_t size);
537
538 This is a non-macro version of talloc_realloc(), which is useful 
539 as libraries sometimes want a ralloc function pointer. A realloc()
540 implementation encapsulates the functionality of malloc(), free() and
541 realloc() in one call, which is why it is useful to be able to pass
542 around a single function pointer.
543
544
545 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
546 void *talloc_autofree_context(void);
547
548 This is a handy utility function that returns a talloc context
549 which will be automatically freed on program exit. This can be used
550 to reduce the noise in memory leak reports.
551
552
553 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
554 void *talloc_check_name(const void *ptr, const char *name);
555
556 This function checks if a pointer has the specified name. If it does
557 then the pointer is returned. It it doesn't then NULL is returned.
558
559
560 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
561 (type *)talloc_get_type(const void *ptr, type);
562
563 This macro allows you to do type checking on talloc pointers. It is
564 particularly useful for void* private pointers. It is equivalent to
565 this:
566
567    (type *)talloc_check_name(ptr, #type)
568
569
570 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
571 talloc_set_type(const void *ptr, type);
572
573 This macro allows you to force the name of a pointer to be a
574 particular type. This can be used in conjunction with
575 talloc_get_type() to do type checking on void* pointers.
576
577 It is equivalent to this:
578    talloc_set_name_const(ptr, #type)
579
580 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
581 talloc_get_size(const void *ctx);
582
583 This function lets you know the amount of memory alloced so far by
584 this context. It does NOT account for subcontext memory.
585 This can be used to calculate the size of an array.
586
587 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
588 void *talloc_find_parent_byname(const void *ctx, const char *name);
589
590 Find a parent memory context of the current context that has the given
591 name. This can be very useful in complex programs where it may be
592 difficult to pass all information down to the level you need, but you
593 know the structure you want is a parent of another context.
594
595 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
596 (type *)talloc_find_parent_bytype(ctx, type);
597
598 Like talloc_find_parent_byname() but takes a type, making it typesafe.
599