s3-ldap: Update LDAP schemata to include sambaTrustedDomain.
[nivanova/samba-autobuild/.git] / lib / talloc / talloc_guide.txt
1 Using talloc in Samba4
2 ======================
3
4 .. contents::
5
6 Andrew Tridgell
7 August 2009
8
9 The most current version of this document is available at
10    http://samba.org/ftp/unpacked/talloc/talloc_guide.txt
11
12 If you are used to the "old" talloc from Samba3 before 3.0.20 then please read
13 this carefully, as talloc has changed a lot. With 3.0.20 (or 3.0.14?) the
14 Samba4 talloc has been ported back to Samba3, so this guide applies to both.
15
16 The new talloc is a hierarchical, reference counted memory pool system
17 with destructors. Quite a mouthful really, but not too bad once you
18 get used to it.
19
20 Perhaps the biggest change from Samba3 is that there is no distinction
21 between a "talloc context" and a "talloc pointer". Any pointer
22 returned from talloc() is itself a valid talloc context. This means
23 you can do this::
24
25   struct foo *X = talloc(mem_ctx, struct foo);
26   X->name = talloc_strdup(X, "foo");
27
28 and the pointer X->name would be a "child" of the talloc context "X"
29 which is itself a child of mem_ctx. So if you do talloc_free(mem_ctx)
30 then it is all destroyed, whereas if you do talloc_free(X) then just X
31 and X->name are destroyed, and if you do talloc_free(X->name) then
32 just the name element of X is destroyed.
33
34 If you think about this, then what this effectively gives you is an
35 n-ary tree, where you can free any part of the tree with
36 talloc_free().
37
38 If you find this confusing, then I suggest you run the testsuite to
39 watch talloc in action. You may also like to add your own tests to
40 testsuite.c to clarify how some particular situation is handled.
41
42
43 Performance
44 -----------
45
46 All the additional features of talloc() over malloc() do come at a
47 price. We have a simple performance test in Samba4 that measures
48 talloc() versus malloc() performance, and it seems that talloc() is
49 about 4% slower than malloc() on my x86 Debian Linux box. For Samba,
50 the great reduction in code complexity that we get by using talloc
51 makes this worthwhile, especially as the total overhead of
52 talloc/malloc in Samba is already quite small.
53
54
55 talloc API
56 ----------
57
58 The following is a complete guide to the talloc API. Read it all at
59 least twice.
60
61 Multi-threading
62 ---------------
63
64 talloc itself does not deal with threads. It is thread-safe (assuming  
65 the underlying "malloc" is), as long as each thread uses different  
66 memory contexts.
67 If two threads uses the same context then they need to synchronize in  
68 order to be safe. In particular:
69 - when using talloc_enable_leak_report(), giving directly NULL as a  
70 parent context implicitly refers to a hidden "null context" global  
71 variable, so this should not be used in a multi-threaded environment  
72 without proper synchronization ;
73 - the context returned by talloc_autofree_context() is also global so  
74 shouldn't be used by several threads simultaneously without  
75 synchronization.
76
77 talloc and shared objects
78 -------------------------
79
80 talloc can be used in shared objects. Special care needs to be taken
81 to never use talloc_autofree_context() in code that might be loaded
82 with dlopen() and unloaded with dlclose(), as talloc_autofree_context()
83 internally uses atexit(3). Some platforms like modern Linux handles
84 this fine, but for example FreeBSD does not deal well with dlopen()
85 and atexit() used simultaneously: dlclose() does not clean up the list
86 of atexit-handlers, so when the program exits the code that was
87 registered from within talloc_autofree_context() is gone, the program
88 crashes at exit.
89
90
91 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
92 (type *)talloc(const void *context, type);
93
94 The talloc() macro is the core of the talloc library. It takes a
95 memory context and a type, and returns a pointer to a new area of
96 memory of the given type.
97
98 The returned pointer is itself a talloc context, so you can use it as
99 the context argument to more calls to talloc if you wish.
100
101 The returned pointer is a "child" of the supplied context. This means
102 that if you talloc_free() the context then the new child disappears as
103 well. Alternatively you can free just the child.
104
105 The context argument to talloc() can be NULL, in which case a new top
106 level context is created. 
107
108
109 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
110 void *talloc_size(const void *context, size_t size);
111
112 The function talloc_size() should be used when you don't have a
113 convenient type to pass to talloc(). Unlike talloc(), it is not type
114 safe (as it returns a void *), so you are on your own for type checking.
115
116 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
117 (typeof(ptr)) talloc_ptrtype(const void *ctx, ptr);
118
119 The talloc_ptrtype() macro should be used when you have a pointer and
120 want to allocate memory to point at with this pointer. When compiling
121 with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size()
122 and talloc_get_name() will return the current location in the source file.
123 and not the type.
124
125 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
126 int talloc_free(void *ptr);
127
128 The talloc_free() function frees a piece of talloc memory, and all its
129 children. You can call talloc_free() on any pointer returned by
130 talloc().
131
132 The return value of talloc_free() indicates success or failure, with 0
133 returned for success and -1 for failure. A possible failure condition
134 is if the pointer had a destructor attached to it and the destructor
135 returned -1. See talloc_set_destructor() for details on
136 destructors. Likewise, if "ptr" is NULL, then the function will make
137 no modifications and returns -1.
138
139 If this pointer has an additional parent when talloc_free() is called
140 then the memory is not actually released, but instead the most
141 recently established parent is destroyed. See talloc_reference() for
142 details on establishing additional parents.
143
144 For more control on which parent is removed, see talloc_unlink()
145
146 talloc_free() operates recursively on its children.
147
148 From the 2.0 version of talloc, as a special case, talloc_free() is
149 refused on pointers that have more than one parent, as talloc would
150 have no way of knowing which parent should be removed. To free a
151 pointer that has more than one parent please use talloc_unlink().
152
153 To help you find problems in your code caused by this behaviour, if
154 you do try and free a pointer with more than one parent then the
155 talloc logging function will be called to give output like this:
156
157   ERROR: talloc_free with references at some_dir/source/foo.c:123
158         reference at some_dir/source/other.c:325
159         reference at some_dir/source/third.c:121
160
161 Please see the documentation for talloc_set_log_fn() and
162 talloc_set_log_stderr() for more information on talloc logging
163 functions.
164
165 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
166 int talloc_free_children(void *ptr);
167
168 The talloc_free_children() walks along the list of all children of a
169 talloc context and talloc_free()s only the children, not the context
170 itself.
171
172
173 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
174 void *talloc_reference(const void *context, const void *ptr);
175
176 The talloc_reference() function makes "context" an additional parent
177 of "ptr".
178
179 The return value of talloc_reference() is always the original pointer
180 "ptr", unless talloc ran out of memory in creating the reference in
181 which case it will return NULL (each additional reference consumes
182 around 48 bytes of memory on intel x86 platforms).
183
184 If "ptr" is NULL, then the function is a no-op, and simply returns NULL.
185
186 After creating a reference you can free it in one of the following
187 ways:
188
189   - you can talloc_free() any parent of the original pointer. That
190     will reduce the number of parents of this pointer by 1, and will
191     cause this pointer to be freed if it runs out of parents.
192
193   - you can talloc_free() the pointer itself. That will destroy the
194     most recently established parent to the pointer and leave the
195     pointer as a child of its current parent.
196
197 For more control on which parent to remove, see talloc_unlink()
198
199
200 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
201 int talloc_unlink(const void *context, const void *ptr);
202
203 The talloc_unlink() function removes a specific parent from ptr. The
204 context passed must either be a context used in talloc_reference()
205 with this pointer, or must be a direct parent of ptr. 
206
207 Note that if the parent has already been removed using talloc_free()
208 then this function will fail and will return -1.  Likewise, if "ptr"
209 is NULL, then the function will make no modifications and return -1.
210
211 Usually you can just use talloc_free() instead of talloc_unlink(), but
212 sometimes it is useful to have the additional control on which parent
213 is removed.
214
215
216 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
217 void talloc_set_destructor(const void *ptr, int (*destructor)(void *));
218
219 The function talloc_set_destructor() sets the "destructor" for the
220 pointer "ptr". A destructor is a function that is called when the
221 memory used by a pointer is about to be released. The destructor
222 receives the pointer as an argument, and should return 0 for success
223 and -1 for failure.
224
225 The destructor can do anything it wants to, including freeing other
226 pieces of memory. A common use for destructors is to clean up
227 operating system resources (such as open file descriptors) contained
228 in the structure the destructor is placed on.
229
230 You can only place one destructor on a pointer. If you need more than
231 one destructor then you can create a zero-length child of the pointer
232 and place an additional destructor on that.
233
234 To remove a destructor call talloc_set_destructor() with NULL for the
235 destructor.
236
237 If your destructor attempts to talloc_free() the pointer that it is
238 the destructor for then talloc_free() will return -1 and the free will
239 be ignored. This would be a pointless operation anyway, as the
240 destructor is only called when the memory is just about to go away.
241
242
243 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
244 int talloc_increase_ref_count(const void *ptr);
245
246 The talloc_increase_ref_count(ptr) function is exactly equivalent to:
247
248   talloc_reference(NULL, ptr);
249
250 You can use either syntax, depending on which you think is clearer in
251 your code.
252
253 It returns 0 on success and -1 on failure.
254
255 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
256 size_t talloc_reference_count(const void *ptr);
257
258 Return the number of references to the pointer.
259
260 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
261 void talloc_set_name(const void *ptr, const char *fmt, ...);
262
263 Each talloc pointer has a "name". The name is used principally for
264 debugging purposes, although it is also possible to set and get the
265 name on a pointer in as a way of "marking" pointers in your code.
266
267 The main use for names on pointer is for "talloc reports". See
268 talloc_report() and talloc_report_full() for details. Also see
269 talloc_enable_leak_report() and talloc_enable_leak_report_full().
270
271 The talloc_set_name() function allocates memory as a child of the
272 pointer. It is logically equivalent to:
273   talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));
274
275 Note that multiple calls to talloc_set_name() will allocate more
276 memory without releasing the name. All of the memory is released when
277 the ptr is freed using talloc_free().
278
279
280 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
281 void talloc_set_name_const(const void *ptr, const char *name);
282
283 The function talloc_set_name_const() is just like talloc_set_name(),
284 but it takes a string constant, and is much faster. It is extensively
285 used by the "auto naming" macros, such as talloc_p().
286
287 This function does not allocate any memory. It just copies the
288 supplied pointer into the internal representation of the talloc
289 ptr. This means you must not pass a name pointer to memory that will
290 disappear before the ptr is freed with talloc_free().
291
292
293 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
294 void *talloc_named(const void *context, size_t size, const char *fmt, ...);
295
296 The talloc_named() function creates a named talloc pointer. It is
297 equivalent to:
298
299    ptr = talloc_size(context, size);
300    talloc_set_name(ptr, fmt, ....);
301
302
303 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
304 void *talloc_named_const(const void *context, size_t size, const char *name);
305
306 This is equivalent to::
307
308    ptr = talloc_size(context, size);
309    talloc_set_name_const(ptr, name);
310
311
312 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
313 const char *talloc_get_name(const void *ptr);
314
315 This returns the current name for the given talloc pointer. See
316 talloc_set_name() for details.
317
318
319 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
320 void *talloc_init(const char *fmt, ...);
321
322 This function creates a zero length named talloc context as a top
323 level context. It is equivalent to::
324
325   talloc_named(NULL, 0, fmt, ...);
326
327
328 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
329 void *talloc_new(void *ctx);
330
331 This is a utility macro that creates a new memory context hanging
332 off an exiting context, automatically naming it "talloc_new: __location__"
333 where __location__ is the source line it is called from. It is
334 particularly useful for creating a new temporary working context.
335
336
337 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
338 (type *)talloc_realloc(const void *context, void *ptr, type, count);
339
340 The talloc_realloc() macro changes the size of a talloc
341 pointer. The "count" argument is the number of elements of type "type"
342 that you want the resulting pointer to hold. 
343
344 talloc_realloc() has the following equivalences::
345
346   talloc_realloc(context, NULL, type, 1) ==> talloc(context, type);
347   talloc_realloc(context, NULL, type, N) ==> talloc_array(context, type, N);
348   talloc_realloc(context, ptr, type, 0)  ==> talloc_free(ptr);
349
350 The "context" argument is only used if "ptr" is NULL, otherwise it is
351 ignored.
352
353 talloc_realloc() returns the new pointer, or NULL on failure. The call
354 will fail either due to a lack of memory, or because the pointer has
355 more than one parent (see talloc_reference()).
356
357
358 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
359 void *talloc_realloc_size(const void *context, void *ptr, size_t size);
360
361 the talloc_realloc_size() function is useful when the type is not 
362 known so the typesafe talloc_realloc() cannot be used.
363
364
365 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
366 void *talloc_steal(const void *new_ctx, const void *ptr);
367
368 The talloc_steal() function changes the parent context of a talloc
369 pointer. It is typically used when the context that the pointer is
370 currently a child of is going to be freed and you wish to keep the
371 memory for a longer time. 
372
373 The talloc_steal() function returns the pointer that you pass it. It
374 does not have any failure modes.
375
376 NOTE: It is possible to produce loops in the parent/child relationship
377 if you are not careful with talloc_steal(). No guarantees are provided
378 as to your sanity or the safety of your data if you do this.
379
380 talloc_steal (new_ctx, NULL) will return NULL with no sideeffects.
381
382 Note that if you try and call talloc_steal() on a pointer that has
383 more than one parent then the result is ambiguous. Talloc will choose
384 to remove the parent that is currently indicated by talloc_parent()
385 and replace it with the chosen parent. You will also get a message
386 like this via the talloc logging functions:
387
388   WARNING: talloc_steal with references at some_dir/source/foo.c:123
389         reference at some_dir/source/other.c:325
390         reference at some_dir/source/third.c:121
391
392 To unambiguously change the parent of a pointer please see the
393 function talloc_reparent(). See the talloc_set_log_fn() documentation
394 for more information on talloc logging.
395
396 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
397 void *talloc_reparent(const void *old_parent, const void *new_parent, const void *ptr);
398
399 The talloc_reparent() function changes the parent context of a talloc
400 pointer. It is typically used when the context that the pointer is
401 currently a child of is going to be freed and you wish to keep the
402 memory for a longer time.
403
404 The talloc_reparent() function returns the pointer that you pass it. It
405 does not have any failure modes.
406
407 The difference between talloc_reparent() and talloc_steal() is that
408 talloc_reparent() can specify which parent you wish to change. This is
409 useful when a pointer has multiple parents via references.
410
411 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
412 void *talloc_parent(const void *ptr);
413
414 The talloc_parent() function returns the current talloc parent. This
415 is usually the pointer under which this memory was originally created,
416 but it may have changed due to a talloc_steal() or talloc_reparent()
417
418 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
419 size_t talloc_total_size(const void *ptr);
420
421 The talloc_total_size() function returns the total size in bytes used
422 by this pointer and all child pointers. Mostly useful for debugging.
423
424 Passing NULL is allowed, but it will only give a meaningful result if
425 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
426 been called.
427
428
429 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
430 size_t talloc_total_blocks(const void *ptr);
431
432 The talloc_total_blocks() function returns the total memory block
433 count used by this pointer and all child pointers. Mostly useful for
434 debugging.
435
436 Passing NULL is allowed, but it will only give a meaningful result if
437 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
438 been called.
439
440 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
441 void talloc_report_depth_cb(const void *ptr, int depth, int max_depth,
442                             void (*callback)(const void *ptr,
443                                              int depth, int max_depth,
444                                              int is_ref,
445                                              void *priv),
446                             void *priv);
447
448 This provides a more flexible reports than talloc_report(). It
449 will recursively call the callback for the entire tree of memory
450 referenced by the pointer. References in the tree are passed with
451 is_ref = 1 and the pointer that is referenced.
452
453 You can pass NULL for the pointer, in which case a report is
454 printed for the top level memory context, but only if
455 talloc_enable_leak_report() or talloc_enable_leak_report_full()
456 has been called.
457
458 The recursion is stopped when depth >= max_depth.
459 max_depth = -1 means only stop at leaf nodes.
460
461
462 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
463 void talloc_report_depth_file(const void *ptr, int depth, int max_depth, FILE *f);
464
465 This provides a more flexible reports than talloc_report(). It
466 will let you specify the depth and max_depth.
467
468
469 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
470 void talloc_report(const void *ptr, FILE *f);
471
472 The talloc_report() function prints a summary report of all memory
473 used by ptr. One line of report is printed for each immediate child of
474 ptr, showing the total memory and number of blocks used by that child.
475
476 You can pass NULL for the pointer, in which case a report is printed
477 for the top level memory context, but only if
478 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
479 been called.
480
481
482 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
483 void talloc_report_full(const void *ptr, FILE *f);
484
485 This provides a more detailed report than talloc_report(). It will
486 recursively print the ensire tree of memory referenced by the
487 pointer. References in the tree are shown by giving the name of the
488 pointer that is referenced.
489
490 You can pass NULL for the pointer, in which case a report is printed
491 for the top level memory context, but only if
492 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
493 been called.
494
495
496 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
497 void talloc_enable_leak_report(void);
498
499 This enables calling of talloc_report(NULL, stderr) when the program
500 exits. In Samba4 this is enabled by using the --leak-report command
501 line option.
502
503 For it to be useful, this function must be called before any other
504 talloc function as it establishes a "null context" that acts as the
505 top of the tree. If you don't call this function first then passing
506 NULL to talloc_report() or talloc_report_full() won't give you the
507 full tree printout.
508
509 Here is a typical talloc report:
510
511 talloc report on 'null_context' (total 267 bytes in 15 blocks)
512         libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
513         libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
514         iconv(UTF8,CP850)              contains     42 bytes in   2 blocks
515         libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
516         iconv(CP850,UTF8)              contains     42 bytes in   2 blocks
517         iconv(UTF8,UTF-16LE)           contains     45 bytes in   2 blocks
518         iconv(UTF-16LE,UTF8)           contains     45 bytes in   2 blocks
519
520
521 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
522 void talloc_enable_leak_report_full(void);
523
524 This enables calling of talloc_report_full(NULL, stderr) when the
525 program exits. In Samba4 this is enabled by using the
526 --leak-report-full command line option.
527
528 For it to be useful, this function must be called before any other
529 talloc function as it establishes a "null context" that acts as the
530 top of the tree. If you don't call this function first then passing
531 NULL to talloc_report() or talloc_report_full() won't give you the
532 full tree printout.
533
534 Here is a typical full report:
535
536 full talloc report on 'root' (total 18 bytes in 8 blocks)
537     p1                             contains     18 bytes in   7 blocks (ref 0)
538         r1                             contains     13 bytes in   2 blocks (ref 0)
539             reference to: p2
540         p2                             contains      1 bytes in   1 blocks (ref 1)
541         x3                             contains      1 bytes in   1 blocks (ref 0)
542         x2                             contains      1 bytes in   1 blocks (ref 0)
543         x1                             contains      1 bytes in   1 blocks (ref 0)
544
545
546 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
547 void talloc_enable_null_tracking(void);
548
549 This enables tracking of the NULL memory context without enabling leak
550 reporting on exit. Useful for when you want to do your own leak
551 reporting call via talloc_report_null_full();
552
553 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
554 void talloc_disable_null_tracking(void);
555
556 This disables tracking of the NULL memory context.
557
558 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
559 (type *)talloc_zero(const void *ctx, type);
560
561 The talloc_zero() macro is equivalent to::
562
563   ptr = talloc(ctx, type);
564   if (ptr) memset(ptr, 0, sizeof(type));
565
566
567 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
568 void *talloc_zero_size(const void *ctx, size_t size)
569
570 The talloc_zero_size() function is useful when you don't have a known type
571
572
573 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
574 void *talloc_memdup(const void *ctx, const void *p, size_t size);
575
576 The talloc_memdup() function is equivalent to::
577
578   ptr = talloc_size(ctx, size);
579   if (ptr) memcpy(ptr, p, size);
580
581
582 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
583 char *talloc_strdup(const void *ctx, const char *p);
584
585 The talloc_strdup() function is equivalent to::
586
587   ptr = talloc_size(ctx, strlen(p)+1);
588   if (ptr) memcpy(ptr, p, strlen(p)+1);
589
590 This functions sets the name of the new pointer to the passed
591 string. This is equivalent to::
592
593    talloc_set_name_const(ptr, ptr)
594
595 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
596 char *talloc_strndup(const void *t, const char *p, size_t n);
597
598 The talloc_strndup() function is the talloc equivalent of the C
599 library function strndup()
600
601 This functions sets the name of the new pointer to the passed
602 string. This is equivalent to:
603    talloc_set_name_const(ptr, ptr)
604
605 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
606 char *talloc_append_string(const void *t, char *orig, const char *append);
607
608 The talloc_append_string() function appends the given formatted
609 string to the given string.
610
611 This function sets the name of the new pointer to the new
612 string. This is equivalent to::
613
614    talloc_set_name_const(ptr, ptr)
615
616 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
617 char *talloc_vasprintf(const void *t, const char *fmt, va_list ap);
618
619 The talloc_vasprintf() function is the talloc equivalent of the C
620 library function vasprintf()
621
622 This functions sets the name of the new pointer to the new
623 string. This is equivalent to::
624
625    talloc_set_name_const(ptr, ptr)
626
627
628 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
629 char *talloc_asprintf(const void *t, const char *fmt, ...);
630
631 The talloc_asprintf() function is the talloc equivalent of the C
632 library function asprintf()
633
634 This functions sets the name of the new pointer to the new
635 string. This is equivalent to::
636
637    talloc_set_name_const(ptr, ptr)
638
639
640 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
641 char *talloc_asprintf_append(char *s, const char *fmt, ...);
642
643 The talloc_asprintf_append() function appends the given formatted
644 string to the given string.
645 Use this varient when the string in the current talloc buffer may
646 have been truncated in length.
647
648 This functions sets the name of the new pointer to the new
649 string. This is equivalent to::
650
651    talloc_set_name_const(ptr, ptr)
652
653
654 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
655 char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...);
656
657 The talloc_asprintf_append() function appends the given formatted 
658 string to the end of the currently allocated talloc buffer.
659 Use this varient when the string in the current talloc buffer has
660 not been changed.
661
662 This functions sets the name of the new pointer to the new
663 string. This is equivalent to::
664
665    talloc_set_name_const(ptr, ptr)
666
667
668 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
669 ((type *)talloc_array(const void *ctx, type, unsigned int count);
670
671 The talloc_array() macro is equivalent to::
672
673   (type *)talloc_size(ctx, sizeof(type) * count);
674
675 except that it provides integer overflow protection for the multiply,
676 returning NULL if the multiply overflows.
677
678
679 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
680 void *talloc_array_size(const void *ctx, size_t size, unsigned int count);
681
682 The talloc_array_size() function is useful when the type is not
683 known. It operates in the same way as talloc_array(), but takes a size
684 instead of a type.
685
686 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
687 (typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, unsigned int count);
688
689 The talloc_ptrtype() macro should be used when you have a pointer to an array
690 and want to allocate memory of an array to point at with this pointer. When compiling
691 with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_array_size()
692 and talloc_get_name() will return the current location in the source file.
693 and not the type.
694
695 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
696 void *talloc_realloc_fn(const void *ctx, void *ptr, size_t size);
697
698 This is a non-macro version of talloc_realloc(), which is useful 
699 as libraries sometimes want a ralloc function pointer. A realloc()
700 implementation encapsulates the functionality of malloc(), free() and
701 realloc() in one call, which is why it is useful to be able to pass
702 around a single function pointer.
703
704
705 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
706 void *talloc_autofree_context(void);
707
708 This is a handy utility function that returns a talloc context
709 which will be automatically freed on program exit. This can be used
710 to reduce the noise in memory leak reports.
711
712
713 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
714 void *talloc_check_name(const void *ptr, const char *name);
715
716 This function checks if a pointer has the specified name. If it does
717 then the pointer is returned. It it doesn't then NULL is returned.
718
719
720 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
721 (type *)talloc_get_type(const void *ptr, type);
722
723 This macro allows you to do type checking on talloc pointers. It is
724 particularly useful for void* private pointers. It is equivalent to
725 this::
726
727    (type *)talloc_check_name(ptr, #type)
728
729
730 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
731 talloc_set_type(const void *ptr, type);
732
733 This macro allows you to force the name of a pointer to be a
734 particular type. This can be used in conjunction with
735 talloc_get_type() to do type checking on void* pointers.
736
737 It is equivalent to this::
738
739    talloc_set_name_const(ptr, #type)
740
741 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
742 talloc_get_size(const void *ctx);
743
744 This function lets you know the amount of memory alloced so far by
745 this context. It does NOT account for subcontext memory.
746 This can be used to calculate the size of an array.
747
748 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
749 void *talloc_find_parent_byname(const void *ctx, const char *name);
750
751 Find a parent memory context of the current context that has the given
752 name. This can be very useful in complex programs where it may be
753 difficult to pass all information down to the level you need, but you
754 know the structure you want is a parent of another context.
755
756 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
757 (type *)talloc_find_parent_bytype(ctx, type);
758
759 Like talloc_find_parent_byname() but takes a type, making it typesafe.
760
761 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
762 void talloc_set_log_fn(void (*log_fn)(const char *message));
763
764 This function sets a logging function that talloc will use for
765 warnings and errors. By default talloc will not print any warnings or
766 errors.
767
768 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
769 void talloc_set_log_stderr(void)
770
771 This sets the talloc log function to write log messages to stderr