]>
git.proxmox.com Git - mirror_frr.git/blob - lib/printfrr.h
2 * Copyright (c) 2019 David Lamparter, for NetDEF, Inc.
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.
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.
17 #ifndef _FRR_PRINTFRR_H
18 #define _FRR_PRINTFRR_H
34 __attribute__((format(printf, a, b)))
36 at(a, b) __attribute__((nonnull(1) _RET_NONNULL))
38 atn(a, b) __attribute__((malloc))
40 /* return value is length needed for the full string (excluding \0) in all
41 * cases. The functions write as much as they can, but continue regardless,
42 * so the return value is independent of buffer length. Both bprintfrr and
43 * snprintf also accept NULL as output buffer.
46 /* bprintfrr does NOT null terminate! use sparingly (only provided since it's
47 * the most direct interface) - useful for incrementally building long text
48 * (call bprintfrr repeatedly with the same buffer)
50 ssize_t
vbprintfrr(struct fbuf
*out
, const char *fmt
, va_list) at(2, 0);
51 ssize_t
bprintfrr(struct fbuf
*out
, const char *fmt
, ...) at(2, 3);
53 /* these do null terminate like their snprintf cousins */
54 ssize_t
vsnprintfrr(char *out
, size_t sz
, const char *fmt
, va_list) at(3, 0);
55 ssize_t
snprintfrr(char *out
, size_t sz
, const char *fmt
, ...) at(3, 4);
57 /* c = continue / concatenate (append at the end of the string)
58 * return value is would-be string length (regardless of buffer length),
59 * i.e. includes already written chars */
60 ssize_t
vcsnprintfrr(char *out
, size_t sz
, const char *fmt
, va_list) at(3, 0);
61 ssize_t
csnprintfrr(char *out
, size_t sz
, const char *fmt
, ...) at(3, 4);
63 /* memory allocations don't fail in FRR, so you always get something here.
64 * (in case of error, returns a strdup of the format string) */
65 char *vasprintfrr(struct memtype
*mt
, const char *fmt
, va_list) atm(2, 0);
66 char *asprintfrr(struct memtype
*mt
, const char *fmt
, ...) atm(2, 3);
68 /* try to use provided buffer (presumably from stack), allocate if it's too
69 * short. Must call XFREE(mt, return value) if return value != out.
71 char *vasnprintfrr(struct memtype
*mt
, char *out
, size_t sz
,
72 const char *fmt
, va_list) atn(4, 0);
73 char *asnprintfrr(struct memtype
*mt
, char *out
, size_t sz
,
74 const char *fmt
, ...) atn(4, 5);
79 /* extension specs must start with a capital letter (this is a restriction
80 * for both performance's and human understanding's sake.)
82 * Note that the entire thing mostly works because a letter directly following
83 * a %p print specifier is extremely unlikely to occur (why would you want to
84 * print "0x12345678HELLO"?) Normally, you'd expect spacing or punctuation
85 * after a placeholder. That also means that neither of those works well for
86 * extension purposes, e.g. "%p{foo}" is reasonable to see actually used.
88 * TODO: would be nice to support a "%pF%dF" specifier that consumes 2
89 * arguments, e.g. to pass an integer + a list of known values... can be
90 * done, but a bit tricky.
92 #define printfrr_ext_char(ch) ((ch) >= 'A' && (ch) <= 'Z')
95 /* embedded string to minimize cache line pollution */
98 /* both can be given, if not the code continues searching
99 * (you can do %pX and %dX in 2 different entries)
101 * return value: number of bytes consumed from the format string, so
102 * you can consume extra flags (e.g. register for "%pX", consume
103 * "%pXfoo" or "%pXbar" for flags.) Convention is to make those flags
104 * lowercase letters or numbers.
106 * bsz is a compile-time constant in printf; it's gonna be relatively
107 * small. This isn't designed to print Shakespeare from a pointer.
109 * prec is the precision specifier (the 999 in "%.999p") -1 means
110 * none given (value in the format string cannot be negative)
112 ssize_t (*print_ptr
)(char *buf
, size_t bsz
, const char *fmt
, int prec
,
114 ssize_t (*print_int
)(char *buf
, size_t bsz
, const char *fmt
, int prec
,
118 /* no locking - must be called when single threaded (e.g. at startup.)
119 * this restriction hopefully won't be a huge bother considering normal usage
122 void printfrr_ext_reg(const struct printfrr_ext
*);
124 #define printfrr_ext_autoreg_p(matchs, print_fn) \
125 static ssize_t print_fn(char *, size_t, const char *, int, \
127 static const struct printfrr_ext _printext_##print_fn = { \
129 .print_ptr = print_fn, \
131 static void _printreg_##print_fn(void) __attribute__((constructor)); \
132 static void _printreg_##print_fn(void) { \
133 printfrr_ext_reg(&_printext_##print_fn); \
137 #define printfrr_ext_autoreg_i(matchs, print_fn) \
138 static ssize_t print_fn(char *, size_t, const char *, int, uintmax_t); \
139 static const struct printfrr_ext _printext_##print_fn = { \
141 .print_int = print_fn, \
143 static void _printreg_##print_fn(void) __attribute__((constructor)); \
144 static void _printreg_##print_fn(void) { \
145 printfrr_ext_reg(&_printext_##print_fn); \