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