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