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