A basic system for command-line tool error messages.

• §1. Errors handler
• §2. Error messages
• §4. Deliberately crashing
• §5. Survivable errors

§1. Errors handler. The user can provide a routine to deal with error messages before they're issued. If this returns FALSE, nothing is printed to stderr.

int (*errors_handler)(text_stream *, int) = NULL;
void (*internal_errors_handler)(void *, char *, char *, int) = NULL;

void Errors::set_handler(int (*f)(text_stream *, int)) {
    errors_handler = f;
}
void Errors::set_internal_handler(void (*f)(void *, char *, char *, int)) {
    internal_errors_handler = f;
}

int problem_count = 0;
int Errors::have_occurred?Usage of Errors::have_occurred:
Streams - §37(void) {
    if (problem_count > 0) return TRUE;
    return FALSE;
}

void Errors::issue?Usage of Errors::issue:
§2, §6, §7(text_stream *message, int fatality) {
    STREAM_FLUSH(STDOUT);
    int rv = TRUE;
    if (errors_handler) rv = (*errors_handler)(message, fatality);
    if (rv) WRITE_TO(STDERR, "%S", message);
    STREAM_FLUSH(STDERR);
    if (fatality) Errors::die(); else problem_count++;
}

§2. Error messages. Ah, they kill you; or they don't. The fatal kind cause an exit code of 2, to distinguish this from a proper completion in which non-fatal errors occur. These two routines (alone) can be caused by failures of the memory allocation or streams systems, and therefore must be written with a little care to use the temporary stream, not some other string which might need fresh allocation.

void Errors::fatal?Usage of Errors::fatal:
Memory - §11.1, §15, §16.1
Locales - §2, §5
Streams - §32, §34.1, §35.3
Command Line Arguments - §8
C Strings - §3
Binary Files - §9
Build Files - §7(char *message) {
    TEMPORARY_TEXT(ERM)
    WRITE_TO(ERM, "%s: fatal error: %s\n", PROGRAM_NAME, message);
    Errors::issue(ERM, TRUE);
    DISCARD_TEXT(ERM)
}

void Errors::fatal_with_C_string?Usage of Errors::fatal_with_C_string:
§3
Memory - §25.1(char *message, char *parameter) {
    TEMPORARY_TEXT(ERM)
    WRITE_TO(ERM, "%s: fatal error: ", PROGRAM_NAME);
    WRITE_TO(ERM, message, parameter);
    WRITE_TO(ERM, "\n");
    Errors::issue(ERM, TRUE);
    DISCARD_TEXT(ERM)
}

void Errors::fatal_with_text?Usage of Errors::fatal_with_text:
Command Line Arguments - §8, §11, §13
Bibliographic Data for Webs - §5
Build Files - §6
Programming Languages - §2, §2.2(char *message, text_stream *parameter) {
    TEMPORARY_TEXT(ERM)
    WRITE_TO(ERM, "%s: fatal error: ", PROGRAM_NAME);
    WRITE_TO(ERM, message, parameter);
    WRITE_TO(ERM, "\n");
    Errors::issue(ERM, TRUE);
    DISCARD_TEXT(ERM)
}

void Errors::fatal_with_file?Usage of Errors::fatal_with_file:
Text Files - §5.1, §5.2, §5.3.2
Preprocessor - §1
Epub Ebooks - §6.1, §6.2, §6.3, §7.2, §7.3
Binary Files - §7, §8, §9, §11
Build Files - §4(char *message, filename *F) {
    TEMPORARY_TEXT(ERM)
    WRITE_TO(ERM, "%s: fatal error: %s: %f\n", PROGRAM_NAME, message, F);
    Errors::issue(ERM, TRUE);
    DISCARD_TEXT(ERM)
}

void Errors::fatal_with_path(char *message, pathname *P) {
    TEMPORARY_TEXT(ERM)
    WRITE_TO(ERM, "%s: fatal error: %s: %p\n", PROGRAM_NAME, message, P);
    Errors::issue(ERM, TRUE);
    DISCARD_TEXT(ERM)
}

§3. Assertion failures lead to the following. Note the use of the C11 syntax _Noreturn; this seems now to be well-supported on modern C compilers, though. (It needs to be on its own line to avoid hassle with InC, which has no special support for C annotations.)

define internal_error(message) Errors::internal_error_handler(NULL, message, __FILE__, __LINE__)

_Noreturn
void Errors::internal_error_handler(void *p, char *message, char *f, int lc) {
    if (internal_errors_handler)
        (*internal_errors_handler)(p, message, f, lc);
    else
        Errors::fatal_with_C_string("internal error (%s)", message);
    exit(1);  redundant but needed to remove compiler warning in clang
}

§4. Deliberately crashing. It's sometimes convenient to get a backtrace from the debugger when an error occurs unexpectedly, and one way to do that is to force a division by zero. (This is only enabled by -crash at the command line and is for debugging only.)

int debugger_mode = FALSE;
void Errors::enter_debugger_mode?Usage of Errors::enter_debugger_mode:
Command Line Arguments - §13.1(void) {
    debugger_mode = TRUE;
    printf("(Debugger mode enabled: will crash on fatal errors)\n");
}

void Errors::die?Usage of Errors::die:
§1(void) {  as void as it gets
    if (DL) STREAM_FLUSH(DL);
    if (debugger_mode) {
        WRITE_TO(STDERR, "(crashing intentionally to allow backtrace)\n");
        __builtin_trap();  both a gcc and clang extension to C, so fairly standard
    }
     on a fatal exit, memory isn't freed, because that causes threading problems
    exit(2);
}

§5. Survivable errors. The trick with error messages is to indicate where they occur, and we can specify this at three levels of abstraction:

void Errors::nowhere?Usage of Errors::nowhere:
Epub Ebooks - §7.2.2.3(char *message) {
    Errors::in_text_file(message, NULL);
}

void Errors::in_text_file?Usage of Errors::in_text_file:
Command Line Arguments - §11
Preprocessor - §3.2, §3.3.1, §3.3.2, §3.3.4, §4, §4.1.3.1.1, §4.1.3.1.3, §11, §11.2, §12, §16, §18
Build Files - §3
Programming Languages - §8.1, §8.2, §13.1, §13.2, §14, §15, §16, §17, §18(char *message, text_file_position *here) {
    if (here)
        Errors::at_position(message, here->text_file_filename, here->line_count);
    else
        Errors::at_position(message, NULL, 0);
}

void Errors::in_text_file_S?Usage of Errors::in_text_file_S:
Preprocessor - §4.1, §4.1.2.1, §4.1.3.1.1, §4.1.3.1.2
JSON - §37, §38
Web Structure - §7.3.2, §7.3.2.1, §7.3.3.2
Programming Languages - §17(text_stream *message, text_file_position *here) {
    if (here)
        Errors::at_position_S(message, here->text_file_filename, here->line_count);
    else
        Errors::at_position_S(message, NULL, 0);
}

§6. Which funnel through:

void Errors::at_position?Usage of Errors::at_position:
§5(char *message, filename *file, int line) {
    TEMPORARY_TEXT(ERM)
    WRITE_TO(ERM, "%s: ", PROGRAM_NAME);
    if (file) WRITE_TO(ERM, "%f, line %d: ", file, line);
    WRITE_TO(ERM, "%s\n", message);
    Errors::issue(ERM, FALSE);
    DISCARD_TEXT(ERM)
}

void Errors::at_position_S?Usage of Errors::at_position_S:
§5(text_stream *message, filename *file, int line) {
    TEMPORARY_TEXT(ERM)
    WRITE_TO(ERM, "%s: ", PROGRAM_NAME);
    if (file) WRITE_TO(ERM, "%f, line %d: ", file, line);
    WRITE_TO(ERM, "%S\n", message);
    Errors::issue(ERM, FALSE);
    DISCARD_TEXT(ERM)
}

§7. Lastly:

void Errors::with_file?Usage of Errors::with_file:
Text Files - §5.1, §5.2, §5.3.2(char *message, filename *F) {
    TEMPORARY_TEXT(ERM)
    WRITE_TO(ERM, "%s: %f: %s\n", PROGRAM_NAME, F, message);
    Errors::issue(ERM, FALSE);
    DISCARD_TEXT(ERM)
}

void Errors::with_text?Usage of Errors::with_text:
Build Files - §9(char *message, text_stream *T) {
    TEMPORARY_TEXT(ERM)
    WRITE_TO(ERM, "%s: ", PROGRAM_NAME);
    WRITE_TO(ERM, message, T);
    WRITE_TO(ERM, "\n");
    Errors::issue(ERM, FALSE);
    DISCARD_TEXT(ERM)
}