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