| Russ Allbery > Software > rra-c-util |
(Checked memory allocation)
#include <util/xmalloc.h>
void *xmalloc(size_t size);
void *xcalloc(size_t nmemb, size_t size);
void *xrealloc(void *ptr, size_t size);
extern void (*xmalloc_error_handler)(const char *, size_t, const char *, int);
The xmalloc(), xcalloc(), and xrealloc() functions are equivalent to the normal C library functions malloc(), calloc(), and realloc(), except that the memory allocation is checked and is guaranteed to never return NULL (indicating an out of memory condition). Instead, if the underlying memory allocation fails, the xmalloc_error_handler callback is called. By default, this will report an error to standard error and then terminate the program.
Just as with the C library functions, xmalloc() takes the amount of memory to allocate and returns a pointer to the newly-allocated memory. xcalloc() takes a count and an item size and returns enough memory to hold nmemb contiguous objects of size size (in other words, nmemb * size). The memory allocated by xcalloc() will be set to the all-0 bit pattern before it is returned. Finally, xrealloc() expands or shrinks an existing piece of allocated memory pointed to by ptr, changing it to point to size bytes. Any existing data pointed to by ptr that fits within the new memory allocation will be preserved. If ptr is NULL, xrealloc() is equivalent to xmalloc().
xmalloc_error_handler is a global variable that holds a function pointer used as the callback for a memory allocation failure. By default, a callback is set that notifies standard error and exits the program. It calls sysdie(), and therefore follows any message handler settings about where to send the error. See sysdie(3) for more information.
xmalloc_error_handler can be set to some other function of the caller's choice to change the failure behavior. That function will be passed the name of the memory allocation function that failed, the size of the failed allocation, the source file where the allocation call was, and the line number where the allocation call was. The size of the failed authentication will be 0 if the failure was some non-memory-related failure from xasprintf() or xvasprintf(). It does not return anything. If this callback doesn't terminate the program, the memory allocation will be retried after it returns. If you choose to write a handler that doesn't terminate the program (if, for example, there is something that can be done to free up memory), be sure that you don't inadvertently cause an infinite loop of retried, failing memory allocations.
xmalloc(), xcalloc(), and xrealloc() all return a pointer to the newly allocated or resized memory. All three functions are guaranteed to never return NULL, so their return value does not need to be checked.
Changing xmalloc_error_handler is global and not thread-safe. It generally should be set to the desired handler at the start of the program, before any threads are created.
The default xmalloc_error_handler terminates the entire program and is therefore obviously not thread-safe. However, generally memory allocation failure is not an error from which most programs can meaningfully recover. If it is possible to meaningfully recover from a particular memory allocation, such as an attempt to allocate very large amounts of memory with a fallback to some other strategy, one should probably not use xmalloc() and friends for that allocation.
calloc(3), malloc(3), realloc(3), sysdie(3)
Other equivalent wrappers that also use xmalloc_error_handler: xasprintf(3), xstrdup(3), xstrndup(3), xvasprintf(3)
The current version of the rra-c-util library is available from its web page at <https://www.eyrie.org/~eagle/software/rra-c-util/>.
Russ Allbery <eagle@eyrie.org>
Copyright 2012, 2013 The Board of Trustees of the Leland Stanford Junior University
Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.
SPDX-License-Identifier: FSFAP
| Russ Allbery > Software > rra-c-util |