pprriinnttff() -- STDIO Function (libc)

Print formatted text
#iinncclluuddee <ssttddiioo.hh>
iinntt pprriinnttff(_f_o_r_m_a_t [,_a_r_g_1, .... _a_r_g_N])
cchhaarr *_f_o_r_m_a_t; [ddaattaa ttyyppee] _a_r_g_1, ... _a_r_g_N;

pprriinnttff() prints  formatted text.  It  uses the _f_o_r_m_a_t string  to specify an
output format for each _a_r_g, which it then writes on the standard output.

pprriinnttff() reads  characters from _f_o_r_m_a_t  one at a time;  any character other
than a percent sign `%' or  a string that is introduced with a percent sign
is copied directly  to the output.  A `%' tells  pprriinnttff() that what follows
specifies how the corresponding _a_r_g is to be formatted; the characters that
follow `%'  can set the  output width and  the type of  conversion desired.
The following modifiers, in this order, may precede the conversion type:

11. A  minus  sign `-'   left-justifies  the output  field,  instead of  the
   default right justify.

22. A  string of  digits gives  the  _w_i_d_t_h of  the output  field.  Normally,
   pprriinnttff() pads the field with spaces  to the field width; it is padded on
   the left unless left justification is specified with a `-'.

   If  the field  width  begins with  `0',  the field  is  padded with  `0'
   characters instead of spaces; the `0'  does not cause the field width to
   be taken  as an octal  number.  Note that  this applies only  to numeric
   string descriptors.   If the field  descriptor describes a  character or
   string (i.e., %cc or %ss), pprriinnttff()  ignores a leading `0' and always pads
   the field with spaces.

   If the width specification is an asterisk `*', the routine uses the next
   _a_r_g as an integer that gives the width of the field.

33. A period  `.' followed by  one or more  digits gives the  _p_r_e_c_i_s_i_o_n. For
   floating point (ee, ff, and  gg) conversions, the precision sets the number
   of digits printed after  the decimal point.  For string (ss) conversions,
   the precision  sets the  maximum number of  characters that can  be used
   from the string.  If the precision specification is given as an asterisk
   `*',   the routine  uses  the next  _a_r_g  as an  integer  that gives  the
   precision.

44. The letter `ll'  before any integer conversion (dd, oo,  xx, or uu) indicates
   that  the  argument is  a  lloonngg  rather than  an  iinntt. Capitalizing  the
   conversion  type has  the same effect;  note, however,  that capitalized
   conversion types  are _n_o_t compatible  with all C  compiler libraries, or
   with the  ANSI standard.  This  feature will not be  supported in future
   editions of COHERENT.

The following format conversions are recognized:

%  Print a `%' character.  No arguments are processed.

cc  Print the iinntt argument as a character.

dd  Print the iinntt argument as signed decimal numerals.

ee  Print the  ffllooaatt or ddoouubbllee argument in exponential  form.  The format is
   _d._d_d_d_d_d_dee_s_d_d, where  there is always one digit  before the decimal point
   and  as many  as  the _p_r_e_c_i_s_i_o_n  digits  after it  (default, six).   The
   exponent sign _s may be either `+' or `-'.

ff  Print the ffllooaatt or ddoouubbllee argument  as a string with an optional leading
   minus sign `-',  at least one  decimal digit, a decimal point (`.'), and
   optional decimal  digits after the decimal point.   The number of digits
   after the decimal point is the _p_r_e_c_i_s_i_o_n (default, six).

gg  Print the ffllooaatt or ddoouubbllee argument  as whichever of the formats dd, ee, or
   ff loses no significant precision and takes the least space.

lldd Print the lloonngg argument as signed decimal numerals.

lloo Print the lloonngg argument in unsigned octal numerals.

lluu Print the lloonngg argument in unsigned decimal numerals.

llxx Print the lloonngg argument in unsigned hexadecimal numerals.

oo  Print the iinntt argument in unsigned octal numerals.

pp  The  ANSI standard  states that  the  behavior of  the %pp  descriptor is
   implementation-specific.  Under COHERENT,  %pp prints in format %#.88XX the
   literal value of a pointer.   Its corresponding variable must be of type
   cchhaarr *.

rr  The next argument  points to an array of new  arguments that may be used
   recursively.  The first argument of the list is a cchhaarr * that contains a
   new format  string.  When the  list is exhausted,  the routine continues
   from where it left off in the original format string.

   This  descriptor  is  not  part  of  the  ANSI  Standard.   Its  use  is
   deprecated.  Code that uses it may not be portable to other systems.

ss  Print the  string to which the cchhaarr *  argument points.  Reaching either
   the end of  the string, indicated by a null  character, or the specified
   _p_r_e_c_i_s_i_o_n, will  terminate output.  If  no _p_r_e_c_i_s_i_o_n is  given, only the
   end of the string will terminate.

uu  Print the iinntt argument in unsigned decimal numerals.

xx  Print the iinntt argument in unsigned hexadecimal numerals.  The digits are
   prefaced by the string 00xx.

XX  Like %xx,  except that the  digits are prefaced  by the string  00XX.  Note
   COHERENT release 4.2 has changed the  means of %XX to conform to the ANSI
   C standard.   In versions prior  to release 4.2,  this format conversion
   printed a lloonngg argument in unsigned hexadecimal numerals.  Programs that
   depend upon the obsolete use of  %XX will no long work the same under the
   current release of COHERENT.

If it wrote the formatted  string correctly, pprriinnttff() returns the number of
characters written.  Otherwise, it returns a negative number.

_E_x_a_m_p_l_e
The following example demonstrates many pprriinnttff() statements.

#include <stdio.h>
#include <stdlib.h>
main()
{
    extern void demo_r();
    int precision = 1;
    int integer = 10;
    float decimal = 2.75;
    double bigdec = 27590.21;
    char letter = 'K';
    char buffer[20];

    strcpy (buffer, "This is a string.\n");

    printf("This is an int:   %d\n", integer);
    printf("This is a float:  %f\n", decimal);
    printf("Another float:    %3.*f\n", precision, decimal);
    printf("This is a double: %f\n", bigdec);
    printf("This is a char:   %c\n", letter);
    printf("%s", buffer);
    printf("%s\n", "This is also a string.");

    demo_r("Print everything: %d %f %f %c",
        integer, decimal, bigdec, letter);
    exit(EXIT_SUCCESS);
}

void demo_r(string)
char *string;
{
    printf("demo_r: %r\n", &string);
}

_S_e_e _A_l_s_o
eeccvvtt(),   ffccvvtt(),  ffpprriinnttff(),  ggccvvtt(),   lliibbcc,  ppuuttcc(),   ppuuttss(),  ssccaannff(),
sspprriinnttff(), vvpprriinnttff()
ANSI Standard, section 7.9.6.3
POSIX Standard, section 8.1

_N_o_t_e_s
Because  C  does not  perform  type  checking, it  is  essential that  each
argument match its counterpart in the format string.

Versions of COHERENT prior to release 4.2 recognized the conversion formats
%DD,  %OO, and  %UU. The  ANSI  standard does  not recognize  these conversion
characters, and  beginning with release 4.2  the COHERENT implementation of
pprriinnttff() no longer  recognizes them.  You should instead use, respectively,
the conversion characters %lldd, %lloo, and %lluu.
