17f7dc10600edb11e8340deb0ff30c4c8cac61e8
[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 /**
33  * @defgroup talloc The talloc API
34  *
35  * talloc is a hierarchical, reference counted memory pool system with
36  * destructors. It is the core memory allocator used in Samba.
37  *
38  * Perhaps the biggest difference from other memory pool systems is that there
39  * is no distinction between a "talloc context" and a "talloc pointer". Any
40  * pointer returned from talloc() is itself a valid talloc context. This means
41  * you can do this:
42  *
43  * @code
44  *      struct foo *X = talloc(mem_ctx, struct foo);
45  *      X->name = talloc_strdup(X, "foo");
46  * @endcode
47  *
48  * The pointer X->name would be a "child" of the talloc context "X" which is
49  * itself a child of mem_ctx. So if you do talloc_free(mem_ctx) then it is all
50  * destroyed, whereas if you do talloc_free(X) then just X and X->name are
51  * destroyed, and if you do talloc_free(X->name) then just the name element of
52  * X is destroyed.
53  *
54  * If you think about this, then what this effectively gives you is an n-ary
55  * tree, where you can free any part of the tree with talloc_free().
56  *
57  * If you find this confusing, then run the testsuite to watch talloc in
58  * action. You may also like to add your own tests to testsuite.c to clarify
59  * how some particular situation is handled.
60  *
61  * @section talloc_performance Performance
62  *
63  * All the additional features of talloc() over malloc() do come at a price. We
64  * have a simple performance test in Samba4 that measures talloc() versus
65  * malloc() performance, and it seems that talloc() is about 4% slower than
66  * malloc() on my x86 Debian Linux box. For Samba, the great reduction in code
67  * complexity that we get by using talloc makes this worthwhile, especially as
68  * the total overhead of talloc/malloc in Samba is already quite small.
69  *
70  * @section talloc_named Named blocks
71  *
72  * Every talloc chunk has a name that can be used as a dynamic type-checking
73  * system. If for some reason like a callback function you had to cast a
74  * "struct foo *" to a "void *" variable, later you can safely reassign the
75  * "void *" pointer to a "struct foo *" by using the talloc_get_type() or
76  * talloc_get_type_abort() macros.
77  *
78  * @code
79  *      struct foo *X = talloc_get_type_abort(ptr, struct foo);
80  * @endcode
81  *
82  * This will abort if "ptr" does not contain a pointer that has been created
83  * with talloc(mem_ctx, struct foo).
84  *
85  * @section talloc_threading Multi-threading
86  *
87  * talloc itself does not deal with threads. It is thread-safe (assuming the
88  * underlying "malloc" is), as long as each thread uses different memory
89  * contexts.
90  *
91  * If two threads uses the same context then they need to synchronize in order
92  * to be safe. In particular:
93  *
94  *   - when using talloc_enable_leak_report(), giving directly NULL as a parent
95  *     context implicitly refers to a hidden "null context" global variable, so
96  *     this should not be used in a multi-threaded environment without proper
97  *     synchronization.
98  *   - the context returned by talloc_autofree_context() is also global so
99  *     shouldn't be used by several threads simultaneously without
100  *     synchronization.
101  *
102  * @{
103  */
104
105 #define TALLOC_VERSION_MAJOR 2
106 #define TALLOC_VERSION_MINOR 0
107
108 int talloc_version_major(void);
109 int talloc_version_minor(void);
110
111 /**
112  * @brief Define a talloc parent type
113  *
114  * As talloc is a hierarchial memory allocator, every talloc chunk is a
115  * potential parent to other talloc chunks. So defining a separate type for a
116  * talloc chunk is not strictly necessary. TALLOC_CTX is defined nevertheless,
117  * as it provides an indicator for function arguments. You will frequently
118  * write code like
119  *
120  * @code
121  *      struct foo *foo_create(TALLOC_CTX *mem_ctx)
122  *      {
123  *              struct foo *result;
124  *              result = talloc(mem_ctx, struct foo);
125  *              if (result == NULL) return NULL;
126  *                      ... initialize foo ...
127  *              return result;
128  *      }
129  * @endcode
130  *
131  * In this type of allocating functions it is handy to have a general
132  * TALLOC_CTX type to indicate which parent to put allocated structures on.
133  */
134 typedef void TALLOC_CTX;
135
136 /*
137   this uses a little trick to allow __LINE__ to be stringified
138 */
139 #ifndef __location__
140 #define __TALLOC_STRING_LINE1__(s)    #s
141 #define __TALLOC_STRING_LINE2__(s)   __TALLOC_STRING_LINE1__(s)
142 #define __TALLOC_STRING_LINE3__  __TALLOC_STRING_LINE2__(__LINE__)
143 #define __location__ __FILE__ ":" __TALLOC_STRING_LINE3__
144 #endif
145
146 #ifndef TALLOC_DEPRECATED
147 #define TALLOC_DEPRECATED 0
148 #endif
149
150 #ifndef PRINTF_ATTRIBUTE
151 #if (__GNUC__ >= 3)
152 /** Use gcc attribute to check printf fns.  a1 is the 1-based index of
153  * the parameter containing the format, and a2 the index of the first
154  * argument. Note that some gcc 2.x versions don't handle this
155  * properly **/
156 #define PRINTF_ATTRIBUTE(a1, a2) __attribute__ ((format (__printf__, a1, a2)))
157 #else
158 #define PRINTF_ATTRIBUTE(a1, a2)
159 #endif
160 #endif
161
162 #ifdef DOXYGEN
163 /**
164  * @brief Create a new talloc context.
165  *
166  * The talloc() macro is the core of the talloc library. It takes a memory
167  * context and a type, and returns a pointer to a new area of memory of the
168  * given type.
169  *
170  * The returned pointer is itself a talloc context, so you can use it as the
171  * context argument to more calls to talloc if you wish.
172  *
173  * The returned pointer is a "child" of the supplied context. This means that if
174  * you talloc_free() the context then the new child disappears as well.
175  * Alternatively you can free just the child.
176  *
177  * @param[in]  ctx      A talloc context to create a new reference on or NULL to
178  *                      create a new top level context.
179  *
180  * @param[in]  type     The type of memory to allocate.
181  *
182  * @return              A type casted talloc context or NULL on error.
183  *
184  * @code
185  *      unsigned int *a, *b;
186  *
187  *      a = talloc(NULL, unsigned int);
188  *      b = talloc(a, unsigned int);
189  * @endcode
190  *
191  * @see talloc_zero
192  * @see talloc_array
193  * @see talloc_steal
194  * @see talloc_free
195  */
196 void *talloc(const void *ctx, #type);
197 #else
198 #define talloc(ctx, type) (type *)talloc_named_const(ctx, sizeof(type), #type)
199 void *_talloc(const void *context, size_t size);
200 #endif
201
202 /**
203  * @brief Create a new top level talloc context.
204  *
205  * This function creates a zero length named talloc context as a top level
206  * context. It is equivalent to:
207  *
208  * @code
209  *      talloc_named(NULL, 0, fmt, ...);
210  * @endcode
211  * @param[in]  fmt      Format string for the name.
212  *
213  * @param[in]  ...      Additional printf-style arguments.
214  *
215  * @return              The allocated memory chunk, NULL on error.
216  *
217  * @see talloc_named()
218  */
219 void *talloc_init(const char *fmt, ...) PRINTF_ATTRIBUTE(1,2);
220
221 #ifdef DOXYGEN
222 /**
223  * @brief Free a chunk of talloc memory.
224  *
225  * This function frees a piece of talloc memory, and all its children. It
226  * operates recursively on its children. You can call talloc_free() on any
227  * pointer returned by talloc().
228  *
229  * If this pointer has an additional parent when talloc_free() is called then
230  * the memory is not actually released, but instead the most recently
231  * established parent is destroyed. See talloc_reference() for details on
232  * establishing additional parents.
233  *
234  * For more control on which parent is removed, see talloc_unlink().
235  *
236  * From the 2.0 version of talloc, as a special case, talloc_free() is
237  * refused on pointers that have more than one parent, as talloc would
238  * have no way of knowing which parent should be removed. To free a
239  * pointer that has more than one parent please use talloc_unlink().
240  *
241  * To help you find problems in your code caused by this behaviour, if
242  * you do try and free a pointer with more than one parent then the
243  * talloc logging function will be called to give output like this:
244  *
245  * @code
246  *   ERROR: talloc_free with references at some_dir/source/foo.c:123
247  *     reference at some_dir/source/other.c:325
248  *     reference at some_dir/source/third.c:121
249  * @endcode
250  *
251  * Please see the documentation for talloc_set_log_fn() and
252  * talloc_set_log_stderr() for more information on talloc logging
253  * functions.
254  *
255  * @param[in]  ptr      The chunk to be freed.
256  *
257  * @return              Returns 0 on success and -1 on error. The only possible
258  *                      failure condition is if the pointer had a destructor
259  *                      attached to it and the destructor returned -1.
260  *
261  * Example:
262  * @code
263  *      unsigned int *a, *b;
264  *      a = talloc(NULL, unsigned int);
265  *      b = talloc(a, unsigned int);
266  *
267  *      talloc_free(a); // Frees a and b
268  * @endcode
269  *
270  * @see talloc_set_destructor()
271  * @see talloc_unlink()
272  */
273 int talloc_free(void *ptr);
274 #else
275 #define talloc_free(ctx) _talloc_free(ctx, __location__)
276 int _talloc_free(void *ptr, const char *location);
277 #endif
278
279 /**
280  * @brief Free a talloc chunk's children.
281  *
282  * The function walks along the list of all children of a talloc context and
283  * talloc_free()s only the children, not the context itself.
284  *
285  * @param[in]  ptr      The chunk that you want to free the children of.
286  */
287 void talloc_free_children(void *ptr);
288
289 #if DOXYGEN
290 /**
291  * @brief Assign a destructor function to be called when a chunk is freed.
292  *
293  * The function talloc_set_destructor() sets the "destructor" for the pointer
294  * "ptr". A destructor is a function that is called when the memory used by a
295  * pointer is about to be released. The destructor receives the pointer as an
296  * argument, and should return 0 for success and -1 for failure.
297  *
298  * The destructor can do anything it wants to, including freeing other pieces
299  * of memory. A common use for destructors is to clean up operating system
300  * resources (such as open file descriptors) contained in the structure the
301  * destructor is placed on.
302  *
303  * You can only place one destructor on a pointer. If you need more than one
304  * destructor then you can create a zero-length child of the pointer and place
305  * an additional destructor on that.
306  *
307  * To remove a destructor call talloc_set_destructor() with NULL for the
308  * destructor.
309  *
310  * If your destructor attempts to talloc_free() the pointer that it is the
311  * destructor for then talloc_free() will return -1 and the free will be
312  * ignored. This would be a pointless operation anyway, as the destructor is
313  * only called when the memory is just about to go away.
314  *
315  * @param[in]  ptr      The talloc chunk to add a destructor to.
316  *
317  * @param[in]  destructor  The destructor function to be called. NULL to remove
318  *                         it.
319  *
320  * Example:
321  * @code
322  *      static int destroy_fd(int *fd) {
323  *              close(*fd);
324  *              return 0;
325  *      }
326  *
327  *      int *open_file(const char *filename) {
328  *              int *fd = talloc(NULL, int);
329  *              *fd = open(filename, O_RDONLY);
330  *              if (*fd < 0) {
331  *                      talloc_free(fd);
332  *                      return NULL;
333  *              }
334  *              // Whenever they free this, we close the file.
335  *              talloc_set_destructor(fd, destroy_fd);
336  *              return fd;
337  *      }
338  * @endcode
339  *
340  * @see talloc()
341  * @see talloc_free()
342  */
343 void talloc_set_destructor(const void *ptr, int (*destructor)(void *));
344
345 /**
346  * @brief Change a talloc chunk's parent.
347  *
348  * The talloc_steal() function changes the parent context of a talloc
349  * pointer. It is typically used when the context that the pointer is
350  * currently a child of is going to be freed and you wish to keep the
351  * memory for a longer time.
352  *
353  * To make the changed hierarchy less error-prone, you might consider to use
354  * talloc_move().
355  *
356  * If you try and call talloc_steal() on a pointer that has more than one
357  * parent then the result is ambiguous. Talloc will choose to remove the
358  * parent that is currently indicated by talloc_parent() and replace it with
359  * the chosen parent. You will also get a message like this via the talloc
360  * logging functions:
361  *
362  * @code
363  *   WARNING: talloc_steal with references at some_dir/source/foo.c:123
364  *     reference at some_dir/source/other.c:325
365  *     reference at some_dir/source/third.c:121
366  * @endcode
367  *
368  * To unambiguously change the parent of a pointer please see the function
369  * talloc_reparent(). See the talloc_set_log_fn() documentation for more
370  * information on talloc logging.
371  *
372  * @param[in]  new_ctx  The new parent context.
373  *
374  * @param[in]  ptr      The talloc chunk to move.
375  *
376  * @return              Returns the pointer that you pass it. It does not have
377  *                      any failure modes.
378  *
379  * @note It is possible to produce loops in the parent/child relationship
380  * if you are not careful with talloc_steal(). No guarantees are provided
381  * as to your sanity or the safety of your data if you do this.
382  */
383 void *talloc_steal(const void *new_ctx, const void *ptr);
384 #else /* DOXYGEN */
385 /* try to make talloc_set_destructor() and talloc_steal() type safe,
386    if we have a recent gcc */
387 #if (__GNUC__ >= 3)
388 #define _TALLOC_TYPEOF(ptr) __typeof__(ptr)
389 #define talloc_set_destructor(ptr, function)                                  \
390         do {                                                                  \
391                 int (*_talloc_destructor_fn)(_TALLOC_TYPEOF(ptr)) = (function);       \
392                 _talloc_set_destructor((ptr), (int (*)(void *))_talloc_destructor_fn); \
393         } while(0)
394 /* this extremely strange macro is to avoid some braindamaged warning
395    stupidity in gcc 4.1.x */
396 #define talloc_steal(ctx, ptr) ({ _TALLOC_TYPEOF(ptr) __talloc_steal_ret = (_TALLOC_TYPEOF(ptr))_talloc_steal_loc((ctx),(ptr), __location__); __talloc_steal_ret; })
397 #else /* __GNUC__ >= 3 */
398 #define talloc_set_destructor(ptr, function) \
399         _talloc_set_destructor((ptr), (int (*)(void *))(function))
400 #define _TALLOC_TYPEOF(ptr) void *
401 #define talloc_steal(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_steal_loc((ctx),(ptr), __location__)
402 #endif /* __GNUC__ >= 3 */
403 void _talloc_set_destructor(const void *ptr, int (*_destructor)(void *));
404 void *_talloc_steal_loc(const void *new_ctx, const void *ptr, const char *location);
405 #endif /* DOXYGEN */
406
407 /**
408  * @brief Assign a name to a talloc chunk.
409  *
410  * Each talloc pointer has a "name". The name is used principally for
411  * debugging purposes, although it is also possible to set and get the name on
412  * a pointer in as a way of "marking" pointers in your code.
413  *
414  * The main use for names on pointer is for "talloc reports". See
415  * talloc_report() and talloc_report_full() for details. Also see
416  * talloc_enable_leak_report() and talloc_enable_leak_report_full().
417  *
418  * The talloc_set_name() function allocates memory as a child of the
419  * pointer. It is logically equivalent to:
420  *
421  * @code
422  *      talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));
423  * @endcode
424  *
425  * @param[in]  ptr      The talloc chunk to assign a name to.
426  *
427  * @param[in]  fmt      Format string for the name.
428  *
429  * @param[in]  ...      Add printf-style additional arguments.
430  *
431  * @return              The assigned name, NULL on error.
432  *
433  * @note Multiple calls to talloc_set_name() will allocate more memory without
434  * releasing the name. All of the memory is released when the ptr is freed
435  * using talloc_free().
436  */
437 const char *talloc_set_name(const void *ptr, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
438
439 #ifdef DOXYGEN
440 /**
441  * @brief Change a talloc chunk's parent.
442  *
443  * This function has the same effect as talloc_steal(), and additionally sets
444  * the source pointer to NULL. You would use it like this:
445  *
446  * @code
447  *      struct foo *X = talloc(tmp_ctx, struct foo);
448  *      struct foo *Y;
449  *      Y = talloc_move(new_ctx, &X);
450  * @endcode
451  *
452  * @param[in]  new_ctx  The new parent context.
453  *
454  * @param[in]  ptr      Pointer to the talloc chunk to move.
455  *
456  * @return              The pointer of the talloc chunk it has been moved to,
457  *                      NULL on error.
458  */
459 void *talloc_move(const void *new_ctx, const void *ptr);
460 #else
461 #define talloc_move(ctx, ptr) (_TALLOC_TYPEOF(*(ptr)))_talloc_move((ctx),(void *)(ptr))
462 void *_talloc_move(const void *new_ctx, const void *pptr);
463 #endif
464
465 /**
466  * @brief Assign a name to a talloc chunk.
467  *
468  * The function is just like talloc_set_name(), but it takes a string constant,
469  * and is much faster. It is extensively used by the "auto naming" macros, such
470  * as talloc_p().
471  *
472  * This function does not allocate any memory. It just copies the supplied
473  * pointer into the internal representation of the talloc ptr. This means you
474  * must not pass a name pointer to memory that will disappear before the ptr
475  * is freed with talloc_free().
476  *
477  * @param[in]  ptr      The talloc chunk to assign a name to.
478  *
479  * @param[in]  name     Format string for the name.
480  */
481 void talloc_set_name_const(const void *ptr, const char *name);
482
483 /**
484  * @brief Create a named talloc chunk.
485  *
486  * The talloc_named() function creates a named talloc pointer. It is
487  * equivalent to:
488  *
489  * @code
490  *      ptr = talloc_size(context, size);
491  *      talloc_set_name(ptr, fmt, ....);
492  * @endcode
493  *
494  * @param[in]  context  The talloc context to hang the result off.
495  *
496  * @param[in]  size     Number of char's that you want to allocate.
497  *
498  * @param[in]  fmt      Format string for the name.
499  *
500  * @param[in]  ...      Additional printf-style arguments.
501  *
502  * @return              The allocated memory chunk, NULL on error.
503  *
504  * @see talloc_set_name()
505  */
506 void *talloc_named(const void *context, size_t size,
507                    const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
508
509 /**
510  * @brief Basic routine to allocate a chunk of memory.
511  *
512  * This is equivalent to:
513  *
514  * @code
515  *      ptr = talloc_size(context, size);
516  *      talloc_set_name_const(ptr, name);
517  * @endcode
518  *
519  * @param[in]  context  The parent context.
520  *
521  * @param[in]  size     The number of char's that we want to allocate.
522  *
523  * @param[in]  name     The name the talloc block has.
524  *
525  * @return             The allocated memory chunk, NULL on error.
526  */
527 void *talloc_named_const(const void *context, size_t size, const char *name);
528
529 #ifdef DOXYGEN
530 /**
531  * @brief Untyped allocation.
532  *
533  * The function should be used when you don't have a convenient type to pass to
534  * talloc(). Unlike talloc(), it is not type safe (as it returns a void *), so
535  * you are on your own for type checking.
536  *
537  * Best to use talloc() or talloc_array() instead.
538  *
539  * @param[in]  ctx     The talloc context to hang the result off.
540  *
541  * @param[in]  size    Number of char's that you want to allocate.
542  *
543  * @return             The allocated memory chunk, NULL on error.
544  *
545  * Example:
546  * @code
547  *      void *mem = talloc_size(NULL, 100);
548  * @endcode
549  */
550 void *talloc_size(const void *ctx, size_t size);
551 #else
552 #define talloc_size(ctx, size) talloc_named_const(ctx, size, __location__)
553 #endif
554
555 #ifdef DOXYGEN
556 /**
557  * @brief Allocate into a typed pointer.
558  *
559  * The talloc_ptrtype() macro should be used when you have a pointer and want
560  * to allocate memory to point at with this pointer. When compiling with
561  * gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size() and
562  * talloc_get_name() will return the current location in the source file and
563  * not the type.
564  *
565  * @param[in]  ctx      The talloc context to hang the result off.
566  *
567  * @param[in]  type     The pointer you want to assign the result to.
568  *
569  * @return              The properly casted allocated memory chunk, NULL on
570  *                      error.
571  *
572  * Example:
573  * @code
574  *       unsigned int *a = talloc_ptrtype(NULL, a);
575  * @endcode
576  */
577 void *talloc_ptrtype(const void *ctx, #type);
578 #else
579 #define talloc_ptrtype(ctx, ptr) (_TALLOC_TYPEOF(ptr))talloc_size(ctx, sizeof(*(ptr)))
580 #endif
581
582 #ifdef DOXYGEN
583 /**
584  * @brief Allocate a new 0-sized talloc chunk.
585  *
586  * This is a utility macro that creates a new memory context hanging off an
587  * exiting context, automatically naming it "talloc_new: __location__" where
588  * __location__ is the source line it is called from. It is particularly
589  * useful for creating a new temporary working context.
590  *
591  * @param[in]  ctx      The talloc parent context.
592  *
593  * @return              A new talloc chunk, NULL on error.
594  */
595 void *talloc_new(const void *ctx);
596 #else
597 #define talloc_new(ctx) talloc_named_const(ctx, 0, "talloc_new: " __location__)
598 #endif
599
600 #ifdef DOXYGEN
601 /**
602  * @brief Allocate a 0-initizialized structure.
603  *
604  * The macro is equivalent to:
605  *
606  * @code
607  *      ptr = talloc(ctx, type);
608  *      if (ptr) memset(ptr, 0, sizeof(type));
609  * @endcode
610  *
611  * @param[in]  ctx      The talloc context to hang the result off.
612  *
613  * @param[in]  type     The type that we want to allocate.
614  *
615  * @return              Pointer to a piece of memory, properly cast to 'type *',
616  *                      NULL on error.
617  *
618  * Example:
619  * @code
620  *      unsigned int *a, *b;
621  *      a = talloc_zero(NULL, unsigned int);
622  *      b = talloc_zero(a, unsigned int);
623  * @endcode
624  *
625  * @see talloc()
626  * @see talloc_zero_size()
627  * @see talloc_zero_array()
628  */
629 void *talloc_zero(const void *ctx, #type);
630
631 /**
632  * @brief Allocate untyped, 0-initialized memory.
633  *
634  * @param[in]  ctx      The talloc context to hang the result off.
635  *
636  * @param[in]  size     Number of char's that you want to allocate.
637  *
638  * @return              The allocated memory chunk.
639  */
640 void *talloc_zero_size(const void *ctx, size_t size);
641 #else
642 #define talloc_zero(ctx, type) (type *)_talloc_zero(ctx, sizeof(type), #type)
643 #define talloc_zero_size(ctx, size) _talloc_zero(ctx, size, __location__)
644 void *_talloc_zero(const void *ctx, size_t size, const char *name);
645 #endif
646
647 /**
648  * @brief Return the name of a talloc chunk.
649  *
650  * @param[in]  ptr      The talloc chunk.
651  *
652  * @return              The current name for the given talloc pointer.
653  *
654  * @see talloc_set_name()
655  */
656 const char *talloc_get_name(const void *ptr);
657
658 /**
659  * @brief Verify that a talloc chunk carries a specified name.
660  *
661  * This function checks if a pointer has the specified name. If it does
662  * then the pointer is returned.
663  *
664  * @param[in]  ptr       The talloc chunk to check.
665  *
666  * @param[in]  name      The name to check against.
667  *
668  * @return               The pointer if the name matches, NULL if it doesn't.
669  */
670 void *talloc_check_name(const void *ptr, const char *name);
671
672 /**
673  * @brief Get the parent chunk of a pointer.
674  *
675  * @param[in]  ptr      The talloc pointer to inspect.
676  *
677  * @return              The talloc parent of ptr, NULL on error.
678  */
679 void *talloc_parent(const void *ptr);
680
681 /**
682  * @brief Get a talloc chunk's parent name.
683  *
684  * @param[in]  ptr      The talloc pointer to inspect.
685  *
686  * @return              The name of ptr's parent chunk.
687  */
688 const char *talloc_parent_name(const void *ptr);
689
690 /**
691  * @brief Get the total size of a talloc chunk including its children.
692  *
693  * The function returns the total size in bytes used by this pointer and all
694  * child pointers. Mostly useful for debugging.
695  *
696  * Passing NULL is allowed, but it will only give a meaningful result if
697  * talloc_enable_leak_report() or talloc_enable_leak_report_full() has
698  * been called.
699  *
700  * @param[in]  ptr      The talloc chunk.
701  *
702  * @return              The total size.
703  */
704 size_t talloc_total_size(const void *ptr);
705
706 /**
707  * @brief Get the number of talloc chunks hanging off a chunk.
708  *
709  * The talloc_total_blocks() function returns the total memory block
710  * count used by this pointer and all child pointers. Mostly useful for
711  * debugging.
712  *
713  * Passing NULL is allowed, but it will only give a meaningful result if
714  * talloc_enable_leak_report() or talloc_enable_leak_report_full() has
715  * been called.
716  *
717  * @param[in]  ptr      The talloc chunk.
718  *
719  * @return              The total size.
720  */
721 size_t talloc_total_blocks(const void *ptr);
722
723 #ifdef DOXYGEN
724 /**
725  * @brief Duplicate a memory area into a talloc chunk.
726  *
727  * The function is equivalent to:
728  *
729  * @code
730  *      ptr = talloc_size(ctx, size);
731  *      if (ptr) memcpy(ptr, p, size);
732  * @endcode
733  *
734  * @param[in]  t        The talloc context to hang the result off.
735  *
736  * @param[in]  p        The memory chunk you want to duplicate.
737  *
738  * @param[in]  size     Number of char's that you want copy.
739  *
740  * @return              The allocated memory chunk.
741  *
742  * @see talloc_size()
743  */
744 void *talloc_memdup(const void *t, const void *p, size_t size);
745 #else
746 #define talloc_memdup(t, p, size) _talloc_memdup(t, p, size, __location__)
747 void *_talloc_memdup(const void *t, const void *p, size_t size, const char *name);
748 #endif
749
750 #ifdef DOXYGEN
751 /**
752  * @brief Assign a type to a talloc chunk.
753  *
754  * This macro allows you to force the name of a pointer to be a particular type.
755  * This can be used in conjunction with talloc_get_type() to do type checking on
756  * void* pointers.
757  *
758  * It is equivalent to this:
759  *
760  * @code
761  *      talloc_set_name_const(ptr, #type)
762  * @endcode
763  *
764  * @param[in]  ptr      The talloc chunk to assign the type to.
765  *
766  * @param[in]  type     The type to assign.
767  */
768 void talloc_set_type(const char *ptr, #type);
769
770 /**
771  * @brief Get a typed pointer out of a talloc pointer.
772  *
773  * This macro allows you to do type checking on talloc pointers. It is
774  * particularly useful for void* private pointers. It is equivalent to
775  * this:
776  *
777  * @code
778  *      (type *)talloc_check_name(ptr, #type)
779  * @endcode
780  *
781  * @param[in]  ptr      The talloc pointer to check.
782  *
783  * @param[in]  type     The type to check against.
784  *
785  * @return              The properly casted pointer given by ptr, NULL on error.
786  */
787 void *talloc_get_name(const void *ptr, #type);
788 #else
789 #define talloc_set_type(ptr, type) talloc_set_name_const(ptr, #type)
790 #define talloc_get_type(ptr, type) (type *)talloc_check_name(ptr, #type)
791 #endif
792
793 #ifdef DOXYGEN
794 /**
795  * @brief Safely turn a void pointer into a typed pointer.
796  *
797  * This macro is used together with talloc(mem_ctx, struct foo). If you had to
798  * assing the talloc chunk pointer to some void pointer variable,
799  * talloc_get_type_abort() is the recommended way to get the convert the void
800  * pointer back to a typed pointer.
801  *
802  * @param[in]  ptr      The void pointer to convert.
803  *
804  * @param[in]  type     The type that this chunk contains
805  *
806  * @return              The ame value as ptr, type-checked and properly cast.
807  */
808 void *talloc_get_type_abort(const void *ptr, #type);
809 #else
810 #define talloc_get_type_abort(ptr, type) (type *)_talloc_get_type_abort(ptr, #type, __location__)
811 void *_talloc_get_type_abort(const void *ptr, const char *name, const char *location);
812 #endif
813
814 /**
815  * @brief Find a parent context by name.
816  *
817  * Find a parent memory context of the current context that has the given
818  * name. This can be very useful in complex programs where it may be
819  * difficult to pass all information down to the level you need, but you
820  * know the structure you want is a parent of another context.
821  *
822  * @param[in]  ctx      The talloc chunk to start from.
823  *
824  * @param[in]  name     The name of the parent we look for.
825  *
826  * @return              The memory context we are looking for, NULL if not
827  *                      found.
828  */
829 void *talloc_find_parent_byname(const void *ctx, const char *name);
830
831 #ifdef DOXYGEN
832 /**
833  * @brief Find a parent context by type.
834  *
835  * Find a parent memory context of the current context that has the given
836  * name. This can be very useful in complex programs where it may be
837  * difficult to pass all information down to the level you need, but you
838  * know the structure you want is a parent of another context.
839  *
840  * Like talloc_find_parent_byname() but takes a type, making it typesafe.
841  *
842  * @param[in]  ptr      The talloc chunk to start from.
843  *
844  * @param[in]  type     The type of the parent to look for.
845  *
846  * @return              The memory context we are looking for, NULL if not
847  *                      found.
848  */
849 void *talloc_find_parent_bytype(const void *ptr, #type);
850 #else
851 #define talloc_find_parent_bytype(ptr, type) (type *)talloc_find_parent_byname(ptr, #type)
852 #endif
853
854 /**
855  * @brief Allocate a talloc pool.
856  *
857  * A talloc pool is a pure optimization for specific situations. In the
858  * release process for Samba 3.2 we found out that we had become considerably
859  * slower than Samba 3.0 was. Profiling showed that malloc(3) was a large CPU
860  * consumer in benchmarks. For Samba 3.2 we have internally converted many
861  * static buffers to dynamically allocated ones, so malloc(3) being beaten
862  * more was no surprise. But it made us slower.
863  *
864  * talloc_pool() is an optimization to call malloc(3) a lot less for the use
865  * pattern Samba has: The SMB protocol is mainly a request/response protocol
866  * where we have to allocate a certain amount of memory per request and free
867  * that after the SMB reply is sent to the client.
868  *
869  * talloc_pool() creates a talloc chunk that you can use as a talloc parent
870  * exactly as you would use any other ::TALLOC_CTX. The difference is that
871  * when you talloc a child of this pool, no malloc(3) is done. Instead, talloc
872  * just increments a pointer inside the talloc_pool. This also works
873  * recursively. If you use the child of the talloc pool as a parent for
874  * grand-children, their memory is also taken from the talloc pool.
875  *
876  * If you talloc_free() children of a talloc pool, the memory is not given
877  * back to the system. Instead, free(3) is only called if the talloc_pool()
878  * itself is released with talloc_free().
879  *
880  * The downside of a talloc pool is that if you talloc_move() a child of a
881  * talloc pool to a talloc parent outside the pool, the whole pool memory is
882  * not free(3)'ed until that moved chunk is also talloc_free()ed.
883  *
884  * @param[in]  context  The talloc context to hang the result off.
885  *
886  * @param[in]  size     Size of the talloc pool.
887  *
888  * @return              The allocated talloc pool, NULL on error.
889  */
890 void *talloc_pool(const void *context, size_t size);
891
892 /**
893  * @brief Free a talloc chunk and NULL out the pointer.
894  *
895  * TALLOC_FREE() frees a pointer and sets it to NULL. Use this if you want
896  * immediate feedback (i.e. crash) if you use a pointer after having free'ed
897  * it.
898  *
899  * @param[in]  ctx      The chunk to be freed.
900  */
901 #define TALLOC_FREE(ctx) do { talloc_free(ctx); ctx=NULL; } while(0)
902
903 /* @} ******************************************************************/
904
905 /**
906  * \defgroup talloc_ref The talloc reference function.
907  * @ingroup talloc
908  *
909  * This module contains the definitions around talloc references
910  *
911  * @{
912  */
913
914 /**
915  * @brief Increase the reference count of a talloc chunk.
916  *
917  * The talloc_increase_ref_count(ptr) function is exactly equivalent to:
918  *
919  * @code
920  *      talloc_reference(NULL, ptr);
921  * @endcode
922  *
923  * You can use either syntax, depending on which you think is clearer in
924  * your code.
925  *
926  * @param[in]  ptr      The pointer to increase the reference count.
927  *
928  * @return              0 on success, -1 on error.
929  */
930 int talloc_increase_ref_count(const void *ptr);
931
932 /**
933  * @brief Get the number of references to a talloc chunk.
934  *
935  * @param[in]  ptr      The pointer to retrieve the reference count from.
936  *
937  * @return              The number of references.
938  */
939 size_t talloc_reference_count(const void *ptr);
940
941 #ifdef DOXYGEN
942 /**
943  * @brief Create an additional talloc parent to a pointer.
944  *
945  * The talloc_reference() function makes "context" an additional parent of
946  * ptr. Each additional reference consumes around 48 bytes of memory on intel
947  * x86 platforms.
948  *
949  * If ptr is NULL, then the function is a no-op, and simply returns NULL.
950  *
951  * After creating a reference you can free it in one of the following ways:
952  *
953  * - you can talloc_free() any parent of the original pointer. That
954  *   will reduce the number of parents of this pointer by 1, and will
955  *   cause this pointer to be freed if it runs out of parents.
956  *
957  * - you can talloc_free() the pointer itself. That will destroy the
958  *   most recently established parent to the pointer and leave the
959  *   pointer as a child of its current parent.
960  *
961  * For more control on which parent to remove, see talloc_unlink()
962  * @param[in]  ctx      The additional parent.
963  *
964  * @param[in]  ptr      The pointer you want to create an additional parent for.
965  *
966  * @return              The original pointer 'ptr', NULL if talloc ran out of
967  *                      memory in creating the reference.
968  *
969  * Example:
970  * @code
971  *      unsigned int *a, *b, *c;
972  *      a = talloc(NULL, unsigned int);
973  *      b = talloc(NULL, unsigned int);
974  *      c = talloc(a, unsigned int);
975  *      // b also serves as a parent of c.
976  *      talloc_reference(b, c);
977  * @endcode
978  *
979  * @see talloc_unlink()
980  */
981 void *talloc_reference(const void *ctx, const void *ptr);
982 #else
983 #define talloc_reference(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_reference_loc((ctx),(ptr), __location__)
984 void *_talloc_reference_loc(const void *context, const void *ptr, const char *location);
985 #endif
986
987 /**
988  * @brief Remove a specific parent from a talloc chunk.
989  *
990  * The function removes a specific parent from ptr. The context passed must
991  * either be a context used in talloc_reference() with this pointer, or must be
992  * a direct parent of ptr.
993  *
994  * Usually you can just use talloc_free() instead of talloc_unlink(), but
995  * sometimes it is useful to have the additional control on which parent is
996  * removed.
997  *
998  * @param[in]  context  The talloc parent to remove.
999  *
1000  * @param[in]  ptr      The talloc ptr you want to remove the parent from.
1001  *
1002  * @return              0 on success, -1 on error.
1003  *
1004  * @note If the parent has already been removed using talloc_free() then
1005  * this function will fail and will return -1.  Likewise, if ptr is NULL,
1006  * then the function will make no modifications and return -1.
1007  *
1008  * Example:
1009  * @code
1010  *      unsigned int *a, *b, *c;
1011  *      a = talloc(NULL, unsigned int);
1012  *      b = talloc(NULL, unsigned int);
1013  *      c = talloc(a, unsigned int);
1014  *      // b also serves as a parent of c.
1015  *      talloc_reference(b, c);
1016  *      talloc_unlink(b, c);
1017  * @endcode
1018  */
1019 int talloc_unlink(const void *context, void *ptr);
1020
1021 /**
1022  * @brief Provide a talloc context that is freed at program exit.
1023  *
1024  * This is a handy utility function that returns a talloc context
1025  * which will be automatically freed on program exit. This can be used
1026  * to reduce the noise in memory leak reports.
1027  *
1028  * @return              A talloc context, NULL on error.
1029  */
1030 void *talloc_autofree_context(void);
1031
1032 /**
1033  * @brief Get the size of a talloc chunk.
1034  *
1035  * This function lets you know the amount of memory alloced so far by
1036  * this context. It does NOT account for subcontext memory.
1037  * This can be used to calculate the size of an array.
1038  *
1039  * @param[in]  ctx      The talloc chunk.
1040  *
1041  * @return              The size of the talloc chunk.
1042  */
1043 size_t talloc_get_size(const void *ctx);
1044
1045 /**
1046  * @brief Show the parentage of a context.
1047  *
1048  * @param[in]  context            The talloc context to look at.
1049  *
1050  * @param[in]  file               The output to use, a file, stdout or stderr.
1051  */
1052 void talloc_show_parents(const void *context, FILE *file);
1053
1054 /**
1055  * @brief Check if a context is parent of a talloc chunk.
1056  *
1057  * This checks if context is referenced in the talloc hierarchy above ptr.
1058  *
1059  * @param[in]  context  The assumed talloc context.
1060  *
1061  * @param[in]  ptr      The talloc chunk to check.
1062  *
1063  * @return              Return 1 if this is the case, 0 if not.
1064  */
1065 int talloc_is_parent(const void *context, const void *ptr);
1066
1067 /**
1068  * @brief Change the parent context of a talloc pointer.
1069  *
1070  * The function changes the parent context of a talloc pointer. It is typically
1071  * used when the context that the pointer is currently a child of is going to be
1072  * freed and you wish to keep the memory for a longer time.
1073  *
1074  * The difference between talloc_reparent() and talloc_steal() is that
1075  * talloc_reparent() can specify which parent you wish to change. This is
1076  * useful when a pointer has multiple parents via references.
1077  *
1078  * @param[in]  old_parent
1079  * @param[in]  new_parent
1080  * @param[in]  ptr
1081  *
1082  * @return              Return the pointer you passed. It does not have any
1083  *                      failure modes.
1084  */
1085 void *talloc_reparent(const void *old_parent, const void *new_parent, const void *ptr);
1086
1087 /* @} ******************************************************************/
1088
1089 /**
1090  * @defgroup talloc_array The talloc array functions
1091  * @ingroup talloc
1092  *
1093  * Talloc contains some handy helpers for handling Arrays conveniently
1094  *
1095  * @{
1096  */
1097
1098 #ifdef DOXYGEN
1099 /**
1100  * @brief Allocate an array.
1101  *
1102  * The macro is equivalent to:
1103  *
1104  * @code
1105  *      (type *)talloc_size(ctx, sizeof(type) * count);
1106  * @endcode
1107  *
1108  * except that it provides integer overflow protection for the multiply,
1109  * returning NULL if the multiply overflows.
1110  *
1111  * @param[in]  ctx      The talloc context to hang the result off.
1112  *
1113  * @param[in]  type     The type that we want to allocate.
1114  *
1115  * @param[in]  count    The number of 'type' elements you want to allocate.
1116  *
1117  * @return              The allocated result, properly cast to 'type *', NULL on
1118  *                      error.
1119  *
1120  * Example:
1121  * @code
1122  *      unsigned int *a, *b;
1123  *      a = talloc_zero(NULL, unsigned int);
1124  *      b = talloc_array(a, unsigned int, 100);
1125  * @endcode
1126  *
1127  * @see talloc()
1128  * @see talloc_array_zero()
1129  */
1130 void *talloc_array(const void *ctx, #type, unsigned count);
1131 #else
1132 #define talloc_array(ctx, type, count) (type *)_talloc_array(ctx, sizeof(type), count, #type)
1133 void *_talloc_array(const void *ctx, size_t el_size, unsigned count, const char *name);
1134 #endif
1135
1136 #ifdef DOXYGEN
1137 /**
1138  * @brief Allocate an array.
1139  *
1140  * @param[in]  ctx      The talloc context to hang the result off.
1141  *
1142  * @param[in]  size     The size of an array element.
1143  *
1144  * @param[in]  count    The number of elements you want to allocate.
1145  *
1146  * @return              The allocated result, NULL on error.
1147  */
1148 void *talloc_array_size(const void *ctx, size_t size, unsigned count);
1149 #else
1150 #define talloc_array_size(ctx, size, count) _talloc_array(ctx, size, count, __location__)
1151 #endif
1152
1153 #ifdef DOXYGEN
1154 /**
1155  * @brief Allocate an array into a typed pointer.
1156  *
1157  * The macro should be used when you have a pointer to an array and want to
1158  * allocate memory of an array to point at with this pointer. When compiling
1159  * with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_array_size()
1160  * and talloc_get_name() will return the current location in the source file
1161  * and not the type.
1162  *
1163  * @param[in]  ctx      The talloc context to hang the result off.
1164  *
1165  * @param[in]  ptr      The pointer you want to assign the result to.
1166  *
1167  * @param[in]  count    The number of elements you want to allocate.
1168  *
1169  * @return              The allocated memory chunk, properly casted. NULL on
1170  *                      error.
1171  */
1172 void *talloc_array_ptrtype(const void *ctx, const void *ptr, unsigned count);
1173 #else
1174 #define talloc_array_ptrtype(ctx, ptr, count) (_TALLOC_TYPEOF(ptr))talloc_array_size(ctx, sizeof(*(ptr)), count)
1175 #endif
1176
1177 #ifdef DOXYGEN
1178 /**
1179  * @brief Get the number of elements in a talloc'ed array.
1180  *
1181  * A talloc chunk carries its own size, so for talloc'ed arrays it is not
1182  * necessary to store the number of elements explicitly.
1183  *
1184  * @param[in]  ctx      The allocated array.
1185  *
1186  * @return              The number of elements in ctx.
1187  */
1188 size_t talloc_array_length(const void *ctx);
1189 #else
1190 #define talloc_array_length(ctx) (talloc_get_size(ctx)/sizeof(*ctx))
1191 #endif
1192
1193 #ifdef DOXYGEN
1194 /**
1195  * @brief Allocate a zero-initialized array
1196  *
1197  * @param[in]  ctx      The talloc context to hang the result off.
1198  *
1199  * @param[in]  type     The type that we want to allocate.
1200  *
1201  * @param[in]  count    The number of "type" elements you want to allocate.
1202  *
1203  * @return              The allocated result casted to "type *", NULL on error.
1204  *
1205  * The talloc_zero_array() macro is equivalent to:
1206  *
1207  * @code
1208  *     ptr = talloc_array(ctx, type, count);
1209  *     if (ptr) memset(ptr, sizeof(type) * count);
1210  * @endcode
1211  */
1212 void *talloc_zero_array(const void *ctx, #type, unsigned count);
1213 #else
1214 #define talloc_zero_array(ctx, type, count) (type *)_talloc_zero_array(ctx, sizeof(type), count, #type)
1215 void *_talloc_zero_array(const void *ctx,
1216                          size_t el_size,
1217                          unsigned count,
1218                          const char *name);
1219 #endif
1220
1221 #ifdef DOXYGEN
1222 /**
1223  * @brief Change the size of a talloc array.
1224  *
1225  * The macro changes the size of a talloc pointer. The 'count' argument is the
1226  * number of elements of type 'type' that you want the resulting pointer to
1227  * hold.
1228  *
1229  * talloc_realloc() has the following equivalences:
1230  *
1231  * @code
1232  *      talloc_realloc(ctx, NULL, type, 1) ==> talloc(ctx, type);
1233  *      talloc_realloc(ctx, NULL, type, N) ==> talloc_array(ctx, type, N);
1234  *      talloc_realloc(ctx, ptr, type, 0)  ==> talloc_free(ptr);
1235  * @endcode
1236  *
1237  * The "context" argument is only used if "ptr" is NULL, otherwise it is
1238  * ignored.
1239  *
1240  * @param[in]  ctx      The parent context used if ptr is NULL.
1241  *
1242  * @param[in]  ptr      The chunk to be resized.
1243  *
1244  * @param[in]  type     The type of the array element inside ptr.
1245  *
1246  * @param[in]  count    The intended number of array elements.
1247  *
1248  * @return              The new array, NULL on error. The call will fail either
1249  *                      due to a lack of memory, or because the pointer has more
1250  *                      than one parent (see talloc_reference()).
1251  */
1252 void *talloc_realloc(const void *ctx, void *ptr, #type, size_t count);
1253 #else
1254 #define talloc_realloc(ctx, p, type, count) (type *)_talloc_realloc_array(ctx, p, sizeof(type), count, #type)
1255 void *_talloc_realloc_array(const void *ctx, void *ptr, size_t el_size, unsigned count, const char *name);
1256 #endif
1257
1258 #if DOXYGEN
1259 /**
1260  * @brief Untyped realloc to change the size of a talloc array.
1261  *
1262  * The macro is useful when the type is not known so the typesafe
1263  * talloc_realloc() cannot be used.
1264  *
1265  * @param[in]  ctx      The parent context used if 'ptr' is NULL.
1266  *
1267  * @param[in]  ptr      The chunk to be resized.
1268  *
1269  * @param[in]  size     The new chunk size.
1270  *
1271  * @return              The new array, NULL on error.
1272  */
1273 void *talloc_realloc_size(const void *ctx, void *ptr, size_t size);
1274 #else
1275 #define talloc_realloc_size(ctx, ptr, size) _talloc_realloc(ctx, ptr, size, __location__)
1276 void *_talloc_realloc(const void *context, void *ptr, size_t size, const char *name);
1277 #endif
1278
1279 /**
1280  * @brief Provide a function version of talloc_realloc_size.
1281  *
1282  * This is a non-macro version of talloc_realloc(), which is useful as
1283  * libraries sometimes want a ralloc function pointer. A realloc()
1284  * implementation encapsulates the functionality of malloc(), free() and
1285  * realloc() in one call, which is why it is useful to be able to pass around
1286  * a single function pointer.
1287  *
1288  * @param[in]  context  The parent context used if ptr is NULL.
1289  *
1290  * @param[in]  ptr      The chunk to be resized.
1291  *
1292  * @param[in]  size     The new chunk size.
1293  *
1294  * @return              The new chunk, NULL on error.
1295  */
1296 void *talloc_realloc_fn(const void *context, void *ptr, size_t size);
1297
1298 /* @} ******************************************************************/
1299
1300 /**
1301  * @defgroup talloc_string The talloc string functions.
1302  * @ingroup talloc
1303  *
1304  * talloc string allocation and manipulation functions.
1305  * @{
1306  */
1307
1308 /**
1309  * @brief Duplicate a string into a talloc chunk.
1310  *
1311  * This function is equivalent to:
1312  *
1313  * @code
1314  *      ptr = talloc_size(ctx, strlen(p)+1);
1315  *      if (ptr) memcpy(ptr, p, strlen(p)+1);
1316  * @endcode
1317  *
1318  * This functions sets the name of the new pointer to the passed
1319  * string. This is equivalent to:
1320  *
1321  * @code
1322  *      talloc_set_name_const(ptr, ptr)
1323  * @endcode
1324  *
1325  * @param[in]  t        The talloc context to hang the result off.
1326  *
1327  * @param[in]  p        The string you want to duplicate.
1328  *
1329  * @return              The duplicated string, NULL on error.
1330  */
1331 char *talloc_strdup(const void *t, const char *p);
1332 char *talloc_strdup_append(char *s, const char *a);
1333 char *talloc_strdup_append_buffer(char *s, const char *a);
1334
1335 /**
1336  * @brief Duplicate a length-limited string into a talloc chunk.
1337  *
1338  * This function is the talloc equivalent of the C library function strndup(3).
1339  *
1340  * This functions sets the name of the new pointer to the passed string. This is
1341  * equivalent to:
1342  *
1343  * @code
1344  *      talloc_set_name_const(ptr, ptr)
1345  * @endcode
1346  *
1347  * @param[in]  t        The talloc context to hang the result off.
1348  *
1349  * @param[in]  p        The string you want to duplicate.
1350  *
1351  * @param[in]  n        The maximum string length to duplicate.
1352  *
1353  * @return              The duplicated string, NULL on error.
1354  */
1355 char *talloc_strndup(const void *t, const char *p, size_t n);
1356 char *talloc_strndup_append(char *s, const char *a, size_t n);
1357 char *talloc_strndup_append_buffer(char *s, const char *a, size_t n);
1358
1359 /**
1360  * @brief Format a string given a va_list.
1361  *
1362  * This function is the talloc equivalent of the C library function
1363  * vasprintf(3).
1364  *
1365  * This functions sets the name of the new pointer to the new string. This is
1366  * equivalent to:
1367  *
1368  * @code
1369  *      talloc_set_name_const(ptr, ptr)
1370  * @endcode
1371  *
1372  * @param[in]  t        The talloc context to hang the result off.
1373  *
1374  * @param[in]  fmt      The format string.
1375  *
1376  * @param[in]  ap       The parameters used to fill fmt.
1377  *
1378  * @return              The formatted string, NULL on error.
1379  */
1380 char *talloc_vasprintf(const void *t, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
1381 char *talloc_vasprintf_append(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
1382 char *talloc_vasprintf_append_buffer(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
1383
1384 /**
1385  * @brief Format a string.
1386  *
1387  * This function is the talloc equivalent of the C library function asprintf(3).
1388  *
1389  * This functions sets the name of the new pointer to the new string. This is
1390  * equivalent to:
1391  *
1392  * @code
1393  *      talloc_set_name_const(ptr, ptr)
1394  * @endcode
1395  *
1396  * @param[in]  t        The talloc context to hang the result off.
1397  *
1398  * @param[in]  fmt      The format string.
1399  *
1400  * @param[in]  ...      The parameters used to fill fmt.
1401  *
1402  * @return              The formatted string, NULL on error.
1403  */
1404 char *talloc_asprintf(const void *t, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
1405
1406 /**
1407  * @brief Append a formatted string to another string.
1408  *
1409  * This function appends the given formatted string to the given string. Use
1410  * this varient when the string in the current talloc buffer may have been
1411  * truncated in length.
1412  *
1413  * This functions sets the name of the new pointer to the new
1414  * string. This is equivalent to:
1415  *
1416  * @code
1417  *      talloc_set_name_const(ptr, ptr)
1418  * @endcode
1419  *
1420  * @param[in]  s        The string to append to.
1421  *
1422  * @param[in]  fmt      The format string.
1423  *
1424  * @param[in]  ...      The parameters used to fill fmt.
1425  *
1426  * @return              The formatted string, NULL on error.
1427  */
1428 char *talloc_asprintf_append(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
1429
1430 /**
1431  * @brief Append a formatted string to another string.
1432  *
1433  * @param[in]  s        The string to append to
1434  *
1435  * @param[in]  fmt      The format string.
1436  *
1437  * @param[in]  ...      The parameters used to fill fmt.
1438  *
1439  * @return              The formatted string, NULL on error.
1440  */
1441 char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
1442
1443 /* @} ******************************************************************/
1444
1445 /**
1446  * @defgroup talloc_debug The talloc debugging support functions
1447  * @ingroup talloc
1448  *
1449  * To aid memory debugging, talloc contains routines to inspect the currently
1450  * allocated memory hierarchy.
1451  *
1452  * @{
1453  */
1454
1455 /**
1456  * @brief Walk a complete talloc hierarchy.
1457  *
1458  * This provides a more flexible reports than talloc_report(). It
1459  * will recursively call the callback for the entire tree of memory
1460  * referenced by the pointer. References in the tree are passed with
1461  * is_ref = 1 and the pointer that is referenced.
1462  *
1463  * You can pass NULL for the pointer, in which case a report is
1464  * printed for the top level memory context, but only if
1465  * talloc_enable_leak_report() or talloc_enable_leak_report_full()
1466  * has been called.
1467  *
1468  * The recursion is stopped when depth >= max_depth.
1469  * max_depth = -1 means only stop at leaf nodes.
1470  *
1471  * @param[in]  ptr      The talloc chunk.
1472  *
1473  * @param[in]  depth    Internal parameter to control recursion. Call with 0.
1474  *
1475  * @param[in]  max_depth  Maximum recursion level.
1476  *
1477  * @param[in]  callback  Function to be called on every chunk.
1478  *
1479  * @param[in]  private_data  Private pointer passed to callback.
1480  */
1481 void talloc_report_depth_cb(const void *ptr, int depth, int max_depth,
1482                             void (*callback)(const void *ptr,
1483                                              int depth, int max_depth,
1484                                              int is_ref,
1485                                              void *private_data),
1486                             void *private_data);
1487
1488 /**
1489  * @brief Print a talloc hierarchy.
1490  *
1491  * This provides a more flexible reports than talloc_report(). It
1492  * will let you specify the depth and max_depth.
1493  *
1494  * @param[in]  ptr      The talloc chunk.
1495  *
1496  * @param[in]  depth    Internal parameter to control recursion. Call with 0.
1497  *
1498  * @param[in]  max_depth  Maximum recursion level.
1499  *
1500  * @param[in]  f        The file handle to print to.
1501  */
1502 void talloc_report_depth_file(const void *ptr, int depth, int max_depth, FILE *f);
1503
1504 /**
1505  * @brief Print a summary report of all memory used by ptr.
1506  *
1507  * This provides a more detailed report than talloc_report(). It will
1508  * recursively print the ensire tree of memory referenced by the
1509  * pointer. References in the tree are shown by giving the name of the
1510  * pointer that is referenced.
1511  *
1512  * You can pass NULL for the pointer, in which case a report is printed
1513  * for the top level memory context, but only if
1514  * talloc_enable_leak_report() or talloc_enable_leak_report_full() has
1515  * been called.
1516  *
1517  * @param[in]  ptr      The talloc chunk.
1518  *
1519  * @param[in]  f        The file handle to print to.
1520  *
1521  * Example:
1522  * @code
1523  *      unsigned int *a, *b;
1524  *      a = talloc(NULL, unsigned int);
1525  *      b = talloc(a, unsigned int);
1526  *      fprintf(stderr, "Dumping memory tree for a:\n");
1527  *      talloc_report_full(a, stderr);
1528  * @endcode
1529  *
1530  * @see talloc_report()
1531  */
1532 void talloc_report_full(const void *ptr, FILE *f);
1533
1534 /**
1535  * @brief Print a summary report of all memory used by ptr.
1536  *
1537  * This function prints a summary report of all memory used by ptr. One line of
1538  * report is printed for each immediate child of ptr, showing the total memory
1539  * and number of blocks used by that child.
1540  *
1541  * You can pass NULL for the pointer, in which case a report is printed
1542  * for the top level memory context, but only if talloc_enable_leak_report()
1543  * or talloc_enable_leak_report_full() has been called.
1544  *
1545  * @param[in]  ptr      The talloc chunk.
1546  *
1547  * @param[in]  f        The file handle to print to.
1548  *
1549  * Example:
1550  * @code
1551  *      unsigned int *a, *b;
1552  *      a = talloc(NULL, unsigned int);
1553  *      b = talloc(a, unsigned int);
1554  *      fprintf(stderr, "Summary of memory tree for a:\n");
1555  *      talloc_report(a, stderr);
1556  * @endcode
1557  *
1558  * @see talloc_report_full()
1559  */
1560 void talloc_report(const void *ptr, FILE *f);
1561
1562 /**
1563  * @brief Enable tracking the use of NULL memory contexts.
1564  *
1565  * This enables tracking of the NULL memory context without enabling leak
1566  * reporting on exit. Useful for when you want to do your own leak
1567  * reporting call via talloc_report_null_full();
1568  */
1569 void talloc_enable_null_tracking(void);
1570
1571 /**
1572  * @brief Enable tracking the use of NULL memory contexts.
1573  *
1574  * This enables tracking of the NULL memory context without enabling leak
1575  * reporting on exit. Useful for when you want to do your own leak
1576  * reporting call via talloc_report_null_full();
1577  */
1578 void talloc_enable_null_tracking_no_autofree(void);
1579
1580 /**
1581  * @brief Disable tracking of the NULL memory context.
1582  *
1583  * This disables tracking of the NULL memory context.
1584  */
1585 void talloc_disable_null_tracking(void);
1586
1587 /**
1588  * @brief Enable leak report when a program exits.
1589  *
1590  * This enables calling of talloc_report(NULL, stderr) when the program
1591  * exits. In Samba4 this is enabled by using the --leak-report command
1592  * line option.
1593  *
1594  * For it to be useful, this function must be called before any other
1595  * talloc function as it establishes a "null context" that acts as the
1596  * top of the tree. If you don't call this function first then passing
1597  * NULL to talloc_report() or talloc_report_full() won't give you the
1598  * full tree printout.
1599  *
1600  * Here is a typical talloc report:
1601  *
1602  * @code
1603  * talloc report on 'null_context' (total 267 bytes in 15 blocks)
1604  *      libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
1605  *      libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
1606  *      iconv(UTF8,CP850)              contains     42 bytes in   2 blocks
1607  *      libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
1608  *      iconv(CP850,UTF8)              contains     42 bytes in   2 blocks
1609  *      iconv(UTF8,UTF-16LE)           contains     45 bytes in   2 blocks
1610  *      iconv(UTF-16LE,UTF8)           contains     45 bytes in   2 blocks
1611  * @endcode
1612  */
1613 void talloc_enable_leak_report(void);
1614
1615 /**
1616  * @brief Enable full leak report when a program exits.
1617  *
1618  * This enables calling of talloc_report_full(NULL, stderr) when the
1619  * program exits. In Samba4 this is enabled by using the
1620  * --leak-report-full command line option.
1621  *
1622  * For it to be useful, this function must be called before any other
1623  * talloc function as it establishes a "null context" that acts as the
1624  * top of the tree. If you don't call this function first then passing
1625  * NULL to talloc_report() or talloc_report_full() won't give you the
1626  * full tree printout.
1627  *
1628  * Here is a typical full report:
1629  *
1630  * @code
1631  * full talloc report on 'root' (total 18 bytes in 8 blocks)
1632  *      p1                             contains     18 bytes in   7 blocks (ref 0)
1633  *      r1                             contains     13 bytes in   2 blocks (ref 0)
1634  *      reference to: p2
1635  *      p2                             contains      1 bytes in   1 blocks (ref 1)
1636  *      x3                             contains      1 bytes in   1 blocks (ref 0)
1637  *      x2                             contains      1 bytes in   1 blocks (ref 0)
1638  *      x1                             contains      1 bytes in   1 blocks (ref 0)
1639  * @endcode
1640  */
1641 void talloc_enable_leak_report_full(void);
1642
1643 /* @} ******************************************************************/
1644
1645 void talloc_set_abort_fn(void (*abort_fn)(const char *reason));
1646 void talloc_set_log_fn(void (*log_fn)(const char *message));
1647 void talloc_set_log_stderr(void);
1648
1649 #if TALLOC_DEPRECATED
1650 #define talloc_zero_p(ctx, type) talloc_zero(ctx, type)
1651 #define talloc_p(ctx, type) talloc(ctx, type)
1652 #define talloc_array_p(ctx, type, count) talloc_array(ctx, type, count)
1653 #define talloc_realloc_p(ctx, p, type, count) talloc_realloc(ctx, p, type, count)
1654 #define talloc_destroy(ctx) talloc_free(ctx)
1655 #define talloc_append_string(c, s, a) (s?talloc_strdup_append(s,a):talloc_strdup(c, a))
1656 #endif
1657
1658 #endif