printa() Function

The printa() function is used to format the results of aggregations in a D program. The function is invoked using one of the two following forms:

printa(@aggregation-name);
printa(format-string, @aggregation-name);

If the first form of the function is used, the dtrace command takes a consistent snapshot of the aggregation data and produces output equivalent to the default output format used for aggregations, described in DTrace Aggregations. If the second form of the function is used, the dtrace command takes a consistent snapshot of the aggregation data and produces output according to the conversions specified in the format string, according to the following rules:

• The format conversions must match the tuple signature used to create the aggregation. Each tuple element may only appear once. For example, aggregate a count using the following D statements:

  @a["hello", 123] = count();
  @a["goodbye", 456] = count();

  Add the D statement printa(format-string, @a) to a probe clause. The dtrace utility takes a snapshot of the aggregation data and produces output as if you had entered the following statements for each tuple defined in the aggregation.

  printf(format-string, "hello", 123);
  printf(format-string, "goodbye", 456);

• Unlike printf(), the format string you use for printa() need not include all elements of the tuple. That is, you can have a tuple of length 3 and only one format conversion. Therefore, you can omit any tuple keys from your printa() output by changing your aggregation declaration to move the keys you want to omit to the end of the tuple and then omit corresponding conversion specifiers for them in the printa() format string.

• You can use the additional @ format flag character, which is only valid when used with printa(), to include the aggregation result in the output. The @ flag can be combined with any appropriate format conversion specifier, and may appear more than once in a format string so that your tuple result can appear anywhere in the output and can appear more than once. The set of conversion specifiers that can be used with each aggregating function are implied by the aggregating function's result type. The following table lists the aggregation result types.

Table 6-1 Aggregation Result Types

Aggregation Result Type	Argument
avg	uint64_t
count	uint64_t
lquantize	int64_t
max	uint64_t
min	uint64_t
quantize	int64_t
sum	uint64_t

For example, to format the results of avg, you can apply the %d, %i, %o, %u, or %x format conversions. The quantize and lquantize functions format the results as an ASCII table rather than as a single value.

The following D program shows a complete example of printa(), using the profile provider to sample the value of caller and then formatting the results as a simple table:

profile:::profile-997
{
        @a[caller] = count();
}

END
{
        printa("%@8u %a\n", @a);
}

If you use dtrace to execute this program, wait a few seconds, and press Control-C, the following output is displayed:

# dtrace -s printa.d
^C
CPU     ID                    FUNCTION:NAME
  1      2                             :END        1 0x1
       1 ohci`ohci_handle_root_hub_status_change+0x148
       1 specfs`spec_write+0xe0
       1 0xff14f950
       1 genunix`cyclic_softint+0x588
       1 0xfef2280c
       1 genunix`getf+0xdc
       1 ufs`ufs_icheck+0x50
       1 genunix`infpollinfo+0x80
       1 genunix`kmem_log_enter+0x1e8
       ...