*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> fprintf (3)              
Title
Content
Arch
Section
 

PRINTF(3)

Contents


NAME    [Toc]    [Back]

     printf,  fprintf,  sprintf,  snprintf,  asprintf,   vprintf,
vfprintf,
     vsprintf, vsnprintf, vasprintf - formatted output conversion

SYNOPSIS    [Toc]    [Back]

     #include <stdio.h>

     int
     printf(const char *format, ...);

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

     int
     sprintf(char *str, const char *format, ...);

     int
     snprintf(char *str, size_t size, const char *format, ...);

     int
     asprintf(char **ret, 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, const char *format, va_list ap);

     int
     vsnprintf(char  *str,  size_t  size,  const  char   *format,
va_list ap);

     int
     vasprintf(char **ret, const char *format, va_list ap);

DESCRIPTION    [Toc]    [Back]

     The printf() family of functions produce output according to
the given
     format as described below.  This format may  contain  ``conversion
     specifiers'';  the  results of such conversions, if any, depend on the arguments
 following the format string.

     The printf() and vprintf() functions  write  output  to  the
standard output
     stream, stdout; fprintf() and vfprintf() write output to the
supplied
     stream pointer stream;  sprintf(),  snprintf(),  vsprintf(),
and vsnprintf()
     write   to   the   character   string  str;  asprintf()  and
vasprintf() write to a
     dynamically allocated string that is stored in ret.

     These functions write the output  under  the  control  of  a
format string
     that  specifies  how  subsequent arguments (or arguments 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 ` ' used to end output to strings), except  for
snprintf()
     and  vsnprintf(), which return the number of characters that
would have
     been printed if the size were unlimited (again, not  including the final
     ` ').   If an output or encoding error occurs, a value of -1
is returned
     instead.

     asprintf() and vasprintf() return a pointer to a buffer sufficiently
     large  to hold the string in the ret argument.  This pointer
should be
     passed to free(3) to release the allocated storage  when  it
is no longer
     needed.   If  sufficient  space  cannot  be allocated, these
functions will
     return -1.  The value of ret in this situation is  implementation-dependent
  (on  OpenBSD, ret will be set to the null pointer, but
this behavior
     should not be relied upon).

     snprintf() and vsnprintf() will write at most size-1 of  the
characters
     printed  into  the output string (the size'th character then
gets the terminating
 ` '); if the return value is greater than or  equal
to the size
     argument,  the  string was too short and some of the printed
characters
     were discarded.

     sprintf() and  vsprintf()  effectively  assume  an  infinite
size.

     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 arguments.  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    An optional field, consisting of a decimal digit string
followed by a
         $ specifying the next argument to access.  If this field
is not provided,
 the argument following the last argument accessed
will be
         used.  Arguments are numbered starting at 1.

     +o   Zero or more of the following flags:

         -   A hash  `#'  character  specifying  that  the  value
should be converted
  to an ``alternate form''.  For c, d, i, n, p, s,
and u conversions,
 this option has no  effect.   For  o  conversions, the precision
  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 conversions,
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.

         -   A zero `0' character specifying zero  padding.   For
all conversions
 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, 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 conversions,
 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).

         -   A `+' character specifying that  a  sign  always  be
placed before a
             number produced by a signed conversion.  A `+' overrides a space
             if both are used.

     +o   An optional decimal digit string  specifying  a  minimum
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 following 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 corresponds to a long int  or  unsigned long int
         argument,  or  that a following n conversion corresponds
to a pointer
         to a long int argument.

     +o   The optional character sequence ll,  specifying  that  a
following d, i,
         o,  u,  x,  or X conversion corresponds to a quad int or
unsigned quad
         int argument, or that a following  n  conversion  corresponds to a
         pointer  to  a quad int argument.  The use of q has been
deprecated as
         conversion character.

     +o   The character L specifying that a following e, E, f,  g,
or G conversion
  corresponds  to  a  long double argument (but note
that long double
         values are not currently supported by the VAX compiler).

     +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 `*'
     or  an asterisk followed by one or more decimal digits and a
`$' 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.  If a single format directive mixes
     positional (nn$) and non-positional arguments,  the  results
are undefined.

     The conversion specifiers and their meanings are:

     diouxX   The  int  (or appropriate variant) argument is converted 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 conversions.
   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 decimal, 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.ddde+-dd  where  there  is one digit before the
decimal-point
             character and the number of digits after it is equal
to the precision;
  if the precision is missing, it is taken as
6; if the
             precision 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.

     gG      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 followed 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
number 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
terminating
             NUL character.

     p       The void * pointer argument is printed in  hexadecimal (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 converted.

     %        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 contain the conversion result.

EXAMPLES    [Toc]    [Back]

     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:%.2d0,
               weekday, month, day, hour, min);

     To print pi to five decimal places:

           #include <math.h>
           #include <stdio.h>

           fprintf(stdout, "pi = %.5f0, 4 * atan(1.0));

     To allocate a 128 byte string and print into it:

           #include <stdarg.h>
           #include <stdio.h>
           #include <stdlib.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    [Toc]    [Back]

      
      
     printf(1), scanf(3)

STANDARDS    [Toc]    [Back]

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

HISTORY    [Toc]    [Back]

     The functions snprintf() and vsnprintf() first  appeared  in
4.4BSD.

     The  functions  asprintf() and vasprintf() first appeared in
the GNU C library.
  This implementation first appeared in OpenBSD 2.3.

CAVEATS    [Toc]    [Back]

     The conversion formats %D, %O, and %U are not  standard  and
are provided
     only  for backward compatibility.  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 conversions, 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.   For safety, programmers should use
the snprintf()
     and asprintf() family of interfaces instead.  Unfortunately,
the
     snprintf()  interface  is not available on older systems and
the asprintf()
     interface is not portable.

     It is important never to pass a  string  with  user-supplied
data as a format
  without  using `%s'.  An attacker can put format specifiers in the
     string to mangle your stack, leading to a possible  security
hole.  This
     holds true even if you have built the string ``by hand'' using a function
     like snprintf(), as the resulting string may  still  contain
user-supplied
     conversion specifiers for later interpolation by printf().

     Be sure to use the proper secure idiom:

           snprintf(buffer, sizeof(buffer), "%s", string);

     There is no way for printf to know the size of each argument
passed.  If
     you use positional arguments you must ensure that all parameters, up to
     the  last  positionally specified parameter, are used in the
format string.
     This allows for the format string to be parsed for this  information.
     Failure  to  do this will mean your code is non-portable and
liable to
     fail.

OpenBSD      3.6                           June      4,      1993
[ Back ]
 Similar pages
Name OS Title
tprintf NetBSD kernel formatted output conversion
kprintf NetBSD kernel formatted output conversion
printf NetBSD kernel formatted output conversion
sprintf NetBSD kernel formatted output conversion
vprintf NetBSD kernel formatted output conversion
tprintf_close NetBSD kernel formatted output conversion
tprintf_open NetBSD kernel formatted output conversion
ttyprintf NetBSD kernel formatted output conversion
vsprintf NetBSD kernel formatted output conversion
uprintf NetBSD kernel formatted output conversion
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service