Some functions, like malloc, rarely fail, and it is often
impossible to recover when these functions do fail. When using these
functions, it may be tempting to simply ignore errors. However, if you
do that, it can cause errors to occur elsewhere, making the source of
the error hard to find.
For example, if you call malloc and it returns NULL, then
if you later try to deference that pointer, it will cause a segmentation
fault. A common solution is to write a function, traditionally called
xmalloc, which calls malloc and terminates the program on
failure.
However, it can be a pain to write these functions over and over again, which is why Mu provides them. In addition, the functions provided in Mu report the exact line in your source where the error occurred, which might be able to help you find where your program is using a lot of memory (or where it causes a different type of error to occur).
In addition, Mu provides several convenience functions for error and warning reporting.
The functions described in this chapter are declared in mu/safe.h.
void mu_die (int status, const char *format, …) ¶This function prints a formatted error message, specified by
format, to standard error and exits the program. If status
is negative, mu_die will exit the program by calling abort
(see (libc)Aborting a Program). Otherwise, mu_die will pass
status to exit (see (libc)Normal Termination). status must not be 0.
If the string to be printed, i.e., the expansion of format, ends in a newline (‘\n’), the expanded string will be printed verbatim. Otherwise, if the expanded string does not end in a newline, context information will be prepended to the string when it is printed.
If an error occurred while printing the error message, mu_die
will terminate by calling abort regardless of the value of
status.
int mu_warn (const char *format, …) ¶This function prints a formatted message to standard error in the exact
same way as mu_die specified above, but it returns instead of
calling exit or abort. If mu_warn could
successfully print a message to standard error, mu_warn will
return 0. Otherwise, mu_warn will return a nonzero value.
void mu_vdie (int status, const char *format, va_list ap) ¶int mu_vwarn (const char *format, va_list ap) ¶Like mu_die and mu_warn respectively (see above), except
that these functions take a va_list argument, ap, instead
of variable arguments. See (libc)Variable Arguments Output.
void * mu_xmalloc (size_t size) ¶Returns a pointer to dynamically allocated memory of size
size. The returned pointer must be passed to
free. See (libc)Basic Allocation.
void * mu_xcalloc (size_t count, size_t eltsize) ¶Returns a pointer to dynamically allocated memory of size
count * eltsize. The returned memory is guaranteed to
be initialized to zero, and this function is also guaranteed to fail
safely and reliably in the event that count * eltsize
overflows. The returned pointer must be passed to
free. See (libc)Allocating Cleared Space.
void * mu_xrealloc (void *ptr, size_t newsize) ¶Changes the size of the block whose address is ptr to be newsize. If the return value is not equal to ptr, ptr will be freed. See (libc)Changing Block Size.
void * mu_xreallocarray (void *ptr, size_t count, size_t eltsize) ¶Equivalent to mu_xrealloc(ptr, count * eltsize)
(see above), except that this function will fail safely and reliably in
the event that count * eltsize overflows. This
function is guaranteed to be available even if your system does not
define reallocarray. See (libc)Changing Block Size and
Compatibility Functions.
char * mu_xstrdup (const char *string) ¶Allocates memory large enough to hold a copy of string, and copies
string to the newly allocated memory. string must be
null-terminated. The returned pointer must be passed to
free. See (libc)Copying Strings and Arrays.
char * mu_xstrndup (const char *string, size_t max) ¶Like mu_xstrdup, but only copies max bytes if there was no
null byte in the first max bytes of string. The returned
string will always be terminated with a null byte. See (libc)Truncating
Strings.
unsigned int mu_xasprintf (char **ptr, const char *format, …) ¶Allocates memory large enough to hold the output string, and returns the
allocated string in ptr (which must be passed to
free). Returns the number of characters in *ptr, not
including the terminating null byte. This function is guaranteed to be
available even if your system does not define
asprintf. See (libc)Dynamic Output and Compatibility Functions.
unsigned int mu_xvasprintf (char **ptr, const char *format, va_list ap) ¶Like mu_xasprintf (see above), but takes a va_list
argument, ap, instead of variable arguments. This function is
guaranteed to be available even if your system does not define
vasprintf. See (libc)Variable Arguments Output and
Compatibility Functions.
void mu_xformat (FILE *stream, unsigned short *cursor, unsigned short goal, unsigned short width, unsigned short indent, unsigned short subindent, const char *format, …) ¶char * mu_xformat_string (unsigned short *cursor, unsigned short goal, unsigned short width, unsigned short indent, unsigned short subindent, const char *format, …) ¶void mu_xvformat (FILE *stream, unsigned short *cursor, unsigned short goal, unsigned short width, unsigned short indent, unsigned short subindent, const char *format, va_list ap) ¶char * mu_xvformat_string (unsigned short *cursor, unsigned short goal, unsigned short width, unsigned short indent, unsigned short subindent, const char *format, va_list ap) ¶These functions are like their non-x counterparts, except that
they terminate the program on error. See Formatting Text.
MU_OPT_CONTEXT * mu_opt_context_xnew (int argc, char **argv, const MU_OPT *options, int flags) ¶MU_OPT_CONTEXT * mu_opt_context_xnew_with_env (int argc, char **argv, char **environment const MU_OPT *options, int flags) ¶Create a new option parsing context. See Parsing Options and Environment.
MU_SUBOPT_CONTEXT * mu_subopt_context_xnew (const char *prog_name, const char *suboptstr, const MU_OPT *subopts) ¶Create a new suboption parsing context. See Parsing Suboptions.
void mu_opt_context_xfree (MU_OPT_CONTEXT *context) ¶Free an option parsing context. See Parsing Options and Environment.
void mu_subopt_context_xfree (const MU_SUBOPT_CONTEXT *context) ¶Free a suboption parsing context. See Parsing Suboptions.
void mu_opt_context_xset_no_prefixes (MU_OPT_CONTEXT *context, …) ¶void mu_opt_context_xset_no_prefix_array (MU_OPT_CONTEXT *context, char **no_prefixes) ¶void mu_subopt_context_xset_no_prefixes (MU_SUBOPT_CONTEXT *context, …) ¶void mu_subopt_context_xset_no_prefix_array (MU_SUBOPT_CONTEXT *context, char **no_prefixes) ¶Set alternative negation prefixes for option and suboption parsing contexts. See Negation Prefixes.
void mu_opt_context_xadd_options (MU_OPT_CONTEXT *context, const MU_OPT *options, enum MU_OPT_WHERE where) ¶Add options to context, either at the beginning or end based on where. See Parsing Options and Environment.
void mu_opt_context_xadd_help_options (MU_OPT_CONTEXT *context, int flags) ¶Add help options to context based on flags. See Formatting Help.
void mu_xformat_help (FILE *stream, const MU_OPT_CONTEXT *context) ¶void mu_xformat_help_man (FILE *stream, const MU_OPT_CONTEXT *context) ¶Format a help message from context, printing it to stream. See Formatting Help.
char * mu_xformat_help_string (const MU_OPT_CONTEXT *context, unsigned short goal, unsigned short width) ¶char * mu_xformat_help_man_string (const MU_OPT_CONTEXT *context) ¶Format a help message from context, returning it as a dynamically allocated string. See Formatting Help.