.\" (C) 2002 Ian Gulliver
.TH firestring_set_error_handler 3 2003-07-21
.SH NAME
firestring_set_error_handler \-
set the function to be called on an allocation failure
.SH SYNOPSIS
.B #include <firestring.h>
.br
.B -lfirestring
.LP
.BI "void firestring_set_error_handler(void (*" "e" ")())"
.SH DESCRIPTION
firestring_set_error_handler() takes the name of a function
that takes no parameters and returns void.  This function will
be called whenever firestring fails to allocate memory.

As memory allocation failures are fatal to most programs, firestring
does not return errors when functions fail to allocate memory; it
simply calls this function, which it expects to call
.I exit()
or
.I abort()
or in some way terminate execution of the program.  It probably is
not safe to pass a function that returns, unless you have a framework
in place for passing the allocation failure information back to the
code calling the firestring function.

The default function calls
.I perror()
and then
.IR exit().
.SH RETURN VALUE
None
.SH AUTHOR
Ian Gulliver <ian@penguinhosting.net>
.SH SEE ALSO
.BR libfirestring (3)