Title: Explanation of error handling in MDIO Author: David Hardy 3-4 levels of errors, depending on how you compile: 1. Warnings: these set a "warning-level" status value and illicit a message to stderr. These are used for conditions that are unexpected, but might not necessarily be errors. Makes call to mdio_warn(). Examples: unknown token found in file (file formats are ambiguous), comment terminated abnormally by end of file, line is truncated because it is too long. 2. Errors: these set an "error-level" status value and illicit a message to stderr. These are used for conditions that are recoverable runtime errors that need to be corrected and are not necessarily the fault of the program that is making MDIO library calls. Makes call to mdio_error(). Examples: illegal file format, can't read from or write to file, can't allocate memory. 3. Fatal errors: these terminate the program after an unrecoverable runtime error in MDIO. Should be used sparingly. Due primarily to misuse of MDIO calls from calling program. Used to aid a program in debugging its use of the MDIO library? Makes call to mdio_fatal(). Examples: ??? 4. Failed assertions: these terminate the program due to not meeting some invariant or condition in the MDIO code. Expands as a macro so that it can be removed when compiling the production version of the library. Test call to MDIO_ASSERT(bool_expr) and expands to a conditional only if MDIO_DEBUG is #defined. Used for debugging the MDIO library. Functions and macros: int mdio_warn(const char *, ...); /* works like printf(), except to stderr */ int mdio_error(const char *, ...); void mdio_fatal(const char *, ...); /* terminates program using exit() */ #define MDIO_ASSERT(bool_expr) /* terminates program if bool_expr fails */ const char *mdio_errmsg(int); /* returns string describing status */ Here are the warning- and error-levels: #define MDIO_WARN_UNKNOWN 1 #define MDIO_WARN_COMMENT 2 #define MDIO_WARN_TRUNC 4 #define MDIO_ERR_LEVEL 1024 /* unused, test whether warning or error */ #define MDIO_ERR_FORMAT 2048 #define MDIO_ERR_MEMALLOC 4096 #define MDIO_ERR_READ 8192 #define MDIO_ERR_WRITE 16384 (and possibly others, maybe particular to param database?) - These correspond to bit positions in the status flag. Can test explicitly against particular errors by logical ANDing. Might have more than one warning or error set at once. - All warnings are below MDIO_ERR_LEVEL (bit positions 0-9) and errors are above MDIO_ERR_LEVEL (bit positions 11-30). Bit position 31 (the sign bit) is unused so that type int can be used for status flag. - Function(s) should be provided to check and clear the error status. - Error handling should make every effort to indicate source file name (__FILE__) and line number (__LINE__) that exception took place.