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