6.1 Out of memory handling

The gnulib API does not have a standard error code for the out of memory error condition. Instead of adding a non-standard error code, gnulib has chosen to adopt a different strategy. Out of memory handling happens in rare situations, but performing the out of memory error handling after almost all API function invocations pollute your source code and might make it harder to spot more serious problems. The strategy chosen improves code readability and robustness.

For most applications, aborting the application with an error message when the out of memory situation occurs is the best that can be wished for. This is how the library behaves by default (using the ‘xalloc-die’ module).

However, we realize that some applications may not want to abort execution in any situation. Gnulib supports a hook to let the application regain control and perform its own cleanups when an out of memory situation has occurred. The application can define a function (having a void prototype, i.e., no return value and no parameters) and set the library variable xalloc_die to that function. The variable should be declared as follows.

extern void (*xalloc_die) (void);

Gnulib will invoke this function if an out of memory error occurs. Note that the function should not return. Of course, care must be taken to not allocate more memory, as that will likely also fail.