X-Git-Url: https://git.distorted.org.uk/~mdw/mLib/blobdiff_plain/814e42ff7421d66c0a2e33af5765afa2078bc18f..adec5584e13c63662fda18915280ec026063b29d:/utils/gprintf.h

diff --git a/utils/gprintf.h b/utils/gprintf.h
index 8c0f87c..7bb0b04 100644
--- a/utils/gprintf.h
+++ b/utils/gprintf.h
@@ -53,38 +53,32 @@ extern const struct gprintf_ops file_printops;
 
 /*----- Functions provided ------------------------------------------------*/
 
-/* --- @vgprintf@ --- *
+/* --- @gprintf@, @vgprintf@ --- *
  *
  * Arguments:	@const struct gprintf_ops *ops@ = output operations
  *		@void *out@ = context for output operations
  *		@const char *p@ = pointer to @printf@-style format string
- *		@va_list *ap@ = argument handle
- *
- * Returns:	The number of characters written to the string.
- *
- * Use:		As for @gprintf@, but takes a reified argument tail.
- */
-
-extern int vgprintf(const struct gprintf_ops */*ops*/, void */*out*/,
-		    const char */*p*/, va_list */*ap*/);
-
-/* --- @gprintf@ --- *
- *
- * Arguments:	@const struct gprintf_ops *ops@ = output operations
- *		@void *out@ = context for output operations
- *		@const char *p@ = pointer to @printf@-style format string
- *		@...@ = argument handle
+ *		@...@ = format arguments
+ *		@va_list *ap@ = captured format-arguments tail
  *
  * Returns:	The number of characters written to the string.
  *
  * Use:		Formats a @printf@-like message and writes the result using
  *		the given output operations.  This is the backend machinery
  *		for @dstr_putf@, for example.
+ *
+ *		The @gprintf@ function receives its format arguments as a
+ *		variable-length argument tail; the @vgprintf@ function
+ *		receives them as %%\emph{a pointer to}%% a captured argument
+ *		tail; it updates @*ap@, leaving it ready to read the next
+ *		unused argument.
  */
 
 extern PRINTF_LIKE(3, 4)
   int gprintf(const struct gprintf_ops */*ops*/, void */*out*/,
 	      const char */*p*/, ...);
+extern int vgprintf(const struct gprintf_ops */*ops*/, void */*out*/,
+		    const char */*p*/, va_list */*ap*/);
 
 /* --- @gprintf_memputf@ --- *
  *