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