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