lib/printfrr.h

   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>
  22 #include <stdint.h>
  23
  24 #include "compiler.h"
  25 #include "memory.h"
  26
  27 struct fbuf {
  28         char *buf;
  29         char *pos;
  30         size_t len;
  31 };
  32
  33 #define at(a, b) \
  34         __attribute__((format(printf, a, b)))
  35 #define atn(a, b) \
  36         at(a, b) __attribute__((nonnull(1) _RET_NONNULL))
  37 #define atm(a, b) \
  38         atn(a, b) __attribute__((malloc))
  39
  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.
  44  */
  45
  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)
  49  */
  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);
  52
  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);
  56
  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);
  62
  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);
  67
  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.
  70  */
  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);
  75
  76 #undef at
  77 #undef atm
  78
  79 /* extension specs must start with a capital letter (this is a restriction
  80  * for both performance's and human understanding's sake.)
  81  *
  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.
  87  *
  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.
  91  */
  92 #define printfrr_ext_char(ch) ((ch) >= 'A' && (ch) <= 'Z')
  93
  94 struct printfrr_ext {
  95         /* embedded string to minimize cache line pollution */
  96         char match[8];
  97
  98         /* both can be given, if not the code continues searching
  99          * (you can do %pX and %dX in 2 different entries)
 100          *
 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.
 105          *
 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.
 108          *
 109          * prec is the precision specifier (the 999 in "%.999p")  -1 means
 110          * none given (value in the format string cannot be negative)
 111          */
 112         ssize_t (*print_ptr)(char *buf, size_t bsz, const char *fmt, int prec,
 113                         const void *);
 114         ssize_t (*print_int)(char *buf, size_t bsz, const char *fmt, int prec,
 115                         uintmax_t);
 116 };
 117
 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
 120  * scenarios...
 121  */
 122 void printfrr_ext_reg(const struct printfrr_ext *);
 123
 124 #define printfrr_ext_autoreg_p(matchs, print_fn)                               \
 125         static ssize_t print_fn(char *, size_t, const char *, int,             \
 126                                 const void *);                                 \
 127         static const struct printfrr_ext _printext_##print_fn = {              \
 128                 .match = matchs,                                               \
 129                 .print_ptr = print_fn,                                         \
 130         };                                                                     \
 131         static void _printreg_##print_fn(void) __attribute__((constructor));   \
 132         static void _printreg_##print_fn(void) {                               \
 133                 printfrr_ext_reg(&_printext_##print_fn);                       \
 134         }                                                                      \
 135         /* end */
 136
 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 = {              \
 140                 .match = matchs,                                               \
 141                 .print_int = print_fn,                                         \
 142         };                                                                     \
 143         static void _printreg_##print_fn(void) __attribute__((constructor));   \
 144         static void _printreg_##print_fn(void) {                               \
 145                 printfrr_ext_reg(&_printext_##print_fn);                       \
 146         }                                                                      \
 147         /* end */
 148
 149 #endif