printf(3S) printf(3S)NAME printf, fprintf, sprintf - format and output string and numeric data SYNOPSIS #include <stdio.h> int printf(format[,arg]...) char *format; int fprintf(stream, format[,arg]...) FILE *stream; char *format; int sprintf(s, format[,arg]...) char *s, format; DESCRIPTION printf places output on the standard output stream stdout. fprintf places output on the named output stream, 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 arguments under control of format. The format argument is a character string that contains two types of objects: plain characters, which are simply copied to the output stream, and conversion specifications, each of which results in fetching zero or more arguments. The results are undefined if there are insufficient arguments for the format. If the format is exhausted while arguments remain, the excess arguments are simply ignored. Each conversion specification is introduced by a percent sign (%). After the %, the following appear in sequence: ⊕ Zero or more options, that modify the meaning of the conversion specification. ⊕ 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 to the field width on the left (default) or right (if the left-adjustment option - has been given); see the option definitions later in this section. If the field width for an s conversion is preceded by a 0, the string is right-adjusted with zero-padding on the left. ⊕ A precision argument that gives the minimum number of digits to appear for d, o, u, x, or X conversions, the number of digits to appear after the decimal point for January 1992 1
printf(3S) printf(3S)e and f conversions, the maximum number of significant digits for g conversion, or the maximum number of characters to be printed from a string in an s conversion. The format of the precision argument is a period (.) followed by a decimal-digit string; a null- digit string is treated as zero. ⊕ An optional l (ell) specifying that a following d, o, u, x, or X conversion character applies to a long integer arg. An l before any other conversion character is ignored. ⊕ A character indicating the type of conversion to apply. A field width or precision may be indicated by an asterisk (*) instead of a digit string. In this case, an integer argument supplies the field width or precision. The argument that is actually converted is not fetched until the conversion letter is seen; therefore, the arguments specifying field width or precision must appear before the argument (if any) to be converted. The options and their meanings are as follows: - 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. A blank implies that if the blank and + options both appear, the blank argument will be ignored. # The value is to be converted to an ``alternate form.'' For c, d, s, and u conversions, the option has no effect. For an o conversion, it increases the precision to force the first digit of the result to be a zero. For an x (X) conversion, a nonzero result will have 0x (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 zeros will not be removed from the result (which they normally are). 2 January 1992
printf(3S) printf(3S)The conversion characters and their meanings are as follows: d o u x X Convert arg (when it is an integer) to a signed decimal, unsigned octal, decimal, or hexadecimal notation (x and X), respectively; the letters abcdef are used for x 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 represented in fewer digits, it will be expanded with leading zeros. (For compatibility with older versions, you can also specify padding with leading zeros by prefixing a zero to the field width.) Padding 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 Converts arg (when it is a float or double) to a 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, six digits are output; if the precision is explicitly 0, no decimal point appears. e E Converts arg (when it is a float or double) in the style [-]d.ddde+dd, where there is one digit before the decimal point and the number of digits after it is equal to the precision. When the precision is missing, six digits are produced; if the precision is zero, no decimal point appears. The E format code produces a number with E instead of e introducing the exponent. The exponent always contains at least two digits. g G Prints arg (when it is a float or double) 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. The style e is used only if the exponent resulting from the conversion is less than -4 or greater than the precision. Trailing zeros are removed from the result; a decimal point appears only if it is followed by a digit. January 1992 3
printf(3S) printf(3S)s Interprets arg as a string (character pointer) and characters from the string are printed until a null character (\0) is encountered or the number of characters indicated by the precision specification is reached. If the precision is missing, it is taken to be infinite, so all characters up to the first null character are printed. A NULL value for arg yields undefined results. % Prints a %; no argument is converted. In no case does a nonexistent 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. Characters generated by printf and fprintf are printed as if putc had been called. STATUS MESSAGES AND VALUES Each function returns the number of characters transmitted (not including the \0 in the case of sprintf), or a negative value if an output error was encountered. EXAMPLES To print a date and time in the form ``Sunday, July 3, 10:02,'' where wkday and mnth are pointers to null- terminated strings, enter printf("%s, %s %d, %.2d:%.2d", wkday, mnth, day, hr, min); To print pi to 5 decimal places, enter printf("pi=%.5f", 4*atan(1.0)); SEE ALSO intro(3), ecvt(3C), putc(3S), scanf(3S) 4 January 1992