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