2000-07-27 00:47:19 +00:00
# ifndef _TALLOC_H_
# define _TALLOC_H_
2012-04-16 12:44:08 +02:00
/*
2002-01-30 06:08:46 +00:00
Unix SMB / CIFS implementation .
2000-01-05 06:36:36 +00:00
Samba temporary memory allocation functions
2005-05-03 07:33:49 +00:00
Copyright ( C ) Andrew Tridgell 2004 - 2005
2006-08-29 16:54:12 +00:00
Copyright ( C ) Stefan Metzmacher 2006
2012-04-16 12:44:08 +02:00
2005-12-01 00:43:34 +00:00
* * NOTE ! The following LGPL license applies to the talloc
* * library . This does NOT imply that all of Samba is released
* * under the LGPL
2012-04-16 12:44:08 +02:00
2005-12-01 00:43:34 +00:00
This library is free software ; you can redistribute it and / or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation ; either
2007-07-10 01:44:42 +00:00
version 3 of the License , or ( at your option ) any later version .
2005-12-01 00:43:34 +00:00
This library is distributed in the hope that it will be useful ,
2000-01-05 06:36:36 +00:00
but WITHOUT ANY WARRANTY ; without even the implied warranty of
2005-12-01 00:43:34 +00:00
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE . See the GNU
Lesser General Public License for more details .
You should have received a copy of the GNU Lesser General Public
2007-07-10 03:42:26 +00:00
License along with this library ; if not , see < http : //www.gnu.org/licenses/>.
2000-01-05 06:36:36 +00:00
*/
2007-04-19 09:08:53 +00:00
# include <stdlib.h>
# include <stdio.h>
# include <stdarg.h>
2010-10-20 13:09:57 -04:00
# ifdef __cplusplus
extern " C " {
# endif
2019-03-07 00:40:12 +01:00
/* for old gcc releases that don't have the feature test macro __has_attribute */
# ifndef __has_attribute
# define __has_attribute(x) 0
# endif
# ifndef _PUBLIC_
# if __has_attribute(visibility)
# define _PUBLIC_ __attribute__((visibility("default")))
# else
# define _PUBLIC_
# endif
# endif
2010-01-17 11:25:02 +01:00
/**
* @ defgroup talloc The talloc API
*
* talloc is a hierarchical , reference counted memory pool system with
* destructors . It is the core memory allocator used in Samba .
*
* @ {
*/
2009-08-20 13:43:42 +02:00
# define TALLOC_VERSION_MAJOR 2
2023-01-18 11:52:33 +01:00
# define TALLOC_VERSION_MINOR 4
2009-08-20 13:43:42 +02:00
2019-03-07 00:40:12 +01:00
_PUBLIC_ int talloc_version_major ( void ) ;
_PUBLIC_ int talloc_version_minor ( void ) ;
2015-09-04 12:03:33 +12:00
/* This is mostly useful only for testing */
2019-03-07 00:40:12 +01:00
_PUBLIC_ int talloc_test_get_magic ( void ) ;
2009-08-20 13:43:42 +02:00
2010-01-17 11:25:02 +01:00
/**
* @ brief Define a talloc parent type
*
* As talloc is a hierarchial memory allocator , every talloc chunk is a
* potential parent to other talloc chunks . So defining a separate type for a
* talloc chunk is not strictly necessary . TALLOC_CTX is defined nevertheless ,
* as it provides an indicator for function arguments . You will frequently
* write code like
*
* @ code
* struct foo * foo_create ( TALLOC_CTX * mem_ctx )
* {
* struct foo * result ;
* result = talloc ( mem_ctx , struct foo ) ;
* if ( result = = NULL ) return NULL ;
* . . . initialize foo . . .
* return result ;
* }
* @ endcode
*
* In this type of allocating functions it is handy to have a general
* TALLOC_CTX type to indicate which parent to put allocated structures on .
*/
2005-05-03 07:33:49 +00:00
typedef void TALLOC_CTX ;
/*
this uses a little trick to allow __LINE__ to be stringified
*/
2007-04-16 19:15:57 +00:00
# ifndef __location__
# define __TALLOC_STRING_LINE1__(s) #s
# define __TALLOC_STRING_LINE2__(s) __TALLOC_STRING_LINE1__(s)
# define __TALLOC_STRING_LINE3__ __TALLOC_STRING_LINE2__(__LINE__)
# define __location__ __FILE__ ":" __TALLOC_STRING_LINE3__
# endif
2005-05-03 07:33:49 +00:00
# ifndef TALLOC_DEPRECATED
# define TALLOC_DEPRECATED 0
# endif
2006-08-29 16:54:12 +00:00
# ifndef PRINTF_ATTRIBUTE
2020-05-24 13:56:22 +02:00
# if __has_attribute(format) || (__GNUC__ >= 3)
2006-08-29 16:54:12 +00:00
/** Use gcc attribute to check printf fns. a1 is the 1-based index of
* the parameter containing the format , and a2 the index of the first
* argument . Note that some gcc 2. x versions don ' t handle this
* properly * */
# define PRINTF_ATTRIBUTE(a1, a2) __attribute__ ((format (__printf__, a1, a2)))
# else
# define PRINTF_ATTRIBUTE(a1, a2)
# endif
# endif
2018-11-05 16:56:05 -08:00
# ifndef _DEPRECATED_
2020-10-08 12:05:41 +02:00
# if __has_attribute(deprecated) || (__GNUC__ >= 3)
2018-11-05 16:56:05 -08:00
# define _DEPRECATED_ __attribute__ ((deprecated))
# else
# define _DEPRECATED_
# endif
# endif
2010-01-17 11:25:02 +01:00
# ifdef DOXYGEN
2018-11-05 16:56:05 -08:00
2010-01-17 11:25:02 +01:00
/**
* @ brief Create a new talloc context .
*
* The talloc ( ) macro is the core of the talloc library . It takes a memory
* context and a type , and returns a pointer to a new area of memory of the
* given type .
*
* The returned pointer is itself a talloc context , so you can use it as the
* context argument to more calls to talloc if you wish .
*
* The returned pointer is a " child " of the supplied context . This means that if
* you talloc_free ( ) the context then the new child disappears as well .
* Alternatively you can free just the child .
*
* @ param [ in ] ctx A talloc context to create a new reference on or NULL to
* create a new top level context .
*
* @ param [ in ] type The type of memory to allocate .
*
* @ return A type casted talloc context or NULL on error .
*
* @ code
* unsigned int * a , * b ;
*
* a = talloc ( NULL , unsigned int ) ;
* b = talloc ( a , unsigned int ) ;
* @ endcode
*
* @ see talloc_zero
* @ see talloc_array
* @ see talloc_steal
* @ see talloc_free
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc ( const void * ctx , # type ) ;
2010-01-17 11:25:02 +01:00
# else
# define talloc(ctx, type) (type *)talloc_named_const(ctx, sizeof(type), #type)
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * _talloc ( const void * context , size_t size ) ;
2010-01-17 11:25:02 +01:00
# endif
/**
* @ brief Create a new top level talloc context .
*
* This function creates a zero length named talloc context as a top level
* context . It is equivalent to :
*
* @ code
* talloc_named ( NULL , 0 , fmt , . . . ) ;
* @ endcode
* @ param [ in ] fmt Format string for the name .
*
* @ param [ in ] . . . Additional printf - style arguments .
*
* @ return The allocated memory chunk , NULL on error .
*
* @ see talloc_named ( )
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_init ( const char * fmt , . . . ) PRINTF_ATTRIBUTE ( 1 , 2 ) ;
2010-01-17 11:25:02 +01:00
# ifdef DOXYGEN
/**
* @ brief Free a chunk of talloc memory .
*
2010-08-14 18:36:49 +02:00
* The talloc_free ( ) function frees a piece of talloc memory , and all its
* children . You can call talloc_free ( ) on any pointer returned by
* talloc ( ) .
2010-01-17 11:25:02 +01:00
*
2010-08-14 18:36:49 +02:00
* The return value of talloc_free ( ) indicates success or failure , with 0
* returned for success and - 1 for failure . A possible failure condition
* is if the pointer had a destructor attached to it and the destructor
* returned - 1. See talloc_set_destructor ( ) for details on
* destructors . Likewise , if " ptr " is NULL , then the function will make
* no modifications and return - 1.
2010-01-17 11:25:02 +01:00
*
2011-03-31 21:32:51 +02:00
* From version 2.0 and onwards , as a special case , talloc_free ( ) is
* refused on pointers that have more than one parent associated , as talloc
* would have no way of knowing which parent should be removed . This is
* different from older versions in the sense that always the reference to
* the most recently established parent has been destroyed . Hence to free a
2010-01-17 11:25:02 +01:00
* pointer that has more than one parent please use talloc_unlink ( ) .
*
* To help you find problems in your code caused by this behaviour , if
* you do try and free a pointer with more than one parent then the
* talloc logging function will be called to give output like this :
*
* @ code
* ERROR : talloc_free with references at some_dir / source / foo . c : 123
* reference at some_dir / source / other . c : 325
* reference at some_dir / source / third . c : 121
* @ endcode
*
* Please see the documentation for talloc_set_log_fn ( ) and
* talloc_set_log_stderr ( ) for more information on talloc logging
* functions .
*
2012-04-16 15:04:44 +02:00
* If < code > TALLOC_FREE_FILL < / code > environment variable is set ,
* the memory occupied by the context is filled with the value of this variable .
* The value should be a numeric representation of the character you want to
* use .
*
2011-03-31 21:32:51 +02:00
* talloc_free ( ) operates recursively on its children .
*
2010-01-17 11:25:02 +01:00
* @ param [ in ] ptr The chunk to be freed .
*
2010-08-14 18:36:49 +02:00
* @ return Returns 0 on success and - 1 on error . A possible
2010-01-17 11:25:02 +01:00
* failure condition is if the pointer had a destructor
2010-08-14 18:36:49 +02:00
* attached to it and the destructor returned - 1. Likewise ,
* if " ptr " is NULL , then the function will make no
* modifications and returns - 1.
2010-01-17 11:25:02 +01:00
*
* Example :
* @ code
* unsigned int * a , * b ;
* a = talloc ( NULL , unsigned int ) ;
* b = talloc ( a , unsigned int ) ;
*
* talloc_free ( a ) ; // Frees a and b
* @ endcode
*
* @ see talloc_set_destructor ( )
* @ see talloc_unlink ( )
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ int talloc_free ( void * ptr ) ;
2010-01-17 11:25:02 +01:00
# else
# define talloc_free(ctx) _talloc_free(ctx, __location__)
2019-03-07 00:40:12 +01:00
_PUBLIC_ int _talloc_free ( void * ptr , const char * location ) ;
2010-01-17 11:25:02 +01:00
# endif
/**
* @ brief Free a talloc chunk ' s children .
*
* The function walks along the list of all children of a talloc context and
* talloc_free ( ) s only the children , not the context itself .
*
2011-03-31 21:32:51 +02:00
* A NULL argument is handled as no - op .
*
* @ param [ in ] ptr The chunk that you want to free the children of
* ( NULL is allowed too )
2010-01-17 11:25:02 +01:00
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_free_children ( void * ptr ) ;
2010-01-17 11:25:02 +01:00
2010-02-08 10:02:49 -05:00
# ifdef DOXYGEN
2010-01-17 11:25:02 +01:00
/**
* @ brief Assign a destructor function to be called when a chunk is freed .
*
* The function talloc_set_destructor ( ) sets the " destructor " for the pointer
* " ptr " . A destructor is a function that is called when the memory used by a
* pointer is about to be released . The destructor receives the pointer as an
* argument , and should return 0 for success and - 1 for failure .
*
* The destructor can do anything it wants to , including freeing other pieces
* of memory . A common use for destructors is to clean up operating system
* resources ( such as open file descriptors ) contained in the structure the
* destructor is placed on .
*
* You can only place one destructor on a pointer . If you need more than one
* destructor then you can create a zero - length child of the pointer and place
* an additional destructor on that .
*
* To remove a destructor call talloc_set_destructor ( ) with NULL for the
* destructor .
*
* If your destructor attempts to talloc_free ( ) the pointer that it is the
* destructor for then talloc_free ( ) will return - 1 and the free will be
* ignored . This would be a pointless operation anyway , as the destructor is
* only called when the memory is just about to go away .
*
* @ param [ in ] ptr The talloc chunk to add a destructor to .
*
* @ param [ in ] destructor The destructor function to be called . NULL to remove
* it .
*
* Example :
* @ code
* static int destroy_fd ( int * fd ) {
* close ( * fd ) ;
* return 0 ;
* }
*
* int * open_file ( const char * filename ) {
* int * fd = talloc ( NULL , int ) ;
* * fd = open ( filename , O_RDONLY ) ;
* if ( * fd < 0 ) {
* talloc_free ( fd ) ;
* return NULL ;
* }
* // Whenever they free this, we close the file.
* talloc_set_destructor ( fd , destroy_fd ) ;
* return fd ;
* }
* @ endcode
*
* @ see talloc ( )
* @ see talloc_free ( )
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_set_destructor ( const void * ptr , int ( * destructor ) ( void * ) ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Change a talloc chunk ' s parent .
*
* The talloc_steal ( ) function changes the parent context of a talloc
* pointer . It is typically used when the context that the pointer is
* currently a child of is going to be freed and you wish to keep the
* memory for a longer time .
*
* To make the changed hierarchy less error - prone , you might consider to use
* talloc_move ( ) .
*
* If you try and call talloc_steal ( ) on a pointer that has more than one
* parent then the result is ambiguous . Talloc will choose to remove the
* parent that is currently indicated by talloc_parent ( ) and replace it with
* the chosen parent . You will also get a message like this via the talloc
* logging functions :
*
* @ code
* WARNING : talloc_steal with references at some_dir / source / foo . c : 123
* reference at some_dir / source / other . c : 325
* reference at some_dir / source / third . c : 121
* @ endcode
*
* To unambiguously change the parent of a pointer please see the function
* talloc_reparent ( ) . See the talloc_set_log_fn ( ) documentation for more
* information on talloc logging .
*
* @ param [ in ] new_ctx The new parent context .
*
* @ param [ in ] ptr The talloc chunk to move .
*
* @ return Returns the pointer that you pass it . It does not have
* any failure modes .
*
* @ note It is possible to produce loops in the parent / child relationship
* if you are not careful with talloc_steal ( ) . No guarantees are provided
* as to your sanity or the safety of your data if you do this .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_steal ( const void * new_ctx , const void * ptr ) ;
2010-01-17 11:25:02 +01:00
# else /* DOXYGEN */
2006-08-29 16:54:12 +00:00
/* try to make talloc_set_destructor() and talloc_steal() type safe,
if we have a recent gcc */
# if (__GNUC__ >= 3)
# define _TALLOC_TYPEOF(ptr) __typeof__(ptr)
# define talloc_set_destructor(ptr, function) \
do { \
int ( * _talloc_destructor_fn ) ( _TALLOC_TYPEOF ( ptr ) ) = ( function ) ; \
_talloc_set_destructor ( ( ptr ) , ( int ( * ) ( void * ) ) _talloc_destructor_fn ) ; \
} while ( 0 )
/* this extremely strange macro is to avoid some braindamaged warning
stupidity in gcc 4.1 . x */
2009-07-02 09:29:20 -04:00
# define talloc_steal(ctx, ptr) ({ _TALLOC_TYPEOF(ptr) __talloc_steal_ret = (_TALLOC_TYPEOF(ptr))_talloc_steal_loc((ctx),(ptr), __location__); __talloc_steal_ret; })
2010-01-17 11:25:02 +01:00
# else /* __GNUC__ >= 3 */
2006-08-29 16:54:12 +00:00
# define talloc_set_destructor(ptr, function) \
_talloc_set_destructor ( ( ptr ) , ( int ( * ) ( void * ) ) ( function ) )
# define _TALLOC_TYPEOF(ptr) void *
2009-07-02 09:29:20 -04:00
# define talloc_steal(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_steal_loc((ctx),(ptr), __location__)
2010-01-17 11:25:02 +01:00
# endif /* __GNUC__ >= 3 */
2019-03-07 00:40:12 +01:00
_PUBLIC_ void _talloc_set_destructor ( const void * ptr , int ( * _destructor ) ( void * ) ) ;
_PUBLIC_ void * _talloc_steal_loc ( const void * new_ctx , const void * ptr , const char * location ) ;
2010-01-17 11:25:02 +01:00
# endif /* DOXYGEN */
2006-08-29 16:54:12 +00:00
2010-01-17 11:25:02 +01:00
/**
* @ brief Assign a name to a talloc chunk .
*
* Each talloc pointer has a " name " . The name is used principally for
* debugging purposes , although it is also possible to set and get the name on
* a pointer in as a way of " marking " pointers in your code .
*
* The main use for names on pointer is for " talloc reports " . See
* talloc_report ( ) and talloc_report_full ( ) for details . Also see
* talloc_enable_leak_report ( ) and talloc_enable_leak_report_full ( ) .
*
* The talloc_set_name ( ) function allocates memory as a child of the
* pointer . It is logically equivalent to :
*
* @ code
* talloc_set_name_const ( ptr , talloc_asprintf ( ptr , fmt , . . . ) ) ;
* @ endcode
*
* @ param [ in ] ptr The talloc chunk to assign a name to .
*
* @ param [ in ] fmt Format string for the name .
*
* @ param [ in ] . . . Add printf - style additional arguments .
*
* @ return The assigned name , NULL on error .
*
* @ note Multiple calls to talloc_set_name ( ) will allocate more memory without
* releasing the name . All of the memory is released when the ptr is freed
* using talloc_free ( ) .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ const char * talloc_set_name ( const void * ptr , const char * fmt , . . . ) PRINTF_ATTRIBUTE ( 2 , 3 ) ;
2010-01-17 11:25:02 +01:00
# ifdef DOXYGEN
/**
* @ brief Change a talloc chunk ' s parent .
*
* This function has the same effect as talloc_steal ( ) , and additionally sets
* the source pointer to NULL . You would use it like this :
*
* @ code
* struct foo * X = talloc ( tmp_ctx , struct foo ) ;
* struct foo * Y ;
* Y = talloc_move ( new_ctx , & X ) ;
* @ endcode
*
* @ param [ in ] new_ctx The new parent context .
*
2017-03-09 14:40:54 +02:00
* @ param [ in ] pptr Pointer to a pointer to the talloc chunk to move .
*
* @ return The pointer to the talloc chunk that moved .
* It does not have any failure modes .
2010-01-17 11:25:02 +01:00
*
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_move ( const void * new_ctx , void * * pptr ) ;
2010-01-17 11:25:02 +01:00
# else
2011-03-24 09:41:19 +01:00
# define talloc_move(ctx, pptr) (_TALLOC_TYPEOF(*(pptr)))_talloc_move((ctx),(void *)(pptr))
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * _talloc_move ( const void * new_ctx , const void * pptr ) ;
2010-01-17 11:25:02 +01:00
# endif
2006-09-22 04:16:58 +00:00
2010-01-17 11:25:02 +01:00
/**
* @ brief Assign a name to a talloc chunk .
*
* The function is just like talloc_set_name ( ) , but it takes a string constant ,
* and is much faster . It is extensively used by the " auto naming " macros , such
* as talloc_p ( ) .
*
* This function does not allocate any memory . It just copies the supplied
* pointer into the internal representation of the talloc ptr . This means you
* must not pass a name pointer to memory that will disappear before the ptr
* is freed with talloc_free ( ) .
*
* @ param [ in ] ptr The talloc chunk to assign a name to .
*
* @ param [ in ] name Format string for the name .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_set_name_const ( const void * ptr , const char * name ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Create a named talloc chunk .
*
* The talloc_named ( ) function creates a named talloc pointer . It is
* equivalent to :
*
* @ code
* ptr = talloc_size ( context , size ) ;
* talloc_set_name ( ptr , fmt , . . . . ) ;
* @ endcode
*
* @ param [ in ] context The talloc context to hang the result off .
*
* @ param [ in ] size Number of char ' s that you want to allocate .
*
* @ param [ in ] fmt Format string for the name .
*
* @ param [ in ] . . . Additional printf - style arguments .
*
* @ return The allocated memory chunk , NULL on error .
*
* @ see talloc_set_name ( )
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_named ( const void * context , size_t size ,
2010-01-17 11:25:02 +01:00
const char * fmt , . . . ) PRINTF_ATTRIBUTE ( 3 , 4 ) ;
/**
* @ brief Basic routine to allocate a chunk of memory .
*
* This is equivalent to :
*
* @ code
* ptr = talloc_size ( context , size ) ;
* talloc_set_name_const ( ptr , name ) ;
* @ endcode
*
* @ param [ in ] context The parent context .
*
* @ param [ in ] size The number of char ' s that we want to allocate .
*
* @ param [ in ] name The name the talloc block has .
*
* @ return The allocated memory chunk , NULL on error .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_named_const ( const void * context , size_t size , const char * name ) ;
2010-01-17 11:25:02 +01:00
# ifdef DOXYGEN
/**
* @ brief Untyped allocation .
*
* The function should be used when you don ' t have a convenient type to pass to
* talloc ( ) . Unlike talloc ( ) , it is not type safe ( as it returns a void * ) , so
* you are on your own for type checking .
*
* Best to use talloc ( ) or talloc_array ( ) instead .
*
* @ param [ in ] ctx The talloc context to hang the result off .
*
* @ param [ in ] size Number of char ' s that you want to allocate .
*
* @ return The allocated memory chunk , NULL on error .
*
* Example :
* @ code
* void * mem = talloc_size ( NULL , 100 ) ;
* @ endcode
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_size ( const void * ctx , size_t size ) ;
2010-01-17 11:25:02 +01:00
# else
2005-05-03 07:33:49 +00:00
# define talloc_size(ctx, size) talloc_named_const(ctx, size, __location__)
2010-01-17 11:25:02 +01:00
# endif
# ifdef DOXYGEN
/**
* @ brief Allocate into a typed pointer .
*
* The talloc_ptrtype ( ) macro should be used when you have a pointer and want
* to allocate memory to point at with this pointer . When compiling with
* gcc > = 3 it is typesafe . Note this is a wrapper of talloc_size ( ) and
* talloc_get_name ( ) will return the current location in the source file and
* not the type .
*
* @ param [ in ] ctx The talloc context to hang the result off .
*
* @ param [ in ] type The pointer you want to assign the result to .
*
* @ return The properly casted allocated memory chunk , NULL on
* error .
*
* Example :
* @ code
* unsigned int * a = talloc_ptrtype ( NULL , a ) ;
* @ endcode
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_ptrtype ( const void * ctx , # type ) ;
2010-01-17 11:25:02 +01:00
# else
2006-08-29 16:54:12 +00:00
# define talloc_ptrtype(ctx, ptr) (_TALLOC_TYPEOF(ptr))talloc_size(ctx, sizeof(*(ptr)))
2010-01-17 11:25:02 +01:00
# endif
2005-05-03 07:33:49 +00:00
2010-01-17 11:25:02 +01:00
# ifdef DOXYGEN
/**
* @ brief Allocate a new 0 - sized talloc chunk .
*
* This is a utility macro that creates a new memory context hanging off an
2010-05-01 15:18:45 +02:00
* existing context , automatically naming it " talloc_new: __location__ " where
2010-01-17 11:25:02 +01:00
* __location__ is the source line it is called from . It is particularly
* useful for creating a new temporary working context .
*
* @ param [ in ] ctx The talloc parent context .
*
* @ return A new talloc chunk , NULL on error .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_new ( const void * ctx ) ;
2010-01-17 11:25:02 +01:00
# else
2005-05-03 07:33:49 +00:00
# define talloc_new(ctx) talloc_named_const(ctx, 0, "talloc_new: " __location__)
2010-01-17 11:25:02 +01:00
# endif
# ifdef DOXYGEN
/**
* @ brief Allocate a 0 - initizialized structure .
*
* The macro is equivalent to :
*
* @ code
* ptr = talloc ( ctx , type ) ;
* if ( ptr ) memset ( ptr , 0 , sizeof ( type ) ) ;
* @ endcode
*
* @ param [ in ] ctx The talloc context to hang the result off .
*
* @ param [ in ] type The type that we want to allocate .
*
* @ return Pointer to a piece of memory , properly cast to ' type * ' ,
* NULL on error .
*
* Example :
* @ code
* unsigned int * a , * b ;
* a = talloc_zero ( NULL , unsigned int ) ;
* b = talloc_zero ( a , unsigned int ) ;
* @ endcode
*
* @ see talloc ( )
* @ see talloc_zero_size ( )
* @ see talloc_zero_array ( )
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_zero ( const void * ctx , # type ) ;
2001-12-19 06:22:23 +00:00
2010-01-17 11:25:02 +01:00
/**
* @ brief Allocate untyped , 0 - initialized memory .
*
* @ param [ in ] ctx The talloc context to hang the result off .
*
* @ param [ in ] size Number of char ' s that you want to allocate .
*
* @ return The allocated memory chunk .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_zero_size ( const void * ctx , size_t size ) ;
2010-01-17 11:25:02 +01:00
# else
2005-05-03 07:33:49 +00:00
# define talloc_zero(ctx, type) (type *)_talloc_zero(ctx, sizeof(type), #type)
# define talloc_zero_size(ctx, size) _talloc_zero(ctx, size, __location__)
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * _talloc_zero ( const void * ctx , size_t size , const char * name ) ;
2010-01-17 11:25:02 +01:00
# endif
2003-10-06 01:38:46 +00:00
2010-01-17 11:25:02 +01:00
/**
* @ brief Return the name of a talloc chunk .
*
* @ param [ in ] ptr The talloc chunk .
*
* @ return The current name for the given talloc pointer .
*
* @ see talloc_set_name ( )
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ const char * talloc_get_name ( const void * ptr ) ;
2003-10-06 01:38:46 +00:00
2010-01-17 11:25:02 +01:00
/**
* @ brief Verify that a talloc chunk carries a specified name .
*
* This function checks if a pointer has the specified name . If it does
* then the pointer is returned .
*
* @ param [ in ] ptr The talloc chunk to check .
*
* @ param [ in ] name The name to check against .
*
* @ return The pointer if the name matches , NULL if it doesn ' t .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_check_name ( const void * ptr , const char * name ) ;
2003-10-06 01:38:46 +00:00
2010-01-17 11:25:02 +01:00
/**
* @ brief Get the parent chunk of a pointer .
*
* @ param [ in ] ptr The talloc pointer to inspect .
*
* @ return The talloc parent of ptr , NULL on error .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_parent ( const void * ptr ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Get a talloc chunk ' s parent name .
*
* @ param [ in ] ptr The talloc pointer to inspect .
*
* @ return The name of ptr ' s parent chunk .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ const char * talloc_parent_name ( const void * ptr ) ;
2010-01-17 11:25:02 +01:00
2023-03-28 10:17:29 +02:00
/**
* @ brief Get the size of a talloc chunk .
*
* This function lets you know the amount of memory allocated so far by
* this context . It does NOT account for subcontext memory .
* This can be used to calculate the size of an array .
*
* @ param [ in ] ctx The talloc chunk .
*
* @ return The size of the talloc chunk .
*/
_PUBLIC_ size_t talloc_get_size ( const void * ctx ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Get the total size of a talloc chunk including its children .
*
* The function returns the total size in bytes used by this pointer and all
* child pointers . Mostly useful for debugging .
*
* Passing NULL is allowed , but it will only give a meaningful result if
* talloc_enable_leak_report ( ) or talloc_enable_leak_report_full ( ) has
* been called .
*
* @ param [ in ] ptr The talloc chunk .
*
* @ return The total size .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ size_t talloc_total_size ( const void * ptr ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Get the number of talloc chunks hanging off a chunk .
*
* The talloc_total_blocks ( ) function returns the total memory block
* count used by this pointer and all child pointers . Mostly useful for
* debugging .
*
* Passing NULL is allowed , but it will only give a meaningful result if
* talloc_enable_leak_report ( ) or talloc_enable_leak_report_full ( ) has
* been called .
*
* @ param [ in ] ptr The talloc chunk .
*
* @ return The total size .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ size_t talloc_total_blocks ( const void * ptr ) ;
2010-01-17 11:25:02 +01:00
# ifdef DOXYGEN
/**
* @ brief Duplicate a memory area into a talloc chunk .
*
* The function is equivalent to :
*
* @ code
* ptr = talloc_size ( ctx , size ) ;
* if ( ptr ) memcpy ( ptr , p , size ) ;
* @ endcode
*
* @ param [ in ] t The talloc context to hang the result off .
*
* @ param [ in ] p The memory chunk you want to duplicate .
*
2023-07-13 11:42:16 +12:00
* @ param [ in ] size Number of chars that you want to copy .
2010-01-17 11:25:02 +01:00
*
* @ return The allocated memory chunk .
*
* @ see talloc_size ( )
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_memdup ( const void * t , const void * p , size_t size ) ;
2010-01-17 11:25:02 +01:00
# else
2005-05-03 07:33:49 +00:00
# define talloc_memdup(t, p, size) _talloc_memdup(t, p, size, __location__)
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * _talloc_memdup ( const void * t , const void * p , size_t size , const char * name ) ;
2010-01-17 11:25:02 +01:00
# endif
# ifdef DOXYGEN
/**
* @ brief Assign a type to a talloc chunk .
*
2011-03-31 21:32:51 +02:00
* This macro allows you to force the name of a pointer to be of a particular
* type . This can be used in conjunction with talloc_get_type ( ) to do type
* checking on void * pointers .
2010-01-17 11:25:02 +01:00
*
* It is equivalent to this :
*
* @ code
* talloc_set_name_const ( ptr , # type )
* @ endcode
*
* @ param [ in ] ptr The talloc chunk to assign the type to .
*
* @ param [ in ] type The type to assign .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_set_type ( const char * ptr , # type ) ;
2003-10-06 01:38:46 +00:00
2010-01-17 11:25:02 +01:00
/**
* @ brief Get a typed pointer out of a talloc pointer .
*
* This macro allows you to do type checking on talloc pointers . It is
* particularly useful for void * private pointers . It is equivalent to
* this :
*
* @ code
* ( type * ) talloc_check_name ( ptr , # type )
* @ endcode
*
* @ param [ in ] ptr The talloc pointer to check .
*
* @ param [ in ] type The type to check against .
*
* @ return The properly casted pointer given by ptr , NULL on error .
*/
2010-03-03 22:07:12 +02:00
type * talloc_get_type ( const void * ptr , # type ) ;
2010-01-17 11:25:02 +01:00
# else
2005-05-03 07:33:49 +00:00
# define talloc_set_type(ptr, type) talloc_set_name_const(ptr, #type)
# define talloc_get_type(ptr, type) (type *)talloc_check_name(ptr, #type)
2010-01-17 11:25:02 +01:00
# endif
2000-01-05 06:36:36 +00:00
2010-01-17 11:25:02 +01:00
# ifdef DOXYGEN
/**
* @ brief Safely turn a void pointer into a typed pointer .
*
* This macro is used together with talloc ( mem_ctx , struct foo ) . If you had to
2016-01-11 19:49:14 +11:00
* assign the talloc chunk pointer to some void pointer variable ,
2010-01-17 11:25:02 +01:00
* talloc_get_type_abort ( ) is the recommended way to get the convert the void
* pointer back to a typed pointer .
*
* @ param [ in ] ptr The void pointer to convert .
*
* @ param [ in ] type The type that this chunk contains
*
2010-02-08 10:58:48 +11:00
* @ return The same value as ptr , type - checked and properly cast .
2010-01-17 11:25:02 +01:00
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_get_type_abort ( const void * ptr , # type ) ;
2010-01-17 11:25:02 +01:00
# else
2013-12-05 08:36:13 +01:00
# ifdef TALLOC_GET_TYPE_ABORT_NOOP
# define talloc_get_type_abort(ptr, type) (type *)(ptr)
# else
2010-01-17 11:25:02 +01:00
# define talloc_get_type_abort(ptr, type) (type *)_talloc_get_type_abort(ptr, #type, __location__)
2013-12-05 08:36:13 +01:00
# endif
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * _talloc_get_type_abort ( const void * ptr , const char * name , const char * location ) ;
2010-01-17 11:25:02 +01:00
# endif
2009-07-01 14:53:01 +10:00
2010-01-17 11:25:02 +01:00
/**
* @ brief Find a parent context by name .
*
* Find a parent memory context of the current context that has the given
* name . This can be very useful in complex programs where it may be
* difficult to pass all information down to the level you need , but you
* know the structure you want is a parent of another context .
*
* @ param [ in ] ctx The talloc chunk to start from .
*
* @ param [ in ] name The name of the parent we look for .
*
* @ return The memory context we are looking for , NULL if not
* found .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_find_parent_byname ( const void * ctx , const char * name ) ;
2005-12-01 00:43:34 +00:00
2010-01-17 11:25:02 +01:00
# ifdef DOXYGEN
/**
* @ brief Find a parent context by type .
*
* Find a parent memory context of the current context that has the given
* name . This can be very useful in complex programs where it may be
* difficult to pass all information down to the level you need , but you
* know the structure you want is a parent of another context .
*
* Like talloc_find_parent_byname ( ) but takes a type , making it typesafe .
*
* @ param [ in ] ptr The talloc chunk to start from .
*
* @ param [ in ] type The type of the parent to look for .
*
* @ return The memory context we are looking for , NULL if not
* found .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_find_parent_bytype ( const void * ptr , # type ) ;
2010-01-17 11:25:02 +01:00
# else
# define talloc_find_parent_bytype(ptr, type) (type *)talloc_find_parent_byname(ptr, #type)
2005-05-03 07:33:49 +00:00
# endif
2001-12-19 05:02:42 +00:00
2010-01-17 11:25:02 +01:00
/**
* @ brief Allocate a talloc pool .
*
* A talloc pool is a pure optimization for specific situations . In the
* release process for Samba 3.2 we found out that we had become considerably
* slower than Samba 3.0 was . Profiling showed that malloc ( 3 ) was a large CPU
* consumer in benchmarks . For Samba 3.2 we have internally converted many
* static buffers to dynamically allocated ones , so malloc ( 3 ) being beaten
* more was no surprise . But it made us slower .
*
* talloc_pool ( ) is an optimization to call malloc ( 3 ) a lot less for the use
* pattern Samba has : The SMB protocol is mainly a request / response protocol
* where we have to allocate a certain amount of memory per request and free
* that after the SMB reply is sent to the client .
*
* talloc_pool ( ) creates a talloc chunk that you can use as a talloc parent
* exactly as you would use any other : : TALLOC_CTX . The difference is that
* when you talloc a child of this pool , no malloc ( 3 ) is done . Instead , talloc
* just increments a pointer inside the talloc_pool . This also works
* recursively . If you use the child of the talloc pool as a parent for
* grand - children , their memory is also taken from the talloc pool .
*
2012-04-16 15:23:55 +02:00
* If there is not enough memory in the pool to allocate the new child ,
* it will create a new talloc chunk as if the parent was a normal talloc
* context .
*
2010-01-17 11:25:02 +01:00
* If you talloc_free ( ) children of a talloc pool , the memory is not given
* back to the system . Instead , free ( 3 ) is only called if the talloc_pool ( )
* itself is released with talloc_free ( ) .
*
* The downside of a talloc pool is that if you talloc_move ( ) a child of a
* talloc pool to a talloc parent outside the pool , the whole pool memory is
* not free ( 3 ) ' ed until that moved chunk is also talloc_free ( ) ed .
*
2013-09-06 14:52:28 -07:00
* @ param [ in ] context The talloc context to hang the result off .
2010-01-17 11:25:02 +01:00
*
* @ param [ in ] size Size of the talloc pool .
*
* @ return The allocated talloc pool , NULL on error .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_pool ( const void * context , size_t size ) ;
2010-01-17 11:25:02 +01:00
2013-09-06 15:15:32 -07:00
# ifdef DOXYGEN
/**
* @ brief Allocate a talloc object as / with an additional pool .
*
* This is like talloc_pool ( ) , but ' s it ' s more flexible
* and allows an object to be a pool for its children .
*
* @ param [ in ] ctx The talloc context to hang the result off .
*
* @ param [ in ] type The type that we want to allocate .
*
* @ param [ in ] num_subobjects The expected number of subobjects , which will
* be allocated within the pool . This allocates
* space for talloc_chunk headers .
*
* @ param [ in ] total_subobjects_size The size that all subobjects can use in total .
*
*
* @ return The allocated talloc object , NULL on error .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_pooled_object ( const void * ctx , # type ,
2013-09-06 15:15:32 -07:00
unsigned num_subobjects ,
size_t total_subobjects_size ) ;
# else
# define talloc_pooled_object(_ctx, _type, \
_num_subobjects , \
_total_subobjects_size ) \
( _type * ) _talloc_pooled_object ( ( _ctx ) , sizeof ( _type ) , # _type , \
( _num_subobjects ) , \
( _total_subobjects_size ) )
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * _talloc_pooled_object ( const void * ctx ,
2013-09-06 15:15:32 -07:00
size_t type_size ,
const char * type_name ,
unsigned num_subobjects ,
size_t total_subobjects_size ) ;
# endif
2010-01-17 11:25:02 +01:00
/**
* @ brief Free a talloc chunk and NULL out the pointer .
*
* TALLOC_FREE ( ) frees a pointer and sets it to NULL . Use this if you want
* immediate feedback ( i . e . crash ) if you use a pointer after having free ' ed
* it .
*
* @ param [ in ] ctx The chunk to be freed .
*/
2013-12-04 15:35:37 +01:00
# define TALLOC_FREE(ctx) do { if (ctx != NULL) { talloc_free(ctx); ctx=NULL; } } while(0)
2009-03-16 10:13:58 +01:00
2010-01-17 11:25:02 +01:00
/* @} ******************************************************************/
/**
* \ defgroup talloc_ref The talloc reference function .
* @ ingroup talloc
*
* This module contains the definitions around talloc references
*
* @ {
*/
/**
* @ brief Increase the reference count of a talloc chunk .
*
* The talloc_increase_ref_count ( ptr ) function is exactly equivalent to :
*
* @ code
* talloc_reference ( NULL , ptr ) ;
* @ endcode
*
* You can use either syntax , depending on which you think is clearer in
* your code .
*
* @ param [ in ] ptr The pointer to increase the reference count .
*
* @ return 0 on success , - 1 on error .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ int talloc_increase_ref_count ( const void * ptr ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Get the number of references to a talloc chunk .
*
* @ param [ in ] ptr The pointer to retrieve the reference count from .
*
* @ return The number of references .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ size_t talloc_reference_count ( const void * ptr ) ;
2010-01-17 11:25:02 +01:00
# ifdef DOXYGEN
/**
* @ brief Create an additional talloc parent to a pointer .
*
* The talloc_reference ( ) function makes " context " an additional parent of
* ptr . Each additional reference consumes around 48 bytes of memory on intel
* x86 platforms .
*
* If ptr is NULL , then the function is a no - op , and simply returns NULL .
*
* After creating a reference you can free it in one of the following ways :
*
* - you can talloc_free ( ) any parent of the original pointer . That
* will reduce the number of parents of this pointer by 1 , and will
* cause this pointer to be freed if it runs out of parents .
*
2011-03-31 21:32:51 +02:00
* - you can talloc_free ( ) the pointer itself if it has at maximum one
* parent . This behaviour has been changed since the release of version
2019-03-25 15:02:45 +01:00
* 2.0 . Further information in the description of " talloc_free " .
2010-01-17 11:25:02 +01:00
*
* For more control on which parent to remove , see talloc_unlink ( )
* @ param [ in ] ctx The additional parent .
*
* @ param [ in ] ptr The pointer you want to create an additional parent for .
*
* @ return The original pointer ' ptr ' , NULL if talloc ran out of
* memory in creating the reference .
*
2013-10-14 13:17:12 +02:00
* @ warning You should try to avoid using this interface . It turns a beautiful
* talloc - tree into a graph . It is often really hard to debug if you
* screw something up by accident .
*
2010-01-17 11:25:02 +01:00
* Example :
* @ code
* unsigned int * a , * b , * c ;
* a = talloc ( NULL , unsigned int ) ;
* b = talloc ( NULL , unsigned int ) ;
* c = talloc ( a , unsigned int ) ;
* // b also serves as a parent of c.
* talloc_reference ( b , c ) ;
* @ endcode
*
* @ see talloc_unlink ( )
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_reference ( const void * ctx , const void * ptr ) ;
2010-01-17 11:25:02 +01:00
# else
# define talloc_reference(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_reference_loc((ctx),(ptr), __location__)
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * _talloc_reference_loc ( const void * context , const void * ptr , const char * location ) ;
2010-01-17 11:25:02 +01:00
# endif
/**
* @ brief Remove a specific parent from a talloc chunk .
*
* The function removes a specific parent from ptr . The context passed must
* either be a context used in talloc_reference ( ) with this pointer , or must be
* a direct parent of ptr .
*
2011-03-31 21:32:51 +02:00
* You can just use talloc_free ( ) instead of talloc_unlink ( ) if there
* is at maximum one parent . This behaviour has been changed since the
2019-03-25 15:02:45 +01:00
* release of version 2.0 . Further information in the description of
2011-03-31 21:32:51 +02:00
* " talloc_free " .
2010-01-17 11:25:02 +01:00
*
* @ param [ in ] context The talloc parent to remove .
*
* @ param [ in ] ptr The talloc ptr you want to remove the parent from .
*
* @ return 0 on success , - 1 on error .
*
* @ note If the parent has already been removed using talloc_free ( ) then
* this function will fail and will return - 1. Likewise , if ptr is NULL ,
* then the function will make no modifications and return - 1.
*
2013-10-14 13:17:12 +02:00
* @ warning You should try to avoid using this interface . It turns a beautiful
* talloc - tree into a graph . It is often really hard to debug if you
* screw something up by accident .
*
2010-01-17 11:25:02 +01:00
* Example :
* @ code
* unsigned int * a , * b , * c ;
* a = talloc ( NULL , unsigned int ) ;
* b = talloc ( NULL , unsigned int ) ;
* c = talloc ( a , unsigned int ) ;
* // b also serves as a parent of c.
* talloc_reference ( b , c ) ;
* talloc_unlink ( b , c ) ;
* @ endcode
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ int talloc_unlink ( const void * context , void * ptr ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Provide a talloc context that is freed at program exit .
*
* This is a handy utility function that returns a talloc context
* which will be automatically freed on program exit . This can be used
* to reduce the noise in memory leak reports .
*
2010-09-24 19:20:06 +02:00
* Never use this in code that might be used in objects loaded with
* dlopen and unloaded with dlclose . talloc_autofree_context ( )
* internally uses atexit ( 3 ) . Some platforms like modern Linux handles
* this fine , but for example FreeBSD does not deal well with dlopen ( )
* and atexit ( ) used simultaneously : dlclose ( ) does not clean up the
* list of atexit - handlers , so when the program exits the code that
* was registered from within talloc_autofree_context ( ) is gone , the
* program crashes at exit .
*
2010-01-17 11:25:02 +01:00
* @ return A talloc context , NULL on error .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_autofree_context ( void ) _DEPRECATED_ ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Show the parentage of a context .
*
* @ param [ in ] context The talloc context to look at .
*
* @ param [ in ] file The output to use , a file , stdout or stderr .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_show_parents ( const void * context , FILE * file ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Check if a context is parent of a talloc chunk .
*
* This checks if context is referenced in the talloc hierarchy above ptr .
*
* @ param [ in ] context The assumed talloc context .
*
* @ param [ in ] ptr The talloc chunk to check .
*
* @ return Return 1 if this is the case , 0 if not .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ int talloc_is_parent ( const void * context , const void * ptr ) ;
2002-01-03 05:25:30 +00:00
2010-01-17 11:25:02 +01:00
/**
* @ brief Change the parent context of a talloc pointer .
*
* The function changes the parent context of a talloc pointer . It is typically
* used when the context that the pointer is currently a child of is going to be
* freed and you wish to keep the memory for a longer time .
*
* The difference between talloc_reparent ( ) and talloc_steal ( ) is that
* talloc_reparent ( ) can specify which parent you wish to change . This is
* useful when a pointer has multiple parents via references .
*
* @ param [ in ] old_parent
* @ param [ in ] new_parent
* @ param [ in ] ptr
*
* @ return Return the pointer you passed . It does not have any
* failure modes .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_reparent ( const void * old_parent , const void * new_parent , const void * ptr ) ;
2010-01-17 11:25:02 +01:00
/* @} ******************************************************************/
/**
* @ defgroup talloc_array The talloc array functions
* @ ingroup talloc
*
* Talloc contains some handy helpers for handling Arrays conveniently
*
* @ {
*/
# ifdef DOXYGEN
/**
* @ brief Allocate an array .
*
* The macro is equivalent to :
*
* @ code
* ( type * ) talloc_size ( ctx , sizeof ( type ) * count ) ;
* @ endcode
*
* except that it provides integer overflow protection for the multiply ,
* returning NULL if the multiply overflows .
*
* @ param [ in ] ctx The talloc context to hang the result off .
*
* @ param [ in ] type The type that we want to allocate .
*
* @ param [ in ] count The number of ' type ' elements you want to allocate .
*
* @ return The allocated result , properly cast to ' type * ' , NULL on
* error .
*
* Example :
* @ code
* unsigned int * a , * b ;
* a = talloc_zero ( NULL , unsigned int ) ;
* b = talloc_array ( a , unsigned int , 100 ) ;
* @ endcode
*
* @ see talloc ( )
2011-01-04 08:42:20 +11:00
* @ see talloc_zero_array ( )
2010-01-17 11:25:02 +01:00
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_array ( const void * ctx , # type , unsigned count ) ;
2010-01-17 11:25:02 +01:00
# else
# define talloc_array(ctx, type, count) (type *)_talloc_array(ctx, sizeof(type), count, #type)
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * _talloc_array ( const void * ctx , size_t el_size , unsigned count , const char * name ) ;
2010-01-17 11:25:02 +01:00
# endif
# ifdef DOXYGEN
/**
* @ brief Allocate an array .
*
* @ param [ in ] ctx The talloc context to hang the result off .
*
* @ param [ in ] size The size of an array element .
*
* @ param [ in ] count The number of elements you want to allocate .
*
* @ return The allocated result , NULL on error .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_array_size ( const void * ctx , size_t size , unsigned count ) ;
2010-01-17 11:25:02 +01:00
# else
# define talloc_array_size(ctx, size, count) _talloc_array(ctx, size, count, __location__)
# endif
# ifdef DOXYGEN
/**
* @ brief Allocate an array into a typed pointer .
*
* The macro should be used when you have a pointer to an array and want to
* allocate memory of an array to point at with this pointer . When compiling
* with gcc > = 3 it is typesafe . Note this is a wrapper of talloc_array_size ( )
* and talloc_get_name ( ) will return the current location in the source file
* and not the type .
*
* @ param [ in ] ctx The talloc context to hang the result off .
*
* @ param [ in ] ptr The pointer you want to assign the result to .
*
* @ param [ in ] count The number of elements you want to allocate .
*
* @ return The allocated memory chunk , properly casted . NULL on
* error .
*/
void * talloc_array_ptrtype ( const void * ctx , const void * ptr , unsigned count ) ;
# else
# define talloc_array_ptrtype(ctx, ptr, count) (_TALLOC_TYPEOF(ptr))talloc_array_size(ctx, sizeof(*(ptr)), count)
# endif
# ifdef DOXYGEN
/**
* @ brief Get the number of elements in a talloc ' ed array .
*
* A talloc chunk carries its own size , so for talloc ' ed arrays it is not
* necessary to store the number of elements explicitly .
*
* @ param [ in ] ctx The allocated array .
*
* @ return The number of elements in ctx .
*/
size_t talloc_array_length ( const void * ctx ) ;
# else
# define talloc_array_length(ctx) (talloc_get_size(ctx) / sizeof(*ctx))
# endif
# ifdef DOXYGEN
/**
* @ brief Allocate a zero - initialized array
*
* @ param [ in ] ctx The talloc context to hang the result off .
*
* @ param [ in ] type The type that we want to allocate .
*
* @ param [ in ] count The number of " type " elements you want to allocate .
*
* @ return The allocated result casted to " type * " , NULL on error .
*
* The talloc_zero_array ( ) macro is equivalent to :
*
* @ code
* ptr = talloc_array ( ctx , type , count ) ;
2018-01-18 16:08:15 +11:00
* if ( ptr ) memset ( ptr , 0 , sizeof ( type ) * count ) ;
2010-01-17 11:25:02 +01:00
* @ endcode
*/
void * talloc_zero_array ( const void * ctx , # type , unsigned count ) ;
# else
# define talloc_zero_array(ctx, type, count) (type *)_talloc_zero_array(ctx, sizeof(type), count, #type)
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * _talloc_zero_array ( const void * ctx ,
2010-01-17 11:25:02 +01:00
size_t el_size ,
unsigned count ,
const char * name ) ;
# endif
# ifdef DOXYGEN
/**
* @ brief Change the size of a talloc array .
*
* The macro changes the size of a talloc pointer . The ' count ' argument is the
* number of elements of type ' type ' that you want the resulting pointer to
* hold .
*
* talloc_realloc ( ) has the following equivalences :
*
* @ code
* talloc_realloc ( ctx , NULL , type , 1 ) = = > talloc ( ctx , type ) ;
* talloc_realloc ( ctx , NULL , type , N ) = = > talloc_array ( ctx , type , N ) ;
* talloc_realloc ( ctx , ptr , type , 0 ) = = > talloc_free ( ptr ) ;
* @ endcode
*
* The " context " argument is only used if " ptr " is NULL , otherwise it is
* ignored .
*
* @ param [ in ] ctx The parent context used if ptr is NULL .
*
* @ param [ in ] ptr The chunk to be resized .
*
* @ param [ in ] type The type of the array element inside ptr .
*
* @ param [ in ] count The intended number of array elements .
*
* @ return The new array , NULL on error . The call will fail either
* due to a lack of memory , or because the pointer has more
* than one parent ( see talloc_reference ( ) ) .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_realloc ( const void * ctx , void * ptr , # type , size_t count ) ;
2010-01-17 11:25:02 +01:00
# else
# define talloc_realloc(ctx, p, type, count) (type *)_talloc_realloc_array(ctx, p, sizeof(type), count, #type)
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * _talloc_realloc_array ( const void * ctx , void * ptr , size_t el_size , unsigned count , const char * name ) ;
2010-01-17 11:25:02 +01:00
# endif
2010-02-08 10:02:49 -05:00
# ifdef DOXYGEN
2010-01-17 11:25:02 +01:00
/**
* @ brief Untyped realloc to change the size of a talloc array .
*
* The macro is useful when the type is not known so the typesafe
* talloc_realloc ( ) cannot be used .
*
* @ param [ in ] ctx The parent context used if ' ptr ' is NULL .
*
* @ param [ in ] ptr The chunk to be resized .
*
* @ param [ in ] size The new chunk size .
*
* @ return The new array , NULL on error .
*/
void * talloc_realloc_size ( const void * ctx , void * ptr , size_t size ) ;
# else
# define talloc_realloc_size(ctx, ptr, size) _talloc_realloc(ctx, ptr, size, __location__)
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * _talloc_realloc ( const void * context , void * ptr , size_t size , const char * name ) ;
2010-01-17 11:25:02 +01:00
# endif
/**
* @ brief Provide a function version of talloc_realloc_size .
*
* This is a non - macro version of talloc_realloc ( ) , which is useful as
* libraries sometimes want a ralloc function pointer . A realloc ( )
* implementation encapsulates the functionality of malloc ( ) , free ( ) and
* realloc ( ) in one call , which is why it is useful to be able to pass around
* a single function pointer .
*
* @ param [ in ] context The parent context used if ptr is NULL .
*
* @ param [ in ] ptr The chunk to be resized .
*
* @ param [ in ] size The new chunk size .
*
* @ return The new chunk , NULL on error .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void * talloc_realloc_fn ( const void * context , void * ptr , size_t size ) ;
2010-01-17 11:25:02 +01:00
/* @} ******************************************************************/
/**
* @ defgroup talloc_string The talloc string functions .
* @ ingroup talloc
*
* talloc string allocation and manipulation functions .
* @ {
*/
/**
* @ brief Duplicate a string into a talloc chunk .
*
* This function is equivalent to :
*
* @ code
* ptr = talloc_size ( ctx , strlen ( p ) + 1 ) ;
* if ( ptr ) memcpy ( ptr , p , strlen ( p ) + 1 ) ;
* @ endcode
*
* This functions sets the name of the new pointer to the passed
* string . This is equivalent to :
*
* @ code
* talloc_set_name_const ( ptr , ptr )
* @ endcode
*
* @ param [ in ] t The talloc context to hang the result off .
*
* @ param [ in ] p The string you want to duplicate .
*
* @ return The duplicated string , NULL on error .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ char * talloc_strdup ( const void * t , const char * p ) ;
2010-05-06 17:50:26 +02:00
/**
2012-04-16 12:44:08 +02:00
* @ brief Append a string to given string .
*
* The destination string is reallocated to take
2012-04-18 10:22:39 +02:00
* < code > strlen ( s ) + strlen ( a ) + 1 < / code > characters .
2012-04-16 12:44:08 +02:00
*
* This functions sets the name of the new pointer to the new
* string . This is equivalent to :
*
* @ code
* talloc_set_name_const ( ptr , ptr )
* @ endcode
2010-05-06 17:50:26 +02:00
*
2012-04-20 14:29:59 +02:00
* If < code > s = = NULL < / code > then new context is created .
*
2010-05-06 17:50:26 +02:00
* @ param [ in ] s The destination to append to .
*
* @ param [ in ] a The string you want to append .
*
2012-04-20 14:32:01 +02:00
* @ return The concatenated strings , NULL on error .
2010-05-06 17:50:26 +02:00
*
* @ see talloc_strdup ( )
2012-04-16 12:44:08 +02:00
* @ see talloc_strdup_append_buffer ( )
2010-05-06 17:50:26 +02:00
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ char * talloc_strdup_append ( char * s , const char * a ) ;
2010-05-06 17:50:26 +02:00
/**
2012-04-16 12:59:22 +02:00
* @ brief Append a string to a given buffer .
*
* This is a more efficient version of talloc_strdup_append ( ) . It determines the
* length of the destination string by the size of the talloc context .
*
* Use this very carefully as it produces a different result than
* talloc_strdup_append ( ) when a zero character is in the middle of the
* destination string .
*
* @ code
* char * str_a = talloc_strdup ( NULL , " hello world " ) ;
* char * str_b = talloc_strdup ( NULL , " hello world " ) ;
* str_a [ 5 ] = str_b [ 5 ] = ' \0 '
*
* char * app = talloc_strdup_append ( str_a , " , hello " ) ;
* char * buf = talloc_strdup_append_buffer ( str_b , " , hello " ) ;
*
* printf ( " %s \n " , app ) ; // hello, hello (app = "hello, hello")
* printf ( " %s \n " , buf ) ; // hello (buf = "hello\0world, hello")
* @ endcode
2010-05-06 17:50:26 +02:00
*
2012-04-20 14:29:59 +02:00
* If < code > s = = NULL < / code > then new context is created .
*
2010-05-06 17:50:26 +02:00
* @ param [ in ] s The destination buffer to append to .
*
* @ param [ in ] a The string you want to append .
*
2012-04-20 14:32:01 +02:00
* @ return The concatenated strings , NULL on error .
2010-05-06 17:50:26 +02:00
*
* @ see talloc_strdup ( )
2012-04-16 12:59:22 +02:00
* @ see talloc_strdup_append ( )
* @ see talloc_array_length ( )
2010-05-06 17:50:26 +02:00
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ char * talloc_strdup_append_buffer ( char * s , const char * a ) ;
2007-09-19 14:44:16 +00:00
2010-01-17 11:25:02 +01:00
/**
* @ brief Duplicate a length - limited string into a talloc chunk .
*
* This function is the talloc equivalent of the C library function strndup ( 3 ) .
*
* This functions sets the name of the new pointer to the passed string . This is
* equivalent to :
*
* @ code
* talloc_set_name_const ( ptr , ptr )
* @ endcode
*
* @ param [ in ] t The talloc context to hang the result off .
*
* @ param [ in ] p The string you want to duplicate .
*
* @ param [ in ] n The maximum string length to duplicate .
*
* @ return The duplicated string , NULL on error .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ char * talloc_strndup ( const void * t , const char * p , size_t n ) ;
2010-05-06 17:50:26 +02:00
/**
2012-04-16 13:12:41 +02:00
* @ brief Append at most n characters of a string to given string .
*
* The destination string is reallocated to take
* < code > strlen ( s ) + strnlen ( a , n ) + 1 < / code > characters .
*
* This functions sets the name of the new pointer to the new
* string . This is equivalent to :
*
* @ code
* talloc_set_name_const ( ptr , ptr )
* @ endcode
2010-05-06 17:50:26 +02:00
*
2012-04-20 14:29:59 +02:00
* If < code > s = = NULL < / code > then new context is created .
*
2010-05-06 17:50:26 +02:00
* @ param [ in ] s The destination string to append to .
*
* @ param [ in ] a The source string you want to append .
*
* @ param [ in ] n The number of characters you want to append from the
* string .
*
2012-04-20 14:32:01 +02:00
* @ return The concatenated strings , NULL on error .
2010-05-06 17:50:26 +02:00
*
* @ see talloc_strndup ( )
2012-04-16 13:12:41 +02:00
* @ see talloc_strndup_append_buffer ( )
2010-05-06 17:50:26 +02:00
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ char * talloc_strndup_append ( char * s , const char * a , size_t n ) ;
2010-05-06 17:50:26 +02:00
/**
2012-04-16 13:17:59 +02:00
* @ brief Append at most n characters of a string to given buffer
*
* This is a more efficient version of talloc_strndup_append ( ) . It determines
* the length of the destination string by the size of the talloc context .
*
* Use this very carefully as it produces a different result than
* talloc_strndup_append ( ) when a zero character is in the middle of the
* destination string .
*
* @ code
* char * str_a = talloc_strdup ( NULL , " hello world " ) ;
* char * str_b = talloc_strdup ( NULL , " hello world " ) ;
* str_a [ 5 ] = str_b [ 5 ] = ' \0 '
*
* char * app = talloc_strndup_append ( str_a , " , hello " , 7 ) ;
* char * buf = talloc_strndup_append_buffer ( str_b , " , hello " , 7 ) ;
*
* printf ( " %s \n " , app ) ; // hello, hello (app = "hello, hello")
* printf ( " %s \n " , buf ) ; // hello (buf = "hello\0world, hello")
* @ endcode
2010-05-06 17:50:26 +02:00
*
2012-04-20 14:29:59 +02:00
* If < code > s = = NULL < / code > then new context is created .
*
2010-05-06 17:50:26 +02:00
* @ param [ in ] s The destination buffer to append to .
*
* @ param [ in ] a The source string you want to append .
*
* @ param [ in ] n The number of characters you want to append from the
* string .
*
2012-04-20 14:32:01 +02:00
* @ return The concatenated strings , NULL on error .
2010-05-06 17:50:26 +02:00
*
* @ see talloc_strndup ( )
2012-04-16 13:17:59 +02:00
* @ see talloc_strndup_append ( )
* @ see talloc_array_length ( )
2010-05-06 17:50:26 +02:00
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ char * talloc_strndup_append_buffer ( char * s , const char * a , size_t n ) ;
2007-09-19 14:44:16 +00:00
2010-01-17 11:25:02 +01:00
/**
* @ brief Format a string given a va_list .
*
* This function is the talloc equivalent of the C library function
* vasprintf ( 3 ) .
*
* This functions sets the name of the new pointer to the new string . This is
* equivalent to :
*
* @ code
* talloc_set_name_const ( ptr , ptr )
* @ endcode
*
* @ param [ in ] t The talloc context to hang the result off .
*
* @ param [ in ] fmt The format string .
*
* @ param [ in ] ap The parameters used to fill fmt .
*
* @ return The formatted string , NULL on error .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ char * talloc_vasprintf ( const void * t , const char * fmt , va_list ap ) PRINTF_ATTRIBUTE ( 2 , 0 ) ;
2010-05-06 17:50:26 +02:00
/**
* @ brief Format a string given a va_list and append it to the given destination
* string .
*
* @ param [ in ] s The destination string to append to .
*
* @ param [ in ] fmt The format string .
*
* @ param [ in ] ap The parameters used to fill fmt .
*
* @ return The formatted string , NULL on error .
*
* @ see talloc_vasprintf ( )
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ char * talloc_vasprintf_append ( char * s , const char * fmt , va_list ap ) PRINTF_ATTRIBUTE ( 2 , 0 ) ;
2010-05-06 17:50:26 +02:00
/**
* @ brief Format a string given a va_list and append it to the given destination
* buffer .
*
* @ param [ in ] s The destination buffer to append to .
*
* @ param [ in ] fmt The format string .
*
* @ param [ in ] ap The parameters used to fill fmt .
*
* @ return The formatted string , NULL on error .
*
* @ see talloc_vasprintf ( )
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ char * talloc_vasprintf_append_buffer ( char * s , const char * fmt , va_list ap ) PRINTF_ATTRIBUTE ( 2 , 0 ) ;
2007-09-19 14:44:16 +00:00
2022-11-28 10:19:54 +01:00
/**
* @ brief Build up a string buffer , handle allocation failure
*
* @ param [ in ] ps Pointer to the talloc ' ed string to be extended
* @ param [ in ] fmt The format string
* @ param [ in ] . . . The parameters used to fill fmt .
*
* This does nothing if * ps is NULL and sets * ps to NULL if the
* intermediate reallocation fails . Useful when building up a string
* step by step , no intermediate NULL checks are required .
*/
_PUBLIC_ void talloc_asprintf_addbuf ( char * * ps , const char * fmt , . . . ) \
PRINTF_ATTRIBUTE ( 2 , 3 ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Format a string .
*
* This function is the talloc equivalent of the C library function asprintf ( 3 ) .
*
* This functions sets the name of the new pointer to the new string . This is
* equivalent to :
*
* @ code
* talloc_set_name_const ( ptr , ptr )
* @ endcode
*
* @ param [ in ] t The talloc context to hang the result off .
*
* @ param [ in ] fmt The format string .
*
* @ param [ in ] . . . The parameters used to fill fmt .
*
* @ return The formatted string , NULL on error .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ char * talloc_asprintf ( const void * t , const char * fmt , . . . ) PRINTF_ATTRIBUTE ( 2 , 3 ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Append a formatted string to another string .
*
* This function appends the given formatted string to the given string . Use
2011-03-31 21:32:51 +02:00
* this variant when the string in the current talloc buffer may have been
2010-01-17 11:25:02 +01:00
* truncated in length .
*
* This functions sets the name of the new pointer to the new
* string . This is equivalent to :
*
* @ code
* talloc_set_name_const ( ptr , ptr )
* @ endcode
*
2012-04-20 14:29:59 +02:00
* If < code > s = = NULL < / code > then new context is created .
*
2010-01-17 11:25:02 +01:00
* @ param [ in ] s The string to append to .
*
* @ param [ in ] fmt The format string .
*
* @ param [ in ] . . . The parameters used to fill fmt .
*
* @ return The formatted string , NULL on error .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ char * talloc_asprintf_append ( char * s , const char * fmt , . . . ) PRINTF_ATTRIBUTE ( 2 , 3 ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Append a formatted string to another string .
*
2012-04-16 13:32:02 +02:00
* This is a more efficient version of talloc_asprintf_append ( ) . It determines
* the length of the destination string by the size of the talloc context .
*
* Use this very carefully as it produces a different result than
* talloc_asprintf_append ( ) when a zero character is in the middle of the
* destination string .
*
* @ code
* char * str_a = talloc_strdup ( NULL , " hello world " ) ;
* char * str_b = talloc_strdup ( NULL , " hello world " ) ;
* str_a [ 5 ] = str_b [ 5 ] = ' \0 '
*
* char * app = talloc_asprintf_append ( str_a , " %s " , " , hello " ) ;
* char * buf = talloc_strdup_append_buffer ( str_b , " %s " , " , hello " ) ;
*
* printf ( " %s \n " , app ) ; // hello, hello (app = "hello, hello")
* printf ( " %s \n " , buf ) ; // hello (buf = "hello\0world, hello")
* @ endcode
*
2012-04-20 14:29:59 +02:00
* If < code > s = = NULL < / code > then new context is created .
*
2010-01-17 11:25:02 +01:00
* @ param [ in ] s The string to append to
*
* @ param [ in ] fmt The format string .
*
* @ param [ in ] . . . The parameters used to fill fmt .
*
* @ return The formatted string , NULL on error .
2012-04-16 13:32:02 +02:00
*
* @ see talloc_asprintf ( )
* @ see talloc_asprintf_append ( )
2010-01-17 11:25:02 +01:00
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ char * talloc_asprintf_append_buffer ( char * s , const char * fmt , . . . ) PRINTF_ATTRIBUTE ( 2 , 3 ) ;
2007-09-19 14:44:16 +00:00
2010-01-17 11:25:02 +01:00
/* @} ******************************************************************/
/**
* @ defgroup talloc_debug The talloc debugging support functions
* @ ingroup talloc
*
* To aid memory debugging , talloc contains routines to inspect the currently
* allocated memory hierarchy .
*
* @ {
*/
/**
* @ brief Walk a complete talloc hierarchy .
*
* This provides a more flexible reports than talloc_report ( ) . It
* will recursively call the callback for the entire tree of memory
* referenced by the pointer . References in the tree are passed with
* is_ref = 1 and the pointer that is referenced .
*
* You can pass NULL for the pointer , in which case a report is
* printed for the top level memory context , but only if
* talloc_enable_leak_report ( ) or talloc_enable_leak_report_full ( )
* has been called .
*
* The recursion is stopped when depth > = max_depth .
* max_depth = - 1 means only stop at leaf nodes .
*
* @ param [ in ] ptr The talloc chunk .
*
* @ param [ in ] depth Internal parameter to control recursion . Call with 0.
*
* @ param [ in ] max_depth Maximum recursion level .
*
* @ param [ in ] callback Function to be called on every chunk .
*
* @ param [ in ] private_data Private pointer passed to callback .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_report_depth_cb ( const void * ptr , int depth , int max_depth ,
2010-01-17 11:25:02 +01:00
void ( * callback ) ( const void * ptr ,
int depth , int max_depth ,
int is_ref ,
void * private_data ) ,
void * private_data ) ;
/**
* @ brief Print a talloc hierarchy .
*
* This provides a more flexible reports than talloc_report ( ) . It
* will let you specify the depth and max_depth .
*
* @ param [ in ] ptr The talloc chunk .
*
* @ param [ in ] depth Internal parameter to control recursion . Call with 0.
*
* @ param [ in ] max_depth Maximum recursion level .
*
* @ param [ in ] f The file handle to print to .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_report_depth_file ( const void * ptr , int depth , int max_depth , FILE * f ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Print a summary report of all memory used by ptr .
*
* This provides a more detailed report than talloc_report ( ) . It will
2011-03-31 21:32:51 +02:00
* recursively print the entire tree of memory referenced by the
2010-01-17 11:25:02 +01:00
* pointer . References in the tree are shown by giving the name of the
* pointer that is referenced .
*
* You can pass NULL for the pointer , in which case a report is printed
* for the top level memory context , but only if
* talloc_enable_leak_report ( ) or talloc_enable_leak_report_full ( ) has
* been called .
*
* @ param [ in ] ptr The talloc chunk .
*
* @ param [ in ] f The file handle to print to .
*
* Example :
* @ code
* unsigned int * a , * b ;
* a = talloc ( NULL , unsigned int ) ;
* b = talloc ( a , unsigned int ) ;
* fprintf ( stderr , " Dumping memory tree for a: \n " ) ;
* talloc_report_full ( a , stderr ) ;
* @ endcode
*
* @ see talloc_report ( )
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_report_full ( const void * ptr , FILE * f ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Print a summary report of all memory used by ptr .
*
* This function prints a summary report of all memory used by ptr . One line of
* report is printed for each immediate child of ptr , showing the total memory
* and number of blocks used by that child .
*
* You can pass NULL for the pointer , in which case a report is printed
* for the top level memory context , but only if talloc_enable_leak_report ( )
* or talloc_enable_leak_report_full ( ) has been called .
*
* @ param [ in ] ptr The talloc chunk .
*
* @ param [ in ] f The file handle to print to .
*
* Example :
* @ code
* unsigned int * a , * b ;
* a = talloc ( NULL , unsigned int ) ;
* b = talloc ( a , unsigned int ) ;
* fprintf ( stderr , " Summary of memory tree for a: \n " ) ;
* talloc_report ( a , stderr ) ;
* @ endcode
*
* @ see talloc_report_full ( )
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_report ( const void * ptr , FILE * f ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Enable tracking the use of NULL memory contexts .
*
* This enables tracking of the NULL memory context without enabling leak
* reporting on exit . Useful for when you want to do your own leak
* reporting call via talloc_report_null_full ( ) ;
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_enable_null_tracking ( void ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Enable tracking the use of NULL memory contexts .
*
* This enables tracking of the NULL memory context without enabling leak
* reporting on exit . Useful for when you want to do your own leak
* reporting call via talloc_report_null_full ( ) ;
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_enable_null_tracking_no_autofree ( void ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Disable tracking of the NULL memory context .
*
* This disables tracking of the NULL memory context .
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_disable_null_tracking ( void ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Enable leak report when a program exits .
*
* This enables calling of talloc_report ( NULL , stderr ) when the program
* exits . In Samba4 this is enabled by using the - - leak - report command
* line option .
*
* For it to be useful , this function must be called before any other
* talloc function as it establishes a " null context " that acts as the
* top of the tree . If you don ' t call this function first then passing
* NULL to talloc_report ( ) or talloc_report_full ( ) won ' t give you the
* full tree printout .
*
* Here is a typical talloc report :
*
* @ code
* talloc report on ' null_context ' ( total 267 bytes in 15 blocks )
* libcli / auth / spnego_parse . c : 55 contains 31 bytes in 2 blocks
* libcli / auth / spnego_parse . c : 55 contains 31 bytes in 2 blocks
* iconv ( UTF8 , CP850 ) contains 42 bytes in 2 blocks
* libcli / auth / spnego_parse . c : 55 contains 31 bytes in 2 blocks
* iconv ( CP850 , UTF8 ) contains 42 bytes in 2 blocks
* iconv ( UTF8 , UTF - 16L E ) contains 45 bytes in 2 blocks
* iconv ( UTF - 16L E , UTF8 ) contains 45 bytes in 2 blocks
* @ endcode
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_enable_leak_report ( void ) ;
2010-01-17 11:25:02 +01:00
/**
* @ brief Enable full leak report when a program exits .
*
* This enables calling of talloc_report_full ( NULL , stderr ) when the
* program exits . In Samba4 this is enabled by using the
* - - leak - report - full command line option .
*
* For it to be useful , this function must be called before any other
* talloc function as it establishes a " null context " that acts as the
* top of the tree . If you don ' t call this function first then passing
* NULL to talloc_report ( ) or talloc_report_full ( ) won ' t give you the
* full tree printout .
*
* Here is a typical full report :
*
* @ code
* full talloc report on ' root ' ( total 18 bytes in 8 blocks )
* p1 contains 18 bytes in 7 blocks ( ref 0 )
* r1 contains 13 bytes in 2 blocks ( ref 0 )
* reference to : p2
* p2 contains 1 bytes in 1 blocks ( ref 1 )
* x3 contains 1 bytes in 1 blocks ( ref 0 )
* x2 contains 1 bytes in 1 blocks ( ref 0 )
* x1 contains 1 bytes in 1 blocks ( ref 0 )
* @ endcode
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_enable_leak_report_full ( void ) ;
2010-01-17 11:25:02 +01:00
2012-04-16 14:43:37 +02:00
/**
* @ brief Set a custom " abort " function that is called on serious error .
*
* The default " abort " function is < code > abort ( ) < / code > .
*
* The " abort " function is called when :
*
* < ul >
* < li > talloc_get_type_abort ( ) fails < / li >
* < li > the provided pointer is not a valid talloc context < / li >
* < li > when the context meta data are invalid < / li >
* < li > when access after free is detected < / li >
* < / ul >
*
* Example :
*
* @ code
* void my_abort ( const char * reason )
* {
* fprintf ( stderr , " talloc abort: %s \n " , reason ) ;
* abort ( ) ;
* }
*
* talloc_set_abort_fn ( my_abort ) ;
* @ endcode
*
* @ param [ in ] abort_fn The new " abort " function .
*
* @ see talloc_set_log_fn ( )
* @ see talloc_get_type ( )
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_set_abort_fn ( void ( * abort_fn ) ( const char * reason ) ) ;
2012-04-16 14:47:16 +02:00
/**
* @ brief Set a logging function .
*
* @ param [ in ] log_fn The logging function .
*
* @ see talloc_set_log_stderr ( )
* @ see talloc_set_abort_fn ( )
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_set_log_fn ( void ( * log_fn ) ( const char * message ) ) ;
2012-04-16 14:49:03 +02:00
/**
* @ brief Set stderr as the output for logs .
*
* @ see talloc_set_log_fn ( )
* @ see talloc_set_abort_fn ( )
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ void talloc_set_log_stderr ( void ) ;
2009-03-12 08:19:50 +01:00
2012-09-22 16:15:47 -04:00
/**
* @ brief Set a max memory limit for the current context hierarchy
* This affects all children of this context and constrain any
* allocation in the hierarchy to never exceed the limit set .
* The limit can be removed by setting 0 ( unlimited ) as the
2018-05-27 08:38:19 +02:00
* max_size by calling the function again on the same context .
* Memory limits can also be nested , meaning a child can have
2012-09-22 16:15:47 -04:00
* a stricter memory limit than a parent .
* Memory limits are enforced only at memory allocation time .
* Stealing a context into a ' limited ' hierarchy properly
* updates memory usage but does * not * cause failure if the
* move causes the new parent to exceed its limits . However
* any further allocation on that hierarchy will then fail .
*
2018-10-16 19:06:48 +02:00
* @ warning talloc memlimit functionality is deprecated . Please
* consider using cgroup memory limits instead .
*
2012-09-22 16:15:47 -04:00
* @ param [ in ] ctx The talloc context to set the limit on
* @ param [ in ] max_size The ( new ) max_size
*/
2019-03-07 00:40:12 +01:00
_PUBLIC_ int talloc_set_memlimit ( const void * ctx , size_t max_size ) _DEPRECATED_ ;
2012-09-22 16:15:47 -04:00
2012-04-16 14:43:37 +02:00
/* @} ******************************************************************/
2010-01-17 11:25:02 +01:00
# if TALLOC_DEPRECATED
# define talloc_zero_p(ctx, type) talloc_zero(ctx, type)
# define talloc_p(ctx, type) talloc(ctx, type)
# define talloc_array_p(ctx, type, count) talloc_array(ctx, type, count)
# define talloc_realloc_p(ctx, p, type, count) talloc_realloc(ctx, p, type, count)
# define talloc_destroy(ctx) talloc_free(ctx)
# define talloc_append_string(c, s, a) (s?talloc_strdup_append(s,a):talloc_strdup(c, a))
# endif
2010-04-02 18:17:52 +11:00
# ifndef TALLOC_MAX_DEPTH
# define TALLOC_MAX_DEPTH 10000
# endif
2010-10-20 13:09:57 -04:00
# ifdef __cplusplus
} /* end of extern "C" */
# endif
2005-05-03 07:33:49 +00:00
# endif