Commands That Control the Function List

The following commands control how the function information is displayed.

functions

Write the function list with the currently selected metrics. The function list includes all functions in load objects that are selected for display of functions, and any load objects whose functions are hidden with the object_select command.

You can limit the number of lines written by using the limit command (see Commands That Control Output).

The default metrics printed are exclusive and inclusive user CPU time, in both seconds and percentage of total program metric. You can change the current metrics displayed with the metrics command, which you must issue before you issue the functions command. You can also change the defaults with the dmetrics command in an .er.rc file.

For applications written in the Java programming language, the displayed function information varies depending on whether the View mode is set to user, expert, or machine.

• User mode shows each method by name, with data for interpreted and HotSpot-compiled methods aggregated together; it also suppresses data for non-user-Java threads.

• Expert mode separates HotSpot-compiled methods from interpreted methods, and does not suppress non-user Java threads.

• Machine mode shows data for interpreted Java methods against the Java Virtual Machine (JVM) software as it does the interpreting, while data for methods compiled with the Java HotSpot virtual machine is reported for named methods. All threads are shown.

In all three modes, data is reported in the usual way for any C, C++, or Fortran code called by a Java target.

metrics metric_spec

Specify a selection of function-list metrics. The string metric_spec can either be the keyword default, which restores the default metric selection, or a list of metric keywords, separated by colons. The following example illustrates a metric list.

% metrics i.user:i%user:e.user:e%user

This command instructs the er_print utility to display the following metrics:

• Inclusive user CPU time in seconds

• Inclusive user CPU time percentage

• Exclusive user CPU time in seconds

• Exclusive user CPU time percentage

By default, the metric setting used is based on the dmetrics command, processed from .er.rc files, as described in Commands That Set Defaults. If a metrics command explicitly sets metric_spec to default, the default settings are restored as appropriate to the data recorded.

When metrics are reset, the default sort metric is set in the new list.

If metric_spec is omitted, the current metrics setting is displayed.

In addition to setting the metrics for the function list, the metrics command sets metrics for callers-callees, for data-derived output, and for index objects. The callers-callees metrics show the attributed metrics that correspond to those metrics in the functions list whose inclusive or exclusive metrics are shown, as well as the static metrics.

The dataspace metrics show the dataspace metrics for which data is available and that correspond to those metrics in the function list whose inclusive or exclusive metrics are shown, as well as the static metrics.

The index objects metrics show the index-object metrics corresponding to those metrics in the function list whose inclusive or exclusive metrics are shown, as well as the static metrics.

When the metrics command is processed, a message is printed showing the current metric selection. For the preceding example the message is as follows.

current: i.user:i%user:e.user:e%user:name

For information on the syntax of metric lists, see Metric Lists. To see a listing of the available metrics, use the metric_list command.

If a metrics command has an error, it is ignored with a warning, and the previous settings remain in effect.

sort metric_spec

Sort the function list on metric_spec. The visibility in the metric name does not affect the sort order. If more than one metric is named in the metric_spec, use the first one that is visible. If none of the metrics named are visible, ignore the command. You can precede the metric_spec with a minus sign (-) to specify a reverse sort.

By default, the metric sort setting is based on the dsort command, processed from .er.rc files, as described in Commands That Set Defaults. If a sort command explicitly sets metric_spec to default, the default settings are used.

The string metric_spec is one of the metric keywords described in Metric Lists, as shown in this example.

sort i.user

This command tells the er_print utility to sort the function list by inclusive user CPU time. If the metric is not in the experiments that have been loaded, a warning is printed and the command is ignored. When the command is finished, the sort metric is printed.

fsummary

Write a summary panel for each function in the function list. You can limit the number of panels written by using the limit command (see Commands That Control Output).

The summary metrics panel includes the name, address and size of the function or load object, and for functions, the name of the source file, object file and load object, and all the recorded metrics for the selected function or load object, both exclusive and inclusive, as values and percentages.

fsingle function_name [N]

Write a summary panel for the specified function. The optional parameter N is needed for those cases where there are several functions with the same name. The summary metrics panel is written for the Nth function with the given function name. When the command is given on the command line, N is required; if it is not needed it is ignored. When the command is given interactively without N but N is required, a list of functions with the corresponding N value is printed.

For a description of the summary metrics for a function, see the fsummary command description.