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.