blob: 693b6d38945e38d09bbf50bd0fad93ca61a61220 [file] [log] [blame]
<html lang="en">
<head>
<title>Executing - GNU gprof</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="GNU gprof">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="prev" href="Compiling.html#Compiling" title="Compiling">
<link rel="next" href="Invoking.html#Invoking" title="Invoking">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This file documents the gprof profiler of the GNU system.
Copyright (C) 1988-2019 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''.
-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Executing"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Invoking.html#Invoking">Invoking</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Compiling.html#Compiling">Compiling</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
<hr>
</div>
<h2 class="chapter">3 Executing the Program</h2>
<p>Once the program is compiled for profiling, you must run it in order to
generate the information that <code>gprof</code> needs. Simply run the program
as usual, using the normal arguments, file names, etc. The program should
run normally, producing the same output as usual. It will, however, run
somewhat slower than normal because of the time spent collecting and
writing the profile data.
<p>The way you run the program&mdash;the arguments and input that you give
it&mdash;may have a dramatic effect on what the profile information shows. The
profile data will describe the parts of the program that were activated for
the particular input you use. For example, if the first command you give
to your program is to quit, the profile data will show the time used in
initialization and in cleanup, but not much else.
<p>Your program will write the profile data into a file called <samp><span class="file">gmon.out</span></samp>
just before exiting. If there is already a file called <samp><span class="file">gmon.out</span></samp>,
its contents are overwritten. There is currently no way to tell the
program to write the profile data under a different name, but you can rename
the file afterwards if you are concerned that it may be overwritten.
<p>In order to write the <samp><span class="file">gmon.out</span></samp> file properly, your program must exit
normally: by returning from <code>main</code> or by calling <code>exit</code>. Calling
the low-level function <code>_exit</code> does not write the profile data, and
neither does abnormal termination due to an unhandled signal.
<p>The <samp><span class="file">gmon.out</span></samp> file is written in the program's <em>current working
directory</em> at the time it exits. This means that if your program calls
<code>chdir</code>, the <samp><span class="file">gmon.out</span></samp> file will be left in the last directory
your program <code>chdir</code>'d to. If you don't have permission to write in
this directory, the file is not written, and you will get an error message.
<p>Older versions of the <span class="sc">gnu</span> profiling library may also write a file
called <samp><span class="file">bb.out</span></samp>. This file, if present, contains an human-readable
listing of the basic-block execution counts. Unfortunately, the
appearance of a human-readable <samp><span class="file">bb.out</span></samp> means the basic-block
counts didn't get written into <samp><span class="file">gmon.out</span></samp>.
The Perl script <code>bbconv.pl</code>, included with the <code>gprof</code>
source distribution, will convert a <samp><span class="file">bb.out</span></samp> file into
a format readable by <code>gprof</code>. Invoke it like this:
<pre class="smallexample"> bbconv.pl &lt; bb.out &gt; <var>bh-data</var>
</pre>
<p>This translates the information in <samp><span class="file">bb.out</span></samp> into a form that
<code>gprof</code> can understand. But you still need to tell <code>gprof</code>
about the existence of this translated information. To do that, include
<var>bb-data</var> on the <code>gprof</code> command line, <em>along with
</em><samp><span class="file">gmon.out</span></samp>, like this:
<pre class="smallexample"> gprof <var>options</var> <var>executable-file</var> gmon.out <var>bb-data</var> [<var>yet-more-profile-data-files</var>...] [&gt; <var>outfile</var>]
</pre>
</body></html>