New talloc_set for auto-cleanup.
[ccan] / ccan / talloc / talloc.h
1 #ifndef CCAN_TALLOC_H
2 #define CCAN_TALLOC_H
3 /* 
4    Copyright (C) Andrew Tridgell 2004-2005
5    Copyright (C) Stefan Metzmacher 2006
6    
7      ** NOTE! The following LGPL license applies to the talloc
8      ** library. This does NOT imply that all of Samba is released
9      ** under the LGPL
10    
11    This library is free software; you can redistribute it and/or
12    modify it under the terms of the GNU Lesser General Public
13    License as published by the Free Software Foundation; either
14    version 2 of the License, or (at your option) any later version.
15
16    This library is distributed in the hope that it will be useful,
17    but WITHOUT ANY WARRANTY; without even the implied warranty of
18    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
19    Lesser General Public License for more details.
20
21    You should have received a copy of the GNU Lesser General Public
22    License along with this library; if not, write to the Free Software
23    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
24 */
25
26 #include <stdlib.h>
27 #include <stdio.h>
28 #include <stdarg.h>
29 #include <ccan/typesafe_cb/typesafe_cb.h>
30 #include "config.h"
31
32 /*
33   this uses a little trick to allow __LINE__ to be stringified
34 */
35 #ifndef __location__
36 #define __TALLOC_STRING_LINE1__(s)    #s
37 #define __TALLOC_STRING_LINE2__(s)   __TALLOC_STRING_LINE1__(s)
38 #define __TALLOC_STRING_LINE3__  __TALLOC_STRING_LINE2__(__LINE__)
39 #define __location__ __FILE__ ":" __TALLOC_STRING_LINE3__
40 #endif
41
42 #if HAVE_ATTRIBUTE_PRINTF
43 /** Use gcc attribute to check printf fns.  a1 is the 1-based index of
44  * the parameter containing the format, and a2 the index of the first
45  * argument. Note that some gcc 2.x versions don't handle this
46  * properly **/
47 #define PRINTF_ATTRIBUTE(a1, a2) __attribute__ ((format (__printf__, a1, a2)))
48 #else
49 #define PRINTF_ATTRIBUTE(a1, a2)
50 #endif
51
52 /* try to make talloc_set_destructor() and talloc_steal() type safe,
53    if we have a recent gcc */
54 #if HAVE_TYPEOF
55 #define _TALLOC_TYPEOF(ptr) __typeof__(ptr)
56 #else
57 #define _TALLOC_TYPEOF(ptr) void *
58 #endif
59
60 #define talloc_move(ctx, ptr) (_TALLOC_TYPEOF(*(ptr)))_talloc_move((ctx),(void *)(ptr))
61
62 /**
63  * talloc - allocate dynamic memory for a type
64  * @ctx: context to be parent of this allocation, or NULL.
65  * @type: the type to be allocated.
66  *
67  * The talloc() macro is the core of the talloc library. It takes a memory
68  * context and a type, and returns a pointer to a new area of memory of the
69  * given type.
70  *
71  * The returned pointer is itself a talloc context, so you can use it as the
72  * context argument to more calls to talloc if you wish.
73  *
74  * The returned pointer is a "child" of @ctx. This means that if you
75  * talloc_free() @ctx then the new child disappears as well.  Alternatively you
76  * can free just the child.
77  *
78  * @ctx can be NULL, in which case a new top level context is created.
79  *
80  * Example:
81  *      unsigned int *a, *b;
82  *      a = talloc(NULL, unsigned int);
83  *      b = talloc(a, unsigned int);
84  *
85  * See Also:
86  *      talloc_zero, talloc_array, talloc_steal, talloc_free.
87  */
88 #define talloc(ctx, type) (type *)talloc_named_const(ctx, sizeof(type), #type)
89
90 /**
91  * talloc_set - allocate dynamic memory for a type, into a pointer
92  * @ptr: pointer to the pointer to assign.
93  * @ctx: context to be parent of this allocation, or NULL.
94  *
95  * talloc_set() does a talloc, but also adds a destructor which will make the
96  * pointer invalid when it is freed.  This can find many use-after-free bugs.
97  *
98  * Note that the destructor is chained off a zero-length allocation, and so
99  * is not affected by talloc_set_destructor().
100  *
101  * Example:
102  *      unsigned int *a;
103  *      a = talloc(NULL, unsigned int);
104  *      talloc_set(&b, a, unsigned int);
105  *      talloc_free(a);
106  *      *b = 1; // This will crash!
107  *
108  * See Also:
109  *      talloc.
110  */
111 #define talloc_set(pptr, ctx) \
112         _talloc_set((pptr), (ctx), sizeof(&**(pptr)), __location__)
113
114 /**
115  * talloc_free - free talloc'ed memory and its children
116  * @ptr: the talloced pointer to free
117  *
118  * The talloc_free() function frees a piece of talloc memory, and all its
119  * children. You can call talloc_free() on any pointer returned by talloc().
120  *
121  * The return value of talloc_free() indicates success or failure, with 0
122  * returned for success and -1 for failure. The only possible failure condition
123  * is if the pointer had a destructor attached to it and the destructor
124  * returned -1. See talloc_set_destructor() for details on destructors.
125  * errno will be preserved unless the talloc_free fails.
126  *
127  * If this pointer has an additional parent when talloc_free() is called then
128  * the memory is not actually released, but instead the most recently
129  * established parent is destroyed. See talloc_reference() for details on
130  * establishing additional parents.
131  *
132  * For more control on which parent is removed, see talloc_unlink().
133  *
134  * talloc_free() operates recursively on its children.
135  *
136  * Example:
137  *      unsigned int *a, *b;
138  *      a = talloc(NULL, unsigned int);
139  *      b = talloc(a, unsigned int);
140  *      // Frees a and b
141  *      talloc_free(a);
142  *
143  * See Also:
144  *      talloc_set_destructor, talloc_unlink
145  */
146 int talloc_free(const void *ptr);
147
148 /**
149  * talloc_set_destructor: set a destructor for when this pointer is freed
150  * @ptr: the talloc pointer to set the destructor on
151  * @destructor: the function to be called
152  *
153  * The function talloc_set_destructor() sets the "destructor" for the pointer
154  * @ptr.  A destructor is a function that is called when the memory used by a
155  * pointer is about to be released.  The destructor receives the pointer as an
156  * argument, and should return 0 for success and -1 for failure.
157  *
158  * The destructor can do anything it wants to, including freeing other pieces
159  * of memory. A common use for destructors is to clean up operating system
160  * resources (such as open file descriptors) contained in the structure the
161  * destructor is placed on.
162  *
163  * You can only place one destructor on a pointer. If you need more than one
164  * destructor then you can create a zero-length child of the pointer and place
165  * an additional destructor on that.
166  *
167  * To remove a destructor call talloc_set_destructor() with NULL for the
168  * destructor.
169  *
170  * If your destructor attempts to talloc_free() the pointer that it is the
171  * destructor for then talloc_free() will return -1 and the free will be
172  * ignored. This would be a pointless operation anyway, as the destructor is
173  * only called when the memory is just about to go away.
174  *
175  * Example:
176  * static int destroy_fd(int *fd)
177  * {
178  *      close(*fd);
179  *      return 0;
180  * }
181  *
182  * int *open_file(const char *filename)
183  * {
184  *      int *fd = talloc(NULL, int);
185  *      *fd = open(filename, O_RDONLY);
186  *      if (*fd < 0) {
187  *              talloc_free(fd);
188  *              return NULL;
189  *      }
190  *      // Whenever they free this, we close the file.
191  *      talloc_set_destructor(fd, destroy_fd);
192  *      return fd;
193  * }
194  *
195  * See Also:
196  *      talloc, talloc_free
197  */
198 #define talloc_set_destructor(ptr, function)                                  \
199         _talloc_set_destructor((ptr), typesafe_cb(int, (function), (ptr)))
200
201 /**
202  * talloc_zero - allocate zeroed dynamic memory for a type
203  * @ctx: context to be parent of this allocation, or NULL.
204  * @type: the type to be allocated.
205  *
206  * The talloc_zero() macro is equivalent to:
207  *
208  *  ptr = talloc(ctx, type);
209  *  if (ptr) memset(ptr, 0, sizeof(type));
210  *
211  * Example:
212  *      unsigned int *a, *b;
213  *      a = talloc_zero(NULL, unsigned int);
214  *      b = talloc_zero(a, unsigned int);
215  *
216  * See Also:
217  *      talloc, talloc_zero_size, talloc_zero_array
218  */
219 #define talloc_zero(ctx, type) (type *)_talloc_zero(ctx, sizeof(type), #type)
220
221 /**
222  * talloc_array - allocate dynamic memory for an array of a given type
223  * @ctx: context to be parent of this allocation, or NULL.
224  * @type: the type to be allocated.
225  * @count: the number of elements to be allocated.
226  *
227  * The talloc_array() macro is a safe way of allocating an array.  It is
228  * equivalent to:
229  *
230  *  (type *)talloc_size(ctx, sizeof(type) * count);
231  *
232  * except that it provides integer overflow protection for the multiply,
233  * returning NULL if the multiply overflows.
234  *
235  * Example:
236  *      unsigned int *a, *b;
237  *      a = talloc_zero(NULL, unsigned int);
238  *      b = talloc_array(a, unsigned int, 100);
239  *
240  * See Also:
241  *      talloc, talloc_zero_array
242  */
243 #define talloc_array(ctx, type, count) (type *)_talloc_array(ctx, sizeof(type), count, #type)
244
245 /**
246  * talloc_size - allocate a particular size of memory
247  * @ctx: context to be parent of this allocation, or NULL.
248  * @size: the number of bytes to allocate
249  *
250  * The function talloc_size() should be used when you don't have a convenient
251  * type to pass to talloc(). Unlike talloc(), it is not type safe (as it
252  * returns a void *), so you are on your own for type checking.
253  *
254  * Best to use talloc() or talloc_array() instead.
255  *
256  * Example:
257  *      void *mem = talloc_size(NULL, 100);
258  *
259  * See Also:
260  *      talloc, talloc_array, talloc_zero_size
261  */
262 #define talloc_size(ctx, size) talloc_named_const(ctx, size, __location__)
263
264 #ifdef HAVE_TYPEOF
265 /**
266  * talloc_steal - change/set the parent context of a talloc pointer
267  * @ctx: the new parent
268  * @ptr: the talloc pointer to reparent
269  *
270  * The talloc_steal() function changes the parent context of a talloc
271  * pointer. It is typically used when the context that the pointer is currently
272  * a child of is going to be freed and you wish to keep the memory for a longer
273  * time.
274  *
275  * The talloc_steal() function returns the pointer that you pass it. It does
276  * not have any failure modes.
277  *
278  * NOTE: It is possible to produce loops in the parent/child relationship if
279  * you are not careful with talloc_steal(). No guarantees are provided as to
280  * your sanity or the safety of your data if you do this.
281  *
282  * talloc_steal (new_ctx, NULL) will return NULL with no sideeffects.
283  *
284  * Example:
285  *      unsigned int *a, *b;
286  *      a = talloc(NULL, unsigned int);
287  *      b = talloc(NULL, unsigned int);
288  *      // Reparent b to a as if we'd done 'b = talloc(a, unsigned int)'.
289  *      talloc_steal(a, b);
290  *
291  * See Also:
292  *      talloc_reference
293  */
294 #define talloc_steal(ctx, ptr) ({ _TALLOC_TYPEOF(ptr) _talloc_steal_ret = (_TALLOC_TYPEOF(ptr))_talloc_steal((ctx),(ptr)); _talloc_steal_ret; }) /* this extremely strange macro is to avoid some braindamaged warning stupidity in gcc 4.1.x */
295 #else
296 #define talloc_steal(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_steal((ctx),(ptr))
297 #endif /* HAVE_TYPEOF */
298
299 /**
300  * talloc_report_full - report all the memory used by a pointer and children.
301  * @ptr: the context to report on
302  * @f: the file to report to
303  *
304  * Recursively print the entire tree of memory referenced by the
305  * pointer. References in the tree are shown by giving the name of the pointer
306  * that is referenced.
307  *
308  * You can pass NULL for the pointer, in which case a report is printed for the
309  * top level memory context, but only if talloc_enable_null_tracking() has been
310  * called.
311  *
312  * Example:
313  *      unsigned int *a, *b;
314  *      a = talloc(NULL, unsigned int);
315  *      b = talloc(a, unsigned int);
316  *      fprintf(stderr, "Dumping memory tree for a:\n");
317  *      talloc_report_full(a, stderr);
318  *
319  * See Also:
320  *      talloc_report
321  */
322 void talloc_report_full(const void *ptr, FILE *f);
323
324 /**
325  * talloc_reference - add an additional parent to a context
326  * @ctx: the additional parent
327  * @ptr: the talloc pointer
328  *
329  * The talloc_reference() function makes @ctx an additional parent of @ptr.
330  *
331  * The return value of talloc_reference() is always the original pointer @ptr,
332  * unless talloc ran out of memory in creating the reference in which case it
333  * will return NULL (each additional reference consumes around 48 bytes of
334  * memory on intel x86 platforms).
335  *
336  * If @ptr is NULL, then the function is a no-op, and simply returns NULL.
337  *
338  * After creating a reference you can free it in one of the following ways:
339  *
340  *  - you can talloc_free() any parent of the original pointer. That will
341  *    reduce the number of parents of this pointer by 1, and will cause this
342  *    pointer to be freed if it runs out of parents.
343  *
344  *  - you can talloc_free() the pointer itself. That will destroy the most
345  *    recently established parent to the pointer and leave the pointer as a
346  *    child of its current parent.
347  *
348  * For more control on which parent to remove, see talloc_unlink().
349  * Example:
350  *      unsigned int *a, *b, *c;
351  *      a = talloc(NULL, unsigned int);
352  *      b = talloc(NULL, unsigned int);
353  *      c = talloc(a, unsigned int);
354  *      // b also serves as a parent of c.
355  *      talloc_reference(b, c);
356  */
357 #define talloc_reference(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_reference((ctx),(ptr))
358
359 /**
360  * talloc_unlink: remove a specific parent from a talloc pointer.
361  * @context: the parent to remove
362  * @ptr: the talloc pointer
363  *
364  * The talloc_unlink() function removes a specific parent from @ptr. The
365  * context passed must either be a context used in talloc_reference() with this
366  * pointer, or must be a direct parent of @ptr.
367  *
368  * Note that if the parent has already been removed using talloc_free() then
369  * this function will fail and will return -1.  Likewise, if @ptr is NULL,
370  * then the function will make no modifications and return -1.
371  *
372  * Usually you can just use talloc_free() instead of talloc_unlink(), but
373  * sometimes it is useful to have the additional control on which parent is
374  * removed.
375  * Example:
376  *      unsigned int *a, *b, *c;
377  *      a = talloc(NULL, unsigned int);
378  *      b = talloc(NULL, unsigned int);
379  *      c = talloc(a, unsigned int);
380  *      // b also serves as a parent of c.
381  *      talloc_reference(b, c);
382  *      talloc_unlink(b, c);
383  */
384 int talloc_unlink(const void *context, void *ptr);
385
386 /**
387  * talloc_report - print a summary of memory used by a pointer
388  *
389  * The talloc_report() function prints a summary report of all memory
390  * used by @ptr.  One line of report is printed for each immediate child of
391  * @ptr, showing the total memory and number of blocks used by that child.
392  *
393  * You can pass NULL for the pointer, in which case a report is printed for the
394  * top level memory context, but only if talloc_enable_null_tracking() has been
395  * called.
396  *
397  * Example:
398  *      unsigned int *a, *b;
399  *      a = talloc(NULL, unsigned int);
400  *      b = talloc(a, unsigned int);
401  *      fprintf(stderr, "Summary of memory tree for a:\n");
402  *      talloc_report(a, stderr);
403  *
404  * See Also:
405  *      talloc_report_full
406  */
407 void talloc_report(const void *ptr, FILE *f);
408
409 /**
410  * talloc_ptrtype - allocate a size of memory suitable for this pointer
411  * @ctx: context to be parent of this allocation, or NULL.
412  * @ptr: the pointer whose type we are to allocate
413  *
414  * The talloc_ptrtype() macro should be used when you have a pointer and
415  * want to allocate memory to point at with this pointer. When compiling
416  * with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size()
417  * and talloc_get_name() will return the current location in the source file.
418  * and not the type.
419  *
420  * Example:
421  *      unsigned int *a = talloc_ptrtype(NULL, a);
422  */
423 #define talloc_ptrtype(ctx, ptr) (_TALLOC_TYPEOF(ptr))talloc_size(ctx, sizeof(*(ptr)))
424
425 /**
426  * talloc_new - create a new context
427  * @ctx: the context to use as a parent.
428  *
429  * This is a utility macro that creates a new memory context hanging off an
430  * exiting context, automatically naming it "talloc_new: __location__" where
431  * __location__ is the source line it is called from. It is particularly useful
432  * for creating a new temporary working context.
433  */
434 #define talloc_new(ctx) talloc_named_const(ctx, 0, "talloc_new: " __location__)
435
436 /**
437  * talloc_zero_size -  allocate a particular size of zeroed memory
438  *
439  * The talloc_zero_size() function is useful when you don't have a known type.
440  */
441 #define talloc_zero_size(ctx, size) _talloc_zero(ctx, size, __location__)
442
443 /**
444  * talloc_zero_array -  allocate an array of zeroed types
445  * @ctx: context to be parent of this allocation, or NULL.
446  * @type: the type to be allocated.
447  * @count: the number of elements to be allocated.
448  *
449  * Just like talloc_array, but zeroes the memory.
450  */
451 #define talloc_zero_array(ctx, type, count) (type *)_talloc_zero_array(ctx, sizeof(type), count, #type)
452
453 /**
454  * talloc_array_size - allocate an array of elements of the given size
455  * @ctx: context to be parent of this allocation, or NULL.
456  * @size: the size of each element
457  * @count: the number of elements to be allocated.
458  *
459  * Typeless form of talloc_array.
460  */
461 #define talloc_array_size(ctx, size, count) _talloc_array(ctx, size, count, __location__)
462
463 /**
464  * talloc_array_ptrtype - allocate an array of memory suitable for this pointer
465  * @ctx: context to be parent of this allocation, or NULL.
466  * @ptr: the pointer whose type we are to allocate
467  * @count: the number of elements for the array
468  *
469  * Like talloc_ptrtype(), except it allocates an array.
470  */
471 #define talloc_array_ptrtype(ctx, ptr, count) (_TALLOC_TYPEOF(ptr))talloc_array_size(ctx, sizeof(*(ptr)), count)
472
473 /**
474  * talloc_realloc - resize a talloc array
475  * @ctx: the parent to assign (if p is NULL)
476  * @p: the memory to reallocate
477  * @type: the type of the object to allocate
478  * @count: the number of objects to reallocate
479  *
480  * The talloc_realloc() macro changes the size of a talloc pointer. The "count"
481  * argument is the number of elements of type "type" that you want the
482  * resulting pointer to hold.
483  *
484  * talloc_realloc() has the following equivalences:
485  *
486  *  talloc_realloc(context, NULL, type, 1) ==> talloc(context, type);
487  *  talloc_realloc(context, NULL, type, N) ==> talloc_array(context, type, N);
488  *  talloc_realloc(context, ptr, type, 0)  ==> talloc_free(ptr);
489  *
490  * The "context" argument is only used if "ptr" is NULL, otherwise it is
491  * ignored.
492  *
493  * talloc_realloc() returns the new pointer, or NULL on failure. The call will
494  * fail either due to a lack of memory, or because the pointer has more than
495  * one parent (see talloc_reference()).
496  */
497 #define talloc_realloc(ctx, p, type, count) (type *)_talloc_realloc_array(ctx, p, sizeof(type), count, #type)
498
499 /**
500  * talloc_realloc_size - resize talloc memory
501  * @ctx: the parent to assign (if p is NULL)
502  * @ptr: the memory to reallocate
503  * @size: the new size of memory.
504  *
505  * The talloc_realloc_size() function is useful when the type is not known so
506  * the typesafe talloc_realloc() cannot be used.
507  */
508 #define talloc_realloc_size(ctx, ptr, size) _talloc_realloc(ctx, ptr, size, __location__)
509
510 /**
511  * talloc_strdup - duplicate a string
512  * @ctx: the talloc context for the new string
513  * @p: the string to copy
514  *
515  * The talloc_strdup() function is equivalent to:
516  *
517  *  ptr = talloc_size(ctx, strlen(p)+1);
518  *  if (ptr) memcpy(ptr, p, strlen(p)+1);
519  *
520  * This functions sets the name of the new pointer to the passed string. This
521  * is equivalent to:
522  *
523  *  talloc_set_name_const(ptr, ptr)
524  */
525 char *talloc_strdup(const void *t, const char *p);
526
527 /**
528  * talloc_strndup - duplicate a limited length of a string
529  * @ctx: the talloc context for the new string
530  * @p: the string to copy
531  * @n: the maximum length of the returned string.
532  *
533  * The talloc_strndup() function is the talloc equivalent of the C library
534  * function strndup(): the result will be truncated to @n characters before
535  * the nul terminator.
536  *
537  * This functions sets the name of the new pointer to the passed string. This
538  * is equivalent to:
539  *
540  *   talloc_set_name_const(ptr, ptr)
541  */
542 char *talloc_strndup(const void *t, const char *p, size_t n);
543
544 /**
545  * talloc_memdup - duplicate some talloc memory
546  *
547  * The talloc_memdup() function is equivalent to:
548  *
549  *  ptr = talloc_size(ctx, size);
550  *  if (ptr) memcpy(ptr, p, size);
551  */
552 #define talloc_memdup(t, p, size) _talloc_memdup(t, p, size, __location__)
553
554 /**
555  * talloc_asprintf - sprintf into a talloc buffer.
556  * @t: The context to allocate the buffer from
557  * @fmt: printf-style format for the buffer.
558  *
559  * The talloc_asprintf() function is the talloc equivalent of the C library
560  * function asprintf().
561  *
562  * This functions sets the name of the new pointer to the new string. This is
563  * equivalent to:
564  *
565  *   talloc_set_name_const(ptr, ptr)
566  */
567 char *talloc_asprintf(const void *t, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
568
569 /**
570  * talloc_append_string - concatenate onto a tallocated string 
571  * @orig: the tallocated string to append to
572  * @append: the string to add, or NULL to add nothing.
573  *
574  * The talloc_append_string() function appends the given formatted string to
575  * the given string.
576  *
577  * This function sets the name of the new pointer to the new string. This is
578  * equivalent to:
579  *
580  *    talloc_set_name_const(ptr, ptr)
581  */
582 char *talloc_append_string(char *orig, const char *append);
583
584 /**
585  * talloc_asprintf_append - sprintf onto the end of a talloc buffer.
586  * @s: The tallocated string buffer
587  * @fmt: printf-style format to append to the buffer.
588  *
589  * The talloc_asprintf_append() function appends the given formatted string to
590  * the given string.
591  *
592  * This functions sets the name of the new pointer to the new string. This is
593  * equivalent to:
594  *   talloc_set_name_const(ptr, ptr)
595  */
596 char *talloc_asprintf_append(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
597
598 /**
599  * talloc_vasprintf - vsprintf into a talloc buffer.
600  * @t: The context to allocate the buffer from
601  * @fmt: printf-style format for the buffer
602  * @ap: va_list arguments
603  *
604  * The talloc_vasprintf() function is the talloc equivalent of the C library
605  * function vasprintf()
606  *
607  * This functions sets the name of the new pointer to the new string. This is
608  * equivalent to:
609  *
610  *   talloc_set_name_const(ptr, ptr)
611  */
612 char *talloc_vasprintf(const void *t, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
613
614 /**
615  * talloc_vasprintf_append - sprintf onto the end of a talloc buffer.
616  * @t: The context to allocate the buffer from
617  * @fmt: printf-style format for the buffer
618  * @ap: va_list arguments
619  *
620  * The talloc_vasprintf_append() function is equivalent to
621  * talloc_asprintf_append(), except it takes a va_list.
622  */
623 char *talloc_vasprintf_append(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
624
625 /**
626  * talloc_set_type - force the name of a pointer to a particular type
627  * @ptr: the talloc pointer
628  * @type: the type whose name to set the ptr name to.
629  *
630  * This macro allows you to force the name of a pointer to be a particular
631  * type. This can be used in conjunction with talloc_get_type() to do type
632  * checking on void* pointers.
633  *
634  * It is equivalent to this:
635  *   talloc_set_name_const(ptr, #type)
636  */
637 #define talloc_set_type(ptr, type) talloc_set_name_const(ptr, #type)
638
639 /**
640  * talloc_get_type - convert a talloced pointer with typechecking
641  * @ptr: the talloc pointer
642  * @type: the type which we expect the talloced pointer to be.
643  *
644  * This macro allows you to do type checking on talloc pointers. It is
645  * particularly useful for void* private pointers. It is equivalent to this:
646  *
647  *   (type *)talloc_check_name(ptr, #type)
648  */
649 #define talloc_get_type(ptr, type) (type *)talloc_check_name(ptr, #type)
650
651 /**
652  * talloc_find_parent_byname - find a talloc parent by type
653  * @ptr: the talloc pointer
654  * @type: the type we're looking for
655  *
656  * Find a parent memory context of the current context that has the given
657  * name. This can be very useful in complex programs where it may be difficult
658  * to pass all information down to the level you need, but you know the
659  * structure you want is a parent of another context.
660  */
661 #define talloc_find_parent_bytype(ptr, type) (type *)talloc_find_parent_byname(ptr, #type)
662
663 /**
664  * talloc_increase_ref_count - hold a reference to a talloc pointer
665  * @ptr: the talloc pointer
666  *
667  * The talloc_increase_ref_count(ptr) function is exactly equivalent to:
668  *
669  *  talloc_reference(NULL, ptr);
670  *
671  * You can use either syntax, depending on which you think is clearer in your
672  * code.
673  *
674  * It returns 0 on success and -1 on failure.
675  */
676 int talloc_increase_ref_count(const void *ptr);
677
678 /**
679  * talloc_set_name - set the name for a talloc pointer
680  * @ptr: the talloc pointer
681  * @fmt: the printf-style format string for the name
682  *
683  * Each talloc pointer has a "name". The name is used principally for debugging
684  * purposes, although it is also possible to set and get the name on a pointer
685  * in as a way of "marking" pointers in your code.
686  *
687  * The main use for names on pointer is for "talloc reports". See
688  * talloc_report() and talloc_report_full() for details. Also see
689  * talloc_enable_leak_report() and talloc_enable_leak_report_full().
690  *
691  * The talloc_set_name() function allocates memory as a child of the
692  * pointer. It is logically equivalent to:
693  *   talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));
694  *
695  * Note that multiple calls to talloc_set_name() will allocate more memory
696  * without releasing the name. All of the memory is released when the ptr is
697  * freed using talloc_free().
698  */
699 const char *talloc_set_name(const void *ptr, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
700
701 /**
702  * talloc_set_name_const - set a talloc pointer name to a string constant
703  * @ptr: the talloc pointer to name
704  * @name: the strucng constant.
705  *
706  * The function talloc_set_name_const() is just like talloc_set_name(), but it
707  * takes a string constant, and is much faster. It is extensively used by the
708  * "auto naming" macros, such as talloc().
709  *
710  * This function does not allocate any memory. It just copies the supplied
711  * pointer into the internal representation of the talloc ptr. This means you
712  * must not pass a name pointer to memory that will disappear before the ptr is
713  * freed with talloc_free().
714  */
715 void talloc_set_name_const(const void *ptr, const char *name);
716
717 /**
718  * talloc_named - create a specifically-named talloc pointer
719  * @context: the parent context for the allocation
720  * @size: the size to allocate
721  * @fmt: the printf-style format for the name
722  *
723  * The talloc_named() function creates a named talloc pointer. It is equivalent
724  * to:
725  *
726  *   ptr = talloc_size(context, size);
727  *   talloc_set_name(ptr, fmt, ....);
728  */
729 void *talloc_named(const void *context, size_t size, 
730                    const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
731
732 /**
733  * talloc_named_const - create a specifically-named talloc pointer
734  * @context: the parent context for the allocation
735  * @size: the size to allocate
736  * @name: the string constant to use as the name
737  *
738  * This is equivalent to:
739  *
740  *   ptr = talloc_size(context, size);
741  *   talloc_set_name_const(ptr, name);
742  */
743 void *talloc_named_const(const void *context, size_t size, const char *name);
744
745 /**
746  * talloc_get_name - get the name of a talloc pointer
747  * @ptr: the talloc pointer
748  *
749  * This returns the current name for the given talloc pointer. See
750  * talloc_set_name() for details.
751  */
752 const char *talloc_get_name(const void *ptr);
753
754 /**
755  * talloc_check_name - check if a pointer has the specified name
756  * @ptr: the talloc pointer
757  * @name: the name to compare with the pointer's name
758  *
759  * This function checks if a pointer has the specified name. If it does then
760  * the pointer is returned. It it doesn't then NULL is returned.
761  */
762 void *talloc_check_name(const void *ptr, const char *name);
763
764 /**
765  * talloc_init - create a top-level context of particular name
766  * @fmt: the printf-style format of the name
767  *
768  * This function creates a zero length named talloc context as a top level
769  * context. It is equivalent to:
770  *
771  *   talloc_named(NULL, 0, fmt, ...);
772  */
773 void *talloc_init(const char *fmt, ...) PRINTF_ATTRIBUTE(1,2);
774
775 /**
776  * talloc_total_size - get the bytes used by the pointer and its children
777  * @ptr: the talloc pointer
778  *
779  * The talloc_total_size() function returns the total size in bytes used by
780  * this pointer and all child pointers. Mostly useful for debugging.
781  *
782  * Passing NULL is allowed, but it will only give a meaningful result if
783  * talloc_enable_leak_report() or talloc_enable_leak_report_full() has been
784  * called.
785  */
786 size_t talloc_total_size(const void *ptr);
787
788 /**
789  * talloc_total_blocks - get the number of allocations for the pointer
790  * @ptr: the talloc pointer
791  *
792  * The talloc_total_blocks() function returns the total allocations used by
793  * this pointer and all child pointers. Mostly useful for debugging. For
794  * example, a pointer with no children will return "1".
795  *
796  * Passing NULL is allowed, but it will only give a meaningful result if
797  * talloc_enable_leak_report() or talloc_enable_leak_report_full() has been
798  * called.
799  */
800 size_t talloc_total_blocks(const void *ptr);
801
802 /**
803  * talloc_report_depth_cb - walk the entire talloc tree under a talloc pointer
804  * @ptr: the talloc pointer to recurse under
805  * @depth: the current depth of traversal
806  * @max_depth: maximum depth to traverse, or -1 for no maximum
807  * @callback: the function to call on each pointer
808  * @private_data: pointer to hand to @callback.
809  *
810  * This provides a more flexible reports than talloc_report(). It will
811  * recursively call the callback for the entire tree of memory referenced by
812  * the pointer. References in the tree are passed with is_ref = 1 and the
813  * pointer that is referenced.
814  *
815  * You can pass NULL for the pointer, in which case a report is printed for the
816  * top level memory context, but only if talloc_enable_leak_report() or
817  * talloc_enable_leak_report_full() has been called.
818  *
819  * The recursion is stopped when depth >= max_depth.  max_depth = -1 means only
820  * stop at leaf nodes.
821  */
822 void talloc_report_depth_cb(const void *ptr, int depth, int max_depth,
823                             void (*callback)(const void *ptr,
824                                              int depth, int max_depth,
825                                              int is_ref,
826                                              void *private_data),
827                             void *private_data);
828
829 /**
830  * talloc_report_depth_file - report talloc usage to a maximum depth
831  * @ptr: the talloc pointer to recurse under
832  * @depth: the current depth of traversal
833  * @max_depth: maximum depth to traverse, or -1 for no maximum
834  * @f: the file to report to
835  *
836  * This provides a more flexible reports than talloc_report(). It will let you
837  * specify the depth and max_depth.
838  */
839 void talloc_report_depth_file(const void *ptr, int depth, int max_depth, FILE *f);
840
841 /**
842  * talloc_enable_null_tracking - enable tracking of top-level tallocs
843  *
844  * This enables tracking of the NULL memory context without enabling leak
845  * reporting on exit. Useful for when you want to do your own leak reporting
846  * call via talloc_report_null_full();
847  */
848 void talloc_enable_null_tracking(void);
849
850 /**
851  * talloc_disable_null_tracking - enable tracking of top-level tallocs
852  *
853  * This disables tracking of the NULL memory context.
854  */
855 void talloc_disable_null_tracking(void);
856
857 /**
858  * talloc_enable_leak_report - call talloc_report on program exit
859  *
860  * This enables calling of talloc_report(NULL, stderr) when the program
861  * exits. In Samba4 this is enabled by using the --leak-report command line
862  * option.
863  *
864  * For it to be useful, this function must be called before any other talloc
865  * function as it establishes a "null context" that acts as the top of the
866  * tree. If you don't call this function first then passing NULL to
867  * talloc_report() or talloc_report_full() won't give you the full tree
868  * printout.
869  *
870  * Here is a typical talloc report:
871  *
872  * talloc report on 'null_context' (total 267 bytes in 15 blocks)
873  *         libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
874  *         libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
875  *         iconv(UTF8,CP850)              contains     42 bytes in   2 blocks
876  *         libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
877  *         iconv(CP850,UTF8)              contains     42 bytes in   2 blocks
878  *         iconv(UTF8,UTF-16LE)           contains     45 bytes in   2 blocks
879  *         iconv(UTF-16LE,UTF8)           contains     45 bytes in   2 blocks
880  */
881 void talloc_enable_leak_report(void);
882
883 /**
884  * talloc_enable_leak_report - call talloc_report_full on program exit
885  *
886  * This enables calling of talloc_report_full(NULL, stderr) when the program
887  * exits. In Samba4 this is enabled by using the --leak-report-full command
888  * line option.
889  *
890  * For it to be useful, this function must be called before any other talloc
891  * function as it establishes a "null context" that acts as the top of the
892  * tree. If you don't call this function first then passing NULL to
893  * talloc_report() or talloc_report_full() won't give you the full tree
894  * printout.
895  *
896  * Here is a typical full report:
897  *
898  * full talloc report on 'root' (total 18 bytes in 8 blocks)
899  *    p1                        contains     18 bytes in   7 blocks (ref 0)
900  *         r1                        contains     13 bytes in   2 blocks (ref 0)
901  *             reference to: p2
902  *         p2                        contains      1 bytes in   1 blocks (ref 1)
903  *         x3                        contains      1 bytes in   1 blocks (ref 0)
904  *         x2                        contains      1 bytes in   1 blocks (ref 0)
905  *         x1                        contains      1 bytes in   1 blocks (ref 0)
906  */
907 void talloc_enable_leak_report_full(void);
908
909 /**
910  * talloc_autofree_context - a context which will be freed at exit
911  *
912  * This is a handy utility function that returns a talloc context which will be
913  * automatically freed on program exit. This can be used to reduce the noise in
914  * memory leak reports.
915  */
916 void *talloc_autofree_context(void);
917
918 /**
919  * talloc_get_size - get the size of an allocation
920  * @ctx: the talloc pointer whose allocation to measure.
921  *
922  * This function lets you know the amount of memory alloced so far by this
923  * context. It does NOT account for subcontext memory.  This can be used to
924  * calculate the size of an array.
925  */
926 size_t talloc_get_size(const void *ctx);
927
928 /**
929  * talloc_find_parent_byname - find a parent of this context with this name
930  * @ctx: the context whose ancestors to search
931  * @name: the name to look for
932  *
933  * Find a parent memory context of @ctx that has the given name. This can be
934  * very useful in complex programs where it may be difficult to pass all
935  * information down to the level you need, but you know the structure you want
936  * is a parent of another context.
937  */
938 void *talloc_find_parent_byname(const void *ctx, const char *name);
939
940 /**
941  * talloc_add_external - create an externally allocated node
942  * @ctx: the parent
943  * @realloc: the realloc() equivalent
944  * @lock: the call to lock before manipulation of external nodes
945  * @unlock: the call to unlock after manipulation of external nodes
946  *
947  * talloc_add_external() creates a node which uses a separate allocator.  All
948  * children allocated from that node will also use that allocator.
949  *
950  * Note: Currently there is only one external allocator, not per-node,
951  * and it is set with this function.
952  *
953  * @lock is handed a pointer which was previous returned from your realloc
954  * function; you should use that to figure out which lock to get if you have
955  * multiple external pools.
956  *
957  * The parent pointers in realloc is the talloc pointer of the parent, if any.
958  */
959 void *talloc_add_external(const void *ctx,
960                           void *(*realloc)(const void *parent,
961                                            void *ptr, size_t),
962                           void (*lock)(const void *p),
963                           void (*unlock)(void));
964
965 /* The following definitions come from talloc.c  */
966 void *_talloc(const void *context, size_t size);
967 void _talloc_set(void *ptr, const void *ctx, size_t size, const char *name);
968 void _talloc_set_destructor(const void *ptr, int (*destructor)(void *));
969 size_t talloc_reference_count(const void *ptr);
970 void *_talloc_reference(const void *context, const void *ptr);
971
972 void *_talloc_realloc(const void *context, void *ptr, size_t size, const char *name);
973 void *talloc_parent(const void *ptr);
974 const char *talloc_parent_name(const void *ptr);
975 void *_talloc_steal(const void *new_ctx, const void *ptr);
976 void *_talloc_move(const void *new_ctx, const void *pptr);
977 void *_talloc_zero(const void *ctx, size_t size, const char *name);
978 void *_talloc_memdup(const void *t, const void *p, size_t size, const char *name);
979 void *_talloc_array(const void *ctx, size_t el_size, unsigned count, const char *name);
980 void *_talloc_zero_array(const void *ctx, size_t el_size, unsigned count, const char *name);
981 void *_talloc_realloc_array(const void *ctx, void *ptr, size_t el_size, unsigned count, const char *name);
982 void *talloc_realloc_fn(const void *context, void *ptr, size_t size);
983 void talloc_show_parents(const void *context, FILE *file);
984 int talloc_is_parent(const void *context, const void *ptr);
985
986 #endif /* CCAN_TALLOC_H */