523a4840d34dbecf8bfe9ab46ec5fffb445ec59b
[ira/wip.git] / lib / talloc / talloc.h
1 #ifndef _TALLOC_H_
2 #define _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 3 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, see <http://www.gnu.org/licenses/>.
26 */
27
28 #include <stdlib.h>
29 #include <stdio.h>
30 #include <stdarg.h>
31
32 /** \mainpage
33  *
34  * \section intro_sec Introduction
35  *
36  * Talloc is a hierarchical, reference counted memory pool system with
37  * destructors. Quite a mouthful really, but not too bad once you get used to
38  * it.
39  *
40  * Perhaps the biggest difference from other memory pool systems is that there
41  * is no distinction between a "talloc context" and a "talloc pointer". Any
42  * pointer returned from talloc() is itself a valid talloc context. This means
43  * you can do this:
44  *
45  * \code
46  * struct foo *X = talloc(mem_ctx, struct foo);
47  * X->name = talloc_strdup(X, "foo");
48  * \endcode
49  *
50  * and the pointer X->name would be a "child" of the talloc context "X" which
51  * is itself a child of mem_ctx. So if you do talloc_free(mem_ctx) then it is
52  * all destroyed, whereas if you do talloc_free(X) then just X and X->name are
53  * destroyed, and if you do talloc_free(X->name) then just the name element of
54  * X is destroyed.
55  *
56  * If you think about this, then what this effectively gives you is an n-ary
57  * tree, where you can free any part of the tree with talloc_free().
58  *
59  * \section named_blocks Named blocks
60  *
61  * Every talloc chunk has a name that can be used as a dynamic type-checking
62  * system. If for some reason like a callback function you had to cast a
63  * "struct foo *" to a "void *" variable, later you can safely reassign the
64  * "void *" pointer to a "struct foo *" by using the talloc_get_type() or
65  * talloc_get_type_abort() macros.
66  *
67  * \code
68  * struct foo *X = talloc_get_type_abort(ptr, struct foo);
69  * \endcode
70  *
71  * This will abort if "ptr" does not contain a pointer that has been created
72  * with talloc(mem_ctx, struct foo).
73  *
74  * \section multi_threading Multi-Threading
75  *
76  * talloc itself does not deal with threads. It is thread-safe (assuming the
77  * underlying "malloc" is), as long as each thread uses different memory
78  * contexts.
79  *
80  * If two threads uses the same context then they need to synchronize in order
81  * to be safe. In particular:
82  *
83  *
84  * - when using talloc_enable_leak_report(), giving directly NULL as a
85  *   parent context implicitly refers to a hidden "null context" global
86  *   variable, so this should not be used in a multi-threaded environment
87  *   without proper synchronization
88  * - the context returned by talloc_autofree_context() is also global so
89  *   shouldn't be used by several threads simultaneously without
90  *   synchronization.
91  */
92
93 /** \defgroup talloc_basic Basic Talloc Routines
94  *
95  * This module contains the basic talloc routines that are used in everyday
96  * programming.
97  */
98
99 /** \defgroup talloc_ref Talloc References
100  *
101  * This module contains the definitions around talloc references
102  */
103
104 /** \defgroup talloc_array Array routines
105  *
106  * Talloc contains some handy helpers for handling Arrays conveniently
107  */
108
109 /** \defgroup talloc_string String handling routines
110  *
111  * Talloc contains some handy string handling functions
112  */
113
114 /** \defgroup talloc_debug Debugging support routines
115  *
116  * To aid memory debugging, talloc contains routines to inspect the currently
117  * allocated memory hierarchy.
118  */
119
120 /** \defgroup todo Default group of undocumented stuff
121  *
122  * This should be empty...
123  */
124
125 /*\{*/
126
127 /**
128  * \typedef TALLOC_CTX
129  * \brief Define a talloc parent type
130  * \ingroup talloc_basic
131  *
132  * As talloc is a hierarchial memory allocator, every talloc chunk is a
133  * potential parent to other talloc chunks. So defining a separate type for a
134  * talloc chunk is not strictly necessary. TALLOC_CTX is defined nevertheless,
135  * as it provides an indicator for function arguments. You will frequently
136  * write code like
137  *
138  * \code
139  * struct foo *foo_create(TALLOC_CTX *mem_ctx)
140  * {
141  *      struct foo *result;
142  *      result = talloc(mem_ctx, struct foo);
143  *      if (result == NULL) return NULL;
144  *      ... initialize foo ...
145  *      return result;
146  * }
147  * \endcode
148  *
149  * In this type of allocating functions it is handy to have a general
150  * TALLOC_CTX type to indicate which parent to put allocated structures on.
151  */
152 typedef void TALLOC_CTX;
153
154 /*
155   this uses a little trick to allow __LINE__ to be stringified
156 */
157 #ifndef __location__
158 #define __TALLOC_STRING_LINE1__(s)    #s
159 #define __TALLOC_STRING_LINE2__(s)   __TALLOC_STRING_LINE1__(s)
160 #define __TALLOC_STRING_LINE3__  __TALLOC_STRING_LINE2__(__LINE__)
161 #define __location__ __FILE__ ":" __TALLOC_STRING_LINE3__
162 #endif
163
164 #ifndef TALLOC_DEPRECATED
165 #define TALLOC_DEPRECATED 0
166 #endif
167
168 #ifndef PRINTF_ATTRIBUTE
169 #if (__GNUC__ >= 3)
170 /** Use gcc attribute to check printf fns.  a1 is the 1-based index of
171  * the parameter containing the format, and a2 the index of the first
172  * argument. Note that some gcc 2.x versions don't handle this
173  * properly **/
174 #define PRINTF_ATTRIBUTE(a1, a2) __attribute__ ((format (__printf__, a1, a2)))
175 #else
176 #define PRINTF_ATTRIBUTE(a1, a2)
177 #endif
178 #endif
179
180 /**
181  * \def talloc_set_destructor
182  * \brief Assign a function to be called when a chunk is freed
183  * \param ptr The talloc chunk to add a destructor to
184  * \param function The destructor function to be called
185  * \ingroup talloc_basic
186  *
187  * The function talloc_set_destructor() sets the "destructor" for the pointer
188  * "ptr". A destructor is a function that is called when the memory used by a
189  * pointer is about to be released. The destructor receives the pointer as an
190  * argument, and should return 0 for success and -1 for failure.
191  *
192  * The destructor can do anything it wants to, including freeing other pieces
193  * of memory. A common use for destructors is to clean up operating system
194  * resources (such as open file descriptors) contained in the structure the
195  * destructor is placed on.
196  *
197  * You can only place one destructor on a pointer. If you need more than one
198  * destructor then you can create a zero-length child of the pointer and place
199  * an additional destructor on that.
200  *
201  * To remove a destructor call talloc_set_destructor() with NULL for the
202  * destructor.
203  *
204  * If your destructor attempts to talloc_free() the pointer that it is the
205  * destructor for then talloc_free() will return -1 and the free will be
206  * ignored. This would be a pointless operation anyway, as the destructor is
207  * only called when the memory is just about to go away.
208  */
209
210 /**
211  * \def talloc_steal(ctx, ptr)
212  * \brief Change a talloc chunk's parent
213  * \param ctx The new parent context
214  * \param ptr The talloc chunk to move
215  * \return ptr
216  * \ingroup talloc_basic
217  *
218  * The talloc_steal() function changes the parent context of a talloc
219  * pointer. It is typically used when the context that the pointer is
220  * currently a child of is going to be freed and you wish to keep the
221  * memory for a longer time.
222  *
223  * The talloc_steal() function returns the pointer that you pass it. It
224  * does not have any failure modes.
225  *
226  * NOTE: It is possible to produce loops in the parent/child relationship
227  * if you are not careful with talloc_steal(). No guarantees are provided
228  * as to your sanity or the safety of your data if you do this.
229  *
230  * To make the changed hierarchy less error-prone, you might consider to use
231  * talloc_move().
232  *
233  * talloc_steal (ctx, NULL) will return NULL with no sideeffects.
234  */
235
236 /* try to make talloc_set_destructor() and talloc_steal() type safe,
237    if we have a recent gcc */
238 #if (__GNUC__ >= 3)
239 #define _TALLOC_TYPEOF(ptr) __typeof__(ptr)
240 #define talloc_set_destructor(ptr, function)                                  \
241         do {                                                                  \
242                 int (*_talloc_destructor_fn)(_TALLOC_TYPEOF(ptr)) = (function);       \
243                 _talloc_set_destructor((ptr), (int (*)(void *))_talloc_destructor_fn); \
244         } while(0)
245 /* this extremely strange macro is to avoid some braindamaged warning
246    stupidity in gcc 4.1.x */
247 #define talloc_steal(ctx, ptr) ({ _TALLOC_TYPEOF(ptr) __talloc_steal_ret = (_TALLOC_TYPEOF(ptr))_talloc_steal((ctx),(ptr)); __talloc_steal_ret; })
248 #else
249 #define talloc_set_destructor(ptr, function) \
250         _talloc_set_destructor((ptr), (int (*)(void *))(function))
251 #define _TALLOC_TYPEOF(ptr) void *
252 #define talloc_steal(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_steal((ctx),(ptr))
253 #endif
254
255 /**
256  * \def talloc_reference(ctx, ptr)
257  * \brief Create an additional talloc parent to a pointer
258  * \param ctx The additional parent
259  * \param ptr The pointer you want to create an additional parent for
260  * \return ptr
261  * \ingroup talloc_ref
262  *
263  * The talloc_reference() function makes "context" an additional parent of
264  * "ptr".
265  *
266  * The return value of talloc_reference() is always the original pointer
267  * "ptr", unless talloc ran out of memory in creating the reference in which
268  * case it will return NULL (each additional reference consumes around 48
269  * bytes of memory on intel x86 platforms).
270  *
271  * If "ptr" is NULL, then the function is a no-op, and simply returns NULL.
272  *
273  * After creating a reference you can free it in one of the following ways:
274  *
275  * - you can talloc_free() any parent of the original pointer. That
276  *   will reduce the number of parents of this pointer by 1, and will
277  *   cause this pointer to be freed if it runs out of parents.
278  *
279  * - you can talloc_free() the pointer itself. That will destroy the
280  *   most recently established parent to the pointer and leave the
281  *   pointer as a child of its current parent.
282  *
283  * For more control on which parent to remove, see talloc_unlink()
284  */
285 #define talloc_reference(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_reference((ctx),(ptr))
286
287
288 /**
289  * \def talloc_move(ctx, ptr)
290  * \brief Change a talloc chunk's parent
291  * \param ctx The new parent context
292  * \param ptr Pointer to the talloc chunk to move
293  * \return ptr
294  * \ingroup talloc_basic
295  *
296  * talloc_move() has the same effect as talloc_steal(), and additionally sets
297  * the source pointer to NULL. You would use it like this:
298  *
299  * \code
300  * struct foo *X = talloc(tmp_ctx, struct foo);
301  * struct foo *Y;
302  * Y = talloc_move(new_ctx, &X);
303  * \endcode
304  */
305 #define talloc_move(ctx, ptr) (_TALLOC_TYPEOF(*(ptr)))_talloc_move((ctx),(void *)(ptr))
306
307 /* useful macros for creating type checked pointers */
308
309 /**
310  * \def talloc(ctx, type)
311  * \brief Main entry point to allocate structures
312  * \param ctx The talloc context to hang the result off
313  * \param type The type that we want to allocate
314  * \return Pointer to a piece of memory, properly cast to "type *"
315  * \ingroup talloc_basic
316  *
317  * The talloc() macro is the core of the talloc library. It takes a memory
318  * context and a type, and returns a pointer to a new area of memory of the
319  * given type.
320  *
321  * The returned pointer is itself a talloc context, so you can use it as the
322  * context argument to more calls to talloc if you wish.
323  *
324  * The returned pointer is a "child" of the supplied context. This means that
325  * if you talloc_free() the context then the new child disappears as
326  * well. Alternatively you can free just the child.
327  *
328  * The context argument to talloc() can be NULL, in which case a new top
329  * level context is created.
330  */
331 #define talloc(ctx, type) (type *)talloc_named_const(ctx, sizeof(type), #type)
332
333 /**
334  * \def talloc_size(ctx, size)
335  * \brief Untyped allocation
336  * \param ctx The talloc context to hang the result off
337  * \param size Number of char's that you want to allocate
338  * \return The allocated memory chunk
339  * \ingroup talloc_basic
340  *
341  * The function talloc_size() should be used when you don't have a convenient
342  * type to pass to talloc(). Unlike talloc(), it is not type safe (as it
343  * returns a void *), so you are on your own for type checking.
344  */
345 #define talloc_size(ctx, size) talloc_named_const(ctx, size, __location__)
346
347 /**
348  * \def talloc_ptrtype(ctx, ptr)
349  * \brief Allocate into a typed pointer
350  * \param ctx The talloc context to hang the result off
351  * \param ptr The pointer you want to assign the result to
352  * \result The allocated memory chunk, properly cast
353  * \ingroup talloc_basic
354  *
355  * The talloc_ptrtype() macro should be used when you have a pointer and
356  * want to allocate memory to point at with this pointer. When compiling
357  * with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size()
358  * and talloc_get_name() will return the current location in the source file.
359  * and not the type.
360  */
361 #define talloc_ptrtype(ctx, ptr) (_TALLOC_TYPEOF(ptr))talloc_size(ctx, sizeof(*(ptr)))
362
363 /**
364  * \def talloc_new(ctx)
365  * \brief Allocate a new 0-sized talloc chunk
366  * \param ctx The talloc parent context
367  * \return A new talloc chunk
368  * \ingroup talloc_basic
369  *
370  * This is a utility macro that creates a new memory context hanging off an
371  * exiting context, automatically naming it "talloc_new: __location__" where
372  * __location__ is the source line it is called from. It is particularly
373  * useful for creating a new temporary working context.
374  */
375 #define talloc_new(ctx) talloc_named_const(ctx, 0, "talloc_new: " __location__)
376
377 /**
378  * \def talloc_zero(ctx, type)
379  * \brief Allocate a 0-initizialized structure
380  * \param ctx The talloc context to hang the result off
381  * \param type The type that we want to allocate
382  * \return Pointer to a piece of memory, properly cast to "type *"
383  * \ingroup talloc_basic
384  *
385  * The talloc_zero() macro is equivalent to:
386  *
387  * \code
388  * ptr = talloc(ctx, type);
389  * if (ptr) memset(ptr, 0, sizeof(type));
390  * \endcode
391  */
392 #define talloc_zero(ctx, type) (type *)_talloc_zero(ctx, sizeof(type), #type)
393
394 /**
395  * \def talloc_zero_size(ctx, size)
396  * \brief Untyped, 0-initialized allocation
397  * \param ctx The talloc context to hang the result off
398  * \param size Number of char's that you want to allocate
399  * \return The allocated memory chunk
400  * \ingroup talloc_basic
401  *
402  * The talloc_zero_size() macro is equivalent to:
403  *
404  * \code
405  * ptr = talloc_size(ctx, size);
406  * if (ptr) memset(ptr, 0, size);
407  * \endcode
408  */
409
410 #define talloc_zero_size(ctx, size) _talloc_zero(ctx, size, __location__)
411
412 #define talloc_zero_array(ctx, type, count) (type *)_talloc_zero_array(ctx, sizeof(type), count, #type)
413
414 /**
415  * \def talloc_array(ctx, type, count)
416  * \brief Allocate an array
417  * \param ctx The talloc context to hang the result off
418  * \param type The type that we want to allocate
419  * \param count The number of "type" elements you want to allocate
420  * \return The allocated result, properly cast to "type *"
421  * \ingroup talloc_array
422  *
423  * The talloc_array() macro is equivalent to::
424  *
425  * \code
426  * (type *)talloc_size(ctx, sizeof(type) * count);
427  * \endcode
428  *
429  * except that it provides integer overflow protection for the multiply,
430  * returning NULL if the multiply overflows.
431  */
432 #define talloc_array(ctx, type, count) (type *)_talloc_array(ctx, sizeof(type), count, #type)
433
434 /**
435  * \def talloc_array_size(ctx, size, count)
436  * \brief Allocate an array
437  * \param ctx The talloc context to hang the result off
438  * \param size The size of an array element
439  * \param count The number of "type" elements you want to allocate
440  * \return The allocated result, properly cast to "type *"
441  * \ingroup talloc_array
442  *
443  * The talloc_array_size() function is useful when the type is not
444  * known. It operates in the same way as talloc_array(), but takes a size
445  * instead of a type.
446  */
447 #define talloc_array_size(ctx, size, count) _talloc_array(ctx, size, count, __location__)
448
449 /**
450  * \def talloc_array_ptrtype(ctx, ptr, count)
451  * \brief Allocate an array into a typed pointer
452  * \param ctx The talloc context to hang the result off
453  * \param ptr The pointer you want to assign the result to
454  * \param count The number of elements you want to allocate
455  * \result The allocated memory chunk, properly cast
456  * \ingroup talloc_array
457  *
458  * The talloc_array_ptrtype() macro should be used when you have a pointer to
459  * an array and want to allocate memory of an array to point at with this
460  * pointer. When compiling with gcc >= 3 it is typesafe. Note this is a
461  * wrapper of talloc_array_size() and talloc_get_name() will return the
462  * current location in the source file.  and not the type.
463  */
464 #define talloc_array_ptrtype(ctx, ptr, count) (_TALLOC_TYPEOF(ptr))talloc_array_size(ctx, sizeof(*(ptr)), count)
465
466 /**
467  * \def talloc_array_length(ctx)
468  * \brief Return the number of elements in a talloc'ed array
469  * \param ctx The talloc'ed array
470  * \return The number of elements in ctx
471  * \ingroup talloc_array
472  *
473  * A talloc chunk carries its own size, so for talloc'ed arrays it is not
474  * necessary to store the number of elements explicitly.
475  */
476 #define talloc_array_length(ctx) ((ctx) ? talloc_get_size(ctx)/sizeof(*ctx) : 0)
477
478 /**
479  * \def talloc_realloc(ctx, p, type, count)
480  * \brief Change the size of a talloc array
481  * \param ctx The parent context used if "p" is NULL
482  * \param p The chunk to be resized
483  * \param type The type of the array element inside p
484  * \param count The intended number of array elements
485  * \return The new array
486  * \ingroup talloc_array
487  *
488  * The talloc_realloc() macro changes the size of a talloc
489  * pointer. The "count" argument is the number of elements of type "type"
490  * that you want the resulting pointer to hold.
491  *
492  * talloc_realloc() has the following equivalences::
493  *
494  * \code
495  * talloc_realloc(context, NULL, type, 1) ==> talloc(context, type);
496  * talloc_realloc(context, NULL, type, N) ==> talloc_array(context, type, N);
497  * talloc_realloc(context, ptr, type, 0)  ==> talloc_free(ptr);
498  * \endcode
499  *
500  * The "context" argument is only used if "ptr" is NULL, otherwise it is
501  * ignored.
502  *
503  * talloc_realloc() returns the new pointer, or NULL on failure. The call
504  * will fail either due to a lack of memory, or because the pointer has
505  * more than one parent (see talloc_reference()).
506  */
507 #define talloc_realloc(ctx, p, type, count) (type *)_talloc_realloc_array(ctx, p, sizeof(type), count, #type)
508
509 /**
510  * \def talloc_realloc_size(ctx, ptr, size)
511  * \brief Untyped realloc
512  * \param ctx The parent context used if "ptr" is NULL
513  * \param ptr The chunk to be resized
514  * \param size The new chunk size
515  * \return The new chunk
516  * \ingroup talloc_array
517  *
518  * The talloc_realloc_size() function is useful when the type is not known so
519  * the typesafe talloc_realloc() cannot be used.
520  */
521 #define talloc_realloc_size(ctx, ptr, size) _talloc_realloc(ctx, ptr, size, __location__)
522
523 /**
524  * \def talloc_memdup(t, p, size)
525  * \brief Duplicate a memory area into a talloc chunk
526  * \param t The talloc context to hang the result off
527  * \param p The memory chunk you want to duplicate
528  * \param size Number of char's that you want copy
529  * \return The allocated memory chunk
530  * \ingroup talloc_basic
531  *
532  * The talloc_memdup() function is equivalent to::
533  *
534  * \code
535  * ptr = talloc_size(ctx, size);
536  * if (ptr) memcpy(ptr, p, size);
537  * \endcode
538  */
539 #define talloc_memdup(t, p, size) _talloc_memdup(t, p, size, __location__)
540
541 /**
542  * \def talloc_set_type(ptr, type)
543  * \brief Assign a type to a talloc chunk
544  * \param ptr The talloc chunk to assign the type to
545  * \param type The type to assign
546  * \ingroup talloc_basic
547  *
548  * This macro allows you to force the name of a pointer to be a
549  * particular type. This can be used in conjunction with
550  * talloc_get_type() to do type checking on void* pointers.
551  *
552  * It is equivalent to this::
553  *
554  * \code
555  * talloc_set_name_const(ptr, #type)
556  * \endcode
557  */
558 #define talloc_set_type(ptr, type) talloc_set_name_const(ptr, #type)
559
560 /**
561  * \def talloc_get_type(ptr, type)
562  * \brief Get a typed pointer out of a talloc pointer
563  * \param ptr The talloc pointer to check
564  * \param type The type to check against
565  * \return ptr, properly cast, or NULL
566  * \ingroup talloc_basic
567  *
568  * This macro allows you to do type checking on talloc pointers. It is
569  * particularly useful for void* private pointers. It is equivalent to
570  * this:
571  *
572  * \code
573  * (type *)talloc_check_name(ptr, #type)
574  * \endcode
575  */
576
577 #define talloc_get_type(ptr, type) (type *)talloc_check_name(ptr, #type)
578
579 /**
580  * \def talloc_get_type_abort(ptr, type)
581  * \brief Helper macro to safely turn a void * into a typed pointer
582  * \param ptr The void * to convert
583  * \param type The type that this chunk contains
584  * \return Same value as ptr, type-checked and properly cast
585  * \ingroup talloc_basic
586  *
587  * This macro is used together with talloc(mem_ctx, struct foo). If you had to
588  * assing the talloc chunk pointer to some void * variable,
589  * talloc_get_type_abort() is the recommended way to get the convert the void
590  * pointer back to a typed pointer.
591  */
592 #define talloc_get_type_abort(ptr, type) (type *)_talloc_get_type_abort(ptr, #type, __location__)
593
594 /**
595  * \def talloc_find_parent_bytype(ptr, type)
596  * \brief Find a parent context by type
597  * \param ptr The talloc chunk to start from
598  * \param type The type of the parent to look for
599  * \ingroup talloc_basic
600  *
601  * Find a parent memory context of the current context that has the given
602  * name. This can be very useful in complex programs where it may be
603  * difficult to pass all information down to the level you need, but you
604  * know the structure you want is a parent of another context.
605  *
606  * Like talloc_find_parent_byname() but takes a type, making it typesafe.
607  */
608 #define talloc_find_parent_bytype(ptr, type) (type *)talloc_find_parent_byname(ptr, #type)
609
610 #if TALLOC_DEPRECATED
611 #define talloc_zero_p(ctx, type) talloc_zero(ctx, type)
612 #define talloc_p(ctx, type) talloc(ctx, type)
613 #define talloc_array_p(ctx, type, count) talloc_array(ctx, type, count)
614 #define talloc_realloc_p(ctx, p, type, count) talloc_realloc(ctx, p, type, count)
615 #define talloc_destroy(ctx) talloc_free(ctx)
616 #define talloc_append_string(c, s, a) (s?talloc_strdup_append(s,a):talloc_strdup(c, a))
617 #endif
618
619 #define TALLOC_FREE(ctx) do { talloc_free(ctx); ctx=NULL; } while(0)
620
621 /* The following definitions come from talloc.c  */
622 void *_talloc(const void *context, size_t size);
623 void *talloc_pool(const void *context, size_t size);
624 void _talloc_set_destructor(const void *ptr, int (*destructor)(void *));
625
626 /**
627  * \brief Increase the reference count of a talloc chunk
628  * \param ptr
629  * \return success?
630  * \ingroup talloc_ref
631  *
632  * The talloc_increase_ref_count(ptr) function is exactly equivalent to:
633  *
634  * \code
635  * talloc_reference(NULL, ptr);
636  * \endcode
637  *
638  * You can use either syntax, depending on which you think is clearer in
639  * your code.
640  *
641  * It returns 0 on success and -1 on failure.
642  */
643 int talloc_increase_ref_count(const void *ptr);
644
645 /**
646  * \brief Return the number of references to a talloc chunk
647  * \param ptr The chunk you are interested in
648  * \return Number of refs
649  * \ingroup talloc_ref
650  */
651 size_t talloc_reference_count(const void *ptr);
652 void *_talloc_reference(const void *context, const void *ptr);
653
654 /**
655  * \brief Remove a specific parent from a talloc chunk
656  * \param context The talloc parent to remove
657  * \param ptr The talloc ptr you want to remove the parent from
658  * \ingroup talloc_ref
659  *
660  * The talloc_unlink() function removes a specific parent from ptr. The
661  * context passed must either be a context used in talloc_reference() with
662  * this pointer, or must be a direct parent of ptr.
663  *
664  * Note that if the parent has already been removed using talloc_free() then
665  * this function will fail and will return -1.  Likewise, if "ptr" is NULL,
666  * then the function will make no modifications and return -1.
667  *
668  * Usually you can just use talloc_free() instead of talloc_unlink(), but
669  * sometimes it is useful to have the additional control on which parent is
670  * removed.
671  */
672 int talloc_unlink(const void *context, void *ptr);
673
674 /**
675  * \brief Assign a name to a talloc chunk
676  * \param ptr The talloc chunk to assign a name to
677  * \param fmt Format string for the name
678  * \param ... printf-style additional arguments
679  * \return The assigned name
680  * \ingroup talloc_basic
681  *
682  * Each talloc pointer has a "name". The name is used principally for
683  * debugging purposes, although it is also possible to set and get the name on
684  * a pointer in as a way of "marking" pointers in your code.
685  *
686  * The main use for names on pointer is for "talloc reports". See
687  * talloc_report() and talloc_report_full() for details. Also see
688  * talloc_enable_leak_report() and talloc_enable_leak_report_full().
689  *
690  * The talloc_set_name() function allocates memory as a child of the
691  * pointer. It is logically equivalent to:
692  *
693  * \code
694  * talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));
695  * \endcode
696  *
697  * Note that multiple calls to talloc_set_name() will allocate more memory
698  * without releasing the name. All of the memory is released when the ptr is
699  * freed using talloc_free().
700  */
701 const char *talloc_set_name(const void *ptr, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
702
703 /**
704  * \brief Assign a name to a talloc chunk
705  * \param ptr The talloc chunk to assign a name to
706  * \param name Format string for the name
707  * \ingroup talloc_basic
708  *
709  * The function talloc_set_name_const() is just like talloc_set_name(), but it
710  * takes a string constant, and is much faster. It is extensively used by the
711  * "auto naming" macros, such as talloc_p().
712  *
713  * This function does not allocate any memory. It just copies the supplied
714  * pointer into the internal representation of the talloc ptr. This means you
715  * must not pass a name pointer to memory that will disappear before the ptr
716  * is freed with talloc_free().
717  */
718 void talloc_set_name_const(const void *ptr, const char *name);
719
720 /**
721  * \brief Create a named talloc chunk
722  * \param context The talloc context to hang the result off
723  * \param size Number of char's that you want to allocate
724  * \param fmt Format string for the name
725  * \param ... printf-style additional arguments
726  * \return The allocated memory chunk
727  * \ingroup talloc_basic
728  *
729  * The talloc_named() function creates a named talloc pointer. It is
730  * equivalent to:
731  *
732  * \code
733  * ptr = talloc_size(context, size);
734  * talloc_set_name(ptr, fmt, ....);
735  * \endcode
736  *
737  */
738 void *talloc_named(const void *context, size_t size, 
739                    const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
740
741 /**
742  * \brief Basic routine to allocate a chunk of memory
743  * \param context The parent context
744  * \param size The number of char's that we want to allocate
745  * \param name The name the talloc block has
746  * \return The allocated chunk
747  * \ingroup talloc_basic
748  *
749  * This is equivalent to:
750  *
751  * \code
752  * ptr = talloc_size(context, size);
753  * talloc_set_name_const(ptr, name);
754  * \endcode
755  */
756 void *talloc_named_const(const void *context, size_t size, const char *name);
757
758 /**
759  * \brief Return the name of a talloc chunk
760  * \param ptr The talloc chunk
761  * \return The name
762  * \ingroup talloc_basic
763  *
764  * This returns the current name for the given talloc pointer. See
765  * talloc_set_name() for details.
766  */
767 const char *talloc_get_name(const void *ptr);
768
769 /**
770  * \brief Verify that a talloc chunk carries a specified name
771  * \param ptr The talloc chunk to check
772  * \param name The name to check agains
773  * \ingroup talloc_basic
774  *
775  * This function checks if a pointer has the specified name. If it does
776  * then the pointer is returned. It it doesn't then NULL is returned.
777  */
778 void *talloc_check_name(const void *ptr, const char *name);
779
780 void *_talloc_get_type_abort(const void *ptr, const char *name, const char *location);
781 void *talloc_parent(const void *ptr);
782 const char *talloc_parent_name(const void *ptr);
783
784 /**
785  * \brief Create a new top level talloc context
786  * \param fmt Format string for the name
787  * \param ... printf-style additional arguments
788  * \return The allocated memory chunk
789  * \ingroup talloc_basic
790  *
791  * This function creates a zero length named talloc context as a top level
792  * context. It is equivalent to:
793  *
794  * \code
795  *   talloc_named(NULL, 0, fmt, ...);
796  * \endcode
797  */
798 void *talloc_init(const char *fmt, ...) PRINTF_ATTRIBUTE(1,2);
799
800 /**
801  * \brief Free a chunk of talloc memory
802  * \param ptr The chunk to be freed
803  * \return success?
804  * \ingroup talloc_basic
805  *
806  * The talloc_free() function frees a piece of talloc memory, and all its
807  * children. You can call talloc_free() on any pointer returned by talloc().
808  *
809  * The return value of talloc_free() indicates success or failure, with 0
810  * returned for success and -1 for failure. The only possible failure
811  * condition is if the pointer had a destructor attached to it and the
812  * destructor returned -1. See talloc_set_destructor() for details on
813  * destructors.
814  *
815  * If this pointer has an additional parent when talloc_free() is called
816  * then the memory is not actually released, but instead the most
817  * recently established parent is destroyed. See talloc_reference() for
818  * details on establishing additional parents.
819  *
820  * For more control on which parent is removed, see talloc_unlink()
821  *
822  * talloc_free() operates recursively on its children.
823  */
824 int talloc_free(void *ptr);
825
826 /**
827  * \brief Free a talloc chunk's children
828  * \param ptr The chunk that you want to free the children of
829  * \return success?
830  * \ingroup talloc_basic
831  *
832  * The talloc_free_children() walks along the list of all children of a talloc
833  * context and talloc_free()s only the children, not the context itself.
834  */
835 void talloc_free_children(void *ptr);
836 void *_talloc_realloc(const void *context, void *ptr, size_t size, const char *name);
837 void *_talloc_steal(const void *new_ctx, const void *ptr);
838 void *_talloc_move(const void *new_ctx, const void *pptr);
839
840 /**
841  * \brief Return the total size of a talloc chunk including its children
842  * \param ptr The talloc chunk
843  * \return The total size
844  * \ingroup talloc_basic
845  *
846  * The talloc_total_size() function returns the total size in bytes used
847  * by this pointer and all child pointers. Mostly useful for debugging.
848  *
849  * Passing NULL is allowed, but it will only give a meaningful result if
850  * talloc_enable_leak_report() or talloc_enable_leak_report_full() has
851  * been called.
852  */
853 size_t talloc_total_size(const void *ptr);
854
855 /**
856  * \brief Return the number of talloc chunks hanging off a chunk
857  * \param ptr The talloc chunk
858  * \return The total size
859  * \ingroup talloc_basic
860  *
861  * The talloc_total_blocks() function returns the total memory block
862  * count used by this pointer and all child pointers. Mostly useful for
863  * debugging.
864  *
865  * Passing NULL is allowed, but it will only give a meaningful result if
866  * talloc_enable_leak_report() or talloc_enable_leak_report_full() has
867  * been called.
868  */
869 size_t talloc_total_blocks(const void *ptr);
870
871 /**
872  * \brief Walk a complete talloc hierarchy
873  * \param ptr The talloc chunk
874  * \param depth Internal parameter to control recursion. Call with 0.
875  * \param max_depth Maximum recursion level.
876  * \param callback Function to be called on every chunk
877  * \param private_data Private pointer passed to callback
878  * \ingroup talloc_debug
879  *
880  * This provides a more flexible reports than talloc_report(). It
881  * will recursively call the callback for the entire tree of memory
882  * referenced by the pointer. References in the tree are passed with
883  * is_ref = 1 and the pointer that is referenced.
884  *
885  * You can pass NULL for the pointer, in which case a report is
886  * printed for the top level memory context, but only if
887  * talloc_enable_leak_report() or talloc_enable_leak_report_full()
888  * has been called.
889  *
890  * The recursion is stopped when depth >= max_depth.
891  * max_depth = -1 means only stop at leaf nodes.
892  */
893 void talloc_report_depth_cb(const void *ptr, int depth, int max_depth,
894                             void (*callback)(const void *ptr,
895                                              int depth, int max_depth,
896                                              int is_ref,
897                                              void *private_data),
898                             void *private_data);
899
900 /**
901  * \brief Print a talloc hierarchy
902  * \param ptr The talloc chunk
903  * \param depth Internal parameter to control recursion. Call with 0.
904  * \param max_depth Maximum recursion level.
905  * \param f The file handle to print to
906  * \ingroup talloc_debug
907  *
908  * This provides a more flexible reports than talloc_report(). It
909  * will let you specify the depth and max_depth.
910  */
911 void talloc_report_depth_file(const void *ptr, int depth, int max_depth, FILE *f);
912
913 /**
914  * \brief Print a summary report of all memory used by ptr
915  * \param ptr The talloc chunk
916  * \param f The file handle to print to
917  * \ingroup talloc_debug
918  *
919  * This provides a more detailed report than talloc_report(). It will
920  * recursively print the ensire tree of memory referenced by the
921  * pointer. References in the tree are shown by giving the name of the
922  * pointer that is referenced.
923  *
924  * You can pass NULL for the pointer, in which case a report is printed
925  * for the top level memory context, but only if
926  * talloc_enable_leak_report() or talloc_enable_leak_report_full() has
927  * been called.
928  */
929 void talloc_report_full(const void *ptr, FILE *f);
930
931 /**
932  * \brief Print a summary report of all memory used by ptr
933  * \param ptr The talloc chunk
934  * \param f The file handle to print to
935  * \ingroup talloc_debug
936  *
937  * The talloc_report() function prints a summary report of all memory
938  * used by ptr. One line of report is printed for each immediate child of
939  * ptr, showing the total memory and number of blocks used by that child.
940  *
941  * You can pass NULL for the pointer, in which case a report is printed
942  * for the top level memory context, but only if
943  * talloc_enable_leak_report() or talloc_enable_leak_report_full() has
944  * been called.
945  */
946 void talloc_report(const void *ptr, FILE *f);
947
948 /**
949  * \brief Enable tracking the use of NULL memory contexts
950  * \ingroup talloc_debug
951  *
952  * This enables tracking of the NULL memory context without enabling leak
953  * reporting on exit. Useful for when you want to do your own leak
954  * reporting call via talloc_report_null_full();
955  */
956 void talloc_enable_null_tracking(void);
957
958 /**
959  * \brief Disable tracking of the NULL memory context
960  * \ingroup talloc_debug
961  *
962  * This disables tracking of the NULL memory context.
963  */
964
965 void talloc_disable_null_tracking(void);
966
967 /**
968  * \brief Enable calling of talloc_report(NULL, stderr) when a program exits
969  * \ingroup talloc_debug
970  *
971  * This enables calling of talloc_report(NULL, stderr) when the program
972  * exits. In Samba4 this is enabled by using the --leak-report command
973  * line option.
974  *
975  * For it to be useful, this function must be called before any other
976  * talloc function as it establishes a "null context" that acts as the
977  * top of the tree. If you don't call this function first then passing
978  * NULL to talloc_report() or talloc_report_full() won't give you the
979  * full tree printout.
980  *
981  * Here is a typical talloc report:
982  *
983 \verbatim
984 talloc report on 'null_context' (total 267 bytes in 15 blocks)
985          libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
986          libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
987          iconv(UTF8,CP850)              contains     42 bytes in   2 blocks
988          libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
989          iconv(CP850,UTF8)              contains     42 bytes in   2 blocks
990          iconv(UTF8,UTF-16LE)           contains     45 bytes in   2 blocks
991          iconv(UTF-16LE,UTF8)           contains     45 bytes in   2 blocks
992 \endverbatim
993  */
994 void talloc_enable_leak_report(void);
995
996 /**
997  * \brief Enable calling of talloc_report(NULL, stderr) when a program exits
998  * \ingroup talloc_debug
999  *
1000  * This enables calling of talloc_report_full(NULL, stderr) when the
1001  * program exits. In Samba4 this is enabled by using the
1002  * --leak-report-full command line option.
1003  *
1004  * For it to be useful, this function must be called before any other
1005  * talloc function as it establishes a "null context" that acts as the
1006  * top of the tree. If you don't call this function first then passing
1007  * NULL to talloc_report() or talloc_report_full() won't give you the
1008  * full tree printout.
1009  *
1010  * Here is a typical full report:
1011 \verbatim
1012 full talloc report on 'root' (total 18 bytes in 8 blocks)
1013     p1                             contains     18 bytes in   7 blocks (ref 0)
1014         r1                             contains     13 bytes in   2 blocks (ref 0)
1015             reference to: p2
1016         p2                             contains      1 bytes in   1 blocks (ref 1)
1017         x3                             contains      1 bytes in   1 blocks (ref 0)
1018         x2                             contains      1 bytes in   1 blocks (ref 0)
1019         x1                             contains      1 bytes in   1 blocks (ref 0)
1020 \endverbatim
1021 */
1022 void talloc_enable_leak_report_full(void);
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 *_talloc_realloc_array(const void *ctx, void *ptr, size_t el_size, unsigned count, const char *name);
1028
1029 /**
1030  * \brief Provide a function version of talloc_realloc_size
1031  * \param context The parent context used if "ptr" is NULL
1032  * \param ptr The chunk to be resized
1033  * \param size The new chunk size
1034  * \return The new chunk
1035  * \ingroup talloc_array
1036  *
1037  * This is a non-macro version of talloc_realloc(), which is useful as
1038  * libraries sometimes want a ralloc function pointer. A realloc()
1039  * implementation encapsulates the functionality of malloc(), free() and
1040  * realloc() in one call, which is why it is useful to be able to pass around
1041  * a single function pointer.
1042 */
1043 void *talloc_realloc_fn(const void *context, void *ptr, size_t size);
1044
1045 /**
1046  * \brief Provide a talloc context that is freed at program exit
1047  * \return A talloc context
1048  * \ingroup talloc_basic
1049  *
1050  * This is a handy utility function that returns a talloc context
1051  * which will be automatically freed on program exit. This can be used
1052  * to reduce the noise in memory leak reports.
1053  */
1054 void *talloc_autofree_context(void);
1055
1056 /**
1057  * \brief Get the size of a talloc chunk
1058  * \param ctx The talloc chunk
1059  * \return The size
1060  * \ingroup talloc_basic
1061  *
1062  * This function lets you know the amount of memory alloced so far by
1063  * this context. It does NOT account for subcontext memory.
1064  * This can be used to calculate the size of an array.
1065  */
1066 size_t talloc_get_size(const void *ctx);
1067
1068 /**
1069  * \brief Find a parent context by name
1070  * \param ctx The talloc chunk to start from
1071  * \param name The name of the parent we look for
1072  * \ingroup talloc_basic
1073  *
1074  * Find a parent memory context of the current context that has the given
1075  * name. This can be very useful in complex programs where it may be
1076  * difficult to pass all information down to the level you need, but you
1077  * know the structure you want is a parent of another context.
1078  */
1079 void *talloc_find_parent_byname(const void *ctx, const char *name);
1080 void talloc_show_parents(const void *context, FILE *file);
1081 int talloc_is_parent(const void *context, const void *ptr);
1082
1083 /**
1084  * \brief Duplicate a string into a talloc chunk
1085  * \param t The talloc context to hang the result off
1086  * \param p The string you want to duplicate
1087  * \return The duplicated string
1088  * \ingroup talloc_string
1089  *
1090  * The talloc_strdup() function is equivalent to:
1091  *
1092  * \code
1093  * ptr = talloc_size(ctx, strlen(p)+1);
1094  * if (ptr) memcpy(ptr, p, strlen(p)+1);
1095  * \endcode
1096  *
1097  * This functions sets the name of the new pointer to the passed
1098  * string. This is equivalent to:
1099  *
1100  * \code
1101  * talloc_set_name_const(ptr, ptr)
1102  * \endcode
1103  */
1104 char *talloc_strdup(const void *t, const char *p);
1105 char *talloc_strdup_append(char *s, const char *a);
1106 char *talloc_strdup_append_buffer(char *s, const char *a);
1107
1108 /**
1109  * \brief Duplicate a length-limited string into a talloc chunk
1110  * \param t The talloc context to hang the result off
1111  * \param p The string you want to duplicate
1112  * \param n The maximum string length to duplicate
1113  * \return The duplicated string
1114  * \ingroup talloc_string
1115  *
1116  * The talloc_strndup() function is the talloc equivalent of the C
1117  * library function strndup()
1118  *
1119  * This functions sets the name of the new pointer to the passed
1120  * string. This is equivalent to:
1121  *
1122  * \code
1123  * talloc_set_name_const(ptr, ptr)
1124  * \endcode
1125  */
1126 char *talloc_strndup(const void *t, const char *p, size_t n);
1127 char *talloc_strndup_append(char *s, const char *a, size_t n);
1128 char *talloc_strndup_append_buffer(char *s, const char *a, size_t n);
1129
1130 /**
1131  * \brief Format a string given a va_list
1132  * \param t The talloc context to hang the result off
1133  * \param fmt The format string
1134  * \param ap The parameters used to fill fmt
1135  * \return The formatted string
1136  * \ingroup talloc_string
1137  *
1138  * The talloc_vasprintf() function is the talloc equivalent of the C
1139  * library function vasprintf()
1140  *
1141  * This functions sets the name of the new pointer to the new
1142  * string. This is equivalent to:
1143  *
1144  * \code
1145  * talloc_set_name_const(ptr, ptr)
1146  * \endcode
1147  */
1148 char *talloc_vasprintf(const void *t, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
1149 char *talloc_vasprintf_append(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
1150 char *talloc_vasprintf_append_buffer(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
1151
1152 /**
1153  * \brief Format a string
1154  * \param t The talloc context to hang the result off
1155  * \param fmt The format string
1156  * \param ... The parameters used to fill fmt
1157  * \return The formatted string
1158  * \ingroup talloc_string
1159  *
1160  * The talloc_asprintf() function is the talloc equivalent of the C
1161  * library function asprintf()
1162  *
1163  * This functions sets the name of the new pointer to the new
1164  * string. This is equivalent to:
1165  *
1166  * \code
1167  * talloc_set_name_const(ptr, ptr)
1168  * \endcode
1169  */
1170 char *talloc_asprintf(const void *t, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
1171
1172 /**
1173  * \brief Append a formatted string to another string
1174  * \param s The string to append to
1175  * \param fmt The format string
1176  * \param ... The parameters used to fill fmt
1177  * \return The formatted string
1178  * \ingroup talloc_string
1179  *
1180  * The talloc_asprintf_append() function appends the given formatted string to
1181  * the given string. Use this varient when the string in the current talloc
1182  * buffer may have been truncated in length.
1183  *
1184  * This functions sets the name of the new pointer to the new
1185  * string. This is equivalent to:
1186  *
1187  * \code
1188  * talloc_set_name_const(ptr, ptr)
1189  * \endcode
1190  */
1191 char *talloc_asprintf_append(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
1192
1193 /**
1194  * \brief Append a formatted string to another string
1195  * \param s The string to append to
1196  * \param fmt The format string
1197  * \param ... The parameters used to fill fmt
1198  * \return The formatted string
1199  * \ingroup talloc_string
1200  *
1201  * The talloc_asprintf_append() function appends the given formatted string to
1202  * the end of the currently allocated talloc buffer. This routine should be
1203  * used if you create a large string step by step. talloc_asprintf() or
1204  * talloc_asprintf_append() call strlen() at every
1205  * step. talloc_asprintf_append_buffer() uses the existing buffer size of the
1206  * talloc chunk to calculate where to append the string.
1207  *
1208  * This functions sets the name of the new pointer to the new
1209  * string. This is equivalent to:
1210  *
1211  * \code
1212  * talloc_set_name_const(ptr, ptr)
1213  * \endcode
1214  */
1215 char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
1216
1217 void talloc_set_abort_fn(void (*abort_fn)(const char *reason));
1218
1219 #endif
1220
1221 /*\}*/