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