GP-DISPLAY-TEXT.1(1)

📦
version 2.42 · 6 versions
, in ubuntu noble

💖 NAME 💖

okay so bestie, welcome to the GP-DISPLAY-TEXT.1(1) manual page — User Commands energy only, we're fancy here 💅

gp-display-text — it displays your performance data in plain text format. that's it. that's the whole vibe. no cap.

🎀 SYNOPSIS 🎀

gprofng display text [option(s)] [commands] [-script script-file]
experiment(s)

✨ DESCRIPTION ✨

It prints a plain text version of the various displays that gprofng supports. simple, clean, iconic.

The input is one or more experiment directories. You control the output through commands. yes queen, you're driving 🚗

There's a rich set of commands to control how the data shows up. The NOTES section down there lists the most common ones, and the gprofng user guide lists literally all of the commands supported. the full menu, bestie 🍓

Commands you put on the command line need to be prepended with the dash (-) symbol. don't forget it, she will not understand you otherwise 🙈

Here's the moment, the example, the main character:

$ gprofng display text -functions -source my-func my-exp.er

so in that one you get a function overview, and then the source code listing of function my-func, all annotated with the performance metrics that got recorded during data collection and stored in experiment directory my-exp.er. chef's kiss 👑

Instead of — or in addition to — putting those commands on the command line, you can also put commands in a file called the script-file. options on options, we love versatility 🦋

⚠️ The commands are processed and interpreted from left to right, so the order matters. fr fr. order is the whole plot.

If you invoke this tool without options, without commands, or without a script file, it starts up in interpreter mode. You can then issue the commands interactively, like a conversation with your computer. The session gets terminated with the exit command in the interpreter. bye bestie 👋

🌸 OPTIONS 🌸

  • --version — print the version number and exit. short, sweet, done ✨
  • --help — print usage information and exit. when you need a lil hand 🫶
  • -script script-file — execute the commands stored in the script file. and yes, this feature can be combined with commands specified at the command line. mix and match, she's flexible 💜

🔥 NOTES 🔥

There are so many commands supported. Below, the more common ones are listed in mostly alphabetical order, because sometimes it's just more logical to swap the order of two entries. we're chaotic but organized 😌

And there are many more commands. Those live in the user guide. go read it, iykyk 📖

💫 the commands 💫

"callers-callees"

In a callers-callees panel, it shows which function(s) call the target function (the callers) and what functions it's calling (the callees). This command prints the callers-callees panel for each of the functions, in the order specified by the function sort metric. the whole social network of your code 🕸️

"calltree"

Display the dynamic call graph from the experiment, showing the hierarchical metrics at each level. it's giving family tree but for functions 🌳

"compare {on | off | delta | ratio}"

By default, the results for multiple experiments are aggregated. This command changes that, to enable the comparison of experiments for certain views (e.g. the function view). The first experiment specified is defined to be the reference. The following options are supported:

  • "on" — For each experiment specified on the command line, print the values for the metrics that have been activated for the experiment.
  • "off" — Disable the comparison of experiments. This is the default. the chill option 😎
  • "delta" — Print the values for the reference experiment. The results for the other experiments are shown as a delta relative to the reference (current-reference).
  • "ratio" — Print the values for the reference experiment. The results for the other experiments are shown as a ratio relative to the reference (current/reference).

"disasm function-name"

List the source code and instructions for the function specified. The instructions are annotated with the metrics used. down to the metal, bestie 🔩

"fsingle function-name [n]"

Write a summary panel for the specified function. The optional parameter n is needed for those cases where several functions have the same name. name twins need IDs, it's giving ✨

"fsummary"

Write a summary panel for each function in the function list. everybody gets their moment 🎀

"functions"

Display a list of all functions executed. For each function the used metrics (e.g. the CPU time) are shown. the classic, the staple 👑

Shows several operational characteristics of the experiment(s) specified on the command line. the little intro card 💌

"limit n"

Limit the output to n lines. boundaries! we love them 🛑

"lines"

Write a list of source lines and their metrics, ordered by the current sort metric.

"metric_list"

Display the currently selected metrics in the function view and a list of all the metrics available for the target experiment(s). window shopping for metrics 🛍️

"metrics metric-spec"

Define the metrics to be displayed in the function and callers-callees overviews.

The metric-spec can either be the keyword default to restore the default metrics selection, or a colon separated list with metrics.

A special metric is "hwc". It automatically expands to the active set of hardware event counters used in the experiment(s). magic, honestly ✨

If both instructions and clock cycles have been measured, the "CPI" and "IPC" metrics can be used to see the Clockcycles Per Instruction and Instructions Per Clockcyle values, respectively.

The gprofng user guide has more details on how to define metrics.

"name {short | long | mangled}[:{soname | nosoname}]"

Specify whether to use the short, long, or mangled form of function names. Optionally, the load object that the function is part of can be included in the output by adding the soname keyword. It can also be ommitted (nosoname), which is the default.

Whether there's an actual difference between these types of names depends on the language. 🤷♀️

⚠️ Note that there should be no (white)space to the left and right of the colon (:).

And don't get it twisted — this option should not be confused with the keyword name in a metric definition, which is used to specify that the names of functions should be shown in the function overview. two different names, one name-iverse 😭

"overview"

Shows a summary of the recorded performance data for the experiment(s) specified on the command line. the TL;DR of your data 💅

"pcs"

Write a list of program counters (PCs) and their metrics, ordered by the current sort metric.

"sort metric-spec"

Sort the function list on the metric-spec given.

@IndexSubentry{Sort, Reverse order} The data can be sorted in reverse order by prepending the metric definition with a minus (-) sign.

For example sort -e.totalcpu.

@IndexSubentry{Sort, Reset to default} A default metric for the sort operation has been defined, and since this is a persistent command, this default can be restored with "default" as the key (sort default). reset era, love that for you 🦋

"source function-name"

List the source code for the function specified, annotated with the metrics used.

"viewmode {user | expert | machine}"

This command is only relevant for Java programs. For all other languages supported, the viewmode setting has no effect. noted 📝

The following options are supported:

  • "user" — Show the Java call stacks for Java threads, but do not show housekeeping threads. The function view includes a function called <JVM-System>. This represents the aggregated time from non-Java threads. In case the JVM software does not report a Java call stack, time is reported against the function <no Java callstack recorded>.
  • "expert" — Show the Java call stacks for Java threads when the user Java code is executed, and machine call stacks when JVM code is executed, or when the JVM software does not report a Java call stack. Show the machine call stacks for housekeeping threads.
  • "machine" — Show the actual native call stacks for all threads. This is the view mode for C, C++, and Fortran. back to the raw stuff 🔧

🦋 SEE ALSO 🦋

The user guide for gprofng is maintained as a Texinfo manual. If the info and gprofng programs are correctly installed, the command info gprofng should give access to this document. go get your reading on 📚

Copyright (c) 2022-2024 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

and that's the whole page bestie!! 🎀 this was binutils-2.42, dated 2025-12-03, from the GP-DISPLAY-TEXT.1(1) manual — go forth and display that text, you absolute icon 💖✨

📦 where this page comes from