source/lib/talloc/talloc_guide.txt

   1 Using talloc in Samba4
   2 ----------------------
   3
   4 Andrew Tridgell
   5 September 2004
   6
   7 The most current version of this document is available at
   8    http://samba.org/ftp/unpacked/samba4/source/lib/talloc/talloc_guide.txt
   9
  10 If you are used to the "old" talloc from Samba3 before 3.0.20 then please read
  11 this carefully, as talloc has changed a lot. With 3.0.20 (or 3.0.14?) the
  12 Samba4 talloc has been ported back to Samba3, so this guide applies to both.
  13
  14 The new talloc is a hierarchical, reference counted memory pool system
  15 with destructors. Quite a mounthful really, but not too bad once you
  16 get used to it.
  17
  18 Perhaps the biggest change from Samba3 is that there is no distinction
  19 between a "talloc context" and a "talloc pointer". Any pointer
  20 returned from talloc() is itself a valid talloc context. This means
  21 you can do this:
  22
  23   struct foo *X = talloc(mem_ctx, struct foo);
  24   X->name = talloc_strdup(X, "foo");
  25
  26 and the pointer X->name would be a "child" of the talloc context "X"
  27 which is itself a child of mem_ctx. So if you do talloc_free(mem_ctx)
  28 then it is all destroyed, whereas if you do talloc_free(X) then just X
  29 and X->name are destroyed, and if you do talloc_free(X->name) then
  30 just the name element of X is destroyed.
  31
  32 If you think about this, then what this effectively gives you is an
  33 n-ary tree, where you can free any part of the tree with
  34 talloc_free().
  35
  36 If you find this confusing, then I suggest you run the testsuite to
  37 watch talloc in action. You may also like to add your own tests to
  38 testsuite.c to clarify how some particular situation is handled.
  39
  40
  41 Performance
  42 -----------
  43
  44 All the additional features of talloc() over malloc() do come at a
  45 price. We have a simple performance test in Samba4 that measures
  46 talloc() versus malloc() performance, and it seems that talloc() is
  47 about 4% slower than malloc() on my x86 Debian Linux box. For Samba,
  48 the great reduction in code complexity that we get by using talloc
  49 makes this worthwhile, especially as the total overhead of
  50 talloc/malloc in Samba is already quite small.
  51
  52
  53 talloc API
  54 ----------
  55
  56 The following is a complete guide to the talloc API. Read it all at
  57 least twice.
  58
  59
  60 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  61 (type *)talloc(const void *context, type);
  62
  63 The talloc() macro is the core of the talloc library. It takes a
  64 memory context and a type, and returns a pointer to a new area of
  65 memory of the given type.
  66
  67 The returned pointer is itself a talloc context, so you can use it as
  68 the context argument to more calls to talloc if you wish.
  69
  70 The returned pointer is a "child" of the supplied context. This means
  71 that if you talloc_free() the context then the new child disappears as
  72 well. Alternatively you can free just the child.
  73
  74 The context argument to talloc() can be NULL, in which case a new top
  75 level context is created.
  76
  77
  78 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  79 void *talloc_size(const void *context, size_t size);
  80
  81 The function talloc_size() should be used when you don't have a
  82 convenient type to pass to talloc(). Unlike talloc(), it is not type
  83 safe (as it returns a void *), so you are on your own for type checking.
  84
  85 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  86 (typeof(ptr)) talloc_ptrtype(const void *ctx, ptr);
  87
  88 The talloc_ptrtype() macro should be used when you have a pointer and
  89 want to allocate memory to point at with this pointer. When compiling
  90 with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size()
  91 and talloc_get_name() will return the current location in the source file.
  92 and not the type.
  93
  94 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  95 int talloc_free(void *ptr);
  96
  97 The talloc_free() function frees a piece of talloc memory, and all its
  98 children. You can call talloc_free() on any pointer returned by
  99 talloc().
 100
 101 The return value of talloc_free() indicates success or failure, with 0
 102 returned for success and -1 for failure. The only possible failure
 103 condition is if the pointer had a destructor attached to it and the
 104 destructor returned -1. See talloc_set_destructor() for details on
 105 destructors.
 106
 107 If this pointer has an additional parent when talloc_free() is called
 108 then the memory is not actually released, but instead the most
 109 recently established parent is destroyed. See talloc_reference() for
 110 details on establishing additional parents.
 111
 112 For more control on which parent is removed, see talloc_unlink()
 113
 114 talloc_free() operates recursively on its children.
 115
 116
 117 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 118 int talloc_free_children(void *ptr);
 119
 120 The talloc_free_children() walks along the list of all children of a
 121 talloc context and talloc_free()s only the children, not the context
 122 itself.
 123
 124
 125 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 126 void *talloc_reference(const void *context, const void *ptr);
 127
 128 The talloc_reference() function makes "context" an additional parent
 129 of "ptr".
 130
 131 The return value of talloc_reference() is always the original pointer
 132 "ptr", unless talloc ran out of memory in creating the reference in
 133 which case it will return NULL (each additional reference consumes
 134 around 48 bytes of memory on intel x86 platforms).
 135
 136 If "ptr" is NULL, then the function is a no-op, and simply returns NULL.
 137
 138 After creating a reference you can free it in one of the following
 139 ways:
 140
 141   - you can talloc_free() any parent of the original pointer. That
 142     will reduce the number of parents of this pointer by 1, and will
 143     cause this pointer to be freed if it runs out of parents.
 144
 145   - you can talloc_free() the pointer itself. That will destroy the
 146     most recently established parent to the pointer and leave the
 147     pointer as a child of its current parent.
 148
 149 For more control on which parent to remove, see talloc_unlink()
 150
 151
 152 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 153 int talloc_unlink(const void *context, const void *ptr);
 154
 155 The talloc_unlink() function removes a specific parent from ptr. The
 156 context passed must either be a context used in talloc_reference()
 157 with this pointer, or must be a direct parent of ptr.
 158
 159 Note that if the parent has already been removed using talloc_free()
 160 then this function will fail and will return -1.  Likewise, if "ptr"
 161 is NULL, then the function will make no modifications and return -1.
 162
 163 Usually you can just use talloc_free() instead of talloc_unlink(), but
 164 sometimes it is useful to have the additional control on which parent
 165 is removed.
 166
 167
 168 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 169 void talloc_set_destructor(const void *ptr, int (*destructor)(void *));
 170
 171 The function talloc_set_destructor() sets the "destructor" for the
 172 pointer "ptr". A destructor is a function that is called when the
 173 memory used by a pointer is about to be released. The destructor
 174 receives the pointer as an argument, and should return 0 for success
 175 and -1 for failure.
 176
 177 The destructor can do anything it wants to, including freeing other
 178 pieces of memory. A common use for destructors is to clean up
 179 operating system resources (such as open file descriptors) contained
 180 in the structure the destructor is placed on.
 181
 182 You can only place one destructor on a pointer. If you need more than
 183 one destructor then you can create a zero-length child of the pointer
 184 and place an additional destructor on that.
 185
 186 To remove a destructor call talloc_set_destructor() with NULL for the
 187 destructor.
 188
 189 If your destructor attempts to talloc_free() the pointer that it is
 190 the destructor for then talloc_free() will return -1 and the free will
 191 be ignored. This would be a pointless operation anyway, as the
 192 destructor is only called when the memory is just about to go away.
 193
 194
 195 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 196 void talloc_increase_ref_count(const void *ptr);
 197
 198 The talloc_increase_ref_count(ptr) function is exactly equivalent to:
 199
 200   talloc_reference(NULL, ptr);
 201
 202 You can use either syntax, depending on which you think is clearer in
 203 your code.
 204
 205
 206 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 207 void talloc_set_name(const void *ptr, const char *fmt, ...);
 208
 209 Each talloc pointer has a "name". The name is used principally for
 210 debugging purposes, although it is also possible to set and get the
 211 name on a pointer in as a way of "marking" pointers in your code.
 212
 213 The main use for names on pointer is for "talloc reports". See
 214 talloc_report() and talloc_report_full() for details. Also see
 215 talloc_enable_leak_report() and talloc_enable_leak_report_full().
 216
 217 The talloc_set_name() function allocates memory as a child of the
 218 pointer. It is logically equivalent to:
 219   talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));
 220
 221 Note that multiple calls to talloc_set_name() will allocate more
 222 memory without releasing the name. All of the memory is released when
 223 the ptr is freed using talloc_free().
 224
 225
 226 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 227 void talloc_set_name_const(const void *ptr, const char *name);
 228
 229 The function talloc_set_name_const() is just like talloc_set_name(),
 230 but it takes a string constant, and is much faster. It is extensively
 231 used by the "auto naming" macros, such as talloc_p().
 232
 233 This function does not allocate any memory. It just copies the
 234 supplied pointer into the internal representation of the talloc
 235 ptr. This means you must not pass a name pointer to memory that will
 236 disappear before the ptr is freed with talloc_free().
 237
 238
 239 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 240 void *talloc_named(const void *context, size_t size, const char *fmt, ...);
 241
 242 The talloc_named() function creates a named talloc pointer. It is
 243 equivalent to:
 244
 245    ptr = talloc_size(context, size);
 246    talloc_set_name(ptr, fmt, ....);
 247
 248
 249 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 250 void *talloc_named_const(const void *context, size_t size, const char *name);
 251
 252 This is equivalent to:
 253
 254    ptr = talloc_size(context, size);
 255    talloc_set_name_const(ptr, name);
 256
 257
 258 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 259 const char *talloc_get_name(const void *ptr);
 260
 261 This returns the current name for the given talloc pointer. See
 262 talloc_set_name() for details.
 263
 264
 265 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 266 void *talloc_init(const char *fmt, ...);
 267
 268 This function creates a zero length named talloc context as a top
 269 level context. It is equivalent to:
 270
 271   talloc_named(NULL, 0, fmt, ...);
 272
 273
 274 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 275 void *talloc_new(void *ctx);
 276
 277 This is a utility macro that creates a new memory context hanging
 278 off an exiting context, automatically naming it "talloc_new: __location__"
 279 where __location__ is the source line it is called from. It is
 280 particularly useful for creating a new temporary working context.
 281
 282
 283 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 284 (type *)talloc_realloc(const void *context, void *ptr, type, count);
 285
 286 The talloc_realloc() macro changes the size of a talloc
 287 pointer. The "count" argument is the number of elements of type "type"
 288 that you want the resulting pointer to hold.
 289
 290 talloc_realloc() has the following equivalences:
 291
 292   talloc_realloc(context, NULL, type, 1) ==> talloc(context, type);
 293   talloc_realloc(context, NULL, type, N) ==> talloc_array(context, type, N);
 294   talloc_realloc(context, ptr, type, 0)  ==> talloc_free(ptr);
 295
 296 The "context" argument is only used if "ptr" is NULL, otherwise it is
 297 ignored.
 298
 299 talloc_realloc() returns the new pointer, or NULL on failure. The call
 300 will fail either due to a lack of memory, or because the pointer has
 301 more than one parent (see talloc_reference()).
 302
 303
 304 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 305 void *talloc_realloc_size(const void *context, void *ptr, size_t size);
 306
 307 the talloc_realloc_size() function is useful when the type is not
 308 known so the typesafe talloc_realloc() cannot be used.
 309
 310
 311 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 312 void *talloc_steal(const void *new_ctx, const void *ptr);
 313
 314 The talloc_steal() function changes the parent context of a talloc
 315 pointer. It is typically used when the context that the pointer is
 316 currently a child of is going to be freed and you wish to keep the
 317 memory for a longer time.
 318
 319 The talloc_steal() function returns the pointer that you pass it. It
 320 does not have any failure modes.
 321
 322 NOTE: It is possible to produce loops in the parent/child relationship
 323 if you are not careful with talloc_steal(). No guarantees are provided
 324 as to your sanity or the safety of your data if you do this.
 325
 326 talloc_steal (new_ctx, NULL) will return NULL with no sideeffects.
 327
 328 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 329 size_t talloc_total_size(const void *ptr);
 330
 331 The talloc_total_size() function returns the total size in bytes used
 332 by this pointer and all child pointers. Mostly useful for debugging.
 333
 334 Passing NULL is allowed, but it will only give a meaningful result if
 335 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
 336 been called.
 337
 338
 339 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 340 size_t talloc_total_blocks(const void *ptr);
 341
 342 The talloc_total_blocks() function returns the total memory block
 343 count used by this pointer and all child pointers. Mostly useful for
 344 debugging.
 345
 346 Passing NULL is allowed, but it will only give a meaningful result if
 347 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
 348 been called.
 349
 350
 351 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 352 void talloc_report(const void *ptr, FILE *f);
 353
 354 The talloc_report() function prints a summary report of all memory
 355 used by ptr. One line of report is printed for each immediate child of
 356 ptr, showing the total memory and number of blocks used by that child.
 357
 358 You can pass NULL for the pointer, in which case a report is printed
 359 for the top level memory context, but only if
 360 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
 361 been called.
 362
 363
 364 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 365 void talloc_report_full(const void *ptr, FILE *f);
 366
 367 This provides a more detailed report than talloc_report(). It will
 368 recursively print the ensire tree of memory referenced by the
 369 pointer. References in the tree are shown by giving the name of the
 370 pointer that is referenced.
 371
 372 You can pass NULL for the pointer, in which case a report is printed
 373 for the top level memory context, but only if
 374 talloc_enable_leak_report() or talloc_enable_leak_report_full() has
 375 been called.
 376
 377
 378 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 379 void talloc_enable_leak_report(void);
 380
 381 This enables calling of talloc_report(NULL, stderr) when the program
 382 exits. In Samba4 this is enabled by using the --leak-report command
 383 line option.
 384
 385 For it to be useful, this function must be called before any other
 386 talloc function as it establishes a "null context" that acts as the
 387 top of the tree. If you don't call this function first then passing
 388 NULL to talloc_report() or talloc_report_full() won't give you the
 389 full tree printout.
 390
 391 Here is a typical talloc report:
 392
 393 talloc report on 'null_context' (total 267 bytes in 15 blocks)
 394         libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
 395         libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
 396         iconv(UTF8,CP850)              contains     42 bytes in   2 blocks
 397         libcli/auth/spnego_parse.c:55  contains     31 bytes in   2 blocks
 398         iconv(CP850,UTF8)              contains     42 bytes in   2 blocks
 399         iconv(UTF8,UTF-16LE)           contains     45 bytes in   2 blocks
 400         iconv(UTF-16LE,UTF8)           contains     45 bytes in   2 blocks
 401
 402
 403 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 404 void talloc_enable_leak_report_full(void);
 405
 406 This enables calling of talloc_report_full(NULL, stderr) when the
 407 program exits. In Samba4 this is enabled by using the
 408 --leak-report-full command line option.
 409
 410 For it to be useful, this function must be called before any other
 411 talloc function as it establishes a "null context" that acts as the
 412 top of the tree. If you don't call this function first then passing
 413 NULL to talloc_report() or talloc_report_full() won't give you the
 414 full tree printout.
 415
 416 Here is a typical full report:
 417
 418 full talloc report on 'root' (total 18 bytes in 8 blocks)
 419     p1                             contains     18 bytes in   7 blocks (ref 0)
 420         r1                             contains     13 bytes in   2 blocks (ref 0)
 421             reference to: p2
 422         p2                             contains      1 bytes in   1 blocks (ref 1)
 423         x3                             contains      1 bytes in   1 blocks (ref 0)
 424         x2                             contains      1 bytes in   1 blocks (ref 0)
 425         x1                             contains      1 bytes in   1 blocks (ref 0)
 426
 427
 428 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 429 void talloc_enable_null_tracking(void);
 430
 431 This enables tracking of the NULL memory context without enabling leak
 432 reporting on exit. Useful for when you want to do your own leak
 433 reporting call via talloc_report_null_full();
 434
 435
 436 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 437 (type *)talloc_zero(const void *ctx, type);
 438
 439 The talloc_zero() macro is equivalent to:
 440
 441   ptr = talloc(ctx, type);
 442   if (ptr) memset(ptr, 0, sizeof(type));
 443
 444
 445 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 446 void *talloc_zero_size(const void *ctx, size_t size)
 447
 448 The talloc_zero_size() function is useful when you don't have a known type
 449
 450
 451 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 452 void *talloc_memdup(const void *ctx, const void *p, size_t size);
 453
 454 The talloc_memdup() function is equivalent to:
 455
 456   ptr = talloc_size(ctx, size);
 457   if (ptr) memcpy(ptr, p, size);
 458
 459
 460 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 461 char *talloc_strdup(const void *ctx, const char *p);
 462
 463 The talloc_strdup() function is equivalent to:
 464
 465   ptr = talloc_size(ctx, strlen(p)+1);
 466   if (ptr) memcpy(ptr, p, strlen(p)+1);
 467
 468 This functions sets the name of the new pointer to the passed
 469 string. This is equivalent to:
 470    talloc_set_name_const(ptr, ptr)
 471
 472 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 473 char *talloc_strndup(const void *t, const char *p, size_t n);
 474
 475 The talloc_strndup() function is the talloc equivalent of the C
 476 library function strndup()
 477
 478 This functions sets the name of the new pointer to the passed
 479 string. This is equivalent to:
 480    talloc_set_name_const(ptr, ptr)
 481
 482
 483 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 484 char *talloc_vasprintf(const void *t, const char *fmt, va_list ap);
 485
 486 The talloc_vasprintf() function is the talloc equivalent of the C
 487 library function vasprintf()
 488
 489
 490 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 491 char *talloc_asprintf(const void *t, const char *fmt, ...);
 492
 493 The talloc_asprintf() function is the talloc equivalent of the C
 494 library function asprintf()
 495
 496 This functions sets the name of the new pointer to the passed
 497 string. This is equivalent to:
 498    talloc_set_name_const(ptr, ptr)
 499
 500
 501 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 502 char *talloc_asprintf_append(char *s, const char *fmt, ...);
 503
 504 The talloc_asprintf_append() function appends the given formatted
 505 string to the given string.
 506
 507
 508 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 509 (type *)talloc_array(const void *ctx, type, uint_t count);
 510
 511 The talloc_array() macro is equivalent to:
 512
 513   (type *)talloc_size(ctx, sizeof(type) * count);
 514
 515 except that it provides integer overflow protection for the multiply,
 516 returning NULL if the multiply overflows.
 517
 518
 519 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 520 void *talloc_array_size(const void *ctx, size_t size, uint_t count);
 521
 522 The talloc_array_size() function is useful when the type is not
 523 known. It operates in the same way as talloc_array(), but takes a size
 524 instead of a type.
 525
 526 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 527 (typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, uint_t count);
 528
 529 The talloc_ptrtype() macro should be used when you have a pointer to an array
 530 and want to allocate memory of an array to point at with this pointer. When compiling
 531 with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_array_size()
 532 and talloc_get_name() will return the current location in the source file.
 533 and not the type.
 534
 535 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 536 void *talloc_realloc_fn(const void *ctx, void *ptr, size_t size);
 537
 538 This is a non-macro version of talloc_realloc(), which is useful
 539 as libraries sometimes want a ralloc function pointer. A realloc()
 540 implementation encapsulates the functionality of malloc(), free() and
 541 realloc() in one call, which is why it is useful to be able to pass
 542 around a single function pointer.
 543
 544
 545 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 546 void *talloc_autofree_context(void);
 547
 548 This is a handy utility function that returns a talloc context
 549 which will be automatically freed on program exit. This can be used
 550 to reduce the noise in memory leak reports.
 551
 552
 553 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 554 void *talloc_check_name(const void *ptr, const char *name);
 555
 556 This function checks if a pointer has the specified name. If it does
 557 then the pointer is returned. It it doesn't then NULL is returned.
 558
 559
 560 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 561 (type *)talloc_get_type(const void *ptr, type);
 562
 563 This macro allows you to do type checking on talloc pointers. It is
 564 particularly useful for void* private pointers. It is equivalent to
 565 this:
 566
 567    (type *)talloc_check_name(ptr, #type)
 568
 569
 570 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 571 talloc_set_type(const void *ptr, type);
 572
 573 This macro allows you to force the name of a pointer to be a
 574 particular type. This can be used in conjunction with
 575 talloc_get_type() to do type checking on void* pointers.
 576
 577 It is equivalent to this:
 578    talloc_set_name_const(ptr, #type)
 579
 580 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 581 talloc_get_size(const void *ctx);
 582
 583 This function lets you know the amount of memory alloced so far by
 584 this context. It does NOT account for subcontext memory.
 585 This can be used to calculate the size of an array.
 586
 587 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 588 void *talloc_find_parent_byname(const void *ctx, const char *name);
 589
 590 Find a parent memory context of the current context that has the given
 591 name. This can be very useful in complex programs where it may be
 592 difficult to pass all information down to the level you need, but you
 593 know the structure you want is a parent of another context.
 594
 595 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 596 (type *)talloc_find_parent_bytype(ctx, type);
 597
 598 Like talloc_find_parent_byname() but takes a type, making it typesafe.
 599