| 1 | .TH PRINTF 3S |
| 2 | .SH NAME |
| 3 | printf, fprintf, sprintf \- formatted output conversion |
| 4 | .SH SYNOPSIS |
| 5 | .B #include <stdio.h> |
| 6 | .PP |
| 7 | .B printf(format |
| 8 | .RB [ , |
| 9 | arg ] ... |
| 10 | .B ) |
| 11 | .br |
| 12 | .B char *format; |
| 13 | .PP |
| 14 | .B fprintf(stream, format |
| 15 | .RB [ , |
| 16 | arg ] ... |
| 17 | .B ) |
| 18 | .br |
| 19 | .SM |
| 20 | .B FILE |
| 21 | .B *stream; |
| 22 | .br |
| 23 | .B char *format; |
| 24 | .PP |
| 25 | .B sprintf(s, format |
| 26 | .RB [ , |
| 27 | arg ] ... |
| 28 | .B ) |
| 29 | .br |
| 30 | .B char *s, format; |
| 31 | .SH DESCRIPTION |
| 32 | .I Printf |
| 33 | places output on the standard output stream |
| 34 | .IR stdout . |
| 35 | .I Fprintf |
| 36 | places output on the named output |
| 37 | .IR stream . |
| 38 | .I Sprintf |
| 39 | places `output' in the string |
| 40 | .I s, |
| 41 | followed by the character `\\0'. |
| 42 | .PP |
| 43 | Each of these functions |
| 44 | converts, formats, and prints its arguments after the first |
| 45 | under control of the first argument. |
| 46 | The first argument is a character string |
| 47 | which contains |
| 48 | two types of objects: |
| 49 | plain characters, which are simply copied to the |
| 50 | output stream, |
| 51 | and conversion specifications, |
| 52 | each of which causes conversion and printing |
| 53 | of the next successive |
| 54 | .I arg |
| 55 | .IR printf . |
| 56 | .PP |
| 57 | Each conversion specification is introduced by |
| 58 | the character |
| 59 | .BR % . |
| 60 | Following the |
| 61 | .BR % , |
| 62 | there may be |
| 63 | .TP |
| 64 | \- |
| 65 | an optional minus sign `\-' which specifies |
| 66 | .I "left adjustment" |
| 67 | of the converted value |
| 68 | in the |
| 69 | indicated field; |
| 70 | .TP |
| 71 | \- |
| 72 | an optional digit string specifying a |
| 73 | .I "field width;" |
| 74 | if the converted value has fewer characters |
| 75 | than the field width |
| 76 | it will be blank-padded on the left (or right, |
| 77 | if the left-adjustment indicator has been |
| 78 | given) to make up the field width; |
| 79 | if the field width begins with a zero, |
| 80 | zero-padding will be done instead of blank-padding; |
| 81 | .TP |
| 82 | \- |
| 83 | an optional period |
| 84 | .RB ` . ' |
| 85 | which serves to |
| 86 | separate the field width from the |
| 87 | next digit string; |
| 88 | .TP |
| 89 | \- |
| 90 | an optional digit string |
| 91 | specifying a |
| 92 | .I precision |
| 93 | which specifies |
| 94 | the number of digits to appear after the |
| 95 | decimal point, for e- and f-conversion, |
| 96 | or the maximum number of characters |
| 97 | to be printed from a string; |
| 98 | .TP |
| 99 | \- |
| 100 | the character |
| 101 | .B l |
| 102 | specifying that a following |
| 103 | .BR d , |
| 104 | .BR o , |
| 105 | .BR x , |
| 106 | or |
| 107 | .B u |
| 108 | corresponds to a long integer |
| 109 | .I arg. |
| 110 | (A capitalized conversion code accomplishes |
| 111 | the same thing.) |
| 112 | .TP |
| 113 | \- |
| 114 | a character which indicates the type of |
| 115 | conversion to be applied. |
| 116 | .PP |
| 117 | A field width or precision may be `*' instead of a digit string. |
| 118 | In this case an integer |
| 119 | .I arg |
| 120 | supplies |
| 121 | the field width or precision. |
| 122 | .PP |
| 123 | The conversion characters |
| 124 | and their meanings are |
| 125 | .TP |
| 126 | .B dox |
| 127 | The integer |
| 128 | .I arg |
| 129 | is converted to decimal, octal, or |
| 130 | hexadecimal notation respectively. |
| 131 | .TP |
| 132 | .B f |
| 133 | The float or double |
| 134 | .I arg |
| 135 | is converted to decimal notation |
| 136 | in the style `[\fB\-\fR]ddd.ddd' |
| 137 | where the number of d's after the decimal point |
| 138 | is equal to the precision specification |
| 139 | for the argument. |
| 140 | If the precision |
| 141 | is missing, |
| 142 | 6 digits are given; |
| 143 | if the precision is explicitly 0, no digits and |
| 144 | no decimal point are printed. |
| 145 | .TP |
| 146 | .B e |
| 147 | The float or double |
| 148 | .I arg |
| 149 | is converted in the style |
| 150 | `[\fB\-\fR]d\fB.\fRddd\fBe\fR\(+-dd' |
| 151 | where there is one digit before the decimal point and |
| 152 | the number after is equal to the |
| 153 | precision specification for the argument; |
| 154 | when the precision is missing, |
| 155 | 6 digits are produced. |
| 156 | .TP |
| 157 | .B g |
| 158 | The float or double |
| 159 | .I arg |
| 160 | is printed in style |
| 161 | .BR d , |
| 162 | in style |
| 163 | .BR f , |
| 164 | or in |
| 165 | style |
| 166 | .BR e , |
| 167 | whichever gives full precision in minimum space. |
| 168 | .TP |
| 169 | .B c |
| 170 | The character |
| 171 | .I arg |
| 172 | is printed. |
| 173 | Null characters are ignored. |
| 174 | .TP |
| 175 | .B s |
| 176 | .I Arg |
| 177 | is taken to be a string (character pointer) |
| 178 | and characters from the string are printed until |
| 179 | a null character or until |
| 180 | the number of characters indicated by the precision |
| 181 | specification is reached; |
| 182 | however if the precision is 0 or missing |
| 183 | all characters up to a null are printed. |
| 184 | .TP |
| 185 | .B u |
| 186 | The unsigned integer |
| 187 | .I arg |
| 188 | is converted to decimal |
| 189 | and printed (the result will be in the |
| 190 | range 0 through MAXUINT, where MAXUINT equals 4294967295 on a VAX-11 |
| 191 | and 65536 on a PDP-11). |
| 192 | .TP |
| 193 | .B % |
| 194 | Print a `%'; no argument is converted. |
| 195 | .PP |
| 196 | In no case does a non-existent or small field width |
| 197 | cause truncation of a field; |
| 198 | padding takes place only if the specified field |
| 199 | width exceeds the actual width. |
| 200 | Characters generated by |
| 201 | .I printf |
| 202 | are printed by |
| 203 | .IR putc (3). |
| 204 | .PP |
| 205 | .B Examples |
| 206 | .br |
| 207 | To print a date and time in the form `Sunday, July 3, 10:02', |
| 208 | where |
| 209 | .I weekday |
| 210 | and |
| 211 | .I month |
| 212 | are pointers to null-terminated strings: |
| 213 | .RS |
| 214 | .HP |
| 215 | .nh |
| 216 | printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min); |
| 217 | .RE |
| 218 | .hy |
| 219 | .PP |
| 220 | To print |
| 221 | .if n pi |
| 222 | .if t \(*p |
| 223 | to 5 decimals: |
| 224 | .IP |
| 225 | printf("pi = %.5f", 4*atan(1.0)); |
| 226 | .SH "SEE ALSO" |
| 227 | putc(3), |
| 228 | scanf(3), |
| 229 | ecvt(3) |
| 230 | .SH BUGS |
| 231 | Very wide fields (>128 characters) fail. |