man/man3/printf.3

   1 .\"     @(#)printf.3s   6.3 (Berkeley) 6/5/86
   2 .\"
   3 .TH PRINTF 3 "June 5, 1986"
   4 .AT 3
   5 .SH NAME
   6 printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf \- formatted output conversion
   7 .SH SYNOPSIS
   8 .nf
   9 .ft B
  10 #include <sys/types.h>
  11 #include <stdio.h>
  12 #include <stdarg.h>
  13
  14 int printf(const char *\fIformat\fP \fR[\fP, \fIarg\fP\fR] ...\fP);
  15 int fprintf(FILE *\fIstream\fP, const char *\fIformat\fP \fR[\fP, \fIarg\fP\fR] ...\fP);
  16 int sprintf(char *\fIs\fP, const char *\fIformat\fP \fR[\fP, \fIarg\fP\fR] ...\fP);
  17 int snprintf(char *\fIs\fP, size_t \fIn\fP, const char *\fIformat\fP \fR[\fP, \fIarg\fP\fR] ...\fP);
  18 int vprintf(const char *\fIformat\fP, va_list \fIargs\fP);
  19 int vfprintf(FILE *\fIstream\fP, const char *\fIformat\fP, va_list \fIargs\fP);
  20 int vsprintf(char *\fIs\fP, const char *\fIformat\fP, va_list \fIargs\fP);
  21 int vsnprintf(char *\fIs\fP, size_t \fIn\fP, const char *\fIformat\fP, va_list \fIargs\fP);
  22 .ft R
  23 .fi
  24 .SH DESCRIPTION
  25 .B Printf
  26 places output on the standard output stream
  27 .BR stdout .
  28 .B Fprintf
  29 places output on the named output
  30 .IR stream .
  31 .B Sprintf
  32 places `output' in the string
  33 .IR s ,
  34 followed by the character `\e0'.
  35 .B Snprintf
  36 (Minix-vmd only)
  37 is like
  38 .B sprintf
  39 except that no more than
  40 .IR n \-1
  41 characters are written to
  42 .I s
  43 followed by a `\e0'.
  44 .PP
  45 The
  46 .B v*printf
  47 functions can be used to make functions like the first four by using the
  48 .BR stdarg (3)
  49 method to process the argument.
  50 .PP
  51 Each of these functions converts, formats, and prints its arguments after
  52 the first under control of the first argument.
  53 The first argument is a character string which contains two types of objects:
  54 plain characters, which are simply copied to the output stream,
  55 and conversion specifications, each of which causes conversion and printing
  56 of the next successive
  57 .IR arg .
  58 .PP
  59 Each conversion specification is introduced by the character
  60 .BR % .
  61 The remainder of the conversion specification includes
  62 in the following order
  63 .TP
  64 \(bu
  65 Zero or more of following flags:
  66 .RS
  67 .TP
  68 \(bu
  69 a `#' character
  70 specifying that the value should be converted to an ``alternate form''.
  71 For
  72 .BR c ,
  73 .BR d ,
  74 .BR s ,
  75 and
  76 .BR u
  77 conversions, this option has no effect.  For
  78 .B o
  79 conversions, the precision of the number is increased to force the first
  80 character of the output string to a zero.  For
  81 .BR x ( X )
  82 conversion, a non-zero result has the string
  83 .BR 0x ( 0X )
  84 prepended to it.  For
  85 .BR e ,
  86 .BR E ,
  87 .BR f ,
  88 .BR g ,
  89 and
  90 .BR G
  91 conversions, the result will always contain a decimal point, even if no
  92 digits follow the point (normally, a decimal point only appears in the
  93 results of those conversions if a digit follows the decimal point).  For
  94 .B g
  95 and
  96 .B G
  97 conversions, trailing zeros are not removed from the result as they
  98 would otherwise be.
  99 .TP
 100 \(bu
 101 a minus sign `\-' which specifies
 102 .I "left adjustment"
 103 of the converted value in the indicated field;
 104 .TP
 105 \(bu
 106 a `+' character specifying that there should always be
 107 a sign placed before the number when using signed conversions.
 108 .TP
 109 \(bu
 110 a space specifying that a blank should be left before a positive number
 111 during a signed conversion.  A `+' overrides a space if both are used.
 112 .RE
 113 .TP
 114 \(bu
 115 an optional digit string specifying a
 116 .I "field width;"
 117 if the converted value has fewer characters than the field width
 118 it will be blank-padded on the left (or right,
 119 if the left-adjustment indicator has been given) to make up the field width;
 120 if the field width begins with a zero,
 121 zero-padding will be done instead of blank-padding;
 122 .TP
 123 \(bu
 124 an optional period
 125 .RB ` . '
 126 which serves to separate the field width from the next digit string;
 127 .TP
 128 \(bu
 129 an optional digit string specifying a
 130 .I precision
 131 which specifies the number of digits to appear after the
 132 decimal point, for e- and f-conversion, or the maximum number of characters
 133 to be printed from a string;
 134 .TP
 135 \(bu
 136 the character
 137 .B l
 138 specifying that a following
 139 .BR d ,
 140 .BR o ,
 141 .BR x ,
 142 or
 143 .B u
 144 corresponds to a long integer
 145 .IR arg .
 146 .TP
 147 \(bu
 148 a character which indicates the type of
 149 conversion to be applied.
 150 .PP
 151 A field width or precision may be `*' instead of a digit string.
 152 In this case an integer
 153 .I arg
 154 supplies
 155 the field width or precision.
 156 .PP
 157 The conversion characters
 158 and their meanings are
 159 .TP
 160 .B dox
 161 The integer
 162 .I arg
 163 is converted to decimal, octal, or
 164 hexadecimal notation respectively.
 165 .TP
 166 .B X
 167 Like
 168 .BR x ,
 169 but use upper case instead of lower case.
 170 .TP
 171 .B f
 172 The float or double
 173 .I arg
 174 is converted to decimal notation
 175 in the style `[\fB\-\fR]ddd.ddd'
 176 where the number of d's after the decimal point
 177 is equal to the precision specification
 178 for the argument.
 179 If the precision
 180 is missing,
 181 6 digits are given;
 182 if the precision is explicitly 0, no digits and
 183 no decimal point are printed.
 184 .TP
 185 .B e
 186 The float or double
 187 .I arg
 188 is converted in the style
 189 `[\fB\-\fR]d\fB.\fRddd\fBe\fR\(+-dd'
 190 where there is one digit before the decimal point and
 191 the number after is equal to the
 192 precision specification for the argument;
 193 when the precision is missing,
 194 6 digits are produced.
 195 .TP
 196 .B g
 197 The float or double
 198 .I arg
 199 is printed in style
 200 .BR d ,
 201 in style
 202 .BR f ,
 203 or in
 204 style
 205 .BR e ,
 206 whichever gives full precision in minimum space.
 207 .TP
 208 .B c
 209 The character
 210 .I arg
 211 is printed.
 212 .TP
 213 .B s
 214 .I Arg
 215 is taken to be a string (character pointer)
 216 and characters from the string are printed until
 217 a null character or until
 218 the number of characters indicated by the precision
 219 specification is reached;
 220 however if the precision is 0 or missing
 221 all characters up to a null are printed.
 222 .TP
 223 .B u
 224 The unsigned integer
 225 .I arg
 226 is converted to decimal
 227 and printed.
 228 .TP
 229 .B %
 230 Print a `%'; no argument is converted.
 231 .PP
 232 In no case does a non-existent or small field width
 233 cause truncation of a field;
 234 padding takes place only if the specified field
 235 width exceeds the actual width.
 236 Characters generated by
 237 .B printf
 238 are printed by
 239 .BR putc (3).
 240 .PP
 241 .B Examples
 242 .br
 243 To print a date and time in the form `Sunday, July 3, 10:02',
 244 where
 245 .I weekday
 246 and
 247 .I month
 248 are pointers to null-terminated strings:
 249 .PP
 250 .RS
 251 printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min);
 252 .RE
 253 .PP
 254 To print
 255 .if n pi
 256 .if t \(*p
 257 to 5 decimals:
 258 .IP
 259 printf("pi = %.5f", 4*atan(1.0));
 260 .SH "SEE ALSO"
 261 .BR putc (3),
 262 .BR scanf (3),
 263 .BR ecvt (3),
 264 .BR stdarg (3).