6.1.5 Conversion Formats

Each conversion character sequence results in fetching zero or more arguments. If insufficient arguments are provided for the format string, if the format string is exhausted and arguments remain, or if an undefined conversion format is specified, then the D compiler issues an appropriate error message. The following table describes the conversion character sequences.

Conversion Characters

Description

a

The pointer or uintptr_t argument is printed as a kernel symbol name in the form module'symbol-name, plus an optional hexadecimal byte offset. If the value does not fall within the range that is defined by a known kernel symbol, the value is printed as a hexadecimal integer.

A

Identical to %a, but is used for user symbols.

c

The char, short, or int argument is printed as an ASCII character.

C

The char, short, or int argument is printed as an ASCII character if the character is a printable ASCII character. If the character is not a printable character, it is printed by using the corresponding escape sequence, as shown in Table 2.6, “Character Escape Sequences”.

d

The char, int, long, long long, or short argument is printed as a decimal (base 10) integer. If the argument is signed, it is printed as a signed value. If the argument is unsigned, it is printed as an unsigned value. This conversion has the same meaning as i.

e, E

The double, float, or long double argument is converted to the style [-]d.ddde[+-]dd, where there is one digit before the radix character and the number of digits that follow is equal to the precision. The radix character is non-zero if the argument is non-zero. If the precision is not specified, the default precision value is 6. If the precision is 0 and the # flag is not specified, no radix character appears. The E conversion format produces a number with E introducing the exponent, instead of e. The exponent always contains at least two digits. The value is rounded up to the appropriate number of digits.

f

The double, float, or long double argument is converted to the style [-]ddd.ddd, where the number of digits after the radix character is equal to the precision specification. If the precision is not specified, the default precision value is 6. If the precision is 0 and the # flag is not specified, no radix character appears. If a radix character appears, at least one digit appears before it. The value is rounded up to the appropriate number of digits.

g, G

The double, float, or long double argument is printed in the style f or e (or in style E in the case of a G conversion character), with the precision specifying the number of significant digits. If an explicit precision is 0, it is taken as 1. The style that is used depends on the value converted: style e (or E) is used only if the exponent resulting from the conversion is less than -4, or greater than or equal to the precision. Trailing zeroes are removed from the fractional part of the result. A radix character appears only if it is followed by a digit. If the # flag is specified, trailing zeroes are not removed from the result.

i

The char, int, long, long long, or short argument is printed as a decimal (base 10) integer. If the argument is signed, it is printed as a signed value. If the argument is unsigned, it is printed as an unsigned value. This conversion has the same meaning as d.

k

The stack argument is printed as if by a call to trace() and handles kernel-level stacks. This argument is valid only with printa because stack cannot be called from a D expression, as a D program context is required.

o

The char, int, long, long long, and short argument is printed as an unsigned octal (base 8) integer. Arguments that are signed or unsigned may be used with this conversion. If the # flag is specified, the precision of the result is increased to force the first digit of the result to be a zero, if necessary.

p

The pointer or uintptr_t argument is printed as a hexadecimal (base 16) integer. D accepts pointer arguments of any type. If the # flag is specified, a non-zero result has 0x prepended to it.

s

The argument must be an array of char or a string. Bytes from the array or string are read up to a terminating null character or the end of the data and interpreted and printed as ASCII characters. If the precision is not specified, it is taken to be infinite so that all characters up to the first null character are printed. If the precision is specified, only the portion of the character array that is displayed in the corresponding number of screen columns is printed. If an argument of type char * is to be formatted, it should be cast to string or prefixed with the D stringof operator to indicate that DTrace should trace the bytes of the string and format them.

S

The argument must be an array of char or string. The argument is processed as if by the %s conversion, but any ASCII characters that are not printable are replaced by the corresponding escape sequence, as described in Table 2.6, “Character Escape Sequences”.

u

The char, int, long, long long, or short argument is printed as an unsigned decimal (base 10) integer. Arguments that are signed or unsigned can be used with this conversion. The result is always formatted as unsigned.

wc

The int argument is converted to a wide character (wchar_t) and the resulting wide character is printed.

ws

The argument must be an array of wchar_t. Bytes from the array are read up to a terminating null character or the end of the data and interpreted and printed as wide characters. If the precision is not specified, it is taken to be infinite, so all wide characters up to the first null character are printed. If the precision is specified, only that portion of the wide character array that is displayed in the corresponding number of screen columns is printed.

x, X

The char, int, long, long long, or short argument is printed as an unsigned hexadecimal (base 16) integer. Arguments that are signed or unsigned may be used with this conversion. If the x form of the conversion is used, the letter digits abcdef are used. If the X form of the conversion is used, the letter digits ABCDEF are used. If the # flag is specified, a non-zero result has 0x (for %x) or 0X (for %X) that is prepended to it.

Y

The uint64_t argument is interpreted to be the number of nanoseconds, since 00:00 Universal Coordinated Time, January 1, 1970, and is printed in the following format: "%Y %a %b %e %T %Z". The current number of nanoseconds since 00:00 UTC, January 1, 1970 is available as the walltimestamp variable.

%

Print a literal % character. No argument is converted. The entire conversion specification must be %%.