error.hh

Click is a modular router toolkit. To use it you ll need to know how to compile and install the sof

// -*- related-file-name: "../../lib/error.cc" -*-
#ifndef CLICK_ERROR_HH
#define CLICK_ERROR_HH
#include <click/string.hh>
#if defined(CLICK_USERLEVEL) || defined(CLICK_TOOL)
# include <stdio.h>
#endif
#include <stdarg.h>
#if HAVE_ADDRESSABLE_VA_LIST
# define VA_LIST_REF_T		va_list *
# define VA_LIST_DEREF(val)	(*(val))
# define VA_LIST_REF(val)	(&(val))
#else
# define VA_LIST_REF_T		va_list
# define VA_LIST_DEREF(val)	(val)
# define VA_LIST_REF(val)	(val)
#endif
#if __GNUC__ <= 3
# define ERRH_SENTINEL
#else
# define ERRH_SENTINEL __attribute__((sentinel))
#endif
CLICK_DECLS

/** @class ErrorHandler
 * @brief Error reporting class.
 *
 * Click elements report errors through ErrorHandler objects, which represent
 * error collectors and printers.  ErrorHandlers are passed to configure() and
 * initialize() methods explicitly, as well as to write handlers; the
 * click_chatter() function calls ErrorHandler implicitly.
 *
 * <h3>Cooked error messages</h3>
 *
 * Most ErrorHandler interactions consist of a simple call like this:
 * @code
 * errh->error("not enough arguments (%d needed)", 5);
 *     // prints something like "not enough arguments (5 needed)\n"
 * @endcode
 *
 * This function constructs an error message string from the format arguments,
 * annotates the string with a default error level (here, el_error), and
 * prints it.  Alternate versions take a landmark specifying where the error
 * took place:
 * @code
 * errh->lwarning("file.click:2", "syntax error at '%s'", word.c_str());
 *     // prints something like "file.click:2: syntax error at 'foo'\n"
 * @endcode
 *
 * <h3>Raw error messages</h3>
 *
 * For finer control over error levels and annotations, construct an error
 * message string directly.  An error message is a string consisting of one or
 * more lines.  Each line begins with a set of optional textual @em
 * annotations.  The following error message has a @em level annotation
 * determining how serious the error is (this one is critical, since
 * el_critical == 2), and a @em landmark annotation, which specifies where the
 * error took place (here, "x.click:1"):
 *
 * <tt>"<2>{l:x.click:1}syntax error"</tt>
 *
 * Click's default ErrorHandlers understand the level and landmark
 * annotations.  Users can add other arbitrary annotations, which can be
 * useful to pass error metadata.  A pair of braces ends the annotation area.
 * This example has one user annotation <tt>eoc</tt>, and a message area that
 * would be mistaken for an annotation were it not for the <tt>{}</tt>:
 *
 * <tt>"<2>{l:x.click:1}{eoc:520}{}{not:an annotation}"</tt>
 *
 * <h3>Stacking handlers</h3>
 *
 * Some ErrorHandlers stack on top of others, adding useful functionality like
 * automatic context description and prefixing.  For example,
 * ContextErrorHandler can be used to print messages like "In function
 * 'xxx':".
 * @code
 * FileErrorHandler errh1(stderr);
 * ContextErrorHandler errh2(&errh1, "While counting to 2:");
 * errh2.error("An error occurred.");
 * errh2.error("Another error occurred.");
 *     // prints "While counting to 2:\n"
 *     //        "  An error occurred.\n"
 *     //        "  Another error occurred.\n"
 * @endcode */
class ErrorHandler { public:

    /** @brief Error level constants.
     *
     * Lower values represent more serious errors.  Levels 0-7 correspond to
     * Linux's error levels.  Negative levels request immediate exit; at user
     * level, the Click process's exit status is the absolute value of the
     * error level. */
    enum Level {
	el_abort = -999,	///< Error level that triggers abort().
	el_fatal = -1,		///< Fatal exit error level.
				///  Exit status equals -(level).
	el_emergency = 0,	///< Emergency error level: system is unusable.
	el_alert = 1,		///< Alert error level: action must be taken.
	el_critical = 2,	///< Error level for critical conditions.
	el_error = 3,		///< Error level for normal error conditions.
	el_warning = 4,		///< Error level for warning conditions.
	el_notice = 5,		///< Error level for normal, but significant
				///  conditions.
	el_info = 6,		///< Error level for informational messages.
	el_debug = 7		///< Error level for debug messages.
    };

    /** @brief Error level indicators. */
    static const char e_abort[],
	e_fatal[],
	e_emergency[],
	e_alert[],
	e_critical[],
	e_error[],
	e_warning[],
	e_warning_annotated[],
	e_notice[],
	e_info[],
	e_debug[];

    /** @brief Construct an ErrorHandler. */
    ErrorHandler()
	: _nerrors(0), _nwarnings(0) {
    }

    virtual ~ErrorHandler() {
    }


    /** @brief Initialize the ErrorHandler implementation.
     * @param errh default error handler
     * @return @a errh
     *
     * Call this function to initialize the ErrorHandler implementation.  The
     * function installs the default conversions, creates the
     * silent_handler(), and installs @a errh as the default error handler
     * (see default_handler()).
     *
     * @note The @a errh object becomes the property of the ErrorHandler
     * implementation and must not be deleted.
     * (ErrorHandler::static_cleanup() will delete it.)  Only the first call
     * to static_initialize() has any effect. */
    static ErrorHandler *static_initialize(ErrorHandler *errh);

    /** @brief Tear down the ErrorHandler implementation.
     *
     * Deletes the internal ErrorHandlers and uninstalls default
     * conversions. */
    static void static_cleanup();


    /** @brief Return the default ErrorHandler.
     * @sa static_initialize() */
    static ErrorHandler *default_handler() {
	return the_default_handler;
    }

    /** @brief Set the default ErrorHandler to @a errh.
     * @note @a errh becomes property of the ErrorHandler implementation,
     * and will be freed by static_cleanup().  However, any prior default
     * handler is @em not destroyed.  Callers should delete the prior handler
     * when necessary. */
    static void set_default_handler(ErrorHandler *errh);

    /** @brief Return the global silent ErrorHandler. */
    static ErrorHandler *silent_handler() {
	return the_silent_handler;
    }


    static const int ok_result;		///< Equals 0, used for error levels
					///  <5> and above
    static const int error_result;	///< Equals -EINVAL, used for error
					///  levels <4> and below


    /** @brief Print a debug message (level el_debug).
     *
     * @a fmt and any following arguments are parsed as by format(), and the
     * resulting string is passed to xmessage(). */
    void debug(const char *fmt, ...);
    /** @brief Print an informational message (level el_info). */
    void message(const char *fmt, ...);
    /** @brief Print a warning message (level el_warning).
     * @return error_result
     *
     * The string "warning: " is prepended to every line of the message. */
    int warning(const char *fmt, ...);
    /** @brief Print an error message (level el_error).
     * @return error_result */
    int error(const char *fmt, ...);
    /** @brief Print a fatal error message (level el_fatal).
     * @return error_result
     *
     * In many ErrorHandlers, calling fatal() will cause Click to abort. */
    int fatal(const char *fmt, ...);

    /** @brief Print a debug message with a landmark annotation. */
    void ldebug(const String &landmark, const char *fmt, ...);
    /** @brief Print an informational message with a landmark annotation. */
    void lmessage(const String &landmark, const char *fmt, ...);
    /** @brief Print a warning message with a landmark annotation. */
    int lwarning(const String &landmark, const char *fmt, ...);
    /** @brief Print an error message with a landmark annotation. */
    int lerror(const String &landmark, const char *fmt, ...);
    /** @brief Print a fatal error message with a landmark annotation. */
    int lfatal(const String &landmark, const char *fmt, ...);


    /** @brief Print an annotated error message.
     * @return ok_result if the minimum error level was el_notice or higher,
     * otherwise error_result
     *
     * This function drives the virtual functions actually responsible for
     * error message decoration and printing.  It passes @a str to decorate(),
     * separates the result into lines, calls emit() for each line, and calls
     * account() with the minimum error level of any line.
     *
     * Most users will call shorthand functions like error(), warning(), or
     * lmessage(), which add relevant annotations to the message. */
    int xmessage(const String &str);
    /** @brief Print an error message, adding annotations.
     * @param anno annotations
     * @param str error message
     *
     * Shorthand for xmessage(combine_anno(@a str, @a anno)). */
    int xmessage(const String &anno, const String &str) {
	return xmessage(combine_anno(str, anno));
    }
    /** @brief Format and print an error message, adding annotations.
     * @param anno annotations
     * @param fmt error message format
     * @param val format arguments
     *
     * Shorthand for xmessage(@a anno, vformat(@a fmt, @a val)). */
    int xmessage(const String &anno, const char *fmt, va_list val) {
	return xmessage(anno, vformat(fmt, val));
    }
    /** @brief Print an error message, adding landmark and other annotations.
     * @param landmark landmark annotation
     * @param anno additional annotations
     * @param str error message
     *
     * Shorthand for xmessage(combine_anno(@a anno, make_landmark_anno(@a
     * landmark)), @a str). */
    int xmessage(const String &landmark, const String &anno,
		 const String &str) {
	return xmessage(combine_anno(anno, make_landmark_anno(landmark)), str);
    }
    /** @brief Format and print an error message, adding landmark and other
     * annotations.
     * @param landmark landmark annotation
     * @param anno additional annotations
     * @param fmt error message format
     * @param val format arguments
     *
     * Shorthand for xmessage(@a landmark, @a anno, vformat(@a fmt, @a
     * val)). */
    int xmessage(const String &landmark, const String &anno,
		 const char *fmt, va_list val) {
	return xmessage(landmark, anno, vformat(fmt, val));
    }


    /** @brief Return the number of errors reported via this handler.
     *
     * An error is any message that contains at least one line with error
     * level 3 (#el_error) or below.
     *
     * @note The error count will also contain errors reported via stacked
     * handlers.  For instance:
     * @code
     * SilentErrorHandler errh1;
     * PrefixErrorHandler errh2(&errh1, "");
     * assert(errh1.nerrors() == 0);
     * errh2.error("blah");
     * assert(errh1.nerrors() == 1);
     * @endcode
     *
     * @sa nwarnings, reset_counts */
    int nerrors() const {
	return _nerrors;
    }

    /** @brief Return the number of warnings reported via this handler.
     *
     * A warning is any message that contains at least one line with error
     * level 4 (#el_warning), and no line with a lower level. */
    int nwarnings() const {
	return _nwarnings;
    }

    /** @brief Reset the nwarnings() and nerrors() counts to zero. */
    void reset_counts() {
	_nwarnings = _nerrors = 0;
    }