]>
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
32 unsigned int off_start
, off_end
;
40 struct fmt_outpos
*outpos
;
41 size_t outpos_n
, outpos_i
;
44 #define at(a, b) PRINTFRR(a, b)
46 at(a, b) __attribute__((nonnull(1) _RET_NONNULL))
48 atn(a, b) __attribute__((malloc))
50 /* return value is length needed for the full string (excluding \0) in all
51 * cases. The functions write as much as they can, but continue regardless,
52 * so the return value is independent of buffer length. Both bprintfrr and
53 * snprintf also accept NULL as output buffer.
56 /* bprintfrr does NOT null terminate! use sparingly (only provided since it's
57 * the most direct interface) - useful for incrementally building long text
58 * (call bprintfrr repeatedly with the same buffer)
60 ssize_t
vbprintfrr(struct fbuf
*out
, const char *fmt
, va_list) at(2, 0);
61 ssize_t
bprintfrr(struct fbuf
*out
, const char *fmt
, ...) at(2, 3);
63 /* these do null terminate like their snprintf cousins */
64 ssize_t
vsnprintfrr(char *out
, size_t sz
, const char *fmt
, va_list) at(3, 0);
65 ssize_t
snprintfrr(char *out
, size_t sz
, const char *fmt
, ...) at(3, 4);
67 /* c = continue / concatenate (append at the end of the string)
68 * return value is would-be string length (regardless of buffer length),
69 * i.e. includes already written chars */
70 ssize_t
vcsnprintfrr(char *out
, size_t sz
, const char *fmt
, va_list) at(3, 0);
71 ssize_t
csnprintfrr(char *out
, size_t sz
, const char *fmt
, ...) at(3, 4);
73 /* memory allocations don't fail in FRR, so you always get something here.
74 * (in case of error, returns a strdup of the format string) */
75 char *vasprintfrr(struct memtype
*mt
, const char *fmt
, va_list) atm(2, 0);
76 char *asprintfrr(struct memtype
*mt
, const char *fmt
, ...) atm(2, 3);
78 /* try to use provided buffer (presumably from stack), allocate if it's too
79 * short. Must call XFREE(mt, return value) if return value != out.
81 char *vasnprintfrr(struct memtype
*mt
, char *out
, size_t sz
,
82 const char *fmt
, va_list) atn(4, 0);
83 char *asnprintfrr(struct memtype
*mt
, char *out
, size_t sz
,
84 const char *fmt
, ...) atn(4, 5);
86 #define printfrr(fmt, ...) \
88 char buf[256], *out; \
89 out = asnprintfrr(MTYPE_TMP, buf, sizeof(buf), fmt, \
93 XFREE(MTYPE_TMP, out); \
100 /* extension specs must start with a capital letter (this is a restriction
101 * for both performance's and human understanding's sake.)
103 * Note that the entire thing mostly works because a letter directly following
104 * a %p print specifier is extremely unlikely to occur (why would you want to
105 * print "0x12345678HELLO"?) Normally, you'd expect spacing or punctuation
106 * after a placeholder. That also means that neither of those works well for
107 * extension purposes, e.g. "%p{foo}" is reasonable to see actually used.
109 * TODO: would be nice to support a "%pF%dF" specifier that consumes 2
110 * arguments, e.g. to pass an integer + a list of known values... can be
111 * done, but a bit tricky.
113 #define printfrr_ext_char(ch) ((ch) >= 'A' && (ch) <= 'Z')
115 struct printfrr_eargs
;
117 struct printfrr_ext
{
118 /* embedded string to minimize cache line pollution */
121 /* both can be given, if not the code continues searching
122 * (you can do %pX and %dX in 2 different entries)
124 * return value: number of bytes that would be printed if the buffer
125 * was large enough. be careful about not under-reporting this;
126 * otherwise asnprintf() & co. will get broken. Returning -1 means
127 * something went wrong & default %p/%d handling should be executed.
129 * to consume extra input flags after %pXY, increment *fmt. It points
130 * at the first character after %pXY at entry. Convention is to make
131 * those flags lowercase letters or numbers.
133 ssize_t (*print_ptr
)(struct fbuf
*buf
, struct printfrr_eargs
*info
,
135 ssize_t (*print_int
)(struct fbuf
*buf
, struct printfrr_eargs
*info
,
139 /* additional information passed to extended formatters */
141 struct printfrr_eargs
{
142 /* position in the format string. Points to directly after the
143 * extension specifier. Increment when consuming extra "flag
149 * not POSIX compatible when used with %p, will cause warnings from
150 * GCC & clang. Usable with %d. Not used by the printfrr() itself
151 * for extension specifiers, so essentially available as a "free"
152 * parameter. -1 if not specified. Value in the format string
153 * cannot be negative, but negative values can be passed with %.*x
158 * regular width specification. Internally handled by printfrr(), set
159 * to 0 if consumed by the extension in order to suppress standard
160 * width/padding behavior. 0 if not specified.
162 * NB: always positive, even if a negative value is passed in with
163 * %*x. (The sign is used for the - flag.)
168 * "alternate representation" flag, not POSIX compatible when used
169 * with %p or %d, will cause warnings from GCC & clang. Not used by
170 * printfrr() itself for extension specifiers.
175 * left-pad flag. Internally handled by printfrr() if width is
176 * nonzero. Only use if the extension sets width to 0.
181 /* for any extension that needs a buffer length */
183 static inline ssize_t
printfrr_ext_len(struct printfrr_eargs
*ea
)
187 if (ea
->precision
>= 0)
189 else if (ea
->width
>= 0) {
198 /* no locking - must be called when single threaded (e.g. at startup.)
199 * this restriction hopefully won't be a huge bother considering normal usage
202 void printfrr_ext_reg(const struct printfrr_ext
*);
204 #define printfrr_ext_autoreg_p(matchs, print_fn) \
205 static ssize_t print_fn(struct fbuf *, struct printfrr_eargs *, \
207 static const struct printfrr_ext _printext_##print_fn = { \
209 .print_ptr = print_fn, \
211 static void _printreg_##print_fn(void) __attribute__((constructor)); \
212 static void _printreg_##print_fn(void) { \
213 printfrr_ext_reg(&_printext_##print_fn); \
217 #define printfrr_ext_autoreg_i(matchs, print_fn) \
218 static ssize_t print_fn(struct fbuf *, struct printfrr_eargs *, \
220 static const struct printfrr_ext _printext_##print_fn = { \
222 .print_int = print_fn, \
224 static void _printreg_##print_fn(void) __attribute__((constructor)); \
225 static void _printreg_##print_fn(void) { \
226 printfrr_ext_reg(&_printext_##print_fn); \
230 /* fbuf helper functions - note all 3 of these return the length that would
231 * be written regardless of how much space was available in the buffer, as
232 * needed for implementing printfrr extensions. (They also accept NULL buf
236 static inline ssize_t
bputs(struct fbuf
*buf
, const char *str
)
238 size_t len
= strlen(str
);
244 ncopy
= MIN(len
, (size_t)(buf
->buf
+ buf
->len
- buf
->pos
));
245 memcpy(buf
->pos
, str
, ncopy
);
251 static inline ssize_t
bputch(struct fbuf
*buf
, char ch
)
253 if (buf
&& buf
->pos
< buf
->buf
+ buf
->len
)
258 static inline ssize_t
bputhex(struct fbuf
*buf
, uint8_t val
)
260 static const char hexch
[] = "0123456789abcdef";
262 if (buf
&& buf
->pos
< buf
->buf
+ buf
->len
)
263 *buf
->pos
++ = hexch
[(val
>> 4) & 0xf];
264 if (buf
&& buf
->pos
< buf
->buf
+ buf
->len
)
265 *buf
->pos
++ = hexch
[val
& 0xf];
269 /* %pVA extension, equivalent to Linux kernel %pV */
276 #ifdef _FRR_ATTRIBUTE_PRINTFRR
277 #pragma FRR printfrr_ext "%pFB" (struct fbuf *)
278 #pragma FRR printfrr_ext "%pVA" (struct va_format *)
280 #pragma FRR printfrr_ext "%pHX" (signed char *)
281 #pragma FRR printfrr_ext "%pHX" (unsigned char *)
282 #pragma FRR printfrr_ext "%pHX" (void *)
283 #pragma FRR printfrr_ext "%pHS" (signed char *)
284 #pragma FRR printfrr_ext "%pHS" (unsigned char *)
285 #pragma FRR printfrr_ext "%pHS" (void *)
287 #pragma FRR printfrr_ext "%pSE" (char *)
288 #pragma FRR printfrr_ext "%pSQ" (char *)
291 /* when using non-ISO-C compatible extension specifiers... */
293 #ifdef _FRR_ATTRIBUTE_PRINTFRR
294 #define FMT_NSTD_BEGIN
296 #else /* !_FRR_ATTRIBUTE_PRINTFRR */
297 #define FMT_NSTD_BEGIN \
298 _Pragma("GCC diagnostic push") \
299 _Pragma("GCC diagnostic ignored \"-Wformat\"") \
301 #define FMT_NSTD_END \
302 _Pragma("GCC diagnostic pop") \
306 #define FMT_NSTD(expr) \