9 Formatted output

9.1 print

General syntax:

     print ()

This function prints a single value of any type.

9.2 printf

General syntax:

     printf (fmt:string, ...)

The printf function takes a formatting string as an argument, and a number of values of corresponding types, and prints them all. The format must be a literal string constant. The printf formatting directives are similar to those of C, except that they are fully checked for type by the translator.

The formatting string can contain tags that are defined as follows:

     %[flags][width][.precision][length]specifier

Where specifier is required and defines the type and the interpretation of the value of the corresponding argument. The following table shows the details of the specifier parameter:


Table 1: printf specifier values



Specifier

Output

Example







d or i

Signed decimal

392




o

Unsigned octal

610




s

String

sample




u

Unsigned decimal

7235




x

Unsigned hexadecimal (lowercase letters)

7fa




X

Unsigned hexadecimal (uppercase letters)

7FA




p

Pointer address

0x0000000000bc614e




b

Writes a binary value as text using the computer’s native byte order. The field width specifies the number of bytes to write. Valid specifications are %b, %1b, %2b, %4b and %8b. The default width is 8 (64-bits).

See below




%

A % followed by another % character will write % to stdout.

%





The tag can also contain flags, width, .precision and modifiers sub-specifiers, which are optional and follow these specifications:


Table 2: printf flag values


Flags

Description





- (minus sign)

Left-justify within the given field width. Right justification is the default (see width sub-specifier).



+ (plus sign)

Precede the result with a plus or minus sign even for positive numbers. By default, only negative numbers are preceded with a minus sign.



(space)

If no sign is going to be written, a blank space is inserted before the value.



#

Used with o, x or X specifiers the value is preceded with 0, 0x or 0X respectively for non-zero values.



0

Left-pads the number with zeroes instead of spaces, where padding is specified (see width sub-specifier).





Table 3: printf width values


Width

Description





(number)

Minimum number of characters to be printed. If the value to be printed is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.





Table 4: printf precision values


Precision

Description





.number

For integer specifiers (d, i, o, u, x, X): precision specifies the minimum number of digits to be written. If the value to be written is shorter than this number, the result is padded with leading zeros. The value is not truncated even if the result is longer. A precision of 0 means that no character is written for the value 0. For s: this is the maximum number of characters to be printed. By default all characters are printed until the ending null character is encountered. When no precision is specified, the default is 1. If the period is specified without an explicit value for precision, 0 is assumed.




Binary Write Examples

The following is an example of using the binary write functions:

     probe begin {
         for (i = 97; i < 110; i++)
             printf("%3d: %1b%1b%1b\n", i, i, i-32, i-64)
         exit()
     }

This prints:

      97: aA!
      98: bB"
      99: cC#
     100: dD$
     101: eE%
     102: fF&
     103: gG’
     104: hH(
     105: iI)
     106: jJ*
     107: kK+
     108: lL,
     109: mM-

Another example:

     stap -e ’probe begin{printf("%b%b", 0xc0dedbad, \
     0x12345678);exit()}’ | hexdump -C

This prints:

     00000000  ad db de c0 00 00 00 00  78 56 34 12 00 00 00 00  |........xV4.....|
     00000010

Another example:

     probe begin{
         printf("%1b%1b%1blo %1b%1brld\n", 72,101,108,87,111)
         exit()
     }

This prints:

     Hello World

9.3 printd

General syntax:

     printd (delimiter:string, ...)

This function takes a string delimiter and two or more values of any type, then prints the values with the delimiter interposed. The delimiter must be a literal string constant.

For example:

     printd("/", "one", "two", "three", 4, 5, 6)

prints:

     one/two/three/4/5/6

9.4 printdln

General syntax:

     printdln (delimiter:string, ...)

This function operates like printd, but also appends a newline.

9.5 println

General syntax:

     println ()

This function prints a single value like print, but also appends a newline.

9.6 sprint

General syntax:

     sprint:string ()

This function operates like print, but returns the string rather than printing it.

9.7 sprintf

General syntax:

     sprintf:string (fmt:string, ...)

This function operates like printf, but returns the formatted string rather than printing it.