ErrorHandler Class Reference

Error reporting class. More...

#include <error.hh>

Inheritance diagram for ErrorHandler:

Public Types
enum	Level {   el_abort = -999 , el_fatal = -1 , el_emergency = 0 , el_alert = 1 ,   el_critical = 2 , el_error = 3 , el_warning = 4 , el_notice = 5 ,   el_info = 6 , el_debug = 7 }
	Error level constants. More...
enum	ConversionFlags {   cf_zero_pad = 1 , cf_plus_positive = 2 , cf_space_positive = 4 , cf_left_just = 8 ,   cf_alternate_form = 16 , cf_singlequote = 32 , cf_uppercase = 64 , cf_signed = 128 ,   cf_negative = 256 , cf_utf8 = 1024 }
typedef String(*	ConversionFunction) (int flags, VA_LIST_REF_T)

Public Member Functions
	ErrorHandler ()
	Construct an ErrorHandler.
void	debug (const char *fmt,...)
	Print a debug message (level el_debug).
void	message (const char *fmt,...)
	Print an informational message (level el_info).
int	warning (const char *fmt,...)
	Print a warning message (level el_warning).
int	error (const char *fmt,...)
	Print an error message (level el_error).
int	fatal (const char *fmt,...)
	Print a fatal error message (level el_fatal).
void	ldebug (const String &landmark, const char *fmt,...)
	Print a debug message with a landmark annotation.
void	lmessage (const String &landmark, const char *fmt,...)
	Print an informational message with a landmark annotation.
int	lwarning (const String &landmark, const char *fmt,...)
	Print a warning message with a landmark annotation.
int	lerror (const String &landmark, const char *fmt,...)
	Print an error message with a landmark annotation.
int	lfatal (const String &landmark, const char *fmt,...)
	Print a fatal error message with a landmark annotation.
int	xmessage (const String &str)
	Print an annotated error message.
int	xmessage (const String &anno, const String &str)
	Print an error message, adding annotations.
int	xmessage (const String &anno, const char *fmt, va_list val)
	Format and print an error message, adding annotations.
int	xmessage (const String &landmark, const String &anno, const String &str)
	Print an error message, adding landmark and other annotations.
int	xmessage (const String &landmark, const String &anno, const char *fmt, va_list val)
	Format and print an error message, adding landmark and other annotations.
int	nerrors () const
	Return the number of errors reported via this handler.
virtual String	vformat (const char *fmt, va_list val)
	Format an error string.
String	format (const char *fmt,...)
	Format an error string.
virtual String	decorate (const String &str)
	Decorate an error message.
virtual void *	emit (const String &str, void *user_data, bool more)
	Output an error message line.
virtual void	account (int level)
	Account for an error message at level level.
virtual void	clear ()
	Clear accumulated error state.

Static Public Member Functions
static ErrorHandler *	static_initialize (ErrorHandler *errh)
	Initialize the ErrorHandler implementation.
static void	static_cleanup ()
	Tear down the ErrorHandler implementation.
static ErrorHandler *	default_handler ()
	Return the default ErrorHandler.
static void	set_default_handler (ErrorHandler *errh)
	Set the default ErrorHandler to errh.
static ErrorHandler *	silent_handler ()
	Return the global silent ErrorHandler.
static String	xformat (int default_flags, const char *fmt,...)
	Format an error string.
static String	vxformat (int default_flags, const char *fmt, va_list val)
static String	xformat (const char *fmt,...)
static String	vxformat (const char *fmt, va_list val)
static String	make_anno (const char *name, const String &value)
	Create an error annotation.
static String	combine_anno (const String &str, const String &anno)
	Apply annotations from anno to every line in str.
static const char *	parse_anno (const String &str, const char *begin, const char *end,...) ERRH_SENTINEL
	Parse error annotations from a string.
static const char *	skip_anno (const char *begin, const char *end)
	Skip a string's error annotations.
static String	make_landmark_anno (const String &x)
	Return a landmark annotation equal to x.
static String	clean_landmark (const String &landmark, bool colon=false)
	Clean the landmark.
static Conversion *	add_conversion (const String &name, ConversionFunction func)
static int	remove_conversion (Conversion *conversion)

Static Public Attributes
static const char	e_abort [] = "<-999>"
	Error level indicators.
static const char	e_fatal [] = "<-1>"
static const char	e_emergency [] = "<0>"
static const char	e_alert [] = "<1>"
static const char	e_critical [] = "<2>"
static const char	e_error [] = "<3>"
static const char	e_warning [] = "<4>"
static const char	e_warning_annotated [] = "<4>warning: "
static const char	e_notice [] = "<5>"
static const char	e_info [] = "<6>"
static const char	e_debug [] = "<7>"
static const int	ok_result = 0
static const int	error_result = -EINVAL

Detailed Description

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.

Cooked error messages

Most ErrorHandler interactions consist of a simple call like this:

errh->error("not enough arguments (%d needed)", 5);
    // prints something like "not enough arguments (5 needed)\n"

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:

errh->lwarning("file.click:2", "syntax error at '%s'", word.c_str());
    // prints something like "file.click:2: syntax error at 'foo'\n"

Raw error messages

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 annotations. The following error message has a level annotation determining how serious the error is (this one is critical, since el_critical == 2), and a landmark annotation, which specifies where the error took place (here, "x.click:1"):

"<2>{l:x.click:1}syntax error"

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 eoc, and a message area that would be mistaken for an annotation were it not for the {}:

"<2>{l:x.click:1}{eoc:520}{}{not:an annotation}"

Stacking handlers

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':".

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"

Member Enumeration Documentation

Level

enum ErrorHandler::Level

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.

Enumerator
el_abort	Error level that triggers abort().
el_fatal	Fatal exit error level. Exit status equals -(level).
el_emergency	Emergency error level: system is unusable.
el_alert	Alert error level: action must be taken.
el_critical	Error level for critical conditions.
el_error	Error level for normal error conditions.
el_warning	Error level for warning conditions.
el_notice	Error level for normal, but significant conditions.
el_info	Error level for informational messages.
el_debug	Error level for debug messages.

ConversionFlags

enum ErrorHandler::ConversionFlags

Enumerator
cf_zero_pad	Set for conversions using the '0' flag.
cf_plus_positive	Set for conversions using the '+' flag.
cf_space_positive	Set for conversions using the ' ' flag.
cf_left_just	Set for conversions using the '-' flag.
cf_alternate_form	Set for conversions using the '#' flag.
cf_singlequote	Set for conversions using the '\'' flag.
cf_uppercase	Set for 'X' conversions (not 'x').
cf_signed	Set for conversions of signed numbers.
cf_negative	Set for conversions of negative numbers.
cf_utf8	Set to use UTF-8 characters on output.

Constructor & Destructor Documentation

ErrorHandler()

ErrorHandler::ErrorHandler ( )

inline

Construct an ErrorHandler.

Member Function Documentation

static_initialize()

ErrorHandler * ErrorHandler::static_initialize ( ErrorHandler *  errh )

static

Initialize the ErrorHandler implementation.

Parameters

errh	default error handler

Returns

errh

Call this function to initialize the ErrorHandler implementation. The function installs the default conversions, creates the silent_handler(), and installs errh as the default error handler (see default_handler()).

Note

The 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_cleanup()

void ErrorHandler::static_cleanup ( )

static

Tear down the ErrorHandler implementation.

Deletes the internal ErrorHandlers and uninstalls default conversions.

default_handler()

static ErrorHandler * ErrorHandler::default_handler ( )

inlinestatic

Return the default ErrorHandler.

See also

static_initialize()

set_default_handler()

void ErrorHandler::set_default_handler ( ErrorHandler *  errh )

static

Set the default ErrorHandler to errh.

Note

errh becomes property of the ErrorHandler implementation, and will be freed by static_cleanup(). However, any prior default handler is not destroyed. Callers should delete the prior handler when necessary.

silent_handler()

static ErrorHandler * ErrorHandler::silent_handler ( )

inlinestatic

Return the global silent ErrorHandler.

debug()

void ErrorHandler::debug	(	const char *	fmt,
			...
	)

Print a debug message (level el_debug).

fmt and any following arguments are parsed as by format(), and the resulting string is passed to xmessage().

message()

void ErrorHandler::message	(	const char *	fmt,
			...
	)

Print an informational message (level el_info).

warning()

int ErrorHandler::warning	(	const char *	fmt,
			...
	)

Print a warning message (level el_warning).

Returns

error_result

The string "warning: " is prepended to every line of the message.

error()

int ErrorHandler::error	(	const char *	fmt,
			...
	)

Print an error message (level el_error).

Returns

error_result

fatal()

int ErrorHandler::fatal	(	const char *	fmt,
			...
	)

Print a fatal error message (level el_fatal).

Returns

error_result

In many ErrorHandlers, calling fatal() will cause Click to abort.

ldebug()

void ErrorHandler::ldebug	(	const String &	landmark,
		const char *	fmt,
			...
	)

Print a debug message with a landmark annotation.

lmessage()

void ErrorHandler::lmessage	(	const String &	landmark,
		const char *	fmt,
			...
	)

Print an informational message with a landmark annotation.

lwarning()

int ErrorHandler::lwarning	(	const String &	landmark,
		const char *	fmt,
			...
	)

Print a warning message with a landmark annotation.

lerror()

int ErrorHandler::lerror	(	const String &	landmark,
		const char *	fmt,
			...
	)

Print an error message with a landmark annotation.

lfatal()

int ErrorHandler::lfatal	(	const String &	landmark,
		const char *	fmt,
			...
	)

Print a fatal error message with a landmark annotation.

xmessage() [1/5]

int ErrorHandler::xmessage

(

const String &

str

)

Print an annotated error message.

Returns

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 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.

xmessage() [2/5]

int ErrorHandler::xmessage ( const String &  anno, const String &  str  )

inline

Print an error message, adding annotations.

Parameters

anno	annotations
str	error message

Shorthand for xmessage(combine_anno(str, anno)).

xmessage() [3/5]

int ErrorHandler::xmessage ( const String &  anno, const char *  fmt, va_list  val  )

inline

Format and print an error message, adding annotations.

Parameters

anno	annotations
fmt	error message format
val	format arguments

Shorthand for xmessage(anno, vformat(fmt, val)).

xmessage() [4/5]

int ErrorHandler::xmessage ( const String &  landmark, const String &  anno, const String &  str  )

inline

Print an error message, adding landmark and other annotations.

Parameters

landmark	landmark annotation
anno	additional annotations
str	error message

Shorthand for xmessage(combine_anno(anno, make_landmark_anno(landmark)), str).

xmessage() [5/5]

int ErrorHandler::xmessage ( const String &  landmark, const String &  anno, const char *  fmt, va_list  val  )

inline

Format and print an error message, adding landmark and other annotations.

Parameters

landmark	landmark annotation
anno	additional annotations
fmt	error message format
val	format arguments

Shorthand for xmessage(landmark, anno, vformat(fmt, val)).

nerrors()

int ErrorHandler::nerrors ( ) const

inline

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:

SilentErrorHandler errh1;
PrefixErrorHandler errh2(&errh1, "");
assert(errh1.nerrors() == 0);
errh2.error("blah");
assert(errh1.nerrors() == 1);

See also

account, clear

xformat() [1/2]

String ErrorHandler::xformat ( int  default_flags, const char *  fmt,   ...  )

static

Format an error string.

Parameters

default_flags	default ConversionFlags
fmt	printf-like format string

Returns

formatted error string

Formats an error string using printf-like % conversions. Conversions include:

%d, %i	Format an int as a decimal string. Understands flags in #0- +, field widths (including *), and precisions.
%hd, %ld, %lld, %zd	Format a short, long, long long, or size_t.
%^16d, %^32d, %^64d	Format a 16-, 32-, or 64-bit integer.
%o, %u, %x, %X	Format an unsigned integer in octal, decimal, or hexadecimal (with lower-case or upper-case letters).
%s	Format a C string (const char *). The alternate form %#s calls String::printable() on the input string. Both %#s and the alternate form %'s ensure that no part of the string is mistaken for an error annotation.
%c	Format a character. Prints a C-like escape if the input character isn't printable ASCII.
%p	Format a pointer as a hexadecimal value.
%e, %E, %f, %F, %g, %G	Format a double (user-level only).
%p{...}	Call a user-provided conversion function. For example, %p{ip_ptr} reads an IPAddress * argument from the argument list, and formats the pointed-to address using IPAddress::unparse().
%%	Format a literal % character.
%<	Format a left quote string. Usually prints a single quote.
%>	Format a right quote string. Usually prints a single quote.
%,	Format an apostrophe string. Usually prints a single quote.

vxformat() [1/2]

String ErrorHandler::vxformat ( int  default_flags, const char *  fmt, va_list  val  )

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

xformat() [2/2]

String ErrorHandler::xformat ( const char *  fmt,   ...  )

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

vxformat() [2/2]

static String ErrorHandler::vxformat ( const char *  fmt, va_list  val  )

inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

vformat()

String ErrorHandler::vformat ( const char *  fmt, va_list  val  )

virtual

Format an error string.

Parameters

fmt	format string
val	argument list

Warning

ErrorHandler users don't need to call this function directly; it is called implicitly by the error()/xmessage() functions.

This virtual function is called to format an error message. The default implementation returns the result of vxformat(fmt, val).

Reimplemented in ErrorVeneer, and FileErrorHandler.

format()

String ErrorHandler::format	(	const char *	fmt,
			...
	)

Format an error string.

Parameters

fmt	format string

Warning

ErrorHandler users don't usually need to call this function directly.

This is a convenience function that calls vformat(const char *fmt, va_list val) for a va_list taken from the ellipsis arguments.

decorate()

String ErrorHandler::decorate ( const String &  str )

virtual

Decorate an error message.

Parameters

str	error message, possibly with annotations

Returns

decorated error message

Warning

ErrorHandler users don't need to call this function directly; it is called implicitly by the error()/xmessage() functions.

This virtual function is called to decorate an error message before it is emitted. The input str is an error message string, possibly annotated. The default implementation returns str unchanged. Other ErrorHandlers might add context lines (ContextErrorHandler), prefixes (PrefixErrorHandler), or a default landmark (LandmarkErrorHandler).

Reimplemented in ErrorVeneer, ContextErrorHandler, PrefixErrorHandler, and LandmarkErrorHandler.

emit()

void * ErrorHandler::emit ( const String &  str, void *  user_data, bool  more  )

virtual

Output an error message line.

Parameters

str	error message line, possibly with annotations
user_data	callback data, 0 for first line in a message
more	true iff this is the last line in the current message

Returns

user_data to be passed to emit() for the next line

Warning

ErrorHandler users don't need to call this function directly; it is called implicitly by the error()/xmessage() functions.

After calling decorate(), ErrorHandler splits the message into individual lines and calls emit() once per line. ErrorHandler subclasses should output the error lines as appropriate; for example, FileErrorHandler outputs the error message to a file.

str does not contain a newline, but may contain annotations, including a landmark annotation. Most ErrorHandlers use parse_anno() to extract the landmark annotation, clean it with clean_landmark(), and print it ahead of the error message proper.

ErrorHandler can handle multi-line error messages. However, the emit() function takes a line at a time; this is more useful in practice for most error message printers. The user_data and more arguments can help an ErrorHandler combine the lines of a multi-line error message. user_data is null for the first line; for second and subsequent lines, ErrorHandler passes the result of the last line's emit() call. more is true iff this is the last line in the current message.

The default emit() implementation does nothing.

Reimplemented in ErrorVeneer, and FileErrorHandler.

account()

virtual void ErrorHandler::account ( int  level )

inlinevirtual

Account for an error message at level level.

Parameters

level

minimum error level in the message

Warning

ErrorHandler users don't need to call this function directly; it is called implicitly by the error()/xmessage() functions.

After calling emit() for the lines of an error message, ErrorHandler calls account(), passing the minimum (worst) error level of any message line (or 1000 if no line had a level). The default implementation updates the nerrors() counter. Some other ErrorHandlers add account() behavior that, for example, exits after printing messages at el_fatal level or below.

Reimplemented in ErrorVeneer, FileErrorHandler, and BailErrorHandler.

clear()

virtual void ErrorHandler::clear ( )

inlinevirtual

Clear accumulated error state.

The default implementation sets the nerrors() counter to zero.

make_anno()

String ErrorHandler::make_anno ( const char *  name, const String &  value  )

static

Create an error annotation.

Parameters

name	annotation name
value	annotation value

Returns

annotation string

Returns an error annotation that associates annotation name with value.

If name equals "<>", then returns a level annotation of the form "<@a value>". value must be valid number; if it isn't, the function returns the empty string.

Otherwise, name must be a nonempty series of letters and digits. make_anno() returns a string of the form "{@a name:@a value}", where special characters in value are quoted with backslashes.

combine_anno()

String ErrorHandler::combine_anno ( const String &  str, const String &  anno  )

static

Apply annotations from anno to every line in str.

Parameters

str	string
anno	annotation string

The annotations from anno are applied to every line in str. New annotations do not override existing annotations with the same names. If the anno string ends with non-annotation characters, this substring is prefixed to every line in str.

For example:

combine_anno("Line 1\n{l:old}{x:x}Line 2\n", "<0>{l:new}  ")
   // returns "<0>{l:new}  Line 1\n<0>{l:old}{x:x}  Line 2\n"

parse_anno()

const char * ErrorHandler::parse_anno ( const String &  str, const char *  begin, const char *  end,   ...  )

static

Parse error annotations from a string.

Parameters

str	the string
begin	pointer within str to start of annotation area
end	pointer to end of error region, usually str.end()

Returns

pointer to first character after annotation area

Precondition

str.begin() <= {begin, end} <= str.end()

Postcondition

begin <= returned value <= end

Use this function to skip an error line's annotation area, possibly extracting named annotations.

The variable arguments portion consists of a series of pairs of C strings and value pointers, terminated by a null character pointer. Each C string is an annotation name. The corresponding annotation value, if found, is stored as a String object in the value pointer. You can also store the int value of an annotation by prefixing an annotation name with the '#' character.

For example:

String line = "{l:file:30}<4.5>error message\n";
String landmark_str, level_str;
const char *s = ErrorHandler::parse_anno(line, line.begin(), line.end(),
           "l", &landmark_str, "<>", &level_str, (const char *) 0);
    // Results: s points to "error message\n",
    // landmark_str == "file:30", level_str == "4.5"
 
int level;
s = ErrorHandler::parse_anno(line, line.begin(), line.end(),
           "#<>", &level, (const char *) 0);
    // Results: s points to "error message\n", level_str == 4

skip_anno()

static const char * ErrorHandler::skip_anno ( const char *  begin, const char *  end  )

inlinestatic

Skip a string's error annotations.

Parameters

begin	pointer to start of string
end	pointer one past end of string

Returns

pointer to first character after annotation area

Postcondition

begin <= returned value <= end

Use this function to skip an error line's annotation area. The error line is defined as a pair of iterators.

make_landmark_anno()

static String ErrorHandler::make_landmark_anno ( const String &  x )

inlinestatic

Return a landmark annotation equal to x.

Parameters

x

landmark

If x is empty, returns the empty string. Otherwise, if x looks like a formatted annotation (it starts with an open brace), returns x unchanged. Otherwise, returns make_anno("l", x).

clean_landmark()

String ErrorHandler::clean_landmark ( const String &  landmark, bool  colon = false  )

static

Clean the landmark.

Parameters

landmark	landmark text
colon	if true, append ": " to a nonempty landmark

Removes trailing space and an optional trailing colon from landmark and returns the result. If colon is true, and the cleaned landmark isn't the empty string, then appends ": " to the result.

Member Data Documentation

e_abort

const char ErrorHandler::e_abort = "<-999>"

static

Error level indicators.

ok_result

const int ErrorHandler::ok_result = 0

static

Equals 0, used for error levels <5> and above

error_result

const int ErrorHandler::error_result = -EINVAL

static

Equals -EINVAL, used for error levels <4> and below

---

The documentation for this class was generated from the following files:

• include/click/error.hh
• lib/error.cc