Skip to content

Memory Handling

Functions

Name
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(). Note wolfSSL_Malloc is not called directly by wolfSSL, but instead called by macro XMALLOC. For the default build only the size argument exists. If using WOLFSSL_STATIC_MEMORY build then heap and type arguments are included.
void wolfSSL_Free(void * ptr, void * heap, int type)
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(). Note wolfSSL_Free is not called directly by wolfSSL, but instead called by macro XFREE. For the default build only the ptr argument exists. If using WOLFSSL_STATIC_MEMORY build then heap and type arguments are included.
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(). Note wolfSSL_Realloc is not called directly by wolfSSL, but instead called by macro XREALLOC. For the default build only the size argument exists. If using WOLFSSL_STATIC_MEMORY build then heap and type arguments are included.
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.
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.
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.
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))
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))
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))

Functions Documentation

function wolfSSL_Malloc

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(). Note wolfSSL_Malloc is not called directly by wolfSSL, but instead called by macro XMALLOC. For the default build only the size argument exists. If using WOLFSSL_STATIC_MEMORY build then heap and type arguments are included.

Parameters:

  • size size, in bytes, of the memory to allocate
  • heap heap hint to use for memory. Can be NULL
  • type dynamic type (see DYNAMIC_TYPE_ list in types.h)

See:

Return:

  • pointer If successful, this function returns a pointer to allocated memory.
  • error If there is an error, NULL will be returned.

Example

int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10);

function wolfSSL_Free

void wolfSSL_Free(
    void * ptr,
    void * heap,
    int type
)

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(). Note wolfSSL_Free is not called directly by wolfSSL, but instead called by macro XFREE. For the default build only the ptr argument exists. If using WOLFSSL_STATIC_MEMORY build then heap and type arguments are included.

Parameters:

  • ptr pointer to the memory to be freed.
  • heap heap hint to use for memory. Can be NULL
  • type dynamic type (see DYNAMIC_TYPE_ list in types.h)

See:

Return: none No returns.

Example

int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10);
// process data as desired
...
if(tenInts) {
    wolfSSL_Free(tenInts);
}

function wolfSSL_Realloc

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(). Note wolfSSL_Realloc is not called directly by wolfSSL, but instead called by macro XREALLOC. For the default build only the size argument exists. If using WOLFSSL_STATIC_MEMORY build then heap and type arguments are included.

Parameters:

  • ptr pointer to the previously-allocated memory, to be reallocated.
  • size number of bytes to allocate.
  • heap heap hint to use for memory. Can be NULL
  • type dynamic type (see DYNAMIC_TYPE_ list in types.h)

See:

Return:

  • 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.

Example

int* tenInts = (int*)wolfSSL_Malloc(sizeof(int)*10);
int* twentyInts = (int*)wolfSSL_Realloc(tenInts, sizeof(int)*20);

function wolfSSL_SetAllocators

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.

Parameters:

  • malloc_function memory allocation function for wolfSSL to use. Function signature must match wolfSSL_Malloc_cb prototype, above.
  • free_function memory free function for wolfSSL to use. Function signature must match wolfSSL_Free_cb prototype, above.
  • realloc_function memory re-allocation function for wolfSSL to use. Function signature must match wolfSSL_Realloc_cb prototype, above.

See: none

Return:

  • 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.

Example

static void* MyMalloc(size_t size)
{
    // custom malloc function
}

static void MyFree(void* ptr)
{
    // custom free function
}

static void* MyRealloc(void* ptr, size_t size)
{
    // custom realloc function
}

// Register custom memory functions with wolfSSL
int ret = wolfSSL_SetAllocators(MyMalloc, MyFree, MyRealloc);
if (ret != 0) {
    // failed to set memory functions
}

function wolfSSL_StaticBufferSz

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.

Parameters:

  • buffer pointer to buffer
  • size size of buffer
  • type desired type of memory ie WOLFMEM_GENERAL or WOLFMEM_IO_POOL

See:

Return:

  • 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.

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);
...

function wolfSSL_MemoryPaddingSz

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.

Parameters:

  • none No parameters.

See:

Return:

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

Example

int padding;
padding = wolfSSL_MemoryPaddingSz();
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)
...

function 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))

Parameters:

  • s size of memory to allocate
  • h (used by custom XMALLOC function) pointer to the heap to use
  • t memory allocation types for user hints. See enum in types.h

See:

Return:

  • pointer Return a pointer to allocated memory on success
  • NULL on failure

Example

int* tenInts = XMALLOC(sizeof(int)*10, NULL, DYNAMIC_TYPE_TMP_BUFFER);
if (tenInts == NULL) {
    // error allocating space
    return MEMORY_E;
}

function 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))

Parameters:

  • p pointer to the address to reallocate
  • n size of memory to allocate
  • h (used by custom XREALLOC function) pointer to the heap to use
  • t memory allocation types for user hints. See enum in types.h

See:

Return:

  • Return a pointer to allocated memory on success
  • NULL on failure

Example

int* tenInts = (int*)XMALLOC(sizeof(int)*10, NULL, DYNAMIC_TYPE_TMP_BUFFER);
int* twentyInts = (int*)XREALLOC(tenInts, sizeof(int)*20, NULL,
    DYNAMIC_TYPE_TMP_BUFFER);

function 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))

Parameters:

  • p pointer to the address to free
  • h (used by custom XFREE function) pointer to the heap to use
  • t memory allocation types for user hints. See enum in types.h

See:

Return: none No returns.

Example

int* tenInts = XMALLOC(sizeof(int) * 10, NULL, DYNAMIC_TYPE_TMP_BUFFER);
if (tenInts == NULL) {
    // error allocating space
    return MEMORY_E;
}

Updated on 2022-05-20 at 08:33:15 +0000