NAME

       reallocarray, recallocarray, freezero — memory allocation and deallocation

LIBRARY

       Utility functions from BSD systems (libbsd, -lbsd)

SYNOPSIS

       #include <stdlib.h>
       (See libbsd(7) for include usage.)

       void *
       reallocarray(void *ptr, size_t nmemb, size_t size);

       void *
       recallocarray(void *ptr, size_t oldnmemb, size_t nmemb, size_t size);

       void
       freezero(void *ptr, size_t size);

DESCRIPTION

       Designed  for  safe  allocation  of arrays, the reallocarray() function is similar to realloc() except it
       operates on nmemb members of size size and checks for integer overflow in the calculation nmemb * size.

       Used for the allocation of memory holding sensitive data, the recallocarray()  function  guarantees  that
       memory  becoming  unallocated  is  explicitly  discarded,  meaning  cached  free objects are cleared with
       explicit_bzero(3).

       The recallocarray() function is similar to reallocarray() except it ensures  newly  allocated  memory  is
       cleared similar to calloc().  If ptr is NULL, oldnmemb is ignored and the call is equivalent to calloc().
       If  ptr  is  not  NULL,  oldnmemb  must  be  a value such that oldnmemb * size is the size of the earlier
       allocation that returned ptr, otherwise the behavior is undefined.  The freezero() function is similar to
       the free() function except it ensures memory is explicitly discarded.  If ptr is NULL, no action  occurs.
       If ptr is not NULL, the size argument must be equal to or smaller than the size of the earlier allocation
       that  returned ptr.  freezero() guarantees the memory range starting at ptr with length size is discarded
       while deallocating the whole object originally allocated.

RETURN VALUES

       The reallocarray() and recallocarray() functions return a pointer to the allocated space  if  successful;
       otherwise, a null pointer is returned and errno is set to ENOMEM.

       If multiplying nmemb and size results in integer overflow, reallocarray() and recallocarray() return NULL
       and set errno to ENOMEM.

       If  ptr is not NULL and multiplying oldnmemb and size results in integer overflow recallocarray() returns
       NULL and sets errno to EINVAL.

IDIOMS

       Consider calloc() or the extensions reallocarray() and recallocarray() when there  is  multiplication  in
       the  size  argument  of  malloc()  or  realloc().  For example, avoid this common idiom as it may lead to
       integer overflow:

             if ((p = malloc(num * size)) == NULL)
                     err(1, NULL);

       A drop-in replacement is reallocarray():

             if ((p = reallocarray(NULL, num, size)) == NULL)
                     err(1, NULL);

       Alternatively, calloc() may be used at the cost of initialization overhead.

       When using realloc(), be careful to avoid the following idiom:

             size += 50;
             if ((p = realloc(p, size)) == NULL)
                     return (NULL);

       Do not adjust the variable describing how much memory has been allocated until the  allocation  has  been
       successful.   This  can  cause  aberrant  program  behavior if the incorrect size value is used.  In most
       cases, the above sample will also result in a leak of memory.  As stated earlier, a return value of  NULL
       indicates that the old object still remains allocated.  Better code looks like this:

             newsize = size + 50;
             if ((newp = realloc(p, newsize)) == NULL) {
                     free(p);
                     p = NULL;
                     size = 0;
                     return (NULL);
             }
             p = newp;
             size = newsize;

       As  with malloc(), it is important to ensure the new size value will not overflow; i.e. avoid allocations
       like the following:

             if ((newp = realloc(p, num * size)) == NULL) {
                     ...

       Instead, use reallocarray():

             if ((newp = reallocarray(p, num, size)) == NULL) {
                     ...

       Calling realloc() with a NULL ptr is equivalent to calling malloc().  Instead of this idiom:

             if (p == NULL)
                     newp = malloc(newsize);
             else
                     newp = realloc(p, newsize);

       Use the following:

             newp = realloc(p, newsize);

       The recallocarray() function should be used for resizing objects containing sensitive data like keys.  To
       avoid leaking information, it guarantees memory is cleared before placing it on the internal  free  list.
       Deallocation of such an object should be done by calling freezero().

SEE ALSO

       malloc(3), calloc(3), alloca(3)

HISTORY

       The reallocarray() function appeared in OpenBSD 5.6, DragonFly 5.5 and glibc 2.26.

       The recallocarray() function appeared in OpenBSD 6.1 and DragonFly 5.5.  The freezero() function appeared
       in OpenBSD 6.2 and DragonFly 5.5.

Debian                                         September 14, 2019                             reallocarray(3bsd)