dwww Home | Manual pages | Find package

reallocarray(3bsd)                   LOCAL                  reallocarray(3bsd)

NAME
     reallocarray, recallocarray, freezero — memory allocation and dealloca-
     tion

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 en-
     sures 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 ac-
     tion 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 inte-
     ger 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 over-
     head.

     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 pro-
     gram 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 allo-
     cated.  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().  In-
     stead 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 contain-
     ing sensitive data like keys.  To avoid leaking information, it guaran-
     tees memory is cleared before placing it on the internal free list.  De-
     allocation 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, and glibc 2.26.  The
     recallocarray() function appeared in OpenBSD 6.1.  The freezero() func-
     tion appeared in OpenBSD 6.2.

BSD                           September 14, 2019                           BSD

Generated by dwww version 1.15 on Sun Jun 16 21:10:16 CEST 2024.