printf(1) printf(1) NAME printf - print formatted output SYNOPSIS printf format [arg . . .] DESCRIPTION The printf command converts, formats, and prints its args under control of the format. It fully supports conversion specifications for strings (%s descriptor); however, the results are undefined for the other conversion specifications not specifically mentioned below. format a character string that contains three types of objects: 1) plain characters, which are simply copied to the output stream; 2) conversion specifications, each of which results in fetching zero or more args; and 3) C-language escape sequences, which are translated into the corresponding characters. arg string(s) to be printed under the control of format. The results are undefined if there are insufficient args for the format. Each conversion specification is introduced by the character %. After the %, the following appear in sequence: An optional field, consisting of a decimal digit string followed by a $, specifying the next arg to be converted. If this field is not provided, the arg following the last arg converted is used. An optional decimal digit string specifying a minimum field width. If the converted value has fewer characters than the field width, it is padded on the left (or right, if the left-adjustment flag `-' 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 padding is with zeros. An optional precision that gives 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 (nothing is printed). Padding specified by the precision overrides the padding specified by the field width. That is, if precision is specified, its value is used to control the number of characters printed. 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 converted. A negative field width argument is taken as a `-' (left-adjustment) flag followed by a positive field width. If the precision argument is negative, it is changed to zero (nothing is printed). 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. The conversion characters and their meanings are: %e, %E, %f, %g and %G These conversion specifications are not supported. %b The argument will be taken to be a string that may contain backslash-escape sequences. %s The arg is taken to be a string 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. %% Print a %; no argument is converted. EXTENDED DESCRIPTION printf does not precede or follow output from the %d or %u conversion specifications with blank characters not specified by the format operand. printf does not precede output from the %o conversion specification with zeros not specified by the format operand. The following backslash-escape sequences are supported: File Format Notation (\\, \a, \b, \f, \n, \r, \t, \v), which will be converted to the characters they represent. \0ddd, where ddd is a zero-, one-, two- or three-digit octal number that will be converted to a byte with the numeric value specified by the octal number\c, which will not be written and will cause printf to ignore any remaining characters in the string operand containing it, any remaining string operands and any additional characters in the format operand. The interpretation of a backslash followed by any other sequence of characters is unspecified. Bytes from the converted string will be written until the end of the string or the number of bytes indicated by the precision specification is reached. If the precision is omitted, it will be taken to be infinite, so all bytes up to the end of the converted string will be written. For each specification that consumes an argument, the next argument operand will be evaluated and converted to the appropriate type for the conversion as specified below. The format operand will be reused as often as necessary to satisfy the argument operands. Any extra %c or %s conversion specifications will be evaluated as if a null string argument were supplied; other extra conversion specifications will be evaluated as if a zero argument were supplied. If the format operand contains no conversion specifications and argument operands are present, the results are unspecified. If a character sequence in the format operand begins with a % character, but does not form a valid conversion specification, the behaviour is unspecified.The argument operands will be treated as strings if the corresponding conversion character is %b, %c or %s; otherwise, it will be evaluated as a C constant, as described by the ISO C standard, with the following extensions: A leading plus or minus sign will be allowed. If the leading character is a single- or double-quote, the value will be the numeric value in the underlying codeset of the character following the single- or double-quote. If an argument operand cannot be completely converted into an internal value appropriate to the corresponding conversion specification, a diagnostic message will be written to standard error and the utility will not exit with a zero exit status, but will continue processing any remaining operands and will write the value accumulated at the time the error was detected to standard output. EXIT STATUS The following exit values are returned: 0 Successful completion. >0 An error occurred. If an argument cannot be parsed correctly for the corresponding conversion specification, the printf utility is required to report an error. Thus, overflow and extraneous characters at the end of an argument being used for a numeric conversion are to be reported as errors. It is not considered an error if an argument operand is not completely used for a %c or %s conversion or if a string operand's first or second character is used to get the numeric value of a character. The printf utility is required to notify the user when conversion errors are detected while producing numeric output; thus, the following results would be expected with 32-bit twos-complement integers when %d is specified as the format operand: Diagnostic Output printf: "5a" not completely converted printf: "9999999999" arithmetic overflow printf: "-9999999999" arithmetic overflow printf: "ABC" expected numeric value Note that the value shown on standard output is what would be expected as the return value from the function strtol. A similar correspondence exists between %u and strtoul. EXAMPLES The command printf '%s %s %s\n' Good Morning World results in the output: Good Morning World The following command produces the same output. printf '%2$s %s %1$s\n' World Good Morning Here is an example that prints the first 6 characters of $PATH left- adjusted in a 10-character field: printf 'First 6 chars of %s are %-10.6s.0 $PATH $PATH If $PATH has the value /usr/bin:/usr/local/bin, then the above command would print the following output: First 6 chars of /usr/bin:/usr/local/bin are /usr/b . To alert the user and then print and read a series of prompts: printf "\aPlease fill in the following: \nName: " read name printf "Phone number: " read phone To read out a list of right and wrong answers from a file, calculate the percentage correctly, and print them out. The numbers are right- justified and separated by a single tab character. The percentage is written to one decimal place of accuracy: while read right wrong ; do percent=$(echo "scale=1;($right*100)/($right+$wrong)" | bc) printf "%2d right%2d wrong(%s%%)0 \ $right $wrong $percent done < database_file The command: printf "%5d%4d\n" 1 21 321 4321 54321 produces: 1 21 321 4321 54321 0 Note that the format operand is used three times to print all of the given strings and that a 0 was supplied by printf to satisfy the last %4d conversion specification. SEE ALSO Page 5