unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

PRINTF(3V)                                                          PRINTF(3V)



NAME
       printf, fprintf, sprintf - formatted output conversion

SYNOPSIS
       #include <&lt;stdio.h>&gt;

       int printf(format [ , arg... ] )
       char *format;

       int fprintf(stream, format [ , arg... ] )
       FILE *stream;
       char *format;

       char *sprintf(s, format [ , arg... ] )
       char *s, *format;

SYSTEM V SYNOPSIS
       The routines above are available as shown, except:

       int sprintf(s, format [ , arg... ] )
       char *s, *format;

       The following are provided for XPG2 compatibility:

       #define   nl_printf      printf
       #define   nl_fprintf     fprintf
       #define   nl_sprintf     sprintf

DESCRIPTION
       printf() places output on the standard output stream stdout.  fprintf()
       places output on the named output stream.  sprintf()  places  "output",
       followed  by  the null character (\0), in consecutive bytes starting at
       *s; it is the user's responsibility to ensure that  enough  storage  is
       available.

       Each  of  these  functions converts, formats, and prints its args under
       control of the format.  The format is a character string which contains
       two  types of objects: plain characters, which are simply copied to the
       output stream, and conversion specifications, each of which causes con-
       version  and  printing of zero or more args.  The results are undefined
       if there are insufficient args  for  the  format.   If  the  format  is
       exhausted while args remain, the excess args are simply ignored.

       Each  conversion  specification is introduced by either the % character
       or by the character sequence %digit$, after which the following  appear
       in sequence:

              o  Zero  or  more flags, which modify the meaning of the conver-
                 sion specification.

              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 on the left (or right, if  the
                 left-adjustment flag `-', described below, has been given) to
                 the field width.  The padding is with blanks unless the field
                 width digit string starts with a zero, in which case the pad-
                 ding is with zeros.

              o  A precision that gives the minimum number of digits to appear
                 for the d, i, o, u, x, or X conversions, the number of digits
                 to appear after the decimal point for the e, E, and f conver-
                 sions, the maximum number of significant digits for the g and
                 G conversion, or the  maximum  number  of  characters  to  be
                 printed  from  a string in s conversion.  The precision takes
                 the form of a period (.)  followed by a decimal digit string;
                 a  null  digit  string is treated as zero.  Padding specified
                 by the precision overrides the padding specified by the field
                 width.

              o  An  optional  l (ell) specifying that a following d, i, o, u,
                 x, or X conversion character applies to a long  integer  arg.
                 An l before any other conversion character is ignored.

              o  A  character  that  indicates  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 integer arg supplies the
       field width or precision.  The arg that is actually  converted  is  not
       fetched  until  the  conversion  letter is seen, so the args specifying
       field width or precision must appear before the arg (if any) to be con-
       verted.   A  negative  field width argument is taken as a `-' flag fol-
       lowed by a positive field width.  If the precision  argument  is  nega-
       tive, it will be changed to zero.

       The flag characters and their meanings are:
       -         The  result  of  the conversion will be left-justified within
                 the field.
       +         The result of a signed conversion will always  begin  with  a
                 sign (+ or -).
       blank     If  the first character of a signed conversion is not a sign,
                 a blank will be prefixed to the result.  This implies that if
                 the  blank  and  +  flags both appear, the blank flag will be
                 ignored.
       #         This flag specifies that the value is to be converted  to  an
                 "alternate  form".   For  c,  d, i, s, and u conversions, the
                 flag has no effect.  For o conversion, it increases the  pre-
                 cision  to  force the first digit of the result to be a zero.
                 For x or X conversion, a non-zero result will have 0x  or  0X
                 prefixed  to  it.   For  e,  E,  f, g, and G conversions, the
                 result will always contain a decimal point, even if no digits
                 follow  the  point  (normally, a decimal point appears in the
                 result of these conversions only if a digit follows it).  For
                 g and G conversions, trailing zeroes will not be removed from
                 the result (which they normally are).

       The conversion characters and their meanings are:

       d,i,o,p,u,x,X
                 The integer arg is converted to  signed  decimal  (d  or  i),
                 unsigned  octal  (o), unsigned decimal (u), or unsigned hexa-
                 decimal notation (x, p, and  X),  respectively;  the  letters
                 abcdef are used for x and p conversion and the letters ABCDEF
                 for X conversion.  The precision specifies the minimum number
                 of digits to appear; if the value being converted can be rep-
                 resented in fewer digits, it will be  expanded  with  leading
                 zeroes.   For compatibility with older versions, padding with
                 leading zeroes may alternatively be specified by prepending a
                 zero  to the field width.  This does not imply an octal value
                 for the field width.  The default precision is 1.  The result
                 of converting a zero value with a precision of zero is a null
                 string.
       f         The float or double arg is converted to decimal  notation  in
                 the style ``[-]ddd.ddd'' where the number of digits after the
                 decimal point is equal to the  precision  specification.   If
                 the  precision  is missing, 6 digits are given; if the preci-
                 sion is explicitly 0, no digits  and  no  decimal  point  are
                 printed.
       e,E       The   float   or   double  arg  is  converted  in  the  style
                 "[-]d.ddde+-ddd," where there is one digit before the decimal
                 point  and the number of digits after it is equal to the pre-
                 cision; when the precision is missing, 6 digits are produced;
                 if  the  precision  is zero, no decimal point appears.  The E
                 format code will produce a number with E instead of e  intro-
                 ducing  the  exponent.  The exponent always contains at least
                 two digits.
       g,G       The float or double arg is printed in style f  or  e  (or  in
                 style  E  in the case of a G format code), with the precision
                 specifying the number of significant digits.  The style  used
                 depends  on  the  value  converted: style e or E will be used
                 only if the exponent resulting from the  conversion  is  less
                 than  -4  or greater than the precision.  Trailing zeroes are
                 removed from the result; a decimal point appears only  if  it
                 is followed by a digit.

       The e, E, f, g, and G formats print IEEE indeterminate values (infinity
       or not-a-number) as "Infinity" or "NaN" respectively.

       c         The character arg is printed.
       s         The arg is taken to be a string (character pointer) and char-
                 acters  from  the  string  are printed until a null character
                 (\0) is encountered or until the number of  characters  indi-
                 cated by the precision specification is reached.  If the pre-
                 cision is missing, it is taken to be infinite, so all charac-
                 ters  up  to  the  first  null character are printed.  A NULL
                 value for arg will yield undefined results.
       n         The argument arg is a pointer to an  integer  into  which  is
                 written the number of characters written to the output so far
                 by this call to one of the printf() functions.   No  argument
                 is converted.
       %         Print a %; no argument is converted.

       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 simply expanded to contain the conversion result.  Padding
       takes place only if the specified field width exceeds the actual width.
       Characters  generated  by  printf()  and  fprintf()  are  printed as if
       putc(3S) had been called.

       All forms of the printf() functions allow for the insertion of  a  lan-
       guage  dependent radix character in the output string.  The radix char-
       acter is defined by the program's locale (category LC_NUMERIC).  In the
       "C"  locale,  or  in a locale where the radix character is not defined,
       the radix character defaults to `.'.

       Conversions can be applied to the nth argument in  the  argument  list,
       rather  than  the  next  unused argument.  In this case, the conversion
       character % is replaced by the sequence %digit$, where digit is a deci-
       mal  integer  n in the range [1,9], giving the position of the argument
       in the argument list.  This feature provides for the definition of for-
       mat  strings  that select arguments in an order appropriate to specific
       languages.

       In format strings containing the %digit$ form of a conversion  specifi-
       cation,  a  field  width  or precision may be indicated by the sequence
       *digit$, where digit is a decimal integer in the range [1,9] giving the
       position  in  the  argument list of an integer arg containing the field
       width or precision.

       The format string can contain either numbered  argument  specifications
       (that  is,  %digit$ and *digit$), or unnumbered argument specifications
       (that is % and *), but not both. The results  of  mixing  numbered  and
       unnumbered  specifications is undefined.  When numbered argument speci-
       fications are used, specifying the nth argument requires that  all  the
       leading  arguments,  from  the first to the (n-1)th be specified in the
       format string.

SYSTEM V DESCRIPTION
       XPG2 requires that nl_printf, nl_fprintf and nl_sprintf be  defined  as
       printf, fprintf and sprintf, respectively for backward compatibility

RETURN VALUES
       On  success,  printf()  and  fprintf()  return the number of characters
       transmitted, excluding the null character.   On  failure,  they  return
       EOF.

       sprintf() returns s.

SYSTEM V RETURN VALUES
       On  success,  sprintf()  returns  the number of characters transmitted,
       excluding the null character.  On failure, it returns EOF.

EXAMPLES
              printf(format, weekday, month, day, hour, min);

       In American usage, format could be a pointer to the string:

              "%s, %s %d, %d:%.2d\n"

       producing the message:

              Sunday, July 3,10:02

       Whereas for German usage, format could be a pointer to the string:

              "%1$s, %3$d.%2$s,%4$d:%5$.2d\n"

       producing the message:

              Sonntag, 3.Juli,10:02

       To print pi to 5 decimal places:

              printf("pi = %.5f", 4 * atan(1. 0));

SEE ALSO
       econvert(3),   putc(3S),    scanf(3V),    setlocale(3V),    varargs(3),
       vprintf(3V)

BUGS
       Very wide fields (>128 characters) fail.



                                21 January 1990                     PRINTF(3V)