337 lines
9.6 KiB
Groff
337 lines
9.6 KiB
Groff
'\"macro stdmacro
|
|
.if n .pH g1.printf @(#)printf 40.17 of 5/9/91
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1989, 1990 AT&T
|
|
.nr X
|
|
.if \nX=0 .ds x} printf 1 "Essential Utilities" "\&"
|
|
.if \nX=1 .ds x} printf 1 "Essential Utilities"
|
|
.if \nX=2 .ds x} printf 1 "" "\&"
|
|
.if \nX=3 .ds x} printf "" "" "\&"
|
|
.TH \*(x}
|
|
.SH NAME
|
|
\f4printf\f1 \- print formatted output
|
|
.SH SYNOPSIS
|
|
\f4printf \f2format \f1[\f2arg\f1 . . .]
|
|
.SH DESCRIPTION
|
|
The
|
|
\f4printf\fP
|
|
command converts, formats, and prints its
|
|
.IR arg s
|
|
under control of the
|
|
.IR format .
|
|
It fully supports conversion
|
|
specifications for strings (\f4%s\f1 descriptor);
|
|
however, the results are undefined for the other conversion
|
|
specifications not specifically mentioned below.
|
|
.PP
|
|
.TP 10
|
|
.I 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
|
|
.IR arg s;
|
|
and 3) C-language escape sequences, which are translated into the corresponding characters.
|
|
.TP 10
|
|
.I arg
|
|
string(s) to be printed under the control of
|
|
.IR format .
|
|
The results are undefined if there are insufficient
|
|
.IR arg s
|
|
for the format.
|
|
.PP
|
|
Each conversion specification is introduced by
|
|
the character
|
|
\f4%\f1.
|
|
After the
|
|
\f4%\f1,
|
|
the following
|
|
appear in sequence:
|
|
.PP
|
|
.RS
|
|
An optional field, consisting of a decimal digit string followed by a
|
|
\f4$\f1,
|
|
specifying the next
|
|
.I arg
|
|
to be converted.
|
|
If this field is not provided,
|
|
the
|
|
.I arg
|
|
following the last
|
|
.I arg
|
|
converted is used.
|
|
.PP
|
|
An optional decimal digit string specifying a minimum
|
|
.IR "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 `\f4\-\fP' 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.
|
|
.PP
|
|
An optional
|
|
.I precision\^
|
|
that gives
|
|
the maximum number of characters
|
|
to be printed from a string in
|
|
\f4%s\f1
|
|
conversion.
|
|
The precision takes the form of a period
|
|
(\f4\&.\f1)
|
|
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 \f2precision\fP is specified, its value is used to control
|
|
the number of characters printed.
|
|
.PP
|
|
A field width or precision or both may be
|
|
indicated by an asterisk
|
|
\f1(\f4\(**\f1)
|
|
instead of a digit string.
|
|
In this case, an integer
|
|
.I arg\^
|
|
supplies
|
|
the field width or precision.
|
|
The
|
|
.I arg\^
|
|
that is actually converted is not fetched until
|
|
the conversion letter is seen, so the
|
|
.IR arg s
|
|
specifying field width or precision must appear
|
|
.I before\^
|
|
the
|
|
.I arg\^
|
|
(if any) to be converted.
|
|
A negative field width argument is taken as a
|
|
\f4`\-'\f1
|
|
(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.
|
|
.RE
|
|
.PP
|
|
The conversion characters and their meanings are:
|
|
.TP
|
|
\f4%e, %E, %f, %g and %G\f1
|
|
These conversion specifications are not supported.
|
|
.TP
|
|
\f4%b\f1
|
|
The argument will be taken to be a string that may contain
|
|
backslash-escape sequences.
|
|
.TP
|
|
\f4%s\f1
|
|
The
|
|
.I arg\^
|
|
is taken to be a string
|
|
and characters from the string are printed until
|
|
a null character
|
|
\f1(\f4\e0\f1)
|
|
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
|
|
.I arg\^
|
|
yields undefined results.
|
|
.TP
|
|
\f4%%\f1
|
|
Print a
|
|
\f4%\f1;
|
|
no argument is converted.
|
|
.SH "EXTENDED DESCRIPTION"
|
|
\f2printf\f1 does not precede or follow output from the
|
|
\f4%d\f1
|
|
or
|
|
\f4%u\f1
|
|
conversion specifications with blank characters not specified by the
|
|
format operand. \f2printf\f1 does not precede output from the
|
|
\f4%o\f1
|
|
conversion specification with zeros not specified by the format operand.
|
|
.PP
|
|
The following backslash-escape sequences are supported:
|
|
.PP
|
|
File Format Notation (\f4\\\\, \\a, \\b, \\f, \\n, \\r, \\t, \\v\fP),
|
|
which will be converted to the characters they represent.
|
|
.PP
|
|
\f4\\0ddd\f1,
|
|
.PP
|
|
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\f4\\c\f1, 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.
|
|
.PP
|
|
The interpretation of a backslash followed by any other sequence of characters
|
|
is unspecified.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
The format operand will be reused as often as necessary to satisfy the argument
|
|
operands.
|
|
.PP
|
|
Any extra \f4%c\f1 or \f4%s\f1 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.
|
|
.PP
|
|
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
|
|
\f4%\f1
|
|
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
|
|
\f4%b\f1, \f4%c\f1 or \f4%s\f1; otherwise, it will be evaluated as a
|
|
C constant, as described by the ISO C standard, with the following extensions:
|
|
.PP
|
|
A leading plus or minus sign will be allowed.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.SH "EXIT STATUS"
|
|
The following exit values are returned:
|
|
.PP
|
|
.RS
|
|
0 Successful completion.
|
|
.RE
|
|
.RS
|
|
>0 An error occurred.
|
|
.RE
|
|
.PP
|
|
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 \f4%c\f1 or \f4%s\f1 conversion or if a string operand's first or second
|
|
character is used to get the numeric value of a character.
|
|
.PP
|
|
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:
|
|
.PP
|
|
\f2Diagnostic Output\fP
|
|
.RS
|
|
printf: "5a" not completely converted
|
|
.RE
|
|
.RS
|
|
printf: "9999999999" arithmetic overflow
|
|
.RE
|
|
.RS
|
|
printf: "-9999999999" arithmetic overflow
|
|
.RE
|
|
.RS
|
|
printf: "ABC" expected numeric value
|
|
.RE
|
|
.PP
|
|
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.
|
|
.SH EXAMPLES
|
|
The command
|
|
.PP
|
|
.RS
|
|
\f4printf '%s %s %s\\n' Good Morning World\fP
|
|
.RE
|
|
.PP
|
|
results in the output:
|
|
.PP
|
|
.RS
|
|
\f5Good Morning World\fP
|
|
.RE
|
|
.PP
|
|
The following command produces the same output.
|
|
.PP
|
|
.RS
|
|
\f4printf '%2$s %s %1$s\\n' World Good Morning\fP
|
|
.RE
|
|
.PP
|
|
Here is an example that prints the first 6 characters of \f4$PATH\fP
|
|
left-adjusted in a 10-character field:
|
|
.PP
|
|
.RS
|
|
\f4printf 'First 6 chars of %s are %-10.6s.\n' $PATH $PATH\fP
|
|
.RE
|
|
.PP
|
|
If \f4$PATH\fP has the value \f4/usr/bin:/usr/local/bin\fP,
|
|
then the above command would print the following output:
|
|
.PP
|
|
.RS
|
|
\f4First 6 chars of /usr/bin:/usr/local/bin are /usr/b .\fP
|
|
.RE
|
|
.PP
|
|
To alert the user and then print and read a series of prompts:
|
|
.PP
|
|
.RS
|
|
\f4printf "\\aPlease fill in the following: \\nName: "\fP
|
|
\f4read name\fP
|
|
\f4printf "Phone number: "\fP
|
|
\f4read phone\fP
|
|
.RE
|
|
.PP
|
|
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:
|
|
.PP
|
|
.RS
|
|
\f4while read right wrong ; do\fP
|
|
\f4percent=$(echo "scale=1;($right*100)/($right+$wrong)" | bc)\fP
|
|
\f4printf "%2d right\t%2d wrong\t(%s%%)\n" \\\fP
|
|
\f4$right $wrong $percent\fP
|
|
\f4done < database_file\fP
|
|
.RE
|
|
.PP
|
|
The command:
|
|
.PP
|
|
.RS
|
|
\f4printf "%5d%4d\\n" 1 21 321 4321 54321\fP
|
|
.RE
|
|
.PP
|
|
produces:
|
|
.PP
|
|
.RS
|
|
\f4 1 21\fP
|
|
.RE
|
|
.RS
|
|
\f4 321 4321\fP
|
|
.RE
|
|
.RS
|
|
\f454321 0\fP
|
|
.RE
|
|
.PP
|
|
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.
|
|
.SH SEE ALSO
|
|
\f4printf\fP(3S)
|
|
.Ee
|