Modula-2 || Compiler & Tools || Library || Search Engine

Ulm's Modula-2 Library:
E

NAME

E - formatted error messages

SYNOPSIS

TYPE 
   ExitCode = [-1..255];
   SigSet   = SET OF Sig;



CONST
   UserSignal  = SigSet {SIGHUP, SIGINT, SIGQUIT, SIGTERM};
   FatalSignal = SigSet {SIGILL..SIGUSR2} - SigSet{SIGKILL};



(* diagnostic *)
PROCEDURE done () : BOOLEAN;
PROCEDURE success() : FmtExitCode;



(* error handling *)
PROCEDURE setmode (mode : BITSET);
PROCEDURE getmode (VAR mode : BITSET);



(* output *)
PROCEDURE rror0 (exit : ExitCode; fmt : ARRAY OF CHAR);
PROCEDURE rror1 (exit : ExitCode; fmt : ARRAY OF CHAR;
   i1 : ARRAY OF BYTE);
PROCEDURE rror2 (exit : ExitCode; fmt : ARRAY OF CHAR; 
   i1, i2 : ARRAY OF BYTE);
(* ... *)
PROCEDURE rror8 (exit : ExitCode; fmt : ARRAY OF CHAR;
   i1, i2, i3, i4, i5, i6, i7 , i8 : ARRAY OF BYTE);



(* useful procedures *)
PROCEDURE AddFatalLine(text : ARRAY OF CHAR);
PROCEDURE EnterInitProc(proc : PROC);
PROCEDURE EnterExitProc(proc : PROC);
PROCEDURE ClearInitProc();
PROCEDURE ClearExitProc();
PROCEDURE Signals(set : SigSet; proc : PROC);

DESCRIPTION

E.rror0 .. E.rror8 (the procedures are intended to be called qualified, that explains their strange names) convert their parameters i1 .. i8, instantiate them into the format string fmt, add some information, and output the whole text as an error message to StdIO.stderr. Finally E.rror0 .. E.rror8 will terminate the current process if exit does not equal zero (0).

exit = 0

An error message of the following form is issued, where 'formatted message' is produced from the parameter fmt, i1 .. i8 according to the general formatting capabilities described in Printf.

     [error] formatted message

exit = -1

Having output the error message, E.rror0 .. E.rror8 send SIGIOT to the current process. This is a sure kill and will produce a core dump for program debugging by mdb.

     [panic] formatted message
     [a.out] Panic exit, core dumped. Stop.

exit > 0

Program termination is realized by calling SysExit.Exit using exit as exit code:

     [fatal] formatted message
     [a.out] Exit code 1. Stop.

Each call of AddFatalLine defines a further line of text inserted by E.rror0 .. E.rror8 into a fatal or panic error message. An empty string can be used to clear previously defined text.

Error messages are echoed to further files, if LongStrings.Echo has been called for stderr before.

EnterInitProc defines proc to be called before an error message is issued. Intended for terminal resetting in those cases, the output would otherwise be unreadable (f.i. when using Windows). EnterExitProc works the other way round and defines a procedure that is called after the output of an error message. May be used to restore a terminal device.

ClearInitProc and ClearExitProc delete preceding definitions by EnterInitProc and EnterExitProc.

done returns TRUE if the last call of E.rror0 .. E.rror8 was successful, more detailed information can be obtained by success (FmtExitCode is imported from Printf).

setmode defines a new error handling mode mode which is by default set to Printf.Default. getmode yields the current mode.

Signals defines proc to be called, if one of the signals in set is received. The meaning of the signals suggest their partition into UserSignal (assuming these signals are produced by the user) and FatalSignal, even if these sets may not be suitable for all applications.

DIAGNOSTICS

Diagnostic is unnecessary unless default error handling strategy has been explicitly modified by prior calls of setmode. See Printf for more details.

Please note that program termination depends on a successful output of the error message. Errors may result from illegal format strings or from problems when writing to stderr (error code CannotWriteStderr).

Error message issued by E for diagnostic reasons will indicate the affected procedure call:

[fatal] E.rror3(-1,"%*u",...);
        Bad Format: too few format elements.
[a.out] Exit code 204. Stop.

AUTHOR

Werner Stanglow

Edited by: borchert, last change: 1997/02/25, revision: 1.2, converted to HTML: 1997/04/28