Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices
The printf function combines the ability to
trace data, as if by the trace function, with
the ability to output the data and other text in a specific format
that you describe. The printf function tells
DTrace to trace the data associated with each argument after the
first argument, and then to format the results using the rules
described by the first printf argument, known
as a format string. The format string is a
regular string that contains any number of format conversions,
each beginning with a % character, that
describe how to format the corresponding argument. The first
conversion in the format string corresponds to the second
printf argument, the second conversion to the
third argument, and so on. All of the text between conversions is
printed verbatim. The character following the %
conversion character describes the format to use for the
corresponding argument.
Unlike the C library's printf(), DTrace's
printf is a built-in function that is
recognized by the D compiler. The D compiler provides several
useful services for DTrace printf that are not
found in printf():
The D compiler compares the arguments to the conversions in the format string. If an argument's type is incompatible with the format conversion, the D compiler provides an error message explaining the problem.
The D compiler does not require the use of size prefixes with
printf format conversions. The C
printf routine requires that you indicate
the size of arguments by adding prefixes such as
%ld for long or
%lld for long long. The
D compiler knows the size and type of your arguments, so these
prefixes are not required in your D printf
statements.
DTrace provides additional format characters that are useful
for debugging and observability. For example, the
%a format conversion can be used to print a
pointer as a symbol name and offset.
In order to implement these features, you must specify the format string in the DTrace
printf function as a string constant in your D program. Format strings
cannot be dynamic variables of type string.
Each conversion specification in the format string is introduced
by the % character, after which the following
information appears in sequence:
Zero or more flags (in any order), that modify the meaning of the conversion specification as described in the next section.
An optional minimum field width. If the
converted value has fewer bytes than the field width, the
value will be padded with spaces on the left by default, or
on the right if the left-adjustment flag
(-) is specified. The field width can
also be specified as an asterisk (*), in
which case the field width is set dynamically based on the
value of an additional argument of type
int.
An optional precision that indicates
the minimum number of digits to appear for the
d, i,
o, u,
x, and X conversions
(the field is padded with leading zeroes); the number of
digits to appear after the radix character for the
e, E, and
f conversions, the maximum number of
significant digits for the g and
G conversions; or the maximum number of
bytes to be printed from a string by the
s conversion. The precision takes the
form of a period (.) followed by either
an asterisk (*) as described in
Section 6.1.3, “Width and Precision Specifiers”, or a decimal digit string.
An optional sequence of size prefixes
that indicate the size of the corresponding argument. The
size prefixes are not required in D, and are provided for
compatibility with the C printf()
function.
A conversion specifier that indicates the type of conversion to be applied to the argument.
The C printf() function also supports conversion specifications of
the form % where
n$n is a decimal integer. DTrace's printf does
not support this type of conversion specification.
The printf conversion flags are enabled by specifying one or more of
the following characters, which may appear in any order:
|
Flag Specifier |
Description |
|---|---|
|
|
The integer portion of the result of a decimal conversion
( |
|
|
The result of the conversion is left-justified within the field. The conversion is right-justified if this flag is not specified. |
|
|
The result of signed conversion always begins with a sign
( |
|
|
If the first character of a signed conversion is not a sign or if a signed
conversion results in no characters, a space is placed before the result. If the
|
|
|
The value is converted to an alternate form if an alternate form is defined for the selected conversion. The alternate formats for conversions are described along with the corresponding conversion. |
|
|
For |
The minimum field width can be specified as a decimal digit
string following any flag specifier, in which case the field
width is set to the specified number of columns. The field width
can also be specified as asterisk (*) in
which case an additional argument of type int
is accessed to determine the field width. For example, to print
an integer x in a field width determined by
the value of the int variable
w, you would write the D statement:
printf("%*d", w, x);
The field width can also be specified using a
? character to indicate that the field width
should be set based on the number of characters required to
format an address in hexadecimal in the data model of the
operating system kernel. The width is set to 8 if the kernel is
using the 32-bit data model, or to 16 if the kernel is using the
64-bit data model. The precision for the conversion can be
specified as a decimal digit string following a period
(.) or by an asterisk (*)
following a period. If an asterisk is used to specify the
precision, an additional argument of type int prior to the
conversion argument is accessed to determine the precision. If
both width and precision are specified as asterisks, the order
of arguments to printf for the conversion
should appear in the following order: width, precision, value.
Size prefixes are required in ANSI C programs that use printf() in
order to indicate the size and type of the conversion argument. The D compiler performs this
processing for your printf calls automatically, so size prefixes are not
required. Although size prefixes are provided for C compatibility, their use is explicitly
discouraged in D programs because they bind your code to a particular data model when using
derived types. For example, if a typedef is redefined to different
integer base types depending on the data model, it is not possible to use a single C
conversion that works in both data models without explicitly knowing the two underlying
types and including a cast expression, or defining multiple format strings. The D compiler
solves this problem automatically by allowing you to omit size prefixes and automatically
determining the argument size.
The size prefixes can be placed just prior to the format conversion name and after any flags, widths, and precision specifiers. The size prefixes are as follows:
An optional h specifies that a following
d, i,
o, u,
x, or X conversion
applies to a short or unsigned short.
An optional l specifies that a following
d, i,
o, u,
x, or X conversion
applies to a long or unsigned long.
An optional ll specifies that a following
d, i,
o, u,
x, or X conversion
applies to a long long or unsigned long long.
An optional L specifies that a following
e, E,
f, g, or
G conversion applies to a long double.
An optional l specifies that a following
c conversion applies to a
wint_t argument, and that a following
s conversion character applies to a
pointer to a wchar_t argument.
Each conversion character sequence results in fetching zero or more arguments. If insufficient arguments are provided for the format string, the format string is exhausted and arguments remain, or an undefined conversion format is specified, the D compiler issues an appropriate error message. The following table lists the conversion character sequences.
|
Conversion Characters |
Description |
|---|---|
|
|
The pointer or |
|
|
Exactly like |
|
|
The |
|
|
The |
|
|
The |
|
|
The |
|
|
The |
|
|
The |
|
|
The |
|
|
The |
|
|
The |
|
|
The pointer or |
|
|
The argument must be an array of |
|
|
The argument must be an array of |
|
|
The |
|
|
The |
|
|
The |
|
|
The argument must be an array of |
|
|
The |
|
|
The |
| Print a literal |
Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices