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