]>
git.proxmox.com Git - mirror_frr.git/blob - lib/printfrr.h
1 // SPDX-License-Identifier: ISC
3 * Copyright (c) 2019 David Lamparter, for NetDEF, Inc.
6 #ifndef _FRR_PRINTFRR_H
7 #define _FRR_PRINTFRR_H
21 unsigned int off_start
, off_end
;
29 struct fmt_outpos
*outpos
;
30 size_t outpos_n
, outpos_i
;
33 #define at(a, b) PRINTFRR(a, b)
35 at(a, b) __attribute__((nonnull(1) _RET_NONNULL))
37 atn(a, b) __attribute__((malloc))
39 /* return value is length needed for the full string (excluding \0) in all
40 * cases. The functions write as much as they can, but continue regardless,
41 * so the return value is independent of buffer length. Both bprintfrr and
42 * snprintf also accept NULL as output buffer.
45 /* bprintfrr does NOT null terminate! use sparingly (only provided since it's
46 * the most direct interface) - useful for incrementally building long text
47 * (call bprintfrr repeatedly with the same buffer)
49 ssize_t
vbprintfrr(struct fbuf
*out
, const char *fmt
, va_list) at(2, 0);
50 ssize_t
bprintfrr(struct fbuf
*out
, const char *fmt
, ...) at(2, 3);
52 /* these do null terminate like their snprintf cousins */
53 ssize_t
vsnprintfrr(char *out
, size_t sz
, const char *fmt
, va_list) at(3, 0);
54 ssize_t
snprintfrr(char *out
, size_t sz
, const char *fmt
, ...) at(3, 4);
56 /* c = continue / concatenate (append at the end of the string)
57 * return value is would-be string length (regardless of buffer length),
58 * i.e. includes already written chars */
59 ssize_t
vcsnprintfrr(char *out
, size_t sz
, const char *fmt
, va_list) at(3, 0);
60 ssize_t
csnprintfrr(char *out
, size_t sz
, const char *fmt
, ...) at(3, 4);
62 /* memory allocations don't fail in FRR, so you always get something here.
63 * (in case of error, returns a strdup of the format string) */
64 char *vasprintfrr(struct memtype
*mt
, const char *fmt
, va_list) atm(2, 0);
65 char *asprintfrr(struct memtype
*mt
, const char *fmt
, ...) atm(2, 3);
67 /* try to use provided buffer (presumably from stack), allocate if it's too
68 * short. Must call XFREE(mt, return value) if return value != out.
70 char *vasnprintfrr(struct memtype
*mt
, char *out
, size_t sz
,
71 const char *fmt
, va_list) atn(4, 0);
72 char *asnprintfrr(struct memtype
*mt
, char *out
, size_t sz
,
73 const char *fmt
, ...) atn(4, 5);
75 #define printfrr(fmt, ...) \
77 char buf[256], *out; \
78 out = asnprintfrr(MTYPE_TMP, buf, sizeof(buf), fmt, \
82 XFREE(MTYPE_TMP, out); \
89 /* extension specs must start with a capital letter (this is a restriction
90 * for both performance's and human understanding's sake.)
92 * Note that the entire thing mostly works because a letter directly following
93 * a %p print specifier is extremely unlikely to occur (why would you want to
94 * print "0x12345678HELLO"?) Normally, you'd expect spacing or punctuation
95 * after a placeholder. That also means that neither of those works well for
96 * extension purposes, e.g. "%p{foo}" is reasonable to see actually used.
98 * TODO: would be nice to support a "%pF%dF" specifier that consumes 2
99 * arguments, e.g. to pass an integer + a list of known values... can be
100 * done, but a bit tricky.
102 #define printfrr_ext_char(ch) ((ch) >= 'A' && (ch) <= 'Z')
104 struct printfrr_eargs
;
106 struct printfrr_ext
{
107 /* embedded string to minimize cache line pollution */
110 /* both can be given, if not the code continues searching
111 * (you can do %pX and %dX in 2 different entries)
113 * return value: number of bytes that would be printed if the buffer
114 * was large enough. be careful about not under-reporting this;
115 * otherwise asnprintf() & co. will get broken. Returning -1 means
116 * something went wrong & default %p/%d handling should be executed.
118 * to consume extra input flags after %pXY, increment *fmt. It points
119 * at the first character after %pXY at entry. Convention is to make
120 * those flags lowercase letters or numbers.
122 ssize_t (*print_ptr
)(struct fbuf
*buf
, struct printfrr_eargs
*info
,
124 ssize_t (*print_int
)(struct fbuf
*buf
, struct printfrr_eargs
*info
,
128 /* additional information passed to extended formatters */
130 struct printfrr_eargs
{
131 /* position in the format string. Points to directly after the
132 * extension specifier. Increment when consuming extra "flag
138 * not POSIX compatible when used with %p, will cause warnings from
139 * GCC & clang. Usable with %d. Not used by the printfrr() itself
140 * for extension specifiers, so essentially available as a "free"
141 * parameter. -1 if not specified. Value in the format string
142 * cannot be negative, but negative values can be passed with %.*x
147 * regular width specification. Internally handled by printfrr(), set
148 * to 0 if consumed by the extension in order to suppress standard
149 * width/padding behavior. 0 if not specified.
151 * NB: always positive, even if a negative value is passed in with
152 * %*x. (The sign is used for the - flag.)
157 * "alternate representation" flag, not POSIX compatible when used
158 * with %p or %d, will cause warnings from GCC & clang. Not used by
159 * printfrr() itself for extension specifiers.
164 * left-pad flag. Internally handled by printfrr() if width is
165 * nonzero. Only use if the extension sets width to 0.
170 /* for any extension that needs a buffer length */
172 static inline ssize_t
printfrr_ext_len(struct printfrr_eargs
*ea
)
176 if (ea
->precision
>= 0)
178 else if (ea
->width
>= 0) {
187 /* no locking - must be called when single threaded (e.g. at startup.)
188 * this restriction hopefully won't be a huge bother considering normal usage
191 void printfrr_ext_reg(const struct printfrr_ext
*);
193 #define printfrr_ext_autoreg_p(matchs, print_fn) \
194 static ssize_t print_fn(struct fbuf *, struct printfrr_eargs *, \
196 static const struct printfrr_ext _printext_##print_fn = { \
198 .print_ptr = print_fn, \
200 static void _printreg_##print_fn(void) __attribute__((constructor)); \
201 static void _printreg_##print_fn(void) \
203 printfrr_ext_reg(&_printext_##print_fn); \
205 MACRO_REQUIRE_SEMICOLON()
207 #define printfrr_ext_autoreg_i(matchs, print_fn) \
208 static ssize_t print_fn(struct fbuf *, struct printfrr_eargs *, \
210 static const struct printfrr_ext _printext_##print_fn = { \
212 .print_int = print_fn, \
214 static void _printreg_##print_fn(void) __attribute__((constructor)); \
215 static void _printreg_##print_fn(void) \
217 printfrr_ext_reg(&_printext_##print_fn); \
219 MACRO_REQUIRE_SEMICOLON()
221 /* fbuf helper functions - note all 3 of these return the length that would
222 * be written regardless of how much space was available in the buffer, as
223 * needed for implementing printfrr extensions. (They also accept NULL buf
227 static inline ssize_t
bputs(struct fbuf
*buf
, const char *str
)
229 size_t len
= strlen(str
);
235 ncopy
= MIN(len
, (size_t)(buf
->buf
+ buf
->len
- buf
->pos
));
236 memcpy(buf
->pos
, str
, ncopy
);
242 static inline ssize_t
bputch(struct fbuf
*buf
, char ch
)
244 if (buf
&& buf
->pos
< buf
->buf
+ buf
->len
)
249 static inline ssize_t
bputhex(struct fbuf
*buf
, uint8_t val
)
251 static const char hexch
[] = "0123456789abcdef";
253 if (buf
&& buf
->pos
< buf
->buf
+ buf
->len
)
254 *buf
->pos
++ = hexch
[(val
>> 4) & 0xf];
255 if (buf
&& buf
->pos
< buf
->buf
+ buf
->len
)
256 *buf
->pos
++ = hexch
[val
& 0xf];
260 /* %pVA extension, equivalent to Linux kernel %pV */
267 #ifdef _FRR_ATTRIBUTE_PRINTFRR
268 #pragma FRR printfrr_ext "%pFB" (struct fbuf *)
269 #pragma FRR printfrr_ext "%pVA" (struct va_format *)
271 #pragma FRR printfrr_ext "%pHX" (signed char *)
272 #pragma FRR printfrr_ext "%pHX" (unsigned char *)
273 #pragma FRR printfrr_ext "%pHX" (void *)
274 #pragma FRR printfrr_ext "%pHS" (signed char *)
275 #pragma FRR printfrr_ext "%pHS" (unsigned char *)
276 #pragma FRR printfrr_ext "%pHS" (void *)
278 #pragma FRR printfrr_ext "%pSE" (char *)
279 #pragma FRR printfrr_ext "%pSQ" (char *)
281 #pragma FRR printfrr_ext "%pTS" (struct timespec *)
282 #pragma FRR printfrr_ext "%pTV" (struct timeval *)
283 #pragma FRR printfrr_ext "%pTT" (time_t *)
286 /* when using non-ISO-C compatible extension specifiers... */
288 #ifdef _FRR_ATTRIBUTE_PRINTFRR
289 #define FMT_NSTD_BEGIN
291 #else /* !_FRR_ATTRIBUTE_PRINTFRR */
292 #define FMT_NSTD_BEGIN \
293 _Pragma("GCC diagnostic push") \
294 _Pragma("GCC diagnostic ignored \"-Wformat\"") \
296 #define FMT_NSTD_END \
297 _Pragma("GCC diagnostic pop") \
301 #define FMT_NSTD(expr) \