doc/invoke-snprintfv.texi

   1 @node snprintfv
   2 @section Replacement for Stdio Formatting Library
   3
   4    Using the `printf' formatting routines in a portable fashion has
   5 always been a pain, and this package has been way more pain than anyone
   6 ever imagined.  Hopefully, with this release of snprintfv, the pain is
   7 now over for all time.
   8
   9    The issues with portable usage are these:
  10
  11 @enumerate
  12 @item
  13 Argument number specifiers are often either not implemented or are
  14 buggy.  Even GNU libc, version 1 got it wrong.
  15
  16 @item
  17 ANSI/ISO "forgot" to provide a mechanism for computing argument
  18 lists for vararg procedures.
  19
  20 @item
  21 The argument array version of printf (`printfv()') is not
  22 generally available, does not work with the native printf, and
  23 does not have a working argument number specifier in the format
  24 specification.  (Last I knew, anyway.)
  25
  26 @item
  27 You cannot fake varargs by calling `vprintf()' with an array of
  28 arguments, because ANSI does not require such an implementation
  29 and some vendors play funny tricks because they are allowed to.
  30 @end enumerate
  31
  32    These four issues made it impossible for AutoGen to ship without its
  33 own implementation of the `printf' formatting routines.  Since we were
  34 forced to do this, we decided to make the formatting routines both
  35 better and more complete :-).  We addressed these issues and added the
  36 following features to the common printf API:
  37
  38 @enumerate 5
  39 @item
  40 The formatted output can be written to
  41
  42 @itemize @bullet
  43 @item
  44 a string allocated by the formatting function (`asprintf()').
  45 @item
  46 a file descriptor instead of a file stream (`dprintf()').
  47 @item
  48 a user specified stream (`stream_printf()').
  49 @end itemize
  50
  51 @item
  52 The formatting functions can be augmented with your own functions.
  53 These functions are allowed to consume more than one character
  54 from the format, but must commence with a unique character.  For
  55 example,
  56
  57 @example
  58 "%@{struct stat@}\n"
  59 @end example
  60
  61 might be used with '@{' registered to a procedure that would look
  62 up "struct stat" in a symbol table and do appropriate things,
  63 consuming the format string through the '@}' character.
  64 @end enumerate
  65
  66    Gary V. Vaughan was generous enough to supply this implementation.
  67 Many thanks!!
  68
  69    For further details, the reader is referred to the snprintfv
  70 documentation.  These functions are also available in the template
  71 processing as@:  `sprintf' (@pxref{SCM sprintf}), `printf'
  72 (@pxref{SCM printf}), `fprintf' (@pxref{SCM fprintf}), and `shellf'
  73 (@pxref{SCM shellf}).
  74