@@@ timeout wip

[mLib] / utils / gprintf.h

diff --git a/utils/gprintf.h b/utils/gprintf.h
index 9e32338827690f0a4534f4a506a00e2b301a6d27..8c0f87c903f44320771a30c3aedb13a992cff697 100644 (file)
--- a/utils/gprintf.h
+++ b/utils/gprintf.h
@@ -45,8 +45,8 @@
 struct gprintf_ops {
   int (*putch)(void */*out*/, int /*ch*/);
   int (*putm)(void */*out*/, const char */*p*/, size_t /*sz*/);
-  PRINTF_LIKE(3, 4) int (*nputf)
-    (void */*out*/, size_t /*maxsz*/, const char */*p*/, ...);
+  PRINTF_LIKE(3, 4)
+    int (*nputf)(void */*out*/, size_t /*maxsz*/, const char */*p*/, ...);
 };
 
 extern const struct gprintf_ops file_printops;
@@ -82,9 +82,36 @@ extern int vgprintf(const struct gprintf_ops */*ops*/, void */*out*/,
  *             for @dstr_putf@, for example.
  */
 
-extern int PRINTF_LIKE(3, 4)
-  gprintf(const struct gprintf_ops */*ops*/, void */*out*/,
-         const char */*p*/, ...);
+extern PRINTF_LIKE(3, 4)
+  int gprintf(const struct gprintf_ops */*ops*/, void */*out*/,
+             const char */*p*/, ...);
+
+/* --- @gprintf_memputf@ --- *
+ *
+ * Arguments:  @char **buf_inout@ = address of output buffer pointer
+ *             @size_t *sz_inout@ = address of buffer size
+ *             @size_t maxsz@ = buffer size needed for this operation
+ *             @const char *p@ = pointer to format string
+ *             @va_list *ap@ = captured format-arguments tail
+ *
+ * Returns:    The formatted length.
+ *
+ * Use:                Generic utility for mostly implementing the @nputf@ output
+ *             function, if you don't have a better option.
+ *
+ *             On entry, @*buf_inout@ should be null or a buffer pointer,
+ *             with @*sz_inout@ either zero or the buffer's size,
+ *             respectively.  On exit, @*buf_input@ and @*sz_inout@ will be
+ *             updated, if necessary, to describe a sufficiently large
+ *             buffer, and the formatted string will have been written to
+ *             the buffer.
+ *
+ *             When the buffer is no longer required, free it using @xfree@.
+ */
+
+extern size_t gprintf_memputf(char **/*buf_inout*/, size_t */*sz_inout*/,
+                             size_t /*maxsz*/,
+                             const char */*p*/, va_list /*ap*/);
 
 /*----- That's all, folks -------------------------------------------------*/