3.6 Error Reporting

Most of the error reporting by other functions in the library is done by way of the functions declared in ‘error.h’. These function communicate directly with the user through standard error. Client programs should also use these functions where possible for the sake of a uniform interface.

Function: void avm_set_program_name (char *argv0)

The argument to this function should be the address of a null terminated string holding the name of the program to be reported in error messages that begin with a program name. Typically this string will be the name of the program as it was invoked on the command line, possibly with path components stripped from it. An alternative would be to set it to the name of a virtual code application being evaluated. If this function is never called, the name "avram" is used by default. Space for a copy of the program name is allocated by this function, and a fatal memory overflow error is possible if there is insufficient space available.

Function: char* avm_program_name ()

This function returns a pointer to a null terminated character string holding the program name presently in use. It will be either the name most recently set by avm_set_program_name, or the default name "avram" if none has been set. The string whose address is returned should not be modified by the caller.

Function: void avm_warning (char *message)

This function writes the null terminated string whose address is given to standard error, prefaced by the program name and followed by a line break.

Function: void avm_error (char *message)

This function writes the null terminated string whose address is given to standard error, prefaced by the program name and followed by a line break, as avm_warning, but it then terminates the process with an exit code of 1.

Function: void avm_fatal_io_error (char *message, char *filename, int reason)

This function is useful for reporting errors caused in the course of reading or writing files. The message is written to standard error prefaced by the program name, and incorporating the name of the relevant file. The reason should be the error code obtained from the standard errno variable, which will be translated to an informative message if possible by the standard strerror function and appended to the message. After the message is written, the process will terminate with an exit code of 1.

Function: void avm_non_fatal_io_error (char *message, char *filename, int reason)

This function does the same as avm_fatal_io_error except that it doesn’t exit the program, and allows control to return to the caller, which should take appropriate action.

Function: void avm_internal_error (int code)

This function is used to report internal errors and halt the program. The error message is written to standard error prefaced by the program name and followed by a line break. The code should be a unique integer constant (i.e., not one that’s used for any other internal error), that will be printed as part of the error message as an aid to the maintainer.

This function should be used by client programs only in the event of conditions that constitute some violation of a required invariant. It indicates to the user that something has gone wrong with the program, for which a bug report would be appropriate.

Function: void avm_reclamation_failure (char *entity, counter count)

This function is used only by the avm_count functions to report unreclaimed storage. The count is the number of units of storage left unreclaimed, and the entity is the address of a null terminated string describing the type of unreclaimed entity, such as "lists" or "branches". The message is written to standard error followed by a line break, but the program is not halted and control returns to the caller.

This document was generated on November 8, 2012 using texi2html 1.82.