printa()

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

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

If the first form of the function is used, the dtrace(1M) command takes a consistent snapshot of the aggregation data and produces output equivalent to the default output format used for aggregations, described in Chapter 9, Aggregations.

If the second form of the function is used, the dtrace(1M) 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, if you aggregate a count using the following D statements:

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

  and then add the D statement printa(format-string, @a) to a probe clause, dtrace will snapshot the aggregation data and produce output as if you had entered the statements:

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

  and so on for each tuple defined in the aggregation.

• 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.

• The aggregation result can be included in the output by using the additional @ format flag character, which is only valid when used with printa(). 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 aggregation result types are:

  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 their 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, you will see output similar to the following example:

# 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
       ...