vsprintf

NAME

       printf,  fprintf,  sprintf,  vprintf, vfprintf, vsprintf -
       formatted output conversion

SYNOPSIS

       #include <stdio.h>

       int printf( const char *format, ...);
       int fprintf( FILE *stream, const char *format, ...);
       int sprintf( char *str, const char *format, ...);

       #include <stdarg.h>

       int vprintf( const char *format, va_list ap);
       int vfprintf( FILE *stream, const  char  *format,  va_list
       ap);
       int vsprintf( char *str, char *format, va_list ap);

DESCRIPTION

       The  printf  family of functions produces output according
       to a format as described below.  Printf and vprintf  write
       output  to stdout, the standard output stream; fprintf and
       vfprintf write output to the given output stream; sprintf,
       and  vsprintf  write  to  the character string str.  These
       functions write the output under the control of  a  format
       string  that  specifies how subsequent arguments (or argu-
       ments accessed via the variable-length argument facilities
       of  stdarg(3)  are  converted for output.  These functions
       return the number of characters printed (not including the
       trailing `##tresc##' used to end output to strings).

       The  format string is composed of zero or more directives:
       ordinary characters (not %), which are copied unchanged to
       the  output stream; and conversion specifications, each of
       which results in fetching zero or  more  subsequent  argu-
       ments.  Each conversion specification is introduced by the
       character  %.   The  arguments  must  correspond  properly
       (after  type  promotion)  with  the  conversion specifier.
       After the %, the following appear in sequence:

       o      Zero or more of the following flags:

              #      specifying that the  value  should  be  con-
                     verted  to an ``alternate form''.  For c, d,
                     i, n, p, s, and u conversions,  this  option
                     has  no effect.  For o conversions, the pre-
                     cision of the number is increased  to  force
                     the  first character of the output string to
                     a zero (except if a zero  value  is  printed
                     with  an explicit precision of zero).  For x
                     and X conversions, a non-zero result has the
                     string  `0x'  (or  `0X'  for  X conversions)
                     prepended to it.  For e, E, f, g, and G con-
                     versions,  the  result will always contain a
                     decimal point, even if no digits  follow  it
                     (normally,  a  decimal  point appears in the
                     results of those conversions only if a digit
                     follows).  For g and G conversions, trailing
                     zeros are not removed  from  the  result  as
                     they would otherwise be.

              0      specifying  zero  padding.   For all conver-
                     sions  except  n,  the  converted  value  is
                     padded  on  the  left with zeros rather than
                     blanks.  If a  precision  is  given  with  a
                     numeric  conversion  (d,  i, o, u, i, x, and
                     X), the 0 flag is ignored.

              -      (a negative field width flag) indicates  the
                     converted  value  is  to be left adjusted on
                     the field boundary.  Except  for  n  conver-
                     sions,  the converted value is padded on the
                     right with blanks, rather than on  the  left
                     with  blanks or zeros.  A - overrides a 0 if
                     both are given.

                     (a space) specifying that a blank should  be
                     left  before a positive number produced by a
                     signed conversion (d, e, E, f, g, G, or  i).

              +      specifying  that  a  sign  always  be placed
                     before a number produced by a signed conver-
                     sion.   A  +  overrides  a space if both are
                     used.

       o      An optional decimal digit string specifying a mini-
              mum  field width.  If the converted value has fewer
              characters than the field width, it will be  padded
              with  spaces  on  the  left (or right, if the left-
              adjustment flag has been given)  to  fill  out  the
              field width.

       o      An  optional  precision,  in  the  form of a period
              (`.')  followed by an optional  digit  string.   If
              the digit string is omitted, the precision is taken
              as zero.  This gives the minimum number  of  digits
              to appear for d, i, o, u, x, and X conversions, the
              number of digits to appear after the  decimal-point
              for  e, E, and f conversions, the maximum number of
              significant digits for g and G conversions, or  the
              maximum  number  of characters to be printed from a
              string for s conversions.

       o      The optional character h, specifying that a follow-
              ing d, i, o, u, x, or X conversion corresponds to a
              short int or unsigned short int argument, or that a
              following  n conversion corresponds to a pointer to
              a short int argument.

       o      The optional character l (ell)  specifying  that  a
              following d, i, o, u, x, or X conversion applies to
              a pointer to a long int or unsigned long int  argu-
              ment,  or that a following n conversion corresponds
              to a pointer to a long int argument.

       o      The character L specifying that a following  e,  E,
              f,  g, or G conversion corresponds to a long double
              argument.

       o      A character that specifies the type  of  conversion
              to be applied.

       A  field  width or precision, or both, may be indicated by
       an asterisk `*' instead of a digit string.  In this  case,
       an  int argument supplies the field width or precision.  A
       negative field width is treated as a left adjustment  flag
       followed  by  a positive field width; a negative precision
       is treated as though it were missing.

       The conversion specifiers and their meanings are:

       diouxX The int (or appropriate variant) argument  is  con-
              verted  to signed decimal (d and i), unsigned octal
              (o, unsigned decimal (u, or unsigned hexadecimal (x
              and X) notation.  The letters abcdef are used for x
              conversions; the letters ABCDEF are used for X con-
              versions.  The precision, if any, gives the minimum
              number of digits that must appear; if the converted
              value  requires  fewer  digits, it is padded on the
              left with zeros.

       DOU    The long int argument is converted to signed  deci-
              mal, unsigned octal, or unsigned decimal, as if the
              format had been ld, lo, or lu respectively.   These
              conversion  characters  are  deprecated,  and  will
              eventually disappear.

       eE     The double argument is rounded and converted in the
              style  [-]d.dddedd  where there is one digit before
              the decimal-point character and the number of  dig-
              its after it is equal to the precision; if the pre-
              cision is missing, it is taken as 6; if the  preci-
              sion  is  zero, no decimal-point character appears.
              An E conversion uses the letter E (rather  than  e)
              to  introduce  the  exponent.   The exponent always
              contains at least two digits; if the value is zero,
              the exponent is 00.

       f      The  double  argument  is  rounded and converted to
              decimal notation in the style [-]ddd.ddd, where the
              number  of digits after the decimal-point character
              is equal to the precision  specification.   If  the
              precision  is  missing,  it  is  taken as 6; if the
              precision  is  explicitly  zero,  no  decimal-point
              character  appears.  If a decimal point appears, at
              least one digit appears before it.

       g      The double argument is converted in style  f  or  e
              (or  E for G conversions).  The precision specifies
              the number of significant digits.  If the precision
              is missing, 6 digits are given; if the precision is
              zero, it is treated as 1.  Style e is used  if  the
              exponent  from  its  conversion  is less than -4 or
              greater than or equal to the  precision.   Trailing
              zeros  are  removed from the fractional part of the
              result; a decimal point appears only if it is  fol-
              lowed by at least one digit.

       c      The  int argument is converted to an unsigned char,
              and the resulting character is written.

       s      The ``char *'' argument is expected to be a pointer
              to  an  array  of  character  type  (pointer  to  a
              string).  Characters from the array are written  up
              to (but not including) a terminating NUL character;
              if a precision is specified, no more than the  num-
              ber  specified  are  written.   If  a  precision is
              given, no null character need be  present;  if  the
              precision  is not specified, or is greater than the
              size of the array, the array must contain a  termi-
              nating NUL character.

       p      The  ``void *'' pointer argument is printed in hex-
              adecimal (as if by %#x or %#lx).

       n      The number of characters written so far  is  stored
              into  the  integer  indicated  by the ``int *'' (or
              variant) pointer argument.   No  argument  is  con-
              verted.

       %      A  `%'  is  written.  No argument is converted. The
              complete conversion specification is `%%'.

       In no case does a non-existent or small field width  cause
       truncation  of  a  field; if the result of a conversion is
       wider than the field width, the field is expanded to  con-
       tain the conversion result.

EXAMPLES

       To  print  a  date  and  time in the form `Sunday, July 3,
       10:02', where weekday and month are pointers to strings:
              #include <stdio.h>
              fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
                   weekday, month, day, hour, min);

       To print to five decimal places:
              #include <math.h>
              #include <stdio.h>
              fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));

       To allocate a 128 byte string and print into it:
              #include <stdio.h>
              #include <stdlib.h>
              #include <stdarg.h>
              char *newfmt(const char *fmt, ...)
              {
                        char *p;
                        va_list ap;
                        if ((p = malloc(128)) == NULL)
                             return (NULL);
                        va_start(ap, fmt);
                        (void) vsnprintf(p, 128, fmt, ap);
                        va_end(ap);
                        return (p);
              }

SEE ALSO

       printf(1), scanf(3)

STANDARDS

       The  fprintf,  printf,  sprintf,  vprintf,  vfprintf,  and
       vsprintf  functions  conform  to  ANSI C3.159-1989 (``ANSI
       C'').

BUGS

       Some floating point conversions under Linux  cause  memory
       leaks.

       The conversion formats %D, %O, and %U are not standard and
       are provided only for backward compatibility.   These  may
       not be provided under Linux.

       The  effect of padding the %p format with zeros (either by
       the 0 flag or by specifying a precision), and  the  benign
       effect  (i.e.,  none)  of  the # flag on %n and %p conver-
       sions, as well as other nonsensical combinations  such  as
       %Ld,   are  not  standard;  such  combinations  should  be
       avoided.

       Because sprintf and vsprintf  assume  an  infinitely  long
       string, callers must be careful not to overflow the actual
       space; this is often impossible to assure.