[mirror_frr.git] / lib / ferr.h

/*
 * Copyright (c) 2015-16  David Lamparter, for NetDEF, Inc.
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */

#ifndef _FRR_FERR_H
#define _FRR_FERR_H

/***********************************************************
 * scroll down to the end of this file for a full example! *
 ***********************************************************/

#include <stdint.h>
#include <limits.h>
#include <errno.h>

#include "vty.h"

/* return type when this error indication stuff is used.
 *
 * guaranteed to have boolean evaluation to "false" when OK, "true" when error
 * (i.e. can be changed to pointer in the future if neccessary)
 *
 * For checking, always use "if (value)", nothing else.
 * Do _NOT_ use any integer constant (!= 0), or sign check (< 0).
 */
typedef int ferr_r;

/* rough category of error indication */
enum ferr_kind {
	/* no error */
	FERR_OK = 0,

	/* something isn't the way it's supposed to be.
	 * (things that might otherwise be asserts, really)
	 */
	FERR_CODE_BUG,

	/* user-supplied parameters don't make sense or is inconsistent
	 * if you can express a rule for it (e.g. "holdtime > 2 * keepalive"),
	 * it's this category.
	 */
	FERR_CONFIG_INVALID,

	/* user-supplied parameters don't line up with reality
	 * (IP address or interface not available, etc.)
	 * NB: these are really TODOs where the code needs to be fixed to
	 * respond to future changes!
	 */
	FERR_CONFIG_REALITY,

	/* out of some system resource (probably memory)
	 * aka "you didn't spend enough money error" */
	FERR_RESOURCE,

	/* system error (permission denied, etc.) */
	FERR_SYSTEM,

	/* error return from some external library
	 * (FERR_SYSTEM and FERR_LIBRARY are not strongly distinct) */
	FERR_LIBRARY,
};

struct ferr {
	/* code location */
	const char *file;
	const char *func;
	int line;

	enum ferr_kind kind;

	/* unique_id is calculated as a checksum of source filename and error
	 * message format (*before* calling vsnprintf).  Line number and
	 * function name are not used; this keeps the number reasonably static
	 * across changes.
	 */
	uint32_t unique_id;

	char message[384];

	/* valid if != 0.  note "errno" might be preprocessor foobar. */
	int errno_val;
	/* valid if pathname[0] != '\0' */
	char pathname[PATH_MAX];
};

/* Numeric ranges assigned to daemons for use as error codes. */
#define LIB_FERR_START 0x01000001
#define LIB_FERR_END 0x01FFFFFF
#define BGP_FERR_START 0x02000000
#define BGP_FERR_END 0x02FFFFFF
#define OSPF_FERR_START 0x03000001
#define OSPF_FERR_END 0x03FFFFFF
#define ZEBRA_FERR_START 0x04000001
#define ZEBRA_FERR_END 0x04FFFFFF
#define END_FERR 0xFFFFFFFF

struct ferr_ref {
	/* Unique error code displayed to end user as a reference. -1 means
	 * this is an uncoded error that does not have reference material. */
	uint32_t code;
	/* Ultra brief title */
	const char *title;
	/* Brief description of error */
	const char *description;
	/* Remedial suggestion */
	const char *suggestion;
};

void ferr_ref_add(struct ferr_ref *ref);
struct ferr_ref *ferr_ref_get(uint32_t code);
void ferr_ref_display(struct vty *, uint32_t code);
void ferr_ref_init(void);
void ferr_ref_fini(void);

/* get error details.
 *
 * NB: errval/ferr_r does NOT carry the full error information.  It's only
 * passed around for future API flexibility.  ferr_get_last always returns
 * the last error set in the current thread.
 */
const struct ferr *ferr_get_last(ferr_r errval);

/* can optionally be called at strategic locations.
 * always returns 0. */
ferr_r ferr_clear(void);

/* do NOT call these functions directly.  only for macro use! */
ferr_r ferr_set_internal(const char *file, int line, const char *func,
			 enum ferr_kind kind, const char *text, ...);
ferr_r ferr_set_internal_ext(const char *file, int line, const char *func,
			     enum ferr_kind kind, const char *pathname,
			     int errno_val, const char *text, ...);

#define ferr_ok() 0

/* Report an error.
 *
 * If you need to do cleanup (free memory, etc.), save the return value in a
 * variable of type ferr_r.
 *
 * Don't put a \n at the end of the error message.
 */
#define ferr_code_bug(...)                                                     \
	ferr_set_internal(__FILE__, __LINE__, __func__, FERR_CODE_BUG,         \
			  __VA_ARGS__)
#define ferr_cfg_invalid(...)                                                  \
	ferr_set_internal(__FILE__, __LINE__, __func__, FERR_CONFIG_INVALID,   \
			  __VA_ARGS__)
#define ferr_cfg_reality(...)                                                  \
	ferr_set_internal(__FILE__, __LINE__, __func__, FERR_CONFIG_REALITY,   \
			  __VA_ARGS__)
#define ferr_cfg_resource(...)                                                 \
	ferr_set_internal(__FILE__, __LINE__, __func__, FERR_RESOURCE,         \
			  __VA_ARGS__)
#define ferr_system(...)                                                       \
	ferr_set_internal(__FILE__, __LINE__, __func__, FERR_SYSTEM,           \
			  __VA_ARGS__)
#define ferr_library(...)                                                      \
	ferr_set_internal(__FILE__, __LINE__, __func__, FERR_LIBRARY,          \
			  __VA_ARGS__)

/* extended information variants */
#define ferr_system_errno(...)                                                 \
	ferr_set_internal_ext(__FILE__, __LINE__, __func__, FERR_SYSTEM, NULL, \
			      errno, __VA_ARGS__)
#define ferr_system_path_errno(path, ...)                                      \
	ferr_set_internal_ext(__FILE__, __LINE__, __func__, FERR_SYSTEM, path, \
			      errno, __VA_ARGS__)

#include "vty.h"
/* print error message to vty;  $ERR is replaced by the error's message */
void vty_print_error(struct vty *vty, ferr_r err, const char *msg, ...);

#define CMD_FERR_DO(func, action, ...)                                         \
	do {                                                                   \
		ferr_r cmd_retval = func;                                      \
		if (cmd_retval) {                                              \
			vty_print_error(vty, cmd_retval, __VA_ARGS__);         \
			action;                                                \
		}                                                              \
	} while (0)

#define CMD_FERR_RETURN(func, ...)                                             \
	CMD_FERR_DO(func, return CMD_WARNING_CONFIG_FAILED, __VA_ARGS__)
#define CMD_FERR_GOTO(func, label, ...)                                        \
	CMD_FERR_DO(func, goto label, __VA_ARGS__)

/* example: uses bogus #define to keep indent.py happy */
#ifdef THIS_IS_AN_EXAMPLE
ferr_r foo_bar_set(struct object *obj, int bar)
{
	if (bar < 1 || bar >= 100)
		return ferr_config_invalid("bar setting (%d) must be 0<x<100",
					   bar);
	obj->bar = bar;
	if (ioctl(obj->fd, bar))
		return ferr_system_errno("couldn't set bar to %d", bar);

	return ferr_ok();
}

DEFUN("bla")
{
	CMD_FERR_RETURN(foo_bar_set(obj, atoi(argv[1])),
			"command failed: $ERR\n");
	return CMD_SUCCESS;
}

#endif /* THIS_IS_AN_EXAMPLE */

#endif /* _FERR_H */
Commit	Line	Data
3155489a DL	1	/*
	2	* Copyright (c) 2015-16 David Lamparter, for NetDEF, Inc.
	3	*
	4	* Permission to use, copy, modify, and distribute this software for any
	5	* purpose with or without fee is hereby granted, provided that the above
	6	* copyright notice and this permission notice appear in all copies.
	7	*
	8	* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
	9	* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
	10	* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
	11	* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
	12	* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
	13	* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
	14	* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
	15	*/
	16
	17	#ifndef _FRR_FERR_H
	18	#define _FRR_FERR_H
	19
	20	/***********************************************************
	21	* scroll down to the end of this file for a full example! *
	22	***********************************************************/
	23
	24	#include <stdint.h>
	25	#include <limits.h>
	26	#include <errno.h>
	27
7b526b61 QY	28	#include "vty.h"
7b526b61 QY	29
3155489a DL	30	/* return type when this error indication stuff is used.
	31	*
	32	* guaranteed to have boolean evaluation to "false" when OK, "true" when error
	33	* (i.e. can be changed to pointer in the future if neccessary)
	34	*
	35	* For checking, always use "if (value)", nothing else.
	36	* Do _NOT_ use any integer constant (!= 0), or sign check (< 0).
	37	*/
	38	typedef int ferr_r;
	39
	40	/* rough category of error indication */
	41	enum ferr_kind {
	42	/* no error */
	43	FERR_OK = 0,
	44
	45	/* something isn't the way it's supposed to be.
	46	* (things that might otherwise be asserts, really)
	47	*/
	48	FERR_CODE_BUG,
	49
	50	/* user-supplied parameters don't make sense or is inconsistent
	51	* if you can express a rule for it (e.g. "holdtime > 2 * keepalive"),
	52	* it's this category.
	53	*/
	54	FERR_CONFIG_INVALID,
	55
	56	/* user-supplied parameters don't line up with reality
	57	* (IP address or interface not available, etc.)
	58	* NB: these are really TODOs where the code needs to be fixed to
	59	* respond to future changes!
	60	*/
	61	FERR_CONFIG_REALITY,
	62
	63	/* out of some system resource (probably memory)
	64	* aka "you didn't spend enough money error" */
	65	FERR_RESOURCE,
	66
	67	/* system error (permission denied, etc.) */
	68	FERR_SYSTEM,
	69
	70	/* error return from some external library
	71	* (FERR_SYSTEM and FERR_LIBRARY are not strongly distinct) */
	72	FERR_LIBRARY,
	73	};
	74
	75	struct ferr {
	76	/* code location */
	77	const char *file;
	78	const char *func;
	79	int line;
	80
	81	enum ferr_kind kind;
	82
	83	/* unique_id is calculated as a checksum of source filename and error
	84	* message format (before calling vsnprintf). Line number and
	85	* function name are not used; this keeps the number reasonably static
	86	* across changes.
	87	*/
	88	uint32_t unique_id;
	89
	90	char message[384];
	91
	92	/* valid if != 0. note "errno" might be preprocessor foobar. */
	93	int errno_val;
94	/* valid if pathname[0] != '\0' */
95	char pathname[PATH_MAX];
96	};
97
7b526b61 QY	98	/* Numeric ranges assigned to daemons for use as error codes. */
	99	#define LIB_FERR_START 0x01000001
	100	#define LIB_FERR_END 0x01FFFFFF
	101	#define BGP_FERR_START 0x02000000
	102	#define BGP_FERR_END 0x02FFFFFF
	103	#define OSPF_FERR_START 0x03000001
	104	#define OSPF_FERR_END 0x03FFFFFF
	105	#define ZEBRA_FERR_START 0x04000001
	106	#define ZEBRA_FERR_END 0x04FFFFFF
90234540	107	#define END_FERR 0xFFFFFFFF
7b526b61 QY	108
	109	struct ferr_ref {
	110	/* Unique error code displayed to end user as a reference. -1 means
	111	* this is an uncoded error that does not have reference material. */
	112	uint32_t code;
	113	/* Ultra brief title */
	114	const char *title;
	115	/* Brief description of error */
	116	const char *description;
	117	/* Remedial suggestion */
	118	const char *suggestion;
	119	};
	120
	121	void ferr_ref_add(struct ferr_ref *ref);
	122	struct ferr_ref *ferr_ref_get(uint32_t code);
	123	void ferr_ref_display(struct vty *, uint32_t code);
	124	void ferr_ref_init(void);
	125	void ferr_ref_fini(void);
	126
3155489a DL	127	/* get error details.
	128	*
	129	* NB: errval/ferr_r does NOT carry the full error information. It's only
	130	* passed around for future API flexibility. ferr_get_last always returns
	131	* the last error set in the current thread.
	132	*/
	133	const struct ferr *ferr_get_last(ferr_r errval);
	134
	135	/* can optionally be called at strategic locations.
	136	* always returns 0. */
	137	ferr_r ferr_clear(void);
	138
	139	/* do NOT call these functions directly. only for macro use! */
	140	ferr_r ferr_set_internal(const char file, int line, const char func,
996c9314	141	enum ferr_kind kind, const char *text, ...);
3155489a	142	ferr_r ferr_set_internal_ext(const char file, int line, const char func,
996c9314 LB	143	enum ferr_kind kind, const char *pathname,
996c9314 LB	144	int errno_val, const char *text, ...);
3155489a	145
996c9314	146	#define ferr_ok() 0
3155489a DL	147
	148	/* Report an error.
	149	*
	150	* If you need to do cleanup (free memory, etc.), save the return value in a
	151	* variable of type ferr_r.
	152	*
	153	* Don't put a \n at the end of the error message.
	154	*/
996c9314 LB	155	#define ferr_code_bug(...) \
	156	ferr_set_internal(__FILE__, __LINE__, __func__, FERR_CODE_BUG, \
	157	__VA_ARGS__)
	158	#define ferr_cfg_invalid(...) \
	159	ferr_set_internal(__FILE__, __LINE__, __func__, FERR_CONFIG_INVALID, \
	160	__VA_ARGS__)
	161	#define ferr_cfg_reality(...) \
	162	ferr_set_internal(__FILE__, __LINE__, __func__, FERR_CONFIG_REALITY, \
	163	__VA_ARGS__)
	164	#define ferr_cfg_resource(...) \
	165	ferr_set_internal(__FILE__, __LINE__, __func__, FERR_RESOURCE, \
	166	__VA_ARGS__)
	167	#define ferr_system(...) \
	168	ferr_set_internal(__FILE__, __LINE__, __func__, FERR_SYSTEM, \
	169	__VA_ARGS__)
	170	#define ferr_library(...) \
	171	ferr_set_internal(__FILE__, __LINE__, __func__, FERR_LIBRARY, \
	172	__VA_ARGS__)
3155489a DL	173
3155489a DL	174	/* extended information variants */
996c9314 LB	175	#define ferr_system_errno(...) \
	176	ferr_set_internal_ext(__FILE__, __LINE__, __func__, FERR_SYSTEM, NULL, \
	177	errno, __VA_ARGS__)
	178	#define ferr_system_path_errno(path, ...) \
	179	ferr_set_internal_ext(__FILE__, __LINE__, __func__, FERR_SYSTEM, path, \
	180	errno, __VA_ARGS__)
3155489a DL	181
	182	#include "vty.h"
	183	/* print error message to vty; $ERR is replaced by the error's message */
	184	void vty_print_error(struct vty vty, ferr_r err, const char msg, ...);
	185
996c9314 LB	186	#define CMD_FERR_DO(func, action, ...) \
	187	do { \
	188	ferr_r cmd_retval = func; \
	189	if (cmd_retval) { \
	190	vty_print_error(vty, cmd_retval, __VA_ARGS__); \
	191	action; \
	192	} \
3155489a DL	193	} while (0)
3155489a DL	194
996c9314	195	#define CMD_FERR_RETURN(func, ...) \
7eb09438	196	CMD_FERR_DO(func, return CMD_WARNING_CONFIG_FAILED, __VA_ARGS__)
996c9314	197	#define CMD_FERR_GOTO(func, label, ...) \
3155489a DL	198	CMD_FERR_DO(func, goto label, __VA_ARGS__)
3155489a DL	199
e894f9fd LB	200	/* example: uses bogus #define to keep indent.py happy */
e894f9fd LB	201	#ifdef THIS_IS_AN_EXAMPLE
3155489a DL	202	ferr_r foo_bar_set(struct object *obj, int bar)
	203	{
	204	if (bar < 1 \|\| bar >= 100)
e894f9fd LB	205	return ferr_config_invalid("bar setting (%d) must be 0<x<100",
e894f9fd LB	206	bar);
3155489a	207	obj->bar = bar;
e894f9fd	208	if (ioctl(obj->fd, bar))
3155489a DL	209	return ferr_system_errno("couldn't set bar to %d", bar);
	210
	211	return ferr_ok();
	212	}
	213
	214	DEFUN("bla")
	215	{
	216	CMD_FERR_RETURN(foo_bar_set(obj, atoi(argv[1])),
996c9314	217	"command failed: $ERR\n");
3155489a DL	218	return CMD_SUCCESS;
	219	}
	220
e894f9fd	221	#endif /* THIS_IS_AN_EXAMPLE */
3155489a DL	222
3155489a DL	223	#endif /* _FERR_H */