1reallocarray(3bsd) LOCAL reallocarray(3bsd)
2
4 reallocarray, recallocarray, freezero — memory allocation and dealloca‐
5 tion
6
8 Utility functions from BSD systems (libbsd, -lbsd)
9
11 #include <stdlib.h>
12 (See libbsd(7) for include usage.)
13 void *
15 reallocarray(void *ptr, size_t nmemb, size_t size);
16 void *
18 recallocarray(void *ptr, size_t oldnmemb, size_t nmemb, size_t size);
19 void
21 freezero(void *ptr, size_t size);
22
24 Designed for safe allocation of arrays, the reallocarray() function is
25 similar to realloc() except it operates on nmemb members of size size and
26 checks for integer overflow in the calculation nmemb * size.
27 Used for the allocation of memory holding sensitive data, the
29 recallocarray() function guarantees that memory becoming unallocated is
30 explicitly discarded, meaning cached free objects are cleared with
31 explicit_bzero(3).
32 The recallocarray() function is similar to reallocarray() except it en‐
34 sures newly allocated memory is cleared similar to calloc(). If ptr is
35 NULL, oldnmemb is ignored and the call is equivalent to calloc(). If ptr
36 is not NULL, oldnmemb must be a value such that oldnmemb * size is the
37 size of the earlier allocation that returned ptr, otherwise the behavior
38 is undefined. The freezero() function is similar to the free() function
39 except it ensures memory is explicitly discarded. If ptr is NULL, no ac‐
40 tion occurs. If ptr is not NULL, the size argument must be equal to or
41 smaller than the size of the earlier allocation that returned ptr.
42 freezero() guarantees the memory range starting at ptr with length size
43 is discarded while deallocating the whole object originally allocated.
44
46 The reallocarray() and recallocarray() functions return a pointer to the
47 allocated space if successful; otherwise, a null pointer is returned and
48 errno is set to ENOMEM.
49 If multiplying nmemb and size results in integer overflow, reallocarray()
51 and recallocarray() return NULL and set errno to ENOMEM.
52 If ptr is not NULL and multiplying oldnmemb and size results in integer
54 overflow recallocarray() returns NULL and sets errno to EINVAL.
55
57 Consider calloc() or the extensions reallocarray() and recallocarray()
58 when there is multiplication in the size argument of malloc() or
59 realloc(). For example, avoid this common idiom as it may lead to inte‐
60 ger overflow:
61 if ((p = malloc(num * size)) == NULL)
63 err(1, NULL);
64 A drop-in replacement is reallocarray():
66 if ((p = reallocarray(NULL, num, size)) == NULL)
68 err(1, NULL);
69 Alternatively, calloc() may be used at the cost of initialization over‐
71 head.
72 When using realloc(), be careful to avoid the following idiom:
74 size += 50;
76 if ((p = realloc(p, size)) == NULL)
77 return (NULL);
78 Do not adjust the variable describing how much memory has been allocated
80 until the allocation has been successful. This can cause aberrant pro‐
81 gram behavior if the incorrect size value is used. In most cases, the
82 above sample will also result in a leak of memory. As stated earlier, a
83 return value of NULL indicates that the old object still remains allo‐
84 cated. Better code looks like this:
85 newsize = size + 50;
87 if ((newp = realloc(p, newsize)) == NULL) {
88 free(p);
89 p = NULL;
90 size = 0;
91 return (NULL);
92 }
93 p = newp;
94 size = newsize;
95 As with malloc(), it is important to ensure the new size value will not
97 overflow; i.e. avoid allocations like the following:
98 if ((newp = realloc(p, num * size)) == NULL) {
100 ...
101 Instead, use reallocarray():
103 if ((newp = reallocarray(p, num, size)) == NULL) {
105 ...
106 Calling realloc() with a NULL ptr is equivalent to calling malloc(). In‐
108 stead of this idiom:
109 if (p == NULL)
111 newp = malloc(newsize);
112 else
113 newp = realloc(p, newsize);
114 Use the following:
116 newp = realloc(p, newsize);
118 The recallocarray() function should be used for resizing objects contain‐
120 ing sensitive data like keys. To avoid leaking information, it guaran‐
121 tees memory is cleared before placing it on the internal free list. De‐
122 allocation of such an object should be done by calling freezero().
123
125 malloc(3), calloc(3), alloca(3)
126
128 The reallocarray() function appeared in OpenBSD 5.6, and glibc 2.26. The
129 recallocarray() function appeared in OpenBSD 6.1. The freezero() func‐
130 tion appeared in OpenBSD 6.2.
131BSD September 14, 2019 BSD