INDEP - TXT_#?
 ----------------------------------------------------------------------------

   NAME

      txt_vpsnprintf() - Produces output according to the format.



   SYNOPSIS

      length = txt_vpsnprintf(buffer, size, vfmt, ap);

      LONG txt_vpsnprintf(UBYTE *, LONG, const UBYTE *, va_list);



   FUNCTION

      This function allows to build a string with the help of
      different datatypes represented as a clear text. Format
      options begin with '%' character and are:


         '+' - Upper case string/char output.

         '-' - Lower case string/char output.

         '0' - When put right after the format pointer will allow
               zero padding with digits(0-9). Padding is also
               possible with the space. In such case one needs to
               start with '1' onwards.

         'l' - If put once will indicate LONG datatype, when put
               once more will indicate QUAD.

         'N' - This modifier can be used together with 'b' and
               's' to detect NULL pointers.

         'q' - This is QUAD modifier and can be used with all the
               integer outputting options below.

         't' - This is number of bits modifier. Effective output
               will be number of bits this integer consists of.



         'B' - Output integer as a binary stream.

         'b' - Output BSTR(Amiga non-NULL terminated string).

         'c' - Output one character excluding 0.

         'd' - Output signed decimal value.

         'i' - Same as above.

         'M' - Load size of the upcoming memory data as passed
               with 'm'.

         'm' - Output non-NULL terminated string or data.

         'O' - Output octal value.

         'o' - Same as above.

         's' - Output NULL terminated string.

         'U' - Output unsigned integer value.

         'u' - Same as above.

         'X' - Output the int. as a hex. with upper case letters.

         'x' - Output the int. as a hex. with lower case letters.



   INPUTS

      buffer - Output buffer(will be NULL terminated).

      size   - Output buffer size.

      vfmt   - Formatting string.

      ap     - Variable args pointer.



   RETURNS

      Returns length of newly formatted string or negative value
      if string had to be truncated.



   BASES

      None.



   NOTES

      There is a wrapper function for direct use and it is called
      'txt_psnprintf()'.

      Truncation can be detected by adding buffer size to the
      output of the function. If it is 1 then the last call did
      truncate the output.

      Beware! Using '%b' with BCPL data on stack may result in
      address mess! All  addresses to be BCPLed must  be multiple
      of 4! See 'testsuite/textfuncs-test.c' for more details.



   SEE ALSO

      txt_psnprintf()



   EXAMPLE

      None.



   BUGS

      None known.                                  



 ----------------------------------------------------------------------------