wolfSSL Manual

Docs -> wolfSSL Manual

Chapter 17: wolfSSL API Reference


17.10  Memory Abstraction Layer


The functions in this section are used when an application sets its own memory handling functions by using the wolfSSL memory abstraction layer.






CyaSSL_Malloc


Synopsis:

#include <cyassl/ctaocrypt/memory.h>


void* CyaSSL_Malloc(size_t size)


Description:

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


Return Values:

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


Parameters:


size - number of bytes to allocate.


Example:


char* buffer;


buffer = (char*) CyaSSL_Malloc(20);

if (buffer == NULL) {

// failed to allocate memory

}


See Also:

CyaSSL_Free

CyaSSL_Realloc

CyaSSL_SetAllocators






CyaSSL_Realloc


Synopsis:

#include <cyassl/ctaocrypt/memory.h>


void* CyaSSL_Realloc(void *ptr, size_t size)


Description:

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


Return Values:

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


Parameters:


ptr - pointer to the previously-allocated memory, to be reallocated.


size - number of bytes to allocate.


Example:


char* buffer;


buffer = (char*) CyaSSL_Realloc(30);

if (buffer == NULL) {

// failed to re-allocate memory

}


See Also:

CyaSSL_Free

CyaSSL_Malloc

CyaSSL_SetAllocators






CyaSSL_Free


Synopsis:

#include <cyassl/ctaocrypt/memory.h>


void CyaSSL_Free(void* ptr)


Description:

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


Return Values:


This function does not have a return value.


Parameters:


ptr - pointer to the memory to be freed.


Example:


char* buffer;

...


CyaSSL_Free(buffer);


See Also:

CyaSSL_Alloc

CyaSSL_Realloc

CyaSSL_SetAllocators






CyaSSL_SetAllocators


Synopsis:

#include <cyassl/ctaocrypt/memory.h>


int CyaSSL_SetAllocators(CyaSSL_Malloc_cb  malloc_function,

                                               CyaSSL_Free_cb free_function,

                                               CyaSSL_Realloc_cb realloc_function);


typedef void *(*CyaSSL_Malloc_cb)(size_t size);

typedef void (*CyaSSL_Free_cb)(void *ptr);

typedef void *(*CyaSSL_Realloc_cb)(void *ptr, size_t size);



Description:

This function registers the allocation functions used by CyaSSL.  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.


Return Values:

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_function - memory allocation function for CyaSSL to use.  Function signature must match CyaSSL_Malloc_cb prototype, above.


free_function - memory free function for CyaSSL to use.  Function signature must match CyaSSL_Free_cb prototype, above.


realloc_function - memory re-allocation function for CyaSSL to use.  Function signature must match CyaSSL_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 CyaSSL

ret = CyaSSL_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:

NA




 

Questions? +1 (425) 245-8247