[mirror_frr.git] / lib / printfrr.h

/*
 * Copyright (c) 2019  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_PRINTFRR_H
#define _FRR_PRINTFRR_H

#include <stddef.h>
#include <stdarg.h>
#include <stdint.h>

#include "compiler.h"
#include "memory.h"

#ifdef __cplusplus
extern "C" {
#endif

struct fbuf {
	char *buf;
	char *pos;
	size_t len;
};

#define at(a, b) PRINTFRR(a, b)
#define atn(a, b) \
	at(a, b) __attribute__((nonnull(1) _RET_NONNULL))
#define atm(a, b) \
	atn(a, b) __attribute__((malloc))

/* return value is length needed for the full string (excluding \0) in all
 * cases.  The functions write as much as they can, but continue regardless,
 * so the return value is independent of buffer length.  Both bprintfrr and
 * snprintf also accept NULL as output buffer.
 */

/* bprintfrr does NOT null terminate! use sparingly (only provided since it's
 * the most direct interface) - useful for incrementally building long text
 * (call bprintfrr repeatedly with the same buffer)
 */
ssize_t vbprintfrr(struct fbuf *out, const char *fmt, va_list) at(2, 0);
ssize_t  bprintfrr(struct fbuf *out, const char *fmt, ...)     at(2, 3);

/* these do null terminate like their snprintf cousins */
ssize_t vsnprintfrr(char *out, size_t sz, const char *fmt, va_list) at(3, 0);
ssize_t  snprintfrr(char *out, size_t sz, const char *fmt, ...)     at(3, 4);

/* c = continue / concatenate (append at the end of the string)
 * return value is would-be string length (regardless of buffer length),
 * i.e. includes already written chars */
ssize_t vcsnprintfrr(char *out, size_t sz, const char *fmt, va_list) at(3, 0);
ssize_t  csnprintfrr(char *out, size_t sz, const char *fmt, ...)     at(3, 4);

/* memory allocations don't fail in FRR, so you always get something here.
 * (in case of error, returns a strdup of the format string) */
char *vasprintfrr(struct memtype *mt, const char *fmt, va_list) atm(2, 0);
char  *asprintfrr(struct memtype *mt, const char *fmt, ...)     atm(2, 3);

/* try to use provided buffer (presumably from stack), allocate if it's too
 * short.  Must call XFREE(mt, return value) if return value != out.
 */
char *vasnprintfrr(struct memtype *mt, char *out, size_t sz,
		   const char *fmt, va_list) atn(4, 0);
char  *asnprintfrr(struct memtype *mt, char *out, size_t sz,
		   const char *fmt, ...)     atn(4, 5);

#define printfrr(fmt, ...)                                                     \
	do {                                                                   \
		char buf[256], *out;                                           \
		out = asnprintfrr(MTYPE_TMP, buf, sizeof(buf), fmt,            \
				  ##__VA_ARGS__);                              \
		fputs(out, stdout);                                            \
		if (out != buf)                                                \
			XFREE(MTYPE_TMP, out);                                 \
	} while (0)

#undef at
#undef atm
#undef atn

/* extension specs must start with a capital letter (this is a restriction
 * for both performance's and human understanding's sake.)
 *
 * Note that the entire thing mostly works because a letter directly following
 * a %p print specifier is extremely unlikely to occur (why would you want to
 * print "0x12345678HELLO"?)  Normally, you'd expect spacing or punctuation
 * after a placeholder.  That also means that neither of those works well for
 * extension purposes, e.g. "%p{foo}" is reasonable to see actually used.
 *
 * TODO: would be nice to support a "%pF%dF" specifier that consumes 2
 * arguments, e.g. to pass an integer + a list of known values...  can be
 * done, but a bit tricky.
 */
#define printfrr_ext_char(ch) ((ch) >= 'A' && (ch) <= 'Z')

struct printfrr_ext {
	/* embedded string to minimize cache line pollution */
	char match[8];

	/* both can be given, if not the code continues searching
	 * (you can do %pX and %dX in 2 different entries)
	 *
	 * return value: number of bytes consumed from the format string, so
	 * you can consume extra flags (e.g. register for "%pX", consume
	 * "%pXfoo" or "%pXbar" for flags.)  Convention is to make those flags
	 * lowercase letters or numbers.
	 *
	 * bsz is a compile-time constant in printf;  it's gonna be relatively
	 * small.  This isn't designed to print Shakespeare from a pointer.
	 *
	 * prec is the precision specifier (the 999 in "%.999p")  -1 means
	 * none given (value in the format string cannot be negative)
	 */
	ssize_t (*print_ptr)(char *buf, size_t bsz, const char *fmt, int prec,
			const void *);
	ssize_t (*print_int)(char *buf, size_t bsz, const char *fmt, int prec,
			uintmax_t);
};

/* no locking - must be called when single threaded (e.g. at startup.)
 * this restriction hopefully won't be a huge bother considering normal usage
 * scenarios...
 */
void printfrr_ext_reg(const struct printfrr_ext *);

#define printfrr_ext_autoreg_p(matchs, print_fn)                               \
	static ssize_t print_fn(char *, size_t, const char *, int,             \
				const void *);                                 \
	static const struct printfrr_ext _printext_##print_fn = {              \
		.match = matchs,                                               \
		.print_ptr = print_fn,                                         \
	};                                                                     \
	static void _printreg_##print_fn(void) __attribute__((constructor));   \
	static void _printreg_##print_fn(void) {                               \
		printfrr_ext_reg(&_printext_##print_fn);                       \
	}                                                                      \
	/* end */

#define printfrr_ext_autoreg_i(matchs, print_fn)                               \
	static ssize_t print_fn(char *, size_t, const char *, int, uintmax_t); \
	static const struct printfrr_ext _printext_##print_fn = {              \
		.match = matchs,                                               \
		.print_int = print_fn,                                         \
	};                                                                     \
	static void _printreg_##print_fn(void) __attribute__((constructor));   \
	static void _printreg_##print_fn(void) {                               \
		printfrr_ext_reg(&_printext_##print_fn);                       \
	}                                                                      \
	/* end */

#ifdef __cplusplus
}
#endif

#endif
Commit	Line	Data
5c25bd87 DL	1	/*
	2	* Copyright (c) 2019 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_PRINTFRR_H
	18	#define _FRR_PRINTFRR_H
	19
	20	#include <stddef.h>
	21	#include <stdarg.h>
bf4d3d80	22	#include <stdint.h>
5c25bd87 DL	23
	24	#include "compiler.h"
	25	#include "memory.h"
	26
17e38209 RW	27	#ifdef __cplusplus
	28	extern "C" {
	29	#endif
	30
5c25bd87 DL	31	struct fbuf {
	32	char *buf;
	33	char *pos;
	34	size_t len;
	35	};
	36
fb84c629	37	#define at(a, b) PRINTFRR(a, b)
5c25bd87 DL	38	#define atn(a, b) \
	39	at(a, b) __attribute__((nonnull(1) _RET_NONNULL))
	40	#define atm(a, b) \
	41	atn(a, b) __attribute__((malloc))
	42
	43	/* return value is length needed for the full string (excluding \0) in all
	44	* cases. The functions write as much as they can, but continue regardless,
	45	* so the return value is independent of buffer length. Both bprintfrr and
	46	* snprintf also accept NULL as output buffer.
	47	*/
	48
	49	/* bprintfrr does NOT null terminate! use sparingly (only provided since it's
	50	* the most direct interface) - useful for incrementally building long text
	51	* (call bprintfrr repeatedly with the same buffer)
	52	*/
	53	ssize_t vbprintfrr(struct fbuf out, const char fmt, va_list) at(2, 0);
	54	ssize_t bprintfrr(struct fbuf out, const char fmt, ...) at(2, 3);
	55
	56	/* these do null terminate like their snprintf cousins */
	57	ssize_t vsnprintfrr(char out, size_t sz, const char fmt, va_list) at(3, 0);
	58	ssize_t snprintfrr(char out, size_t sz, const char fmt, ...) at(3, 4);
	59
	60	/* c = continue / concatenate (append at the end of the string)
	61	* return value is would-be string length (regardless of buffer length),
	62	* i.e. includes already written chars */
	63	ssize_t vcsnprintfrr(char out, size_t sz, const char fmt, va_list) at(3, 0);
	64	ssize_t csnprintfrr(char out, size_t sz, const char fmt, ...) at(3, 4);
	65
	66	/* memory allocations don't fail in FRR, so you always get something here.
	67	* (in case of error, returns a strdup of the format string) */
	68	char vasprintfrr(struct memtype mt, const char *fmt, va_list) atm(2, 0);
	69	char asprintfrr(struct memtype mt, const char *fmt, ...) atm(2, 3);
	70
	71	/* try to use provided buffer (presumably from stack), allocate if it's too
	72	* short. Must call XFREE(mt, return value) if return value != out.
	73	*/
	74	char vasnprintfrr(struct memtype mt, char *out, size_t sz,
	75	const char *fmt, va_list) atn(4, 0);
	76	char asnprintfrr(struct memtype mt, char *out, size_t sz,
	77	const char *fmt, ...) atn(4, 5);
	78
fb84c629 DL	79	#define printfrr(fmt, ...) \
	80	do { \
	81	char buf[256], *out; \
	82	out = asnprintfrr(MTYPE_TMP, buf, sizeof(buf), fmt, \
	83	##__VA_ARGS__); \
	84	fputs(out, stdout); \
	85	if (out != buf) \
	86	XFREE(MTYPE_TMP, out); \
	87	} while (0)
	88
5c25bd87 DL	89	#undef at
5c25bd87 DL	90	#undef atm
07ef3e34	91	#undef atn
5c25bd87	92
bf4d3d80 DL	93	/* extension specs must start with a capital letter (this is a restriction
	94	* for both performance's and human understanding's sake.)
	95	*
	96	* Note that the entire thing mostly works because a letter directly following
	97	* a %p print specifier is extremely unlikely to occur (why would you want to
	98	* print "0x12345678HELLO"?) Normally, you'd expect spacing or punctuation
	99	* after a placeholder. That also means that neither of those works well for
	100	* extension purposes, e.g. "%p{foo}" is reasonable to see actually used.
	101	*
	102	* TODO: would be nice to support a "%pF%dF" specifier that consumes 2
	103	* arguments, e.g. to pass an integer + a list of known values... can be
	104	* done, but a bit tricky.
	105	*/
	106	#define printfrr_ext_char(ch) ((ch) >= 'A' && (ch) <= 'Z')
5c25bd87	107
bf4d3d80 DL	108	struct printfrr_ext {
	109	/* embedded string to minimize cache line pollution */
	110	char match[8];
	111
	112	/* both can be given, if not the code continues searching
	113	* (you can do %pX and %dX in 2 different entries)
	114	*
	115	* return value: number of bytes consumed from the format string, so
	116	* you can consume extra flags (e.g. register for "%pX", consume
	117	* "%pXfoo" or "%pXbar" for flags.) Convention is to make those flags
	118	* lowercase letters or numbers.
	119	*
	120	* bsz is a compile-time constant in printf; it's gonna be relatively
	121	* small. This isn't designed to print Shakespeare from a pointer.
	122	*
	123	* prec is the precision specifier (the 999 in "%.999p") -1 means
	124	* none given (value in the format string cannot be negative)
	125	*/
	126	ssize_t (print_ptr)(char buf, size_t bsz, const char *fmt, int prec,
	127	const void *);
	128	ssize_t (print_int)(char buf, size_t bsz, const char *fmt, int prec,
	129	uintmax_t);
5c25bd87 DL	130	};
5c25bd87 DL	131
bf4d3d80 DL	132	/* no locking - must be called when single threaded (e.g. at startup.)
	133	* this restriction hopefully won't be a huge bother considering normal usage
	134	* scenarios...
	135	*/
5c25bd87	136	void printfrr_ext_reg(const struct printfrr_ext *);
bf4d3d80 DL	137
	138	#define printfrr_ext_autoreg_p(matchs, print_fn) \
	139	static ssize_t print_fn(char , size_t, const char , int, \
	140	const void *); \
2b64873d	141	static const struct printfrr_ext _printext_##print_fn = { \
bf4d3d80 DL	142	.match = matchs, \
	143	.print_ptr = print_fn, \
	144	}; \
	145	static void _printreg_##print_fn(void) __attribute__((constructor)); \
	146	static void _printreg_##print_fn(void) { \
	147	printfrr_ext_reg(&_printext_##print_fn); \
	148	} \
	149	/* end */
	150
	151	#define printfrr_ext_autoreg_i(matchs, print_fn) \
	152	static ssize_t print_fn(char , size_t, const char , int, uintmax_t); \
2b64873d	153	static const struct printfrr_ext _printext_##print_fn = { \
bf4d3d80 DL	154	.match = matchs, \
	155	.print_int = print_fn, \
	156	}; \
	157	static void _printreg_##print_fn(void) __attribute__((constructor)); \
	158	static void _printreg_##print_fn(void) { \
	159	printfrr_ext_reg(&_printext_##print_fn); \
	160	} \
	161	/* end */
5c25bd87	162
17e38209 RW	163	#ifdef __cplusplus
	164	}
	165	#endif
	166
5c25bd87	167	#endif