SEPRINTF(7)            Miscellaneous Information Manual            SEPRINTF(7)

NAME
     seprintf – an snprintf alternative

SYNOPSIS
     char *
     seprintf(char *ptr, char *end, const char *fmt, ...);

DESCRIPTION
     While discussing string building in C recently, mcf pointed out
     seprint(2) from Plan 9, and it kind of blew my mind.  I had implemented
     my own function in catgirl(1) for building up strings using snprintf(3)
     and a struct containing pointer, length and capacity, but it felt out of
     place.  seprintf() (I add the “f”, Plan 9 doesn't) is a much simpler and
     more “C-like” interface with really nice usage patterns.

     The obvious difference from snprintf(3) is that seprintf() takes an end
     pointer rather than a size.  This means you need only calculate it once
     for each buffer, rather than subtracting the running length from the
     buffer size.  seprintf()'s return value is a pointer to the terminating
     null of the string it wrote, so you can pass that back in to continue
     appending to the same buffer.

     I'm not sure of the exact behaviour on Plan 9, but my implementation
     indicates truncation occurred by returning the end pointer.  That makes
     it both easy to check, and perfectly fine to keep calling seprintf()
     anyway.  It just won't write anything if ptr == end.

     In the case of formatting failure (which should be prevented by compile-
     time format string checking, but should still be considered), seprintf()
     returns NULL.  I'm again not sure if this matches Plan 9.  I like this a
     lot better than snprintf(3) returning -1, because an unchecked NULL is
     likely to quickly cause a crash, while blindly adding snprintf(3)'s
     return value to your running length is a non-obvious logic error.

EXAMPLES
     Here's an example of what some code using seprintf() might look like:

           char buf[4096];
           char *ptr = buf, *end = &buf[sizeof(buf)];
           ptr = seprintf(ptr, end, "argv: ");
           for (int i = 1; i < argc; ++i) {
                   ptr = seprintf(
                           ptr, end, "%s%s",
                           (i > 1 ? ", " : ""), argv[i]
                   );
           }
           if (ptr == end) errx(1, "truncation occurred :(");

     And here is the very short implementation of it against vsnprintf(3)
     which I copy into my project header files:

           #include <stdarg.h>
           #include <stdio.h>
           static inline char *
           seprintf(char *ptr, char *end, const char *fmt, ...)
                   __attribute__((format(printf, 3, 4)));
           static inline char *
           seprintf(char *ptr, char *end, const char *fmt, ...) {
                   va_list ap;
                   va_start(ap, fmt);
                   int n = vsnprintf(ptr, end - ptr, fmt, ap);
                   va_end(ap);
                   if (n < 0) return NULL;
                   if (n > end - ptr) return end;
                   return ptr + n;
           }

AUTHORS
     june <june@causal.agency>

     Another short one before git-subtree(1).  I just think this function is
     really neat.

Causal Agency                    June 12, 2021                   Causal Agency