Functions
Memory Handling

Functions

WOLFSSL_API void * wolfSSL_Malloc (size_t size, void *heap, int type, const char *func, unsigned int line)
 This function calls the custom malloc function, if one has been defined, or simply calls the default C malloc function if no custom function exists. It is not called directly by wolfSSL, but instead generally called by using XMALLOC, which may be replaced by wolfSSL_Malloc during preprocessing. More...
 
WOLFSSL_API void wolfSSL_Free (void *ptr, void *heap, int type, const char *func, unsigned int line)
 This function calls a custom free function, if one has been defined, or simply calls the default C free function if no custom function exists. It is not called directly by wolfSSL, but instead generally called by using XFREE, which may be replaced by wolfSSL_Free during preprocessing. More...
 
WOLFSSL_API void * wolfSSL_Realloc (void *ptr, size_t size, void *heap, int type, const char *func, unsigned int line)
 This function calls a custom realloc function, if one has been defined, or simply calls the default C realloc function if no custom function exists. It is not called directly by wolfSSL, but instead generally called by using XREALLOC, which may be replaced by wolfSSL_Realloc during preprocessing. More...
 
WOLFSSL_API void * wolfSSL_Malloc (size_t size, void *heap, int type)
 This function is similar to malloc(), but calls the memory allocation function which wolfSSL has been configured to use. By default, wolfSSL uses malloc(). This can be changed using the wolfSSL memory abstraction layer - see wolfSSL_SetAllocators(). More...
 
WOLFSSL_API void * wolfSSL_Realloc (void *ptr, size_t size, void *heap, int type)
 This function is similar to realloc(), but calls the memory re-allocation function which wolfSSL has been configured to use. By default, wolfSSL uses realloc(). This can be changed using the wolfSSL memory abstraction layer - see wolfSSL_SetAllocators(). More...
 
WOLFSSL_API void wolfSSL_Free (void *ptr, const char *func, unsigned int line)
 This function is similar to free(), but calls the memory free function which wolfSSL has been configured to use. By default, wolfSSL uses free(). This can be changed using the wolfSSL memory abstraction layer - see wolfSSL_SetAllocators(). More...
 
WOLFSSL_API int wolfSSL_SetAllocators (wolfSSL_Malloc_cb, wolfSSL_Free_cb, wolfSSL_Realloc_cb)
 This function registers the allocation functions used by wolfSSL. By default, if the system supports it, malloc/free and realloc are used. Using this function allows the user at runtime to install their own memory handlers. More...
 
WOLFSSL_API int wolfSSL_StaticBufferSz (byte *buffer, word32 sz, int flag)
 This function is available when static memory feature is used (–enable-staticmemory). It gives the optimum buffer size for memory “buckets”. This allows for a way to compute buffer size so that no extra unused memory is left at the end after it has been partitioned. The returned value, if positive, is the computed buffer size to use. More...
 
WOLFSSL_API int wolfSSL_MemoryPaddingSz (void)
 This function is available when static memory feature is used (–enable-staticmemory). It gives the size of padding needed for each partition of memory. This padding size will be the size needed to contain a memory management structure along with any extra for memory alignment. More...
 
WOLFSSL_API void * XMALLOC (size_t n, void *heap, int type)
 This is not actually a function, but rather a preprocessor macro, which allows the user to substitute in their own malloc, realloc, and free functions in place of the standard C memory functions. To use external memory functions, define XMALLOC_USER. This will cause the memory functions to be replaced by external functions of the form: extern void XMALLOC(size_t n, void heap, int type); extern void XREALLOC(void *p, size_t n, void heap, int type); extern void XFREE(void p, void heap, int type); To use the basic C memory functions in place of wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));} #define XREALLOC(p, n, h, t) realloc((p), (n)) If none of these options are selected, the system will default to use the wolfSSL memory functions. A user can set custom memory functions through callback hooks, (see wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free). This option will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, wolfSSL_Malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) wolfSSL_Free((xp));} #define XREALLOC(p, n, h, t) wolfSSL_Realloc((p), (n)) More...
 
WOLFSSL_API void * XREALLOC (void *p, size_t n, void *heap, int type)
 This is not actually a function, but rather a preprocessor macro, which allows the user to substitute in their own malloc, realloc, and free functions in place of the standard C memory functions. To use external memory functions, define XMALLOC_USER. This will cause the memory functions to be replaced by external functions of the form: extern void XMALLOC(size_t n, void heap, int type); extern void XREALLOC(void *p, size_t n, void heap, int type); extern void XFREE(void p, void heap, int type); To use the basic C memory functions in place of wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));} #define XREALLOC(p, n, h, t) realloc((p), (n)) If none of these options are selected, the system will default to use the wolfSSL memory functions. A user can set custom memory functions through callback hooks, (see wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free). This option will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, wolfSSL_Malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) wolfSSL_Free((xp));} #define XREALLOC(p, n, h, t) wolfSSL_Realloc((p), (n)) More...
 
WOLFSSL_API void XFREE (void *p, void *heap, int type)
 This is not actually a function, but rather a preprocessor macro, which allows the user to substitute in their own malloc, realloc, and free functions in place of the standard C memory functions. To use external memory functions, define XMALLOC_USER. This will cause the memory functions to be replaced by external functions of the form: extern void XMALLOC(size_t n, void heap, int type); extern void XREALLOC(void *p, size_t n, void heap, int type); extern void XFREE(void p, void heap, int type); To use the basic C memory functions in place of wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));} #define XREALLOC(p, n, h, t) realloc((p), (n)) If none of these options are selected, the system will default to use the wolfSSL memory functions. A user can set custom memory functions through callback hooks, (see wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free). This option will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, wolfSSL_Malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) wolfSSL_Free((xp));} #define XREALLOC(p, n, h, t) wolfSSL_Realloc((p), (n)) More...
 

Detailed Description

Function Documentation

◆ wolfSSL_Free() [1/2]

WOLFSSL_API void wolfSSL_Free ( void *  ptr,
void *  heap,
int  type,
const char *  func,
unsigned int  line 
)

This function calls a custom free function, if one has been defined, or simply calls the default C free function if no custom function exists. It is not called directly by wolfSSL, but instead generally called by using XFREE, which may be replaced by wolfSSL_Free during preprocessing.

Returns
none No returns.
Parameters
ptrpointer to the memory to free

Example

int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10);
// process data as desired
...
if(tenInts) {
wolfSSL_Free(tenInts);
}
See also
wolfSSL_Malloc
wolfSSL_Realloc
XMALLOC
XFREE
XREALLOC

◆ wolfSSL_Free() [2/2]

WOLFSSL_API void wolfSSL_Free ( void *  ptr,
const char *  func,
unsigned int  line 
)

This function is similar to free(), but calls the memory free function which wolfSSL has been configured to use. By default, wolfSSL uses free(). This can be changed using the wolfSSL memory abstraction layer - see wolfSSL_SetAllocators().

Returns
none No returns.
Parameters
ptrpointer to the memory to be freed.

Example

char* buffer;
...
wolfSSL_Free(buffer);
See also
wolfSSL_Alloc
wolfSSL_Realloc
wolfSSL_SetAllocators

◆ wolfSSL_Malloc() [1/2]

WOLFSSL_API void* wolfSSL_Malloc ( size_t  size,
void *  heap,
int  type,
const char *  func,
unsigned int  line 
)

This function calls the custom malloc function, if one has been defined, or simply calls the default C malloc function if no custom function exists. It is not called directly by wolfSSL, but instead generally called by using XMALLOC, which may be replaced by wolfSSL_Malloc during preprocessing.

Returns
Success On successfully allocating the desired memory, returns a void* to that location
NULL Returned when there is a failure to allocate memory
Parameters
sizesize, in bytes, of the memory to allocate

Example

int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10);
See also
wolfSSL_Free
wolfSSL_Realloc
XMALLOC
XFREE
XREALLOC

◆ wolfSSL_Malloc() [2/2]

WOLFSSL_API void* wolfSSL_Malloc ( size_t  size,
void *  heap,
int  type 
)

This function is similar to malloc(), but calls the memory allocation function which wolfSSL has been configured to use. By default, wolfSSL uses malloc(). This can be changed using the wolfSSL memory abstraction layer - see wolfSSL_SetAllocators().

Returns
pointer If successful, this function returns a pointer to allocated memory.
error If there is an error, NULL will be returned.
other Specific return values may be dependent on the underlying memory allocation function being used (if not using the default malloc()).
Parameters
sizenumber of bytes to allocate.

Example

char* buffer;
buffer = (char*) wolfSSL_Malloc(20);
if (buffer == NULL) {
// failed to allocate memory
}
See also
wolfSSL_Free
wolfSSL_Realloc
wolfSSL_SetAllocators

◆ wolfSSL_MemoryPaddingSz()

WOLFSSL_API int wolfSSL_MemoryPaddingSz ( void  )

This function is available when static memory feature is used (–enable-staticmemory). It gives the size of padding needed for each partition of memory. This padding size will be the size needed to contain a memory management structure along with any extra for memory alignment.

Returns
On successfully memory padding calculation the return value will be a positive value
All negative values are considered error cases.
Parameters
noneNo parameters.

Example

int padding;
if (padding < 0) { //handle error case }
printf(“The padding size needed for each \”bucket\” of memory is %d\n”,
padding);
// calculation of buffer for IO POOL size is number of buckets
// times (padding + WOLFMEM_IO_SZ)
...
See also
wolfSSL_Malloc
wolfSSL_Free

◆ wolfSSL_Realloc() [1/2]

WOLFSSL_API void* wolfSSL_Realloc ( void *  ptr,
size_t  size,
void *  heap,
int  type,
const char *  func,
unsigned int  line 
)

This function calls a custom realloc function, if one has been defined, or simply calls the default C realloc function if no custom function exists. It is not called directly by wolfSSL, but instead generally called by using XREALLOC, which may be replaced by wolfSSL_Realloc during preprocessing.

Returns
Success On successfully reallocating the desired memory, returns a void* to that location
NULL Returned when there is a failure to reallocate memory
Parameters
ptrpointer to the memory to the memory to reallocate
sizedesired size after reallocation

Example

int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10);
int* twentyInts = (int*)realloc(tenInts, sizeof(tenInts)*2);
See also
wolfSSL_Malloc
wolfSSL_Free
XMALLOC
XFREE
XREALLOC

◆ wolfSSL_Realloc() [2/2]

WOLFSSL_API void* wolfSSL_Realloc ( void *  ptr,
size_t  size,
void *  heap,
int  type 
)

This function is similar to realloc(), but calls the memory re-allocation function which wolfSSL has been configured to use. By default, wolfSSL uses realloc(). This can be changed using the wolfSSL memory abstraction layer - see wolfSSL_SetAllocators().

Returns
pointer If successful, this function returns a pointer to re-allocated memory. This may be the same pointer as ptr, or a new pointer location.
Null If there is an error, NULL will be returned.
other Specific return values may be dependent on the underlying memory re-allocation function being used (if not using the default realloc()).
Parameters
ptrpointer to the previously-allocated memory, to be reallocated.
sizenumber of bytes to allocate.

Example

char* buffer;
buffer = (char*) wolfSSL_Realloc(30);
if (buffer == NULL) {
// failed to re-allocate memory
}
See also
wolfSSL_Free
wolfSSL_Malloc
wolfSSL_SetAllocators

◆ wolfSSL_SetAllocators()

WOLFSSL_API int wolfSSL_SetAllocators ( wolfSSL_Malloc_cb  ,
wolfSSL_Free_cb  ,
wolfSSL_Realloc_cb   
)

This function registers the allocation functions used by wolfSSL. By default, if the system supports it, malloc/free and realloc are used. Using this function allows the user at runtime to install their own memory handlers.

Returns
Success If successful this function will return 0.
BAD_FUNC_ARG is the error that will be returned if a function pointer is not provided.
Parameters
malloc_functionmemory allocation function for wolfSSL to use. Function signature must match wolfSSL_Malloc_cb prototype, above.
free_functionmemory free function for wolfSSL to use. Function signature must match wolfSSL_Free_cb prototype, above.
realloc_functionmemory re-allocation function for wolfSSL to use. Function signature must match wolfSSL_Realloc_cb prototype, above.

Example

int ret = 0;
// Memory function prototypes
void* MyMalloc(size_t size);
void MyFree(void* ptr);
void* MyRealloc(void* ptr, size_t size);
// Register custom memory functions with wolfSSL
ret = wolfSSL_SetAllocators(MyMalloc, MyFree, MyRealloc);
if (ret != 0) {
// failed to set memory functions
}
void* MyMalloc(size_t size)
{
// custom malloc function
}
void MyFree(void* ptr)
{
// custom free function
}
void* MyRealloc(void* ptr, size_t size)
{
// custom realloc function
}
See also
none

◆ wolfSSL_StaticBufferSz()

WOLFSSL_API int wolfSSL_StaticBufferSz ( byte *  buffer,
word32  sz,
int  flag 
)

This function is available when static memory feature is used (–enable-staticmemory). It gives the optimum buffer size for memory “buckets”. This allows for a way to compute buffer size so that no extra unused memory is left at the end after it has been partitioned. The returned value, if positive, is the computed buffer size to use.

Returns
Success On successfully completing buffer size calculations a positive value is returned. This returned value is for optimum buffer size.
Failure All negative values are considered to be error cases.
Parameters
bufferpointer to buffer
sizesize of buffer
typedesired type of memory ie WOLFMEM_GENERAL or WOLFMEM_IO_POOL

Example

byte buffer[1000];
word32 size = sizeof(buffer);
int optimum;
optimum = wolfSSL_StaticBufferSz(buffer, size, WOLFMEM_GENERAL);
if (optimum < 0) { //handle error case }
printf(“The optimum buffer size to make use of all memory is %d\n”,
optimum);
...
See also
wolfSSL_Malloc
wolfSSL_Free

◆ XFREE()

void XFREE ( void *  p,
void *  heap,
int  type 
)

This is not actually a function, but rather a preprocessor macro, which allows the user to substitute in their own malloc, realloc, and free functions in place of the standard C memory functions. To use external memory functions, define XMALLOC_USER. This will cause the memory functions to be replaced by external functions of the form: extern void XMALLOC(size_t n, void heap, int type); extern void XREALLOC(void *p, size_t n, void heap, int type); extern void XFREE(void p, void heap, int type); To use the basic C memory functions in place of wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));} #define XREALLOC(p, n, h, t) realloc((p), (n)) If none of these options are selected, the system will default to use the wolfSSL memory functions. A user can set custom memory functions through callback hooks, (see wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free). This option will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, wolfSSL_Malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) wolfSSL_Free((xp));} #define XREALLOC(p, n, h, t) wolfSSL_Realloc((p), (n))

Returns
none No returns.
Parameters
ppointer to the address to free
h(used by custom XFREE function) pointer to the heap to use
tmemory allocation types for user hints. See enum in types.h

Example

int* 10 ints = XMALLOC(10 * sizeof(int), NULL, DYNAMIC_TYPE_TMP_BUFFER);
if ( ints == NULL) {
// error allocating space
return MEMORY_E;
}
See also
wolfSSL_Malloc
wolfSSL_Realloc
wolfSSL_Free
wolfSSL_SetAllocators

◆ XMALLOC()

void * XMALLOC ( size_t  n,
void *  heap,
int  type 
)

This is not actually a function, but rather a preprocessor macro, which allows the user to substitute in their own malloc, realloc, and free functions in place of the standard C memory functions. To use external memory functions, define XMALLOC_USER. This will cause the memory functions to be replaced by external functions of the form: extern void XMALLOC(size_t n, void heap, int type); extern void XREALLOC(void *p, size_t n, void heap, int type); extern void XFREE(void p, void heap, int type); To use the basic C memory functions in place of wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));} #define XREALLOC(p, n, h, t) realloc((p), (n)) If none of these options are selected, the system will default to use the wolfSSL memory functions. A user can set custom memory functions through callback hooks, (see wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free). This option will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, wolfSSL_Malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) wolfSSL_Free((xp));} #define XREALLOC(p, n, h, t) wolfSSL_Realloc((p), (n))

Returns
pointer Return a pointer to allocated memory on success
NULL on failure
Parameters
ssize of memory to allocate
h(used by custom XMALLOC function) pointer to the heap to use
tmemory allocation types for user hints. See enum in types.h

Example

int* 10 ints = XMALLOC(10 * sizeof(int), NULL, DYNAMIC_TYPE_TMP_BUFFER);
if ( ints == NULL) {
// error allocating space
return MEMORY_E;
}
See also
wolfSSL_Malloc
wolfSSL_Realloc
wolfSSL_Free
wolfSSL_SetAllocators

◆ XREALLOC()

void * XREALLOC ( void *  p,
size_t  n,
void *  heap,
int  type 
)

This is not actually a function, but rather a preprocessor macro, which allows the user to substitute in their own malloc, realloc, and free functions in place of the standard C memory functions. To use external memory functions, define XMALLOC_USER. This will cause the memory functions to be replaced by external functions of the form: extern void XMALLOC(size_t n, void heap, int type); extern void XREALLOC(void *p, size_t n, void heap, int type); extern void XFREE(void p, void heap, int type); To use the basic C memory functions in place of wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free, define NO_WOLFSSL_MEMORY. This will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) free((xp));} #define XREALLOC(p, n, h, t) realloc((p), (n)) If none of these options are selected, the system will default to use the wolfSSL memory functions. A user can set custom memory functions through callback hooks, (see wolfSSL_Malloc, wolfSSL_Realloc, wolfSSL_Free). This option will replace the memory functions with: #define XMALLOC(s, h, t) ((void)h, (void)t, wolfSSL_Malloc((s))) #define XFREE(p, h, t) {void* xp = (p); if((xp)) wolfSSL_Free((xp));} #define XREALLOC(p, n, h, t) wolfSSL_Realloc((p), (n))

Returns
Return a pointer to allocated memory on success
NULL on failure
Parameters
ppointer to the address to reallocate
nsize of memory to allocate
h(used by custom XREALLOC function) pointer to the heap to use
tmemory allocation types for user hints. See enum in types.h

Example

none
See also
wolfSSL_Malloc
wolfSSL_Realloc
wolfSSL_Free
wolfSSL_SetAllocators