[PATCH 2/3] gprofng: Add documentation on converting gmon files.
claudiu.zissulescu-ianculescu@oracle.com
claudiu.zissulescu-ianculescu@oracle.com
Thu Oct 23 12:06:27 GMT 2025
From: Claudiu Zissulescu <claudiu.zissulescu-ianculescu@oracle.com>
Add documentation on converting gmon files.
Signed-off-by: Claudiu Zissulescu <claudiu.zissulescu-ianculescu@oracle.com>
---
gprof/gprof.texi | 4 +
gprofng/doc/Makefile.am | 4 +-
gprofng/doc/Makefile.in | 4 +-
gprofng/doc/gprofng-display-gmon.texi | 213 ++++++++++++++++++++++++++
gprofng/doc/gprofng.texi | 4 +
gprofng/doc/gprofng_ug.texi | 9 ++
6 files changed, 236 insertions(+), 2 deletions(-)
create mode 100644 gprofng/doc/gprofng-display-gmon.texi
diff --git a/gprof/gprof.texi b/gprof/gprof.texi
index c2a6a1029c8..772b9f46d25 100644
--- a/gprof/gprof.texi
+++ b/gprof/gprof.texi
@@ -429,6 +429,10 @@ to interpret the information in it. The @code{gprof} program prints a
flat profile and a call graph on standard output. Typically you would
redirect the output of @code{gprof} into a file with @samp{>}.
+Note that @code{gprofng}, a more modern profiler which is also part of
+binutils, can also read gmon files and provides more functionality
+than @code{gprof}.
+
You run @code{gprof} like this:
@smallexample
diff --git a/gprofng/doc/Makefile.am b/gprofng/doc/Makefile.am
index 8678f22e3a4..331b2686d1f 100644
--- a/gprofng/doc/Makefile.am
+++ b/gprofng/doc/Makefile.am
@@ -36,7 +36,8 @@ TEXINFO_TEX = .
MAKEINFOHTML = $(MAKEINFO) --html --no-split
man_MANS = gprofng.1 gprofng-archive.1 gprofng-collect-app.1 \
- gprofng-display-html.1 gprofng-display-src.1 gprofng-display-text.1
+ gprofng-display-html.1 gprofng-display-src.1 gprofng-display-text.1 \
+ gprofng-display-gmon.1
# Build the man page from the texinfo file
# The sed command removes the no-adjust Nroff command so that
@@ -54,6 +55,7 @@ gprofng-collect-app.1: $(srcdir)/gprofng-collect-app.texi
gprofng-display-html.1: $(srcdir)/gprofng-display-html.texi
gprofng-display-src.1: $(srcdir)/gprofng-display-src.texi
gprofng-display-text.1: $(srcdir)/gprofng-display-text.texi
+gprofng-display-gmon.1: $(srcdir)/gprofng-display-gmon.texi
MAINTAINERCLEANFILES = gprofng.info $(man_MANS)
EXTRA_DIST = $(man_MANS) version.texi
diff --git a/gprofng/doc/Makefile.in b/gprofng/doc/Makefile.in
index 162ae4b19c1..978d07ab17d 100644
--- a/gprofng/doc/Makefile.in
+++ b/gprofng/doc/Makefile.in
@@ -376,7 +376,8 @@ gprofng_ug_TEXINFOS = fdl.texi gp-macros.texi
TEXINFO_TEX = .
MAKEINFOHTML = $(MAKEINFO) --html --no-split
man_MANS = gprofng.1 gprofng-archive.1 gprofng-collect-app.1 \
- gprofng-display-html.1 gprofng-display-src.1 gprofng-display-text.1
+ gprofng-display-html.1 gprofng-display-src.1 gprofng-display-text.1 \
+ gprofng-display-gmon.1
MAINTAINERCLEANFILES = gprofng.info $(man_MANS)
EXTRA_DIST = $(man_MANS) version.texi
@@ -891,6 +892,7 @@ gprofng-collect-app.1: $(srcdir)/gprofng-collect-app.texi
gprofng-display-html.1: $(srcdir)/gprofng-display-html.texi
gprofng-display-src.1: $(srcdir)/gprofng-display-src.texi
gprofng-display-text.1: $(srcdir)/gprofng-display-text.texi
+gprofng-display-gmon.1: $(srcdir)/gprofng-display-gmon.texi
info: $(man_MANS)
diff --git a/gprofng/doc/gprofng-display-gmon.texi b/gprofng/doc/gprofng-display-gmon.texi
new file mode 100644
index 00000000000..463f18bcd5c
--- /dev/null
+++ b/gprofng/doc/gprofng-display-gmon.texi
@@ -0,0 +1,213 @@
+@c ----------------------------------------------------------------------------
+@c This is the Texinfo source file for the gprofng-display-gmon man page.
+@c
+@c Author: Claudiu Zissulescu
+@c ----------------------------------------------------------------------------
+@ifset man
+\input texinfo @c -*-texinfo-*-
+@setfilename gprofng-display-gmon
+@settitle Convert a gmon profile data to a gprofng experiment.
+@include gp-macros.texi
+@end ifset
+
+@c ----------------------------------------------------------------------------
+@c This is from the man-pages(7) man page
+@c
+@c "The list below shows conventional or suggested sections. Most manual pages
+@c should include at least the highlighted sections. Arrange a new manual
+@c page so that sections are placed in the order shown in the list."
+@c
+@c NAME
+@c SYNOPSIS
+@c CONFIGURATION [Normally only in Section 4]
+@c DESCRIPTION
+@c OPTIONS [Normally only in Sections 1, 8]
+@c EXIT STATUS [Normally only in Sections 1, 8]
+@c RETURN VALUE [Normally only in Sections 2, 3]
+@c ERRORS [Typically only in Sections 2, 3]
+@c ENVIRONMENT
+@c FILES
+@c VERSIONS [Normally only in Sections 2, 3]
+@c ATTRIBUTES [Normally only in Sections 2, 3]
+@c CONFORMING TO
+@c NOTES
+@c BUGS
+@c EXAMPLES
+@c AUTHORS [Discouraged]
+@c REPORTING BUGS [Not used in man-pages]
+@c COPYRIGHT [Not used in man-pages]
+@c SEE ALSO
+@c
+@c This is what the texi2pod.pl tool recognizes:
+@c
+@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
+@c BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
+@c
+@c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
+@c makes sense and adhered to for the other formats.
+@c ----------------------------------------------------------------------------
+
+@c ----------------------------------------------------------------------------
+@c NAME section
+@c ----------------------------------------------------------------------------
+
+@ManPageStart{NAME}
+@c man begin NAME
+
+gprofng-display-gmon - Convert a given @file{gmon.out} file to gprofng
+experiments.
+
+@c man end
+@ManPageEnd{}
+
+@c ----------------------------------------------------------------------------
+@c SYNOPSIS section
+@c ----------------------------------------------------------------------------
+
+@ManPageStart{SYNOPSIS}
+@c man begin SYNOPSIS
+
+@command{gprofng display gmon} [@var{option(s)}] [@var{target} [@var{gmon-file}]]
+
+@c man end
+@ManPageEnd{}
+
+@c ----------------------------------------------------------------------------
+@c DESCRIPTION section
+@c ----------------------------------------------------------------------------
+
+@ManPageStart{DESCRIPTION}
+@c man begin DESCRIPTION
+
+Reads the @file{gmon.out} file and the profiled executable. With the
+executable, we can reconstruct information about the profiled symbols
+and the memory map layout. The @file{gmon.out} file provides details
+about the execution duration for each symbol, as well as data used to
+build the call graph. The profile data is taken from the call graph
+profile file (@file{gmon.out} default) which is created by programs
+that are compiled with profile arches (i.e., the @samp{-pg} option of
+@code{cc}).
+
+For example, this command converts the profile data (@file{gmon.out})
+for an executable called @samp{a.out} and stores the data collected in
+an experiment directory with the name @samp{example.er}.
+
+@smallexample
+$ gprofng display gmon -o example.er ./a.out gmon.out
+@end smallexample
+
+@c man end
+@ManPageEnd{}
+
+@c ----------------------------------------------------------------------------
+@c OPTIONS section
+@c ----------------------------------------------------------------------------
+
+@ManPageStart{OPTIONS}
+@c man begin OPTIONS
+
+@table @gcctabopt
+
+@item --version
+@ifclear man
+@IndexSubentry{Options, @code{--version}}
+@end ifclear
+
+Print the version number and exit.
+
+@item --help
+@ifclear man
+@IndexSubentry{Options, @code{--help}}
+@end ifclear
+
+Print usage information and exit.
+
+@item -o @var{<exp_name>}
+@ifclear man
+@IndexSubentry{Options, @code{-o}}
+@end ifclear
+
+Specify the name for the experiment directory. The name has to end with
+@samp{.er} and may contain an absolute path (e.g. @file{/tmp/experiment.er}).
+An existing experiment with the same name will not be overwritten.
+
+@item -O @var{<exp_name>}
+@ifclear man
+@IndexSubentry{Options, @code{-O}}
+@end ifclear
+
+This is the same as the @samp{-o} option, but unlike this option, silently
+overwrites an existing experiment directory with the same name.
+
+@end table
+
+@c man end
+@ManPageEnd{}
+
+@c ----------------------------------------------------------------------------
+@c NOTES section
+@c ----------------------------------------------------------------------------
+
+@ManPageStart{NOTES}
+@c man begin NOTES
+
+Any executable in the ELF (Executable and Linkable Format) object
+format can be used for profiling with gprofng. If @var{target} is
+missing, the default executable name is @file{a.out}. If
+@var{gmon-file} is missing, the default profile data file name is
+@file{gmon.out}.
+
+@c man end
+@ManPageEnd{}
+
+@c ----------------------------------------------------------------------------
+@c SEEALSO section
+@c ----------------------------------------------------------------------------
+
+@ManPageStart{SEE ALSO}
+@c man begin SEEALSO
+
+gprofng(1),
+gprofng-archive(1),
+@c -- gprofng-display-gui(1),
+gprofng-display-html(1),
+gprofng-display-src(1),
+gprofng-display-text(1)
+
+@iftex
+@vspace{1}
+@end iftex
+
+The user guide for gprofng is maintained as a Texinfo manual. If the
+@command{info} and @command{gprofng} programs are correctly installed, the
+command @command{info gprofng} should give access to this document.
+
+@c man end
+@ManPageEnd{}
+
+@c ----------------------------------------------------------------------------
+@c COPYRIGHT section
+@c ----------------------------------------------------------------------------
+
+@ManPageStart{COPYRIGHT}
+@c man begin COPYRIGHT
+
+Copyright @copyright{} 2025 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''.
+
+@c man end
+@ManPageEnd{}
+
+@c ----------------------------------------------------------------------------
+@c If this text is used for a man page, exit. Otherwise we need to continue.
+@c ----------------------------------------------------------------------------
+
+@ifset man
+@bye
+@end ifset
diff --git a/gprofng/doc/gprofng.texi b/gprofng/doc/gprofng.texi
index 67f6167d5ab..04dce20dc47 100644
--- a/gprofng/doc/gprofng.texi
+++ b/gprofng/doc/gprofng.texi
@@ -299,6 +299,9 @@ be installed seperately.
@item gprofng display src
Display source or disassembly with compiler annotations.
+@item gprofng display gmon
+Convert a given @file{gmon.out} file to gprofng experiments.
+
@item gprofng archive
Include binaries and source code in an experiment directory.
@@ -329,6 +332,7 @@ gprofng-collect-app(1),
gprofng-display-html(1),
gprofng-display-src(1),
gprofng-display-text(1)
+gprofng-display-gmon(1)
@iftex
@vspace{1}
diff --git a/gprofng/doc/gprofng_ug.texi b/gprofng/doc/gprofng_ug.texi
index f23f7b379ee..7b04a3f7c5a 100644
--- a/gprofng/doc/gprofng_ug.texi
+++ b/gprofng/doc/gprofng_ug.texi
@@ -157,6 +157,7 @@ The gprofng Man Pages
* Man page for @command{gprofng display text}:: The man page for gprofng display text.
* Man page for @command{gprofng display html}:: The man page for gprofng display html.
* Man page for @command{gprofng display src}:: The man page for gprofng display src.
+* Man page for @command{gprofng display gmon}:: The man page for gprofng display gmon.
* Man page for @command{gprofng archive}:: The man page for gprofng archive.
@c -- Index
@@ -4426,6 +4427,14 @@ In this appendix the man pages for the various @ProductName{} tools are listed.
@include gprofng-display-src.texi
+@c -- A new node --------------------------------------------------------------
+@page
+@node Man page for @command{gprofng display gmon}
+@section Man page for @command{gprofng display gmon}
+@c ----------------------------------------------------------------------------
+
+@include gprofng-display-gmon.texi
+
@c -- A new node --------------------------------------------------------------
@page
@node Man page for @command{gprofng archive}
--
2.51.0
More information about the Binutils
mailing list